FRC プログラミング Limelight Lib を使用して (WPILib Java & C++)

JavaDocs: https://limelightlib-wpijava-reference.limelightvision.io

使用方法

これは単一ファイルのライブラリです。必要なのは、最新リリース（https://github.com/LimelightVision/limelightlib-wpijava/releases）から LimelightHelpers.java ファイルをコピーして、Javaプロジェクトの「robot」フォルダに配置するだけです。Limelightのオブジェクトを作成する必要はありません - このライブラリはシンプルで機能的であり、使いやすさと信頼性を最大化しています。

成功のためのヒント

シンプルに始めましょう！多くの成功しているFRCチームは基本的なアプローチを効果的に使用しています。例えば、2024年のチーム2056はゲームピーストラッキングにニューラルネットワークではなく、標準的な90FPSカラーパイプラインを使用しました。
実際に必要なものを考えましょう：フィールド全体のローカライゼーションが必要ですか？それとも単純なターゲットセンタリング（例：driveSpeed = result.getTx() * 0.03）で十分ですか？

主要な概念

1. 基本的な使用方法

すべてのメソッドはLimelightの名前パラメータを受け付けます。空白またはnullを指定すると「limelight」が使用されます：

// 基本的なターゲティングデータ
double tx = LimelightHelpers.getTX("");  // 照準からターゲットまでの水平オフセット（度）
double ty = LimelightHelpers.getTY("");  // 照準からターゲットまでの垂直オフセット（度）
double ta = LimelightHelpers.getTA("");  // ターゲット面積（画像の0%から100%）
boolean hasTarget = LimelightHelpers.getTV(""); // 有効なターゲットがありますか？

double txnc = LimelightHelpers.getTXNC("");  // 主要ピクセル/ポイントからターゲットまでの水平オフセット（度）
double tync = LimelightHelpers.getTYNC("");  // 主要ピクセル/ポイントからターゲットまでの垂直オフセット（度）

2. パイプライン管理

パイプラインは、Limelightが画像を処理する方法を変更する即座に切り替え可能なプログラムのようなものです。ウェブインターフェースで10種類の異なるパイプラインを設定できます：

// パイプライン0に切り替え
LimelightHelpers.setPipelineIndex("", 0);

3. LED制御

明るい照明LEDを持つLimelightでは、異なる状況に応じてLEDを制御できます：

// 現在のパイプラインにLEDの制御を任せる
LimelightHelpers.setLEDMode_PipelineControl("");

// LEDを強制的にオン/オフ/点滅させる
LimelightHelpers.setLEDMode_ForceOn("");
LimelightHelpers.setLEDMode_ForceOff("");
LimelightHelpers.setLEDMode_ForceBlink("");

4. MegaTagによるフィールドローカライゼーション

（詳細はMegaTagのドキュメントとSwerve姿勢推定チュートリアルを参照してください。）

// 周期的な関数内で：
LimelightHelpers.PoseEstimate limelightMeasurement = LimelightHelpers.getBotPoseEstimate_wpiBlue("limelight");
if (limelightMeasurement.tagCount >= 2) {  // 複数のタグが見える場合のみ測定を信頼する
    m_poseEstimator.setVisionMeasurementStdDevs(VecBuilder.fill(0.7, 0.7, 9999999));
    m_poseEstimator.addVisionMeasurement(
        limelightMeasurement.pose,
        limelightMeasurement.timestampSeconds
    );
}

5. MegaTag2によるフィールドローカライゼーション

（詳細はMegaTag2のドキュメントとSwerve姿勢推定チュートリアルを参照してください。）

MegaTag2はロボットの向きデータとビジョンを融合させることでローカライゼーションの精度を向上させます。ジャイロデータを提供することで、MegaTag2はローカライゼーションの問題を制約し、1つのタグしか見えない場合でも優れた結果を提供します：

// まず、Limelightにロボットの現在の向きを伝える
double robotYaw = m_gyro.getYaw();  
LimelightHelpers.SetRobotOrientation("", robotYaw, 0.0, 0.0, 0.0, 0.0, 0.0);

// 姿勢推定を取得
LimelightHelpers.PoseEstimate limelightMeasurement = LimelightHelpers.getBotPoseEstimate_wpiBlue("");

