التعليق التوضيحي للصور

هيّئ التعليق التوضيحي للصور في Potato باستخدام المربعات المحيطة والمضلعات والأقنعة والمعالم. اعرض الصور باستخدام instance_display وصدّرها إلى COCO أو YOLO.

يدعم Potato التعليق التوضيحي للصور لمهام التصنيف واكتشاف الكائنات والتجزئة والنقاط المفتاحية.

عرض صورة

عرض الصورة وجمع التعليق التوضيحي إعدادان منفصلان. يحدد instance_display ما يراه المُعلّق، ويحدد annotation_schemes ما يجيب عنه. والفصل بينهما يتيح وضع أي نوع من المحتوى إلى جانب أي نوع من الأسئلة:

yaml

instance_display:
  fields:
    - key: image_url          # Field name in your data file
      type: image
      label: "Image to classify"
      display_options:
        max_width: 600
        zoomable: true

المخطط image_annotation مخصص للرسم على الصورة، لا لعرضها. ومهمة التصنيف لا تحتاج إلا إلى حقل العرض أعلاه مع مخطط radio أو multiselect.

خيارات العرض

الخيار	الوصف
`max_width`	أقصى عرض معروض بالبكسل
`max_height`	أقصى ارتفاع معروض بالبكسل
`zoomable`	تفعيل التكبير بالنقر
`object_fit`	طريقة ملء الصورة لإطارها
`alt_text`	نص بديل لقارئات الشاشة

اسم الخيار الذي لا يتعرف عليه Potato يُعد خطأً في الإعداد، لا مفتاحاً يُتجاهل بصمت، وتقترح رسالة الخطأ أقرب خيار حقيقي.

تنسيق البيانات

أشر إلى الصور في ملف البيانات:

json

{"id": "img_001", "image_url": "https://example.com/photo_001.jpg"}
{"id": "img_002", "image_url": "/static/images/photo_002.png"}

data_files قائمة من المسارات، ويربط item_properties أسماء حقولك بالأسماء التي يقرؤها Potato:

yaml

data_files:
  - "data/image_tasks.json"
 
item_properties:
  id_key: id
  text_key: image_url   # The field holding the image URL

تصنيف الصور

تصنيف الصور بالكامل:

yaml

annotation_schemes:
  - annotation_type: radio
    name: category
    description: "What is shown in this image?"
    labels:
      - Cat
      - Dog
      - Bird
      - Other
 
  - annotation_type: multiselect
    name: attributes
    description: "Select all that apply"
    labels:
      - Indoor
      - Outdoor
      - Multiple animals
      - Human present

التصنيف متعدد التسميات

yaml

annotation_schemes:
  - annotation_type: multiselect
    name: objects
    description: "What objects are visible?"
    labels:
      - Person
      - Car
      - Building
      - Tree
      - Animal
      - Furniture
      - Food
      - Electronic device

تقييم جودة الصور

yaml

annotation_schemes:
  - annotation_type: likert
    name: quality
    description: "Overall image quality"
    size: 5
    min_label: "Very poor"
    max_label: "Excellent"
 
  - annotation_type: multiselect
    name: issues
    description: "Select any quality issues"
    labels:
      - Blurry
      - Overexposed
      - Underexposed
      - Noisy
      - Low resolution
      - Watermark visible

الرسم على الصور

يتطلب المخطط image_annotation كلاً من tools وlabels. ويستحق إعطاء كل تسمية لوناً وkey_value الأسطر الإضافية، لأن المُعلّقين يعيّنون التسميات بلوحة المفاتيح أسرع بكثير من النقر:

yaml

annotation_schemes:
  - annotation_type: image_annotation
    name: object_detection
    description: "Draw boxes around objects"
    tools:
      - bbox
      - polygon
    labels:
      - name: person
        color: "#FF6B6B"
        key_value: "1"
      - name: vehicle
        color: "#4ECDC4"
        key_value: "2"
      - name: animal
        color: "#45B7D1"
        key_value: "3"
    min_annotations: 1
    zoom_enabled: true
    pan_enabled: true

