影像標註

在 Potato 中用邊界框、多邊形、自由繪製、標記點和塗繪分割掩碼標註影像，支援縮放、平移和工具快捷鍵。

Potato 的影像標註系統支援多種標註方法，適用於計算機視覺任務，包括目標檢測、分割和關鍵點標註。

支援的工具

方案在 tools 中列出它需要的工具，工具欄裡只會出現這些工具。少啟用一些工具，是阻止標註者為該任務畫出錯誤幾何形狀的最省事的辦法。

工具	描述	使用場景
`bbox`	邊界框	目標檢測
`polygon`	多邊形	實例分割
`polyline`	折線（開放路徑）	車道、邊界、開放輪廓
`ellipse`	橢圓	圓形和橢圓形物體
`freeform`	自由繪製	不規則形狀
`landmark`	標記點	關鍵點檢測
`keypoint_set`	骨架／關鍵點集	姿態與骨架標註
`cuboid_2d`	投影 3D 立方體	帶投影深度面的框
`fill`	漫水填充	分割掩碼
`eraser`	橡皮擦	分割掩碼修正
`brush`	分割畫筆	精細分割
`sam`	互動式分割	模型輔助掩碼

sam 工具需要下載模型。無論模型是否就位，它的按鈕都會渲染出來並說明缺少什麼，而不是悄悄失敗。

基本配置

tools 和 labels 都是必填項，缺少任何一個 Potato 都會拒絕載入該方案。檢測任務不需要別的配置，因為縮放和平移預設開啟：

yaml

annotation_schemes:
  - name: "objects"
    description: "Draw boxes around all objects"
    annotation_type: "image_annotation"
    tools:
      - bbox
    labels:
      - person
      - car
      - bicycle

配置選項

欄位	類型	預設值	描述
`name`	string	必填	標註的唯一識別符號
`description`	string	必填	顯示給標註者的說明
`annotation_type`	string	必填	必須為 `"image_annotation"`
`tools`	list	必填	啟用的標註工具（見上表）
`labels`	list	必填	標註的類別標籤
`zoom_enabled`	boolean	true	啟用縮放控制
`pan_enabled`	boolean	true	啟用拖動導航
`min_annotations`	integer	0	最少所需標註數
`max_annotations`	integer	null	最大允許標註數（null = 無限制）
`freeform_brush_size`	integer	5	自由繪製工具的筆畫寬度
`freeform_simplify`	boolean	true	簡化自由繪製路徑
`brush_size`	integer	20	塗繪掩碼時的初始畫筆寬度
`eraser_size`	integer	20	初始橡皮擦寬度
`mask_opacity`	float	0.5	塗繪掩碼覆蓋在影像上的不透明度
`fill_tolerance`	integer	32	漫水填充視為同一區域的顏色距離
`keybinding_profile`	string	`"v7"`	工具快捷鍵配置：`"v7"` 或 `"legacy"`
`carry_over`	boolean or string	false	複製上一張影像的標註：`"prompt"` 或 `"auto"`
`source_field`	string	`""`	當條目顯示多張影像時，本方案標註的顯示欄位

標籤配置

標籤可以是簡單字串，也可以是詳細物件。Potato 會自動分配顏色，所以當顏色需要對標註者有含義，或者標籤需要按鍵時，寫詳細形式才值得。

簡單標籤按列表順序取調色盤顏色：

yaml

labels:
  - person
  - car
  - tree

詳細形式為每個標籤指定顏色和按鍵：

yaml

labels:
  - name: "person"
    color: "#FF6B6B"
    key_value: "1"
  - name: "car"
    color: "#4ECDC4"
    key_value: "2"
  - name: "bicycle"
    color: "#45B7D1"
    key_value: "3"

key_value 用數字比較穩妥，因為預設的工具快捷鍵是字母，而複用了某個工具按鍵的標籤會在一次按鍵中觸發兩個動作。

示例

目標檢測（邊界框）