// 姿勢推定器に追加
m_poseEstimator.setVisionMeasurementStdDevs(VecBuilder.fill(.5, .5, 9999999));
m_poseEstimator.addVisionMeasurement(
    limelightMeasurement.pose,
    limelightMeasurement.timestampSeconds
);

6. AprilTagの特別な機能

// パフォーマンス向上のためのカスタムクロップウィンドウを設定（各値は-1から1）
LimelightHelpers.setCropWindow("", -0.5, 0.5, -0.5, 0.5);


// ロボット中心に対するカメラの姿勢を変更（x前方、y左、z上、度）
LimelightHelpers.setCameraPose_RobotSpace("", 
    0.5,    // 前方オフセット（メートル）
    0.0,    // 側面オフセット（メートル）
    0.5,    // 高さオフセット（メートル）
    0.0,    // ロール（度）
    30.0,   // ピッチ（度）
    0.0     // ヨー（度）
);

// AprilTagオフセットトラッキングポイントを設定（メートル）
LimelightHelpers.setFiducial3DOffset("", 
    0.0,    // 前方オフセット
    0.0,    // 側面オフセット  
    0.5     // 高さオフセット
);

// AprilTag検出を設定
LimelightHelpers.SetFiducialIDFiltersOverride("", new int[]{1, 2, 3, 4}); // これらのタグIDのみを追跡
LimelightHelpers.SetFiducialDownscalingOverride("", 2.0f); // フレームレート向上と検出範囲縮小のために半分の解像度で処理

7. Python統合

カスタムPython SnapScriptsと通信：

// Pythonにデータを送信
double[] dataToSend = {1.0, 2.0, 3.0};
LimelightHelpers.setPythonScriptData("", dataToSend);

// Pythonからデータを取得
double[] dataFromPython = LimelightHelpers.getPythonScriptData("");

8. NetworkTablesから詳細な結果を取得する（RawTargets）

最大のパフォーマンスを得るために、JSONパースをバイパスしてNetworkTablesから直接生のターゲットデータにアクセスできます：

// 生のAprilTag/Fiducialデータを取得
RawFiducial[] fiducials = LimelightHelpers.getRawFiducials("");
for (RawFiducial fiducial : fiducials) {
    int id = fiducial.id;                    // タグID
    double txnc = fiducial.txnc;             // Xオフセット（照準なし）
    double tync = fiducial.tync;             // Yオフセット（照準なし）
    double ta = fiducial.ta;                 // ターゲット面積
    double distToCamera = fiducial.distToCamera;  // カメラまでの距離
    double distToRobot = fiducial.distToRobot;    // ロボットまでの距離
    double ambiguity = fiducial.ambiguity;   // タグ姿勢の曖昧さ
}

// ニューラル検出器の生の結果を取得
RawDetection[] detections = LimelightHelpers.getRawDetections("");
for (RawDetection detection : detections) {
    int classID = detection.classId;
    double txnc = detection.txnc;
    double tync = detection.tync;
    double ta = detection.ta;
    // 必要に応じて角座標にアクセス
    double corner0X = detection.corner0_X;
    double corner0Y = detection.corner0_Y;
    // ... 同様に角1-3も利用可能
}

9. JSONから詳細な結果を取得する（Results オブジェクト）

ResultsオブジェクトはすべてのLimelightデータタイプへの包括的なアクセスを提供します。RoboRIOでの解析に最大2msかかる可能性があるため、FRCではこのアプローチを推奨していません：

