# data annotation

**Repository Path**: shaynin/data-annotation

## Basic Information

- **Project Name**: data annotation
- **Description**: 一个数据标注工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 遥感地块标注 · 标注者完整上手手册

> **给谁看**：第一次接这个标注任务、只懂一点电脑操作的人。照着从头做一遍即可独立开工。
> **预计**：环境准备 10 分钟（只做一次），看完操作说明 10 分钟，之后就能正式标。
> **遇到"这块到底算哪类"**：查 **`标注规范.md`**，每一类都有定义、怎么认、画到哪、易错点；文末还有"易混淆速查"。

---

## 目录

1. [这个任务是做什么](#一这个任务是做什么)
2. [先认识 8 个标签和 4 种画法](#二先认识-8-个标签和-4-种画法最重要)
3. [一次性环境准备](#三一次性环境准备只做一次)
4. [启动标注工具](#四启动标注工具)
5. [LabelMe 界面速览](#五labelme-界面速览)
6. [标注操作分步教程](#六标注操作分步教程跟着做一遍)
7. [逐类怎么画](#七逐类怎么画对照表照着画就行)
8. [画的时候的通用规则](#八画的时候的通用规则)
9. [保存与自动保存](#九保存与自动保存)
10. [交付前自检（校验脚本）](#十交付前自检校验脚本)
11. [交付什么、怎么打包](#十一交付什么怎么打包)
12. [常见问题排查 FAQ](#十二常见问题排查-faq)
13. [套件文件清单](#十三套件文件清单)

---

## 一、这个任务是做什么

你拿到一批**遥感图像**（卫星/航拍俯视图）。任务是把图里出现的 **6 类目标**用鼠标圈出来、打上标签。不同目标圈法不一样——有的整片圈、有的一个一个圈、有的画框、有的画线。

你**不用懂遥感、不用写代码**，只要：会装一次软件 → 会用鼠标画形状 → 会保存。本手册把这三件事讲透。

---

## 二、先认识 8 个标签和 4 种画法（最重要）

6 类目标拆成 **8 个标签**，分属 **4 种画法**。这张表是全任务的核心，建议打印或截图贴在手边：

| 中文 | 选这个标签 | 画法 | 画几个 | 形状工具 |
|------|-----------|------|--------|---------|
| 垃圾场 | `garbage_dump` | 多边形圈整片 | 每片一个 | Create Polygons |
| 工地 | `construction_site` | 多边形圈整片 | 每片一个 | Create Polygons |
| 果园 | `orchard` | 多边形圈整片 | 每片一个 | Create Polygons |
| 菜地 | `cropland` | 多边形圈整片 | 每片一个 | Create Polygons |
| 停车场 | `parking_lot` | 多边形圈**整片地面** | 每片一个 | Create Polygons |
| 车辆 | `vehicle` | 多边形描**每一辆车** | **每辆车一个** | Create Polygons |
| 电塔 | `power_tower` | **矩形框**框住塔 | 每座一个 | Create Rectangle |
| 电线 | `power_line` | **折线**沿电线走向画 | 每根一条 | Create LineStrip |

**4 种画法对应的 4 个工具：**
- **多边形（Polygon）**——前 6 个标签都用它，沿目标边缘点一圈点把它围起来。
- **矩形（Rectangle）**——只有电塔用，拉一个框框住它。
- **折线（LineStrip）**——只有电线用，沿着线的走向点几个点连成折线。

**三条最容易错、必须记牢的规则：**
1. **停车场和车辆要同时标，会重叠是正常的**：停车场是**一整片地面**（用多边形整片圈，不要把车抠掉），车辆是**一辆一辆**单独描（每辆车一个多边形）。同一个停车场图里，地面圈 1 个 `parking_lot`，再把每辆车各描 1 个 `vehicle`。
2. **电塔必须用矩形**，不能用多边形。
3. **电线必须用折线（LineStrip）**，沿线走向点点，拐弯处加点（**至少点 3 个点**，只点 2 个会被判无效）。

> 标签是**锁死**的：工具里只能从这 8 个里选，打不出别的、也不会拼错。

---

## 三、一次性环境准备（只做一次）

### 1. 装 Python 3

- **Windows**：去 https://www.python.org/downloads/ 下载安装，安装时**务必勾选 "Add Python to PATH"**。
- **Mac**：通常自带；没有就装 https://www.python.org/downloads/ 。
- 验证：打开终端（Windows 叫"命令提示符"或"PowerShell"，Mac 叫"终端"），输入 `python3 --version`（Windows 上可能是 `python --version`），能显示版本号即可。

### 2. 装标注软件 LabelMe

在终端里运行（国内用清华源会快很多）：

```bash
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple labelme
```

> 装不上看 [FAQ](#十二常见问题排查-faq) 第 1 条。启动脚本里也带了自动安装，万一没装它会帮你装。

### 3. 获取并放置图片

**下载图片(数据源)**：用夸克网盘分享，打开下方链接(或用夸克 APP)下载「datas」：

- 链接：https://pan.quark.cn/s/503622aaf000

下载后，把图片全部放进套件目录下的 **`images/`** 文件夹（没有就自己新建一个 `images` 文件夹）。或者放别处也行，启动时把路径告诉脚本即可。

---

## 四、启动标注工具

在套件目录下，终端运行（**把路径换成你放图片的目录**；不填则默认用 `images/`）：

```bash
bash scripts/start_labelme.sh /你的图片目录
```

例如图片放在 `images/`：

```bash
bash scripts/start_labelme.sh images
```

脚本会自动帮你做好这些设置（你不用操心）：
- **锁死 8 个标签**——只能从下拉里选，不会自创、不会拼错。
- **自动保存**——切换到下一张图时自动存，防丢。
- **标注 JSON 不嵌图片**——文件很小，方便回传。
- **标签精确校验**——大小写/空格不对会被挡住。

窗口弹出来就可以开始标了。**关闭窗口 = 结束本次标注。**

> Windows 用户如果 `bash` 命令用不了，看 [FAQ](#十二常见问题排查-faq) 第 2 条，里面有不用脚本的等价启动方式。

---

## 五、LabelMe 界面速览

打开后界面大致分四块：

- **中间**：当前图片，你在这里画。鼠标滚轮缩放，按住可拖动。
- **左侧工具栏**：画形状的按钮——`Create Polygons`（多边形）、`Create Rectangle`（矩形）、`Create LineStrip`（折线）、`Edit Polygons`（编辑/移动已画的形状）。
- **右侧上方 Polygon Labels / Label List**：当前图已经画了哪些标注，点一条可选中、删除、改标签。
- **右侧下方 File List**：这个目录里所有图片的列表，点一张就跳过去标。

**最常用快捷键：**

| 操作 | 快捷键 |
|------|--------|
| 多边形工具 | `Ctrl + N` 或点左侧 Create Polygons |
| 保存 | `Ctrl + S`（已开自动保存，手动再存更保险） |
| 下一张图 | `D` |
| 上一张图 | `A` |
| 撤销上一个点 / 上一步 | `Ctrl + Z` |
| 删除选中的形状 | 选中后按 `Delete` |
| 编辑已有形状（移动顶点） | 左侧 `Edit Polygons` |
| 放大 / 缩小 | 滚轮，或 `Ctrl + +` / `Ctrl + -` |

---

## 六、标注操作分步教程（跟着做一遍）

以**画一片果园（多边形）**为例，其它多边形目标完全一样：

1. 左侧点 **`Create Polygons`**（或按 `Ctrl + N`）。
2. 在目标边缘**点第一个点**，沿着边缘一路点下去，每个拐弯点一下。点越密贴得越准，但不用过度，圆弧地方多点几个即可。
3. 画错点了按 **`Ctrl + Z`** 撤销上一个点。
4. 回到**起点附近双击**（或点回第一个点）**闭合**多边形。
5. 弹出标签框 → **从下拉里选 `orchard`** → 确认。形状就画好了，右侧列表会出现一条。
6. 接着画下一个目标，重复 1–5。

**画矩形（电塔）：** 左侧 `Create Rectangle` → 在电塔一角按下鼠标拖到对角松开 → 选 `power_tower`。

**画折线（电线）：** 左侧 `Create LineStrip` → 沿电线走向一个点一个点地点，拐弯处加点（**至少 3 个点**，否则无效）→ 画到线的末端后**双击结束** → 选 `power_line`。

**改错了怎么办：**
- 标签选错 → 右侧列表里双击那条，重新选标签。
- 形状画歪了 → 左侧 `Edit Polygons`，拖动顶点微调。
- 整个画错了 → 在右侧列表选中它，按 `Delete` 删掉重画。

**一张图标完 → 按 `D` 跳下一张**（会自动保存当前张）。

---

## 七、逐类怎么画对照表（照着画就行）

| 目标 | 标签 | 怎么画 | 关键注意 |
|------|------|--------|---------|
| 垃圾场 | `garbage_dump` | 多边形沿成片废弃物最外缘圈 | 多色杂乱才算；单一料堆/煤堆不算 |
| 工地 | `construction_site` | 多边形圈施工范围 | 有围挡/塔吊/基坑/建材堆 |
| 果园 | `orchard` | 多边形圈整片 | 能看到一颗颗圆树冠按行列排 |
| 菜地 | `cropland` | 多边形圈整片 | 小拼块马赛克、有垄沟/大棚 |
| 停车场 | `parking_lot` | 多边形圈**整片地面**（连车一起圈，不要把车抠掉） | 和车辆并存，都要标 |
| 车辆 | `vehicle` | 多边形把**每辆车**单独贴边描 | **绝不合并成一片**，一辆一个 |
| 电塔 | `power_tower` | **矩形**框住整座塔 | 用矩形，不是多边形 |
| 电线 | `power_line` | **折线**沿电线走向画，一根一条 | 拐弯处加点，至少 3 个点 |

> 每一类**怎么认、画到哪里截断、算/不算、最容易错**的详细判据，全部在 **`标注规范.md`** 里。拿不准一定先查它，特别是文末的"易混淆速查"（果园 vs 菜地、菜地 vs 工地、垃圾场 vs 工地、停车场 vs 车辆等）。

---

## 八、画的时候的通用规则

- **贴边但别外扩**：多边形沿目标真实边缘画，别把周围干净地、马路、空地圈进来。
- **分片 vs 整片**：被马路/河完全切断的两片，**分开画两个**；只是中间有田埂/小路、本质连成一片的，算一整片**画一个**。
- **拿不准类别** → 查 `标注规范.md`，尤其"易混淆速查"。
- **真的分不清** → 别硬猜，记下文件名问对接人，宁可标存疑也别误标。
- **漏标也是错**：图里所有属于这 8 类的目标都要标到，别只标显眼的。

---

## 九、保存与自动保存

- 已开**自动保存**：你切到下一张图（按 `D`）时，当前图自动存。
- 保险起见，标完一张也可以手动按 **`Ctrl + S`**。
- 标注结果存成**和图片同名的 `.json`**，就在图片同一个目录里。例如 `001.jpg` → `001.json`。
- JSON 不嵌图片，体积很小，正常现象。

---

## 十、交付前自检（校验脚本）

标完一批，**强烈建议**跑一下校验。机器会自动挑出：用错形状（比如电塔画成多边形）、打错/非法标签、点数太少画退化的形状，并统计每类标了多少个：

```bash
python3 scripts/validate.py /你的图片目录
```

例如：

```bash
python3 scripts/validate.py images
```

看输出最后一行：
- **`错误总数: 0`** → 通过，可以交付。
- 有错误 → 它会逐条告诉你**哪个文件、第几个形状、错在哪**，照着回去改，改完再跑一遍。

它还会打印"各类标注数量统计"，可以顺便核对有没有整类漏标（比如这批图明明有车却统计是 0）。

---

## 十一、交付什么、怎么打包

- 每张图旁边的**同名 `.json`** 就是你的成果。
- 把这些 **`.json` 连同对应图片一起打包**（zip）回传给对接人即可。
- 交付前确认：校验脚本 `错误总数: 0`。

---

## 十二、常见问题排查 FAQ

**1. `pip install` 装不上 / 报错？**
- 确认 Python 装好了（`python3 --version` 有输出）。
- 换源重试：命令里的 `-i https://pypi.tuna.tsinghua.edu.cn/simple` 就是清华源；也可试阿里源 `https://mirrors.aliyun.com/pypi/simple/`。
- 还不行，把完整报错截图发对接人。

**2. Windows 上 `bash scripts/start_labelme.sh` 用不了？**
- 装了 Git for Windows 后可用 Git Bash 跑 `bash`。
- 或者**不用脚本**，直接在命令提示符里运行等价命令（效果一样）：
  ```bash
  labelme 你的图片目录 --labels labels.txt --validate-label exact --output 你的图片目录
  ```

**3. 找不到 `labelme` 命令 / 提示未安装？**
- 重新跑第三步的 `pip install`。装完若仍找不到，关掉终端重开一个再试（PATH 需要刷新）。

**4. 标签下拉里没有我要的类别？**
- 本任务只有这 8 个标签，没有别的。如果你觉得某目标不在这 8 类里，那它就**不用标**。

**5. 停车场里的车要不要标？**
- 要。停车场地面整片圈一个 `parking_lot`，**每辆车再单独**各描一个 `vehicle`，两者重叠是对的。

**6. 一张图没有任何目标怎么办？**
- 不用画，直接按 `D` 跳下一张即可（这张不会生成 json，正常）。

**7. 校验脚本报"形状类型错误"？**
- 多半是电塔画成了多边形（应为矩形 Rectangle）、或电线画成了多边形（应为折线 LineStrip）。回去删掉重画成对的形状。

---

## 十三、套件文件清单

```
annotation-kit/
├── README.md                  ← 本手册
├── 标注规范.md                 ← 每类的详细定义、判据、易混淆速查（必备）
├── labels.json                ← 标签唯一事实源（label_id/中文/形状/颜色），改类别只改这里
├── labels.txt                 ← 锁定给 LabelMe 的 8 个标签
├── scripts/
│   ├── start_labelme.sh       ← 一键启动标注
│   └── validate.py            ← 交付前校验脚本
├── examples/
│   └── per_label_spec.json    ← 各标签规格示例（参考用，非标注文件）
└── images/                    ← 把待标图片放这里（可自建）
```

---

**还有疑问？** 先查 `标注规范.md`，再不行直接问对接人。标错可以改，别怕。