انتقل إلى المحتوى الرئيسي

دليل برمجة FTC Java و Blockly

(صور Blockly قادمة قريبًا!)

تأكد من قراءة البدء السريع لبرمجة FTC.

Javadoc: [رابط Javadoc قادم قريبًا]

مستودع الأمثلة الكاملة: مستودع أمثلة Limelight FTC

نصائح للنجاح​

  • قم بالشيء البسيط أولاً. في FRC، تعلمنا أن أفضل فرق البرمجيات غالبًا ما تستخدم الأساليب الأبسط. على سبيل المثال، استخدم فريق FRC 2056 في عام 2024 خط أنابيب ألوان قياسي بسرعة 90 إطارًا في الثانية بدلاً من شبكة عصبية لتتبع قطع اللعبة.

إليك مثالاً على نوع السؤال الذي يجب طرحه عند بدء البرمجة: في وضع التحكم عن بعد، هل تحتاج إلى معرفة موقع روبوتك على الملعب، أم تحتاج ببساطة إلى التحرك جانبيًا حتى يتم توسيط العلامة المتقاطعة على علامة معينة (سرعة التحرك الجانبي = result.getTx()*.03)؟

المفاهيم الأساسية​

1. التهيئة​

نحتاج إلى إعداد Limelight3A في كود الروبوت الخاص بنا.

import com.qualcomm.hardware.limelightvision.LLResult;
import com.qualcomm.hardware.limelightvision.LLResultTypes;
import com.qualcomm.hardware.limelightvision.LLStatus;
import com.qualcomm.hardware.limelightvision.Limelight3A;
Limelight3A limelight;

@Override
public void init() {
    limelight = hardwareMap.get(Limelight3A.class, "limelight");
    limelight.setPollRateHz(100); // هذا يحدد عدد مرات طلب البيانات من Limelight (100 مرة في الثانية)
    limelight.start(); // هذا يخبر Limelight بالبدء في النظر!
}

2. إدارة خطوط الأنابيب​

خطوط الأنابيب هي مثل برامج صغيرة قابلة للتبديل فوريًا تغير كيفية نظر Limelight إلى العالم. يمكنك إعداد 10 خطوط أنابيب مختلفة في واجهة Limelight الويب، كل منها لمهمة مختلفة. إليك كيفية التبديل بينها:

limelight.pipelineSwitch(0); // التبديل إلى خط الأنابيب رقم 0

هذا أمر "أطلق وانسَ". سيغير Limelight خط الأنابيب الخاص به في غضون مللي ثانية، ولكن الكود الخاص بك لن ينتظر هذا قبل الاستمرار. إذا كنت ترغب في التحقق من فهرس خط الأنابيب الحالي، قم باستدعاء

result.getPipelineIndex()

انظر القسم التالي لمعرفة المزيد عن الحصول على كائن LLResult.

3. الحصول على النتائج واستخدامها​

LLResult هو مثل حاوية مليئة بالمعلومات حول ما يراه Limelight. إليك كيفية الحصول على تلك المعلومات واستخدامها:

LLResult result = limelight.getLatestResult();
if (result != null && result.isValid()) {
    double tx = result.getTx(); // مدى بعد الهدف يسارًا أو يمينًا (بالدرجات)
    double ty = result.getTy(); // مدى ارتفاع أو انخفاض الهدف (بالدرجات)
    double ta = result.getTa(); // مدى كبر الهدف (0%-100% من الصورة)
    
    telemetry.addData("الهدف X", tx);
    telemetry.addData("الهدف Y", ty);
    telemetry.addData("مساحة الهدف", ta);
} else {
    telemetry.addData("Limelight", "لا توجد أهداف");
}

4. التحدث مع SnapScripts بايثون​

يمكنك كتابة خطوط أنابيب SnapScript بايثون الخاصة بك في واجهة الويب. استخدم مولد SnapScript المعتمد على LLM لمساعدتك في كتابة الكود الخاص بك.

إليك كيفية إرسال الأرقام من كود الروبوت إلى بايثون والحصول على الأرقام مرة أخرى:

// إرسال الأرقام إلى بايثون
double[] inputs = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0};
limelight.updatePythonInputs(inputs);

// الحصول على الأرقام من بايثون
double[] pythonOutputs = result.getPythonOutput();
if (pythonOutputs != null && pythonOutputs.length > 0) {
    double firstOutput = pythonOutputs[0];
    telemetry.addData("مخرجات بايثون:", firstOutput);
}

5. أين روبوتي؟ (MegaTag 1)​

يمكن لـ Limelight المساعدة في معرفة مكان روبوتك على الملعب باستخدام AprilTags. يأتي Limelight الخاص بك مع خريطة AprilTag مثبتة مسبقًا للعبة الحالية، ولكن يمكنك تصميم وتحميل خرائطك الخاصة باستخدام منشئ الخرائط ثلاثي الأبعاد الخاص بنا.

قبل محاولة الحصول على موقع روبوتك، قم بما يلي:

  1. قم بتمكين "Full 3D" في علامة التبويب "Advanced" لخط أنابيب AprilTag في واجهة الويب.
  2. استخدم واجهة الويب لتحديد موضع الكاميرا بالنسبة لمركز بصمة روبوتك.