LimelightResults results = LimelightHelpers.getLatestResults("");
if (results.valid) {
    // カラー/レトロリフレクティブターゲット
    if (results.targets_Retro.length > 0) {
        LimelightTarget_Retro target = results.targets_Retro[0];
        double skew = target.ts;             // ターゲットの傾き/回転
        double shortSide = target.short_side; // 最短辺（ピクセル）
        double longSide = target.long_side;   // 最長辺（ピクセル）
        Pose3d targetPose = target.getCameraPose_TargetSpace();
    }
    
    // AprilTags/Fiducials
    if (results.targets_Fiducials.length > 0) {
        LimelightTarget_Fiducial tag = results.targets_Fiducials[0];
        double id = tag.fiducialID;          // タグID
        String family = tag.fiducialFamily;   // タグファミリー（例：「16h5」）
        
        // 3D姿勢データ
        Pose3d robotPoseField = tag.getRobotPose_FieldSpace();    // フィールド空間におけるロボットの姿勢
        Pose3d cameraPoseTag = tag.getCameraPose_TargetSpace();   // タグに対するカメラの姿勢
        Pose3d robotPoseTag = tag.getRobotPose_TargetSpace();     // タグに対するロボットの姿勢
        Pose3d tagPoseCamera = tag.getTargetPose_CameraSpace();   // カメラに対するタグの姿勢
        Pose3d tagPoseRobot = tag.getTargetPose_RobotSpace();     // ロボットに対するタグの姿勢
        
        // 2Dターゲティングデータ
        double tx = tag.tx;                  // 照準からの水平オフセット
        double ty = tag.ty;                  // 照準からの垂直オフセット
        double ta = tag.ta;                  // ターゲット面積（画像の0-100%）
    }

    // ニューラルネットワーク検出
    if (results.targets_Detector.length > 0) {
        LimelightTarget_Detector detection = results.targets_Detector[0];
        String className = detection.className;
        double confidence = detection.confidence;
        double area = detection.ta;
    }
    
    // 分類器の結果
    if (results.targets_Classifier.length > 0) {
        LimelightTarget_Classifier result = results.targets_Classifier[0];
        String class_name = result.className;
        double confidence = result.confidence;
        int classID = (int)result.classID;
    }
    
    // バーコード/QRコードの結果
    if (results.targets_Barcode.length > 0) {
        LimelightTarget_Barcode barcode = results.targets_Barcode[0];
        String data = barcode.data;
        String family = barcode.family;
    }
}

10. スナップショット管理

オフラインでのパイプラインチューニング用にスナップショットを撮影：

// 後でウェブインターフェースで表示するためにスナップショットを撮影
LimelightHelpers.takeSnapshot("", "auto_shot_1");

11. その他の機能

// ストリームモードの変更
LimelightHelpers.setStreamMode_Standard("");        // 並べて表示するストリーム
LimelightHelpers.setStreamMode_PiPMain("");        // 隅に副ストリームを表示
LimelightHelpers.setStreamMode_PiPSecondary("");   // 隅に主ストリームを表示

LimelightHelpers 静的メソッド

ターゲットデータ

public static boolean getTV(String limelightName)
public static double getTX(String limelightName)
public static double getTY(String limelightName)
public static double getTXNC(String limelightName)
public static double getTYNC(String limelightName)
public static double getTA(String limelightName)
public static double[] getT2DArray(String limelightName)
public static int getTargetCount(String limelightName)
public static RawFiducial[] getRawFiducials(String limelightName)
public static RawDetection[] getRawDetections(String limelightName)

ニューラルネットワーク結果

public static int getClassifierClassIndex(String limelightName)  
public static int getDetectorClassIndex(String limelightName)
public static String getClassifierClass(String limelightName)
public static String getDetectorClass(String limelightName)

姿勢推定

public static PoseEstimate getBotPoseEstimate_wpiBlue(String limelightName)
public static PoseEstimate getBotPoseEstimate_wpiRed(String limelightName)
public static PoseEstimate getBotPoseEstimate_wpiBlue_MegaTag2(String limelightName)
public static PoseEstimate getBotPoseEstimate_wpiRed_MegaTag2(String limelightName)

public static Pose3d getBotPose3d(String limelightName)
public static Pose3d getBotPose3d_wpiRed(String limelightName)
public static Pose3d getBotPose3d_wpiBlue(String limelightName)
public static Pose3d getBotPose3d_TargetSpace(String limelightName)
public static Pose3d getCameraPose3d_TargetSpace(String limelightName)
public static Pose3d getTargetPose3d_CameraSpace(String limelightName)
public static Pose3d getTargetPose3d_RobotSpace(String limelightName)
public static Pose3d getCameraPose3d_RobotSpace(String limelightName)

public static Pose2d getBotPose2d(String limelightName)
public static Pose2d getBotPose2d_wpiBlue(String limelightName)
public static Pose2d getBotPose2d_wpiRed(String limelightName)

