תכנות FRC עם Limelight Lib (WPILib Java & C++)
- https://github.com/LimelightVision/limelightlib-wpijava
- https://github.com/LimelightVision/limelightlib-wpicpp
JavaDocs: https://limelightlib-wpijava-reference.limelightvision.io
שימוש
זוהי ספרייה בקובץ בודד. כל מה שעליך לעשות הוא להעתיק את הקובץ LimelightHelpers.java מהגרסה האחרונה (https://github.com/LimelightVision/limelightlib-wpijava/releases) לתיקיית "robot" בפרויקט Java שלך. אין צורך ליצור אובייקטים עבור ה-Limelights שלך - הספרייה פשוטה ופונקציונלית כדי למקסם את קלות השימוש והאמינות.
טיפים להצלחה
- התחל בפשטות! קבוצות FRC מצליחות רבות משתמשות בגישות בסיסיות באופן יעיל. לדוגמה, קבוצה 2056 בשנת 2024 השתמשה בצינור צבע סטנדרטי של 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. ניהול צינורות (Pipelines)
צינורות הם כמו תוכניות שניתן להחליף באופן מיידי המשנות את אופן עיבוד התמונות של Limelight. ניתן להגדיר 10 צינורות שונים בממשק האינטרנט:
// עבור לצינור 0
LimelightHelpers.setPipelineIndex("", 0);
3. שליטה ב-LED
עבור Limelight עם נורות LED בהירות, ניתן לשלוט ב-LED למצבים שונים:
// תן לצינור הנוכחי לשלוט ב-LED
LimelightHelpers.setLEDMode_PipelineControl("");
// כפה הדלקה/כיבוי/הבהוב של ה-LED
LimelightHelpers.setLEDMode_ForceOn("");
LimelightHelpers.setLEDMode_ForceOff("");
LimelightHelpers.setLEDMode_ForceBlink("");
4. מיקום בשדה עם MegaTag
(ראה את התיעוד של MegaTag ואת המדריך Swerve Pose Estimation לפרטים נוספים.)
// בפונקציה המחזורית שלך:
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 Pose Estimation לפרטים נוספים.)
MegaTag2 משפר את דיוק המיקום על ידי מיזוג נתוני כיוון הרובוט עם ראייה. על ידי אספקת נתוני גירוסקופ, אתה עוזר ל-MegaTag2 להגביל את בעיית המיקום ולספק תוצאות מצוינות גם אם רק תג אחד גלוי:
// ראשית, ספר ל-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}); // עקוב רק אחרי מזהי תגים אלה
LimelightHelpers.SetFiducialDownscalingOverride("", 2.0f); // עבד ברזולוציה חצויה לשיפור קצב הפריימים והפחתת טווח
7. אינטגרציה עם Python
תקשורת עם סקריפטי Python מותאמים אישית:
// שלח נתונים ל-Python
double[] dataToSend = {1.0, 2.0, 3.0};
LimelightHelpers.setPythonScriptData("", dataToSend);
// קבל נתונים מ-Python
double[] dataFromPython = LimelightHelpers.getPythonScriptData("");
8. קבלת תוצאות מפורטות מ-NetworkTables (RawTargets)
לביצועים מקסימליים, ניתן לגשת לנתוני מטרה גולמיים ישירות מ-NetworkTables, עוקף ניתוח JSON:
// קבל נתוני AprilTag/Fiducial גולמיים
RawFiducial[] fiducials = LimelightHelpers.getRawFiducials("");
for (RawFiducial fiducial : fiducials) {
int id = fiducial.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. זה יכול לקחת עד 2 מילישניות לניתוח ב-RoboRIO, לכן איננו ממליצים להשתמש בגישה זו ב-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; // מזהה תג
String family = tag.fiducialFamily; // משפחת תג (למשל, "16h5")
// נתוני מיקום תלת-ממדי
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(); // מיקום התג ביחס לרובוט
// נתוני מיקוד דו-ממדיים
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/Fiducial
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)
ממשק סקריפט פייתון
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
מייצג הערכת תנוחה תלת-ממדית
מאפיינים ציבוריים:
Pose2d pose
- התנוחה המוערכתdouble timestampSeconds
- חותמת זמן של ההערכהdouble latency
- השהיית עיבודint tagCount
- מספר התגים שנעשה בהם שימושdouble tagSpan
- מרווח בין התגים שזוהוdouble avgTagDist
- מרחק ממוצע לתגיםdouble avgTagArea
- שטח ממוצע של התגיםRawFiducial[] rawFiducials
- זיהויי סמנים גולמייםboolean isMegaTag2
- האם זו תוצאה של MegaTag2