設定 min_annotations: 1 會阻止提交沒有畫框的影像，它攔住的是沒看就翻頁的標註者，而不是確實沒有目標的影像。只在每張影像都至少有一個實例的資料上使用它：

yaml

annotation_schemes:
  - name: "detection"
    description: "Draw bounding boxes around all vehicles"
    annotation_type: "image_annotation"
    tools:
      - bbox
    labels:
      - name: "car"
        color: "#3B82F6"
        key_value: "1"
      - name: "truck"
        color: "#10B981"
        key_value: "2"
      - name: "motorcycle"
        color: "#F59E0B"
        key_value: "3"
    min_annotations: 1
    zoom_enabled: true

實例分割（多邊形）

多邊形工作要在高倍放大下進行，所以縮放和平移決定了邊界的精度：

yaml

annotation_schemes:
  - name: "segmentation"
    description: "Draw polygons around each object"
    annotation_type: "image_annotation"
    tools:
      - polygon
    labels:
      - name: "building"
        color: "#8B5CF6"
      - name: "road"
        color: "#64748B"
      - name: "vegetation"
        color: "#22C55E"
    zoom_enabled: true
    pan_enabled: true

關鍵點標註（標記點）

每個標記點都是獨立的標籤，輸出中能區分這些點靠的就是這一點。給成對的點相同的顏色，這樣左右顛倒在畫布上就能看出來：

yaml

annotation_schemes:
  - name: "facial_landmarks"
    description: "Mark facial keypoints"
    annotation_type: "image_annotation"
    tools:
      - landmark
    labels:
      - name: "left_eye"
        color: "#3B82F6"
      - name: "right_eye"
        color: "#3B82F6"
      - name: "nose"
        color: "#10B981"
      - name: "left_mouth"
        color: "#F59E0B"
      - name: "right_mouth"
        color: "#F59E0B"

多工具

當一張影像需要不止一種幾何形狀時，一個方案可以啟用多個工具：

yaml

annotation_schemes:
  - name: "mixed_annotation"
    description: "Use boxes for objects and polygons for regions"
    annotation_type: "image_annotation"
    tools:
      - bbox
      - polygon
    labels:
      - name: "object"
        color: "#3B82F6"
      - name: "region"
        color: "#10B981"

鍵盤快捷鍵

工具按鍵來自 keybinding_profile 指定的配置。預設的 v7 配置沿用 V7 Darwin 和 CVAT 的習慣，從這兩者轉過來的標註者可以保留肌肉記憶；legacy 保留 Potato 早先使用的繫結。只有啟用的工具才會分到按鍵。

工具	`v7`（預設）	`legacy`
`brush`	`b`	`m`
`eraser`	`e`	`e`
`fill`	`f`	`g`
`bbox`	`r`	`b`
`polygon`	`p`	`p`
`landmark`	`k`	`l`
`freeform`	`d`	`f`
`polyline`	`n`	`n`
`ellipse`	`i`	`i`
`keypoint_set`	`s`	`s`
`cuboid_2d`	`c`	`c`
`sam`	`w`	`w`

其餘快捷鍵在兩種配置中相同：

按鍵	操作
`v`	選擇／移動模式
`h`	隱藏／顯示當前標籤
`Shift+H`	只顯示當前標籤
`Del`	刪除選中項
`+` / `-`	放大／縮小
`0`	適應檢視
`[` / `]`	減小／增大畫筆大小（需啟用 `brush` 或 `eraser`）
`Ctrl+D`	從上一張影像複製標註（需設定 `carry_over`）

每個帶 key_value 的標籤會再增加一個自己的按鍵。

資料格式

輸入資料

資料檔案應包含影像路徑或 URL：

json

[
  {
    "id": "img_001",
    "image_url": "https://example.com/images/photo1.jpg"
  },
  {
    "id": "img_002",
    "image_url": "/data/images/photo2.png"
  }
]

把 text_key 指向儲存影像路徑的欄位，因為 Potato 交給標註控制元件的就是這個欄位：