public static double[] getBotPose(String limelightName)
public static double[] getBotPose_wpiRed(String limelightName)
public static double[] getBotPose_wpiBlue(String limelightName)
public static double[] getBotPose_TargetSpace(String limelightName)
public static double[] getCameraPose_TargetSpace(String limelightName)
public static double[] getTargetPose_CameraSpace(String limelightName)
public static double[] getTargetPose_RobotSpace(String limelightName)

カメラ/パイプライン設定

public static void setPipelineIndex(String limelightName, int pipelineIndex)
public static void setPriorityTagID(String limelightName, int ID)
public static double getCurrentPipelineIndex(String limelightName)
public static String getCurrentPipelineType(String limelightName)

public static void setLEDMode_PipelineControl(String limelightName)
public static void setLEDMode_ForceOff(String limelightName)
public static void setLEDMode_ForceBlink(String limelightName)
public static void setLEDMode_ForceOn(String limelightName)

public static void setStreamMode_Standard(String limelightName)
public static void setStreamMode_PiPMain(String limelightName)
public static void setStreamMode_PiPSecondary(String limelightName)

public static void setCropWindow(String limelightName, double cropXMin, double cropXMax, double cropYMin, double cropYMax)
public static void setCameraPose_RobotSpace(String limelightName, double forward, double side, double up, double roll, double pitch, double yaw)

高度なAprilTag/フィデューシャル設定

public static void setFiducial3DOffset(String limelightName, double offsetX, double offsetY, double offsetZ)
public static void SetRobotOrientation(String limelightName, double yaw, double yawRate, double pitch, double pitchRate, double roll, double rollRate)
public static void SetFiducialIDFiltersOverride(String limelightName, int[] validIDs)
public static void SetFiducialDownscalingOverride(String limelightName, float downscale)

結果とデータアクセス

public static double getLatency_Pipeline(String limelightName)
public static double getLatency_Capture(String limelightName)
public static double[] getTargetColor(String limelightName)
public static double getFiducialID(String limelightName)
public static String getNeuralClassID(String limelightName)
public static String[] getRawBarcodeData(String limelightName)
public static String getJSONDump(String limelightName)
public static LimelightResults getLatestResults(String limelightName)

Pythonスクリプトインターフェース

public static void setPythonScriptData(String limelightName, double[] outgoingPythonData)
public static double[] getPythonScriptData(String limelightName)

ユーティリティメソッド

public static CompletableFuture<Boolean> takeSnapshot(String tableName, String snapshotName)
public static NetworkTable getLimelightNTTable(String tableName)
public static NetworkTableEntry getLimelightNTTableEntry(String tableName, String entryName)
public static double getLimelightNTDouble(String tableName, String entryName)
public static void setLimelightNTDouble(String tableName, String entryName, double val)
public static void setLimelightNTDoubleArray(String tableName, String entryName, double[] val)
public static double[] getLimelightNTDoubleArray(String tableName, String entryName)
public static String getLimelightNTString(String tableName, String entryName)
public static URL getLimelightURLString(String tableName, String request)

コアクラス

PoseEstimate

3Dポーズ推定を表します

パブリックプロパティ:

Pose2d pose - 推定されたポーズ
double timestampSeconds - 推定のタイムスタンプ
double latency - 処理の遅延
int tagCount - 使用されたタグの数
double tagSpan - 検出されたタグ間のスパン
double avgTagDist - タグまでの平均距離
double avgTagArea - タグの平均面積
RawFiducial[] rawFiducials - 生のフィデューシャル検出
boolean isMegaTag2 - これがMegaTag2の結果かどうか

(NetworkTables由来) RawFiducial

生のAprilTag/フィデューシャル検出データを表します

パブリックプロパティ:

int id - AprilTag ID番号
double txnc - カメラ中心からの水平オフセット（度）
double tync - カメラ中心からの垂直オフセット（度）
double ta - ターゲット面積（画像の0-100%）
double distToCamera - カメラからターゲットまでの距離（メートル）
double distToRobot - ロボットからターゲットまでの距離（メートル）
double ambiguity - AprilTagポーズの曖昧さスコア

(NetworkTables由来) RawDetection

ニューラルネットワーク検出の生データを表します