يجب أن تكون قيمة color بالنظام الست عشري (#rgb أو #rrggbb أو #rrggbbaa). أسماء ألوان CSS وrgb() لا تُقرأ. ستبدو الأشكال صحيحة، لكن الأقنعة تُرسم بكسلاً بكسلاً فتعود إلى اللون الأحمر.

الأدوات المتاحة

الأداة	الوصف
`bbox`	مربعات محيطة مستطيلة
`polygon`	مضلعات مغلقة متعددة النقاط
`polyline`	مسارات مفتوحة متعددة النقاط، لعلامات الحارات والأوعية والشقوق والسواحل
`ellipse`	أشكال بيضاوية ودوائر، للخلايا والأنوية والعجلات والوجوه
`keypoint_set`	هياكل عظمية مرتبة، لوضعيات البشر أو الحيوانات ومعالم الوجه
`cuboid_2d`	صناديق ثلاثية الأبعاد مُسقطة على الصورة، على طريقة KITTI
`sam`	العصا السحرية: انقر على كائن فيجزّئه نموذج
`freeform`	رسم حر باليد
`landmark`	علامات نقطة واحدة
`brush`	فرشاة تجزئة للأقنعة على مستوى البكسل
`eraser`	إزالة مناطق من القناع
`fill`	تعبئة المناطق المغلقة

المضلع مغلق ويحيط بمساحة، أما الخط المتعدد فمفتوح وله طول بلا داخل. ويهم هذا الفرق عند التصدير، إذ يُكتب الخط المتعدد مع area: 0 ولا يُعامل أبداً كمنطقة.

التعليق التوضيحي بالمضلعات

للمناطق غير المستطيلة:

yaml

annotation_schemes:
  - annotation_type: image_annotation
    name: regions
    description: "Outline regions of interest"
    tools:
      - polygon
    labels:
      - name: Building
      - name: Road
      - name: Vegetation
      - name: Water

أقنعة التجزئة

للعمل على مستوى البكسل، فعّل أدوات الطلاء. تُخزَّن الأقنعة بترميز طول التشغيل (run-length) بدلاً من مصفوفات لكل بكسل، وهذا ما يُبقي قناع الصورة الكاملة صغيراً:

yaml

annotation_schemes:
  - annotation_type: image_annotation
    name: segmentation
    description: "Paint regions using the brush tool"
    tools:
      - brush
      - eraser
      - fill
    labels:
      - name: road
        color: "#45B7D1"
      - name: sidewalk
        color: "#96CEB4"
    brush_size: 20
    mask_opacity: 0.5
    mask_mode: semantic

يدمج mask_mode: semantic كل ضربات الفئة الواحدة في منطقة واحدة. استخدم instance عندما يجب أن يبقى كائنان من الفئة نفسها منفصلين.

تنسيق المخرجات

تُخزَّن التعليقات التوضيحية كمصفوفة JSON مسطحة، وكل الأشكال والأقنعة في القائمة نفسها. تُطبَّع الإحداثيات إلى المدى من 0 إلى 1 بالنسبة إلى الصورة، فتبقى التعليقات التوضيحية صحيحة عندما تُقدَّم الصورة بحجم مختلف:

json

[
  {
    "type": "bbox",
    "label": "person",
    "color": "#FF6B6B",
    "coordinates": {"x": 0.125, "y": 0.104, "width": 0.3125, "height": 0.625}
  },
  {
    "type": "polygon",
    "label": "vehicle",
    "color": "#4ECDC4",
    "coordinates": [
      {"x": 0.02, "y": 0.04}, {"x": 0.20, "y": 0.04},
      {"x": 0.20, "y": 0.21}, {"x": 0.02, "y": 0.21}
    ]
  },
  {
    "type": "mask",
    "label": "road",
    "color": "#45B7D1",
    "rle": {"counts": [12, 40, 8], "size": [480, 640]}
  }
]

يختلف مفتاح الشكل الهندسي حسب النوع:

النوع	مفتاح الشكل الهندسي	البنية
`bbox`	`coordinates`	`{x, y, width, height}`، مُطبَّعة
`polygon`	`coordinates`	قائمة من `{x, y}`، مُطبَّعة
`landmark`	`coordinates`	`{x, y}`، مُطبَّعة
`freeform`	`coordinates`	`{path, left, top, scaleX, scaleY}`
`mask`	`rle`	`{counts: [ints], size: [height, width]}`

rle.size هو [height, width] بهذا الترتيب. للتحويل من هذه البنى وإليها في Python، استخدم normalize_annotation_object() وto_client_object() من potato.export.cv_utils بدلاً من قراءة الحقول مباشرة.

مصدر الشكل

بعد التخزين، لا يختلف اكتشاف مقبول من نموذج عن مربع مرسوم باليد في شيء، لذلك يسجّل كل شكل مصدره. ومن دون ذلك لا يستطيع مشروع يستخدم نموذجاً للتسمية المسبقة أن يحسب معدل القبول لديه من بياناته:

json

{
  "type": "bbox",
  "label": "person",
  "coordinates": {"x": 0.125, "y": 0.104, "width": 0.3125, "height": 0.625},
  "source": "ai",
  "ai_model": "yolov8n",
  "confidence": 0.82,
  "edited": true
}

المفتاح	المعنى
`source`	`human` (رُسم في المتصفح)، `ai` (اقترحه نموذج وقبله المُعلّق)، `import` (وصل مع البيانات)
`ai_model`	أي نموذج، عندما تُبلغ عنه نقطة النهاية
`confidence`	درجة الكاشف نفسه لهذا الشكل
`edited`	حرّك المُعلّق لاحقاً شكلاً لم يرسمه، أو غيّر حجمه أو تسميته
`carried_over`	منسوخ من الصورة السابقة وليس مصنوعاً على هذه الصورة

edited هو ما يميّز قبول المربع كما هو عن قبوله ثم تصحيحه. والحالة الأولى وحدها هي اتفاق مع النموذج.

مراجعة التعليقات التوضيحية الموجودة

لمراجعة أشكال موجودة بالفعل، استوردها بدلاً من إضافتها إلى حقل في البيانات. يحوّل potato import ملف COCO إلى مشروع قابل للتشغيل، ويضع على كل شكل source: import:

bash

potato import --input instances_val2017.json \
    --image-dir /data/val2017 \
    --image-url-prefix /files \
    --output-dir my-project/ \
    --schema-name object_detection
 
potato start my-project/config.yaml -p 8000

بعد ذلك يصحح المُعلّقون الأشكال المستوردة في مكانها، ويحتفظ التصدير بالتمييز بين ما صنعه الإنسان وما صنعه النموذج طوال الدورة كاملة.

مقارنة الصور

قارن بين صورتين باستخدام المخطط pairwise. يحدد items_key حقل البيانات الذي يحمل الزوج:

yaml

annotation_schemes:
  - annotation_type: pairwise
    name: preference
    description: "Which image looks better?"
    mode: binary
    items_key: images
    show_labels: true
    labels:
      - "Original"
      - "Edited"
    allow_tie: true
    tie_label: "About the same"

كتابة وصف الصور

yaml

annotation_schemes:
  - annotation_type: text
    name: caption
    description: "Write a caption for this image"
    rows: 4
    placeholder: "Describe what you see..."

مراجعة جودة الوصف

اعرض الصورة والوصف المُولَّد جنباً إلى جنب، ثم قيّم الوصف:

yaml

instance_display:
  fields:
    - key: image_url
      type: image
      label: "Image"
    - key: generated_caption
      type: text
      label: "Generated caption"
 
annotation_schemes:
  - annotation_type: likert
    name: accuracy
    description: "How accurate is this caption?"
    size: 5
    min_label: "Very inaccurate"
    max_label: "Very accurate"
 
  - annotation_type: likert
    name: fluency
    description: "How natural is the language?"
    size: 5
    min_label: "Very awkward"
    max_label: "Very natural"
 
  - annotation_type: text
    name: improved_caption
    description: "Suggest a better caption (optional)"
    rows: 4
    label_requirement:
      required: false

إدارة المحتوى

yaml

annotation_schemes:
  - annotation_type: radio
    name: safe_for_work
    description: "Is this image safe for work?"
    labels:
      - Safe
      - Questionable
      - Not Safe
 
  - annotation_type: multiselect
    name: violation_types
    description: "Select all violations (if any)"
    labels:
      - Violence
      - Adult content
      - Hate symbols
      - Graphic content
      - Spam/advertisement

تنسيقات التبادل

يقرأ Potato تنسيق COCO JSON، بما في ذلك كل ترميزات التجزئة ومناطق الحشود (crowd)، ويكتب COCO وYOLO وPascal VOC وملفات PNG للأقنعة لكل تسمية:

bash

python -m potato.export -c my-project/config.yaml -f coco -o ./export/

لا يحمل YOLO وPascal VOC إلا المربعات المحيطة، لذلك تُختزل الأشكال الأخرى إلى المربع المحيط بها.

مثال كامل: مراجعة اكتشاف الكائنات

yaml

annotation_task_name: "Object Detection Verification"
task_dir: "."
 
data_files:
  - "data/detections.json"
 
item_properties:
  id_key: id
  text_key: image_url
 
instance_display:
  fields:
    - key: image_url
      type: image
      label: "Image"
      display_options:
        max_width: 1000
        zoomable: true
 
annotation_schemes:
  # Correct the boxes
  - annotation_type: image_annotation
    name: objects
    description: "Verify and correct object boxes"
    tools:
      - bbox
    labels:
      - name: Person
        key_value: "1"
      - name: Vehicle
        key_value: "2"
      - name: Animal
        key_value: "3"
      - name: Object
        key_value: "4"
    zoom_enabled: true
    pan_enabled: true
 
  # Overall assessment
  - annotation_type: radio
    name: prediction_quality
    description: "How accurate were the predictions?"
    labels:
      - All correct
      - Minor corrections needed
      - Major corrections needed
      - Mostly incorrect
 
  - annotation_type: number
    name: missed_objects
    description: "How many objects were missed?"
    min: 0
    max: 50
 
  - annotation_type: text
    name: notes
    description: "Any issues or comments?"
    rows: 4
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
export_annotation_format: jsonl
 
user_config:
  allow_all_users: true

شغّل الخادم:

bash

potato start config.yaml -p 8000

نصائح الأداء

غيّر حجم الصور قبل التعليق التوضيحي: الصور المصدرية الكبيرة تبطئ التحميل دون أن تحسّن التعليق التوضيحي
استخدم JPEG للصور الفوتوغرافية: ملفات أصغر وتحميل أسرع
استخدم PNG للرسومات: جودة أفضل للمخططات ولقطات الشاشة
حدّد الحجم المعروض: اضبط max_width كي لا يضطر المتصفح إلى تحجيم صورة ضخمة في كل عنصر
عالج البيانات مسبقاً بشكل متسق: وحّد الأحجام والتنسيقات في مجموعة البيانات كلها