图像标注

在 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

画布会用 CORS 方式请求每张图像，以便读取图像的像素。许多公共主机（cocodataset.org 就是其中之一）不发送 Access-Control-Allow-Origin 头，会拒绝这种请求；从 Potato 2.11 起，画布遇到这种情况会不经 CORS 再加载一次图像。以这种方式加载的图像上，矩形框、多边形、椭圆、点、自由笔画和画笔都能正常使用。需要读取图像像素的工具无法在这类图像上运行：区域填充会说明它读不了这张图像，并且什么也不填；SAM 和文本提示分割会说明该主机没有发送 CORS 头。要使用这些工具，请把图像复制到任务的 media_directory 中，并以 /media/<file> 的形式引用。

输出格式

绘制出的区域放在导出记录里自己的 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 确保完整性
启用缩放 - 高分辨率图像上的精细工作依赖于它
给标签配键盘快捷键 - 不用离开画布就能选标签的标注者干活更快
提供标签颜色 - 使视觉区分标注更容易