パブリックプロパティ:

int classId - ニューラルネットワークのクラスID
double txnc - カメラ中心からの水平オフセット（度）
double tync - カメラ中心からの垂直オフセット（度）
double ta - ターゲット面積（画像の0-100%）
double corner0_X - 1つ目の角のX座標
double corner0_Y - 1つ目の角のY座標
double corner1_X - 2つ目の角のX座標
double corner1_Y - 2つ目の角のY座標
double corner2_X - 3つ目の角のX座標
double corner2_Y - 3つ目の角のY座標
double corner3_X - 4つ目の角のX座標
double corner3_Y - 4つ目の角のY座標

(JSON由来) LimelightResults

LimelightのJSON出力からのすべての結果を含みます

パブリックプロパティ:

String error - エラーメッセージ（ある場合）
double pipelineID - 現在のパイプラインインデックス
double latency_pipeline - パイプライン処理の遅延（ms）
double latency_capture - 画像キャプチャの遅延（ms）
double latency_jsonParse - JSON解析の遅延（ms）
double timestamp_LIMELIGHT_publish - データが公開されたときのタイムスタンプ
double timestamp_RIOFPGA_capture - RoboRIO FPGAがデータをキャプチャしたときのタイムスタンプ
boolean valid - ターゲットが有効かどうか
double[] botpose - フィールド空間内のロボットポーズ
double[] botpose_wpired - WPILib赤アライアンス空間内のロボットポーズ
double[] botpose_wpiblue - WPILib青アライアンス空間内のロボットポーズ
double botpose_tagcount - ポーズ推定に使用されたタグの数
double botpose_span - 検出されたタグ間のスパン
double botpose_avgdist - 検出されたタグまでの平均距離
double botpose_avgarea - 検出されたタグの平均面積
double[] camerapose_robotspace - ロボットに対するカメラのポーズ
LimelightTarget_Retro[] targets_Retro - レトロリフレクティブターゲットの配列
LimelightTarget_Fiducial[] targets_Fiducials - AprilTagターゲットの配列
LimelightTarget_Classifier[] targets_Classifier - 分類器結果の配列
LimelightTarget_Detector[] targets_Detector - 検出器結果の配列
LimelightTarget_Barcode[] targets_Barcode - バーコード結果の配列

パブリックメソッド:

Pose3d getBotPose3d()
Pose3d getBotPose3d_wpiRed()
Pose3d getBotPose3d_wpiBlue()
Pose2d getBotPose2d()
Pose2d getBotPose2d_wpiRed()
Pose2d getBotPose2d_wpiBlue()

(JSON由来) LimelightTarget_Retro

カラー/レトロリフレクティブターゲット結果を表します

パブリックプロパティ:

double ta - ターゲット面積（画像の0-100%）
double tx - 十字線からターゲットまでの水平オフセット（-29.8〜29.8度）
double ty - 十字線からターゲットまでの垂直オフセット（-24.85〜24.85度）
double tx_pixels - ピクセル単位の水平オフセット
double ty_pixels - ピクセル単位の垂直オフセット
double tx_nocrosshair - カメラ中心からの水平オフセット
double ty_nocrosshair - カメラ中心からの垂直オフセット
double ts - ターゲットの傾きまたは回転（-90〜0度）

パブリックメソッド:

Pose3d getCameraPose_TargetSpace()
Pose3d getRobotPose_FieldSpace()
Pose3d getRobotPose_TargetSpace()
Pose3d getTargetPose_CameraSpace()
Pose3d getTargetPose_RobotSpace()
Pose2d getCameraPose_TargetSpace2D()
Pose2d getRobotPose_FieldSpace2D()
Pose2d getRobotPose_TargetSpace2D()
Pose2d getTargetPose_CameraSpace2D()
Pose2d getTargetPose_RobotSpace2D()

(JSON由来) LimelightTarget_Fiducial

AprilTag/フィデューシャルターゲット結果を表します

パブリックプロパティ:

double fiducialID - AprilTag ID番号
String fiducialFamily - AprilTagファミリータイプ
LimelightTarget_Retroからのすべてのプロパティ

パブリックメソッド:

LimelightTarget_Retroからのすべてのメソッド