يتطابق نظام الإحداثيات لـ botPose مع نظام إحداثيات FTC القياسي.

  • (0,0,0) هو مركز أرضية الملعب
  • بالنسبة للتكوينات غير الماسية، يعني 0 درجة انحراف أن التحالف الأزرق على الجانب الأيسر من روبوتك، والتحالف الأحمر على الجانب الأيمن من روبوتك.
if (result != null && result.isValid()) {
    Pose3D botpose = result.getBotpose();
    if (botpose != null) {
        double x = botpose.getX();
        double y = botpose.getY();
        telemetry.addData("موقع MT1", "(" + x + ", " + y + ")");
    }
}

6. أين روبوتي؟ (MegaTag 2)​

MegaTag 2 يشبه MegaTag 1، ولكنه يدمج بيانات IMU الخاصة بك لزيادة الدقة:

// أولاً، أخبر Limelight في أي اتجاه يواجه روبوتك
double robotYaw = imu.getAngularOrientation().firstAngle;
limelight.updateRobotOrientation(robotYaw);
if (result != null && result.isValid()) {
    Pose3D botpose_mt2 = result.getBotpose_MT2();
    if (botpose_mt2 != null) {
        double x = botpose_mt2.getX();
        double y = botpose_mt2.getY();
        telemetry.addData("موقع MT2:", "(" + x + ", " + y + ")");
    }
}

7. أنواع النتائج الداخلية​

اعتمادًا على كيفية تكوين خطوط الأنابيب الخاصة بك، سيكون لديك إمكانية الوصول إلى أنواع مختلفة من قوائم النتائج المفصلة داخل كائن LLResults الأصلي.

ربما لن تحتاج إلى استخدام قوائم النتائج هذه. نوصي باستخدام getTx() و getTy() الأساسيين كلما أمكن ذلك.

7.1 نتائج الألوان​

تساعد نتائج الألوان في العثور على الأهداف الملونة:

List<ColorResult> colorTargets = result.getColorResults();
for (ColorResult colorTarget : colorTargets) {
    double x = detection.getTargetXDegrees(); // أين هو (يسار-يمين)
    double y = detection.getTargetYDegrees(); // أين هو (أعلى-أسفل)
    double area = colorTarget.getTargetArea(); // الحجم (0-100)
    telemetry.addData("الهدف الملون", "يشغل " + area + "% من الصورة");
}

7.2 نتائج Fiducial/AprilTag​

Fiducials هي علامات خاصة (مثل AprilTags) تساعد Limelight في معرفة مكانه:

List<FiducialResult> fiducials = result.getFiducialResults();
for (FiducialResult fiducial : fiducials) {
    int id = fiducial.getFiducialId(); // رقم معرف الـ fiducial
    double x = detection.getTargetXDegrees(); // أين هو (يسار-يمين)
    double y = detection.getTargetYDegrees(); // أين هو (أعلى-أسفل)
    double StrafeDistance_3D = fiducial.getRobotPoseTargetSpace().getY(); 
    telemetry.addData("Fiducial " + id, "على بعد " + distance + " متر");
}

إذا كنت ترغب في استخدام معلومات الوضع ثلاثي الأبعاد داخل كل FiducialResult، يمكنك استخدام الطرق التالية:

fiducial.getRobotPoseTargetSpace(); // وضع الروبوت بالنسبة لنظام إحداثيات AprilTag (الأكثر فائدة)
fiducial.getCameraPoseTargetSpace(); // وضع الكاميرا بالنسبة لـ AprilTag (مفيد)
fiducial.getRobotPoseFieldSpace(); // وضع الروبوت في نظام إحداثيات الملعب بناءً على هذه العلامة وحدها (مفيد)
fiducial.getTargetPoseCameraSpace(); // وضع AprilTag في نظام إحداثيات الكاميرا (ليس مفيدًا جدًا)
fiducial.getTargetPoseRobotSpace(); // وضع AprilTag في نظام إحداثيات الروبوت (ليس مفيدًا جدًا)

7.3 نتائج الباركود​

خط أنابيب الباركود الخاص بـ Limelight جيد في اكتشاف وتتبع رموز QR.

List<BarcodeResult> barcodes = result.getBarcodeResults();
for (BarcodeResult barcode : barcodes) {
    String data = barcode.getData(); // ما يقوله الباركود
    String family = barcode.getFamily(); // نوع الباركود
    telemetry.addData("الباركود", data + " (" + family + ")");
}

7.4 نتائج المصنف​

تسمح المصنفات العصبية لـ Limelight بالقول "أعتقد أن هذه صورة لـ...".

List<ClassifierResult> classifications = result.getClassifierResults();
for (ClassifierResult classification : classifications) {
    String className = classification.getClassName(); // ما يعتقد Limelight أنه يراه
    double confidence = classification.getConfidence(); // درجة الثقة
    telemetry.addData("أرى", className + " (" + confidence + "%)");
}

7.5 نتائج الكاشف​

الكواشف تجد أشياء محددة وتخبرنا أين هي:

List<DetectorResult> detections = result.getDetectorResults();
for (DetectorResult detection : detections) {
    String className = detection.getClassName(); // ما تم اكتشافه
    double x = detection.getTargetXDegrees(); // أين هو (يسار-يمين)
    double y = detection.getTargetYDegrees(); // أين هو