> This page is for 平台, version 旧版.
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 实验版: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - 旧版: https://next.developer.frame.io/platform/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.

# 使用批注

# 概述

Frame.io 中的批注以序列化的 JSON blob 形式表示，其中包含绘图对象，以及颜色、坐标和大小。在 blob 中，除最外层的边界引号对之外，所有内部引号都用正斜杠进行转义（例如 `\"key\":\"value\"`）。有三种基本形状：**箭头**、**矩形**和**线条**——以及手绘图形，手绘图形不在本指南的讨论范围之内，但它遵循相同的序列化坐标数据基本原理。

## 坐标系




所有形状都放置在一个笛卡尔坐标系上，该坐标系的原点位于左上角，每个轴的刻度范围均为 0 到 1。

<img alt="coordinate_plane.png" src="/_fern-img/099478340a4f8604fd4389c5d431ec9e9321f509f2d6055b0c92dd62e4e36147.webp" />

## 基本形状数据




所有形状都通过坐标和样式数据的组合放置在上述平面上。每种形状都有一些共同的属性，而每种形状在引用坐标系的方式上又略有不同。





所有表示距离/宽度/高度的属性都使用与主坐标网格相同的 0 到 1 比例尺，但通常是从形状的起始点开始标记的。

换句话说，如果一个视频在 640x480 视口中显示，那么在该上下文中，`x=1` 将等于绝对的 640 像素。这使得批注能够无缝缩放，同时在观看屏幕、大小和上下文发生变化时保持其相对位置不变。**注意**：*矩形* 的原点始终是该形状的左上角，无论绘制时的起点在哪里。

### 共同属性




| 属性 | 描述 |
| ---------- | ---------- |
| `tool` | *箭头*、*矩形* 或 *线条*。指明正在创建的是哪种形状。 |
| `color` | 该形状的六位十六进制颜色代码。 |
| `size` | 形状线条的像素大小。对于箭头，这仅指线条起点的粗细，因为终点的宽度是由程序决定的。 |




### 箭头




| 属性 | 描述 |
|:--------|:----------|
| `x` | 箭头起点的 x 坐标。 |
| `y` | 箭头起点的 y 坐标。 |
| `w` | 箭头从起点到终点在 y 轴位置上的差值，相对于箭头的起点而言。 |
| `h` | 箭头从起点到终点在 x 轴位置上的差值，相对于箭头的起点而言。 |




### 矩形




| 属性 | 描述 |
|:--------|:----------|
| `x` | 矩形左上角的 x 坐标。 |
| `y` | 矩形左上角的 y 坐标。 |
| `w` | 矩形的宽度，相对于矩形的左上角原点。 |
| `h` | 矩形的高度，相对于矩形的左上角原点。 |
| `ix` | 矩形绘制时的 x 原点。（非必需）。 |
| `iy` | 矩形绘制时的 y 原点。（非必需）。 |
| `radius` | 矩形圆角的半径。必须为正值。数值超过 150 时在视觉上难以区分。 |




### 线条




| 属性 | 描述 |
|:--------|:----------|
| `x1` | 线条起点的 x 坐标。 |
| `y1` | 线条起点的 y 坐标。 |
| `x2` | 线条终点的 x 坐标。在图像平面上的绝对值。 |
| `y2` | 线条终点的 y 坐标。在图像平面上的绝对值。 |




## 简单示例：坐标平面

<img alt="plane-example.png" src="/_fern-img/99384da1b5af9a10636927f13840b9554fa518600b181af4f71f094dab50861c.webp" />

```serialized
{"annotation": "[{\"tool\":\"line\",\"color\":\"#E74A3C\",\"size\":3,\"x1\":0.0028530670470756064,\"y1\":0.012680297987002695,\"x2\":0.9964336661911555,\"y2\":0.9903312727849104},{\"tool\":\"line\",\"color\":\"#34A3DB\",\"size\":3,\"x1\":0.004992867332382311,\"y1\":0.98779521318751,\"x2\":0.9942938659058488,\"y2\":0.012680297987002695}]}
```