(JSON由来) LimelightTarget_Barcode

バーコードターゲット結果を表します

パブリックプロパティ:

String family - バーコードファミリータイプ（例：「QR」、「DataMatrix」）
String data - デコードされたバーコードデータの内容
double tx_pixels - ピクセル単位の水平オフセット
double ty_pixels - ピクセル単位の垂直オフセット
double tx - 十字線からの水平オフセット
double ty - 十字線からの垂直オフセット
double tx_nocrosshair - カメラ中心からの水平オフセット
double ty_nocrosshair - カメラ中心からの垂直オフセット
double ta - ターゲット面積
double[][] corners - 角の座標

パブリックメソッド:

String getFamily()

(JSON由来) LimelightTarget_Classifier

ニューラル分類器パイプラインの結果を表します

パブリックプロパティ:

String className - 検出されたクラス名
double classID - 検出されたクラスID番号
double confidence - 検出信頼度（0-100%）
double zone - 検出ゾーン
double tx - 十字線からの水平オフセット
double ty - 十字線からの垂直オフセット
double txp - ピクセル単位の水平オフセット
double typ - ピクセル単位の垂直オフセット

(JSON由来) LimelightTarget_Detector

ニューラル検出器パイプラインの結果を表します

パブリックプロパティ:

String className - 検出されたクラス名
double classID - 検出されたクラスID番号
double confidence - 検出信頼度（0-100%）
double ta - ターゲット面積
double tx - 十字線からの水平オフセット
double ty - 十字線からの垂直オフセット
double txp - ピクセル単位の水平オフセット
double typ - ピクセル単位の垂直オフセット
double tx_nocrosshair - カメラ中心からの水平オフセット
double ty_nocrosshair - カメラ中心からの垂直オフセット

FRC プログラミング Limelight Lib を使用して (WPILib Java & C++)

使用方法​

成功のためのヒント​

主要な概念​

1. 基本的な使用方法​

2. パイプライン管理​

3. LED制御​

4. MegaTagによるフィールドローカライゼーション​

5. MegaTag2によるフィールドローカライゼーション​

6. AprilTagの特別な機能​

7. Python統合​

8. NetworkTablesから詳細な結果を取得する（RawTargets）​

9. JSONから詳細な結果を取得する（Results オブジェクト）​

10. スナップショット管理​

11. その他の機能​

LimelightHelpers 静的メソッド​

ターゲットデータ​

ニューラルネットワーク結果​

姿勢推定​

カメラ/パイプライン設定​

高度なAprilTag/フィデューシャル設定​

結果とデータアクセス​

Pythonスクリプトインターフェース​

ユーティリティメソッド​

コアクラス​

PoseEstimate​

(NetworkTables由来) RawFiducial​

(NetworkTables由来) RawDetection​

(JSON由来) LimelightResults​

(JSON由来) LimelightTarget_Retro​

(JSON由来) LimelightTarget_Fiducial​

(JSON由来) LimelightTarget_Barcode​

(JSON由来) LimelightTarget_Classifier​

(JSON由来) LimelightTarget_Detector​

使用方法

成功のためのヒント

主要な概念

1. 基本的な使用方法

2. パイプライン管理

3. LED制御

4. MegaTagによるフィールドローカライゼーション

5. MegaTag2によるフィールドローカライゼーション

6. AprilTagの特別な機能

7. Python統合

8. NetworkTablesから詳細な結果を取得する（RawTargets）

9. JSONから詳細な結果を取得する（Results オブジェクト）

10. スナップショット管理

11. その他の機能

LimelightHelpers 静的メソッド

ターゲットデータ

ニューラルネットワーク結果

姿勢推定

カメラ/パイプライン設定

高度なAprilTag/フィデューシャル設定

結果とデータアクセス

Pythonスクリプトインターフェース

ユーティリティメソッド

コアクラス

PoseEstimate

(NetworkTables由来) RawFiducial

(NetworkTables由来) RawDetection

(JSON由来) LimelightResults

(JSON由来) LimelightTarget_Retro

(JSON由来) LimelightTarget_Fiducial

(JSON由来) LimelightTarget_Barcode

(JSON由来) LimelightTarget_Classifier

(JSON由来) LimelightTarget_Detector