yaml

item_properties:
  id_key: id
  text_key: image_url

輸出格式

繪製出的區域放在匯出記錄裡自己的 image_annotations 鍵中，按方案名分組，而不是放在 labels 裡面。瀏覽器為每種工具寫出一個形狀：一個 type、label、它的 color，以及 coordinates 下的幾何資料，座標相對影像歸一化而不是畫素值。掩碼是例外，它攜帶的是 rle：

json

{
  "instance_id": "img_001",
  "user_id": "annotator1",
  "labels": {},
  "spans": {},
  "links": {},
  "image_annotations": {
    "objects": [
      {
        "type": "bbox",
        "label": "car",
        "color": "#FF6B6B",
        "coordinates": {"x": 0.12, "y": 0.30, "width": 0.25, "height": 0.20}
      },
      {
        "type": "polygon",
        "label": "building",
        "color": "#4ECDC4",
        "coordinates": [{"x": 0.06, "y": 0.10}, {"x": 0.19, "y": 0.10}, {"x": 0.19, "y": 0.40}]
      }
    ]
  }
}

匯出器不會直接讀取這個結構。normalize_annotation_object 先把每個物件轉換成絕對畫素——{type, label, color, bbox, points, rle, area, instance, iscrowd, warnings}，其中 bbox 即使對多邊形也始終存在——視覺格式在此基礎上構建。兩種結構是按結構區分的，即是否存在 coordinates 鍵，而不是按數值大小：原點處 1×1 畫素的框在兩種座標空間裡都是 [0, 0, 1, 1]。

jsonl 匯出不攜帶這個鍵：它只寫出 instance_id、user_id、 labels、spans 和 links。要把幾何資料匯出來，請使用某種視覺格式—— coco、yolo、pascal_voc、mask_png、cvat、labelme—— 它們會直接讀取 image_annotations。

支援的影像格式

JPEG / JPG
PNG
GIF
WebP

分割掩碼

v2.2.0 新增

fill、eraser 和 brush 工具為多邊形邊界過於粗糙的任務生成畫素級掩碼。這三個工具要一起啟用，因為只有畫筆而沒有橡皮擦，標註者就無法修正塗過界的地方：

yaml

annotation_schemes:
  - name: "mask_painting"
    description: "Paint segmentation masks"
    annotation_type: "image_annotation"
    tools:
      - fill
      - eraser
      - brush
    labels:
      - name: "foreground"
        color: "#3B82F6"
      - name: "background"
        color: "#6B7280"
    brush_size: 10
    eraser_size: 10
    mask_opacity: 0.5

在預設的 v7 配置下，這三個工具分別是畫筆 b、橡皮擦 e、填充 f，而 [ 和 ] 可以不離開畫布就改變畫筆大小。當標註者需要透過塗繪區域看到影像時，調低 mask_opacity。

PDF/文件邊界框

v2.2.0 新增

在 PDF 頁面和文件影像上繪製邊界框。與 instance_display 中的 pdf 顯示類型結合使用時，標註者可以在 PDF 文件的各個頁面上繪製框：

yaml

instance_display:
  fields:
    - key: pdf_url
      type: pdf
 
annotation_schemes:
  - name: "document_regions"
    description: "Draw boxes around figures and tables"
    annotation_type: "image_annotation"
    tools:
      - bbox
    labels:
      - name: "figure"
        color: "#3B82F6"
      - name: "table"
        color: "#10B981"
      - name: "equation"
        color: "#F59E0B"

最佳實踐

使用合適的工具 - 快速檢測用邊界框，精確邊界用多邊形，分割用填充/畫筆
定義清晰的標籤 - 使用獨特、不重疊的類別
設定標註限制 - 使用 min_annotations 確保完整性
啟用縮放 - 高解析度影像上的精細工作依賴於它
給標籤配鍵盤快捷鍵 - 不用離開畫布就能選標籤的標註者幹活更快
提供標籤顏色 - 使視覺區分標註更容易