```json
{
    "annotation": [
        {
            "tool": "line",
            "color": "#E74A3C",
            "size": 3,
            "x1": 0.0028530670470756064,
            "y1": 0.012680297987002695,
            "x2": 0.9964336661911555,
            "y2": 0.9903312727849104
        },
        {
            "tool": "line",
            "color": "#34A3DB",
            "size": 3,
            "x1": 0.004992867332382311,
            "y1": 0.98779521318751,
            "x2": 0.9942938659058488,
            "y2": 0.012680297987002695
        }
    ]
}
```





### 分解说明

<img alt="blue-plane.png" src="/_fern-img/ced74a7487e5331393af727a794384e9e3294d7f048fda4c64e73b4ba32b4445.webp" />

```json
{
   "tool":"line",
   "color":"#34A3DB",
   "size":3,
   "x1":0.004992867332382311,
   "y1":0.98779521318751,
   "x2":0.9942938659058488,
   "y2":0.012680297987002695
}
```

<img alt="plane-example-red.png" src="/_fern-img/35bbbbcbe89e4262ec4e0fedf5e13d48baeceb10421fe48bcb854eb216a28676.webp" />

```json
{
   "tool":"line",
   "color":"#E74A3C",
   "size":3,
   "x1":0.0028530670470756064,
   "y1":0.012680297987002695,
   "x2":0.9964336661911555,
   "y2":0.9903312727849104
}
```





## 复杂示例：多个方框

<img alt="lots-of-boxes.png" src="/_fern-img/9241b75e4785251c5c42b5b11306370df8d0510932e1537e20dbcde58977fea3.webp" />

```serialized
{"annotation": "[{\"tool\":\"rect\",\"color\":\"#34A3DB\",\"size\":3,\"x\":0.008426966292134831,\"y\":0.02663337494798169,\"w\":0.0702247191011236,\"h\":0.10986267166042447,\"ix\":0.008426966292134831,\"iy\":0.02663337494798169,\"radius\":8},{\"tool\":\"rect\",\"color\":\"#1ABCA1\",\"size\":3,\"x\":0.8932584269662921,\"y\":0.0449438202247191,\"w\":0.08895131086142327,\"h\":0.35122763212650854,\"ix\":0.8932584269662921,\"iy\":0.0449438202247191,\"radius\":8},{\"tool\":\"rect\",\"color\":\"#E67422\",\"size\":3,\"x\":0.023408239700374533,\"y\":0.7873491468997087,\"w\":0.1254681647940075,\"h\":0.2047440699126093,\"ix\":0.023408239700374533,\"iy\":0.7873491468997087,\"radius\":8},{\"tool\":\"rect\",\"color\":\"#E74A3C\",\"size\":3,\"x\":0.6919475655430711,\"y\":0.5409904286308781,\"w\":0.29868913857677903,\"h\":0.4427798585101955,\"ix\":0.6919475655430711,\"iy\":0.5409904286308781,\"radius\":8},{\"tool\":\"arrow\",\"color\":\"#E74A3C\",\"size\":3,\"x\":0.25374531835205993,\"y\":0.23137744486059092,\"w\":0.24250936329588013,\"h\":0}]}"
```





```json
{
    "annotation": [
        {
            "tool": "rect",
            "color": "#34A3DB",
            "size": 3,
            "x": 0.008426966292134831,
            "y": 0.02663337494798169,
            "w": 0.0702247191011236,
            "h": 0.10986267166042447,
            "ix": 0.008426966292134831,
            "iy": 0.02663337494798169,
            "radius": 8
        },
        {
            "tool": "rect",
            "color": "#1ABCA1",
            "size": 3,
            "x": 0.8932584269662921,
            "y": 0.0449438202247191,
            "w": 0.08895131086142327,
            "h": 0.35122763212650854,
            "ix": 0.8932584269662921,
            "iy": 0.0449438202247191,
            "radius": 8
        },
        {
            "tool": "rect",
            "color": "#E67422",
            "size": 3,
            "x": 0.023408239700374533,
            "y": 0.7873491468997087,
            "w": 0.1254681647940075,
            "h": 0.2047440699126093,
            "ix": 0.023408239700374533,
            "iy": 0.7873491468997087,
            "radius": 8
        },
        {
            "tool": "rect",
            "color": "#E74A3C",
            "size": 3,
            "x": 0.6919475655430711,
            "y": 0.5409904286308781,
            "w": 0.29868913857677903,
            "h": 0.4427798585101955,
            "ix": 0.6919475655430711,
            "iy": 0.5409904286308781,
            "radius": 8
        },
        {
            "tool": "arrow",
            "color": "#E74A3C",
            "size": 3,
            "x": 0.25374531835205993,
            "y": 0.23137744486059092,
            "w": 0.24250936329588013,
            "h": 0
        }
    ]
}
```





### 分解说明

了解以上所有内容之后，将上图中的每个元素逐一列出，有助于更清晰地理解标注坐标系。请注意，此示例中每个矩形的 `size` 和 `radius` 都采用了 Frame.io UI 默认值。

#### 蓝色矩形

<img alt="blue-box.png" src="/_fern-img/ccc803531559e559395c2811d2be436316bbce6249c89b4af0b366efcf6b4d27.webp" />

```json
{
   "tool":"rect",
   "color":"#34A3DB",
   "size":3,
   "x":0.008426966292134831,
   "y":0.02663337494798169,
   "w":0.0702247191011236,
   "h":0.10986267166042447,
   "ix":0.008426966292134831,
   "iy":0.02663337494798169,
   "radius":8
}
```





#### 绿色矩形

<img alt="box-green.png" src="/_fern-img/4ce987f7843bf36e865fe0ceb6ae0ebbfa383cf719018754070a489fb3e3f17a.webp" />

```json
{
   "tool":"rect",
   "color":"#1ABCA1",
   "size":3,
   "x":0.8932584269662921,
   "y":0.0449438202247191,
   "w":0.08895131086142327,
   "h":0.35122763212650854,
   "ix":0.8932584269662921,
   "iy":0.0449438202247191,
   "radius":8
}
```





#### 红色矩形

<img alt="red-box.png" src="/_fern-img/61638bc1073613b5456b11ac4ce287447c3aaade152c0e6faf7699d995b11b31.webp" />

```json
{
   "tool":"rect",
   "color":"#E74A3C",
   "size":3,
   "x":0.6919475655430711,
   "y":0.5409904286308781,
   "w":0.29868913857677903,
   "h":0.4427798585101955,
   "ix":0.6919475655430711,
   "iy":0.5409904286308781,
   "radius":8
}
```





#### 橙色矩形

<img alt="orange-box.png" src="/_fern-img/b7a8f7c7feb18d0439ef14f7fe71441d3cada3f551dda44c9e69ef9c8b34a8d4.webp" />

```json
{
   "tool":"rect",
   "color":"#E67422",
   "size":3,
   "x":0.023408239700374533,
   "y":0.7873491468997087,
   "w":0.1254681647940075,
   "h":0.2047440699126093,
   "ix":0.023408239700374533,
   "iy":0.7873491468997087,
   "radius":8
}
```





#### 红色箭头

<img alt="red-arrow.png" src="/_fern-img/1f3e9db0880bf0bef5aa305de38471893b8ae9901226383441ff08c317087160.webp" />

```json
{
   "tool":"arrow",
   "color":"#E74A3C",
   "size":3,
   "x":0.25374531835205993,
   "y":0.23137744486059092,
   "w":0.24250936329588013,
   "h":0
}
```