简介：这份资源是面向计算机视觉、机器学习初学者及数据标注从业者的 Labelme 安装与使用教程文档，帮助读者快速搭建图像分割与标注环境，解决从零配置工具链时容易遇到的版本与环境问题。资源包共 1 个 docx 文件，约 14KB，内容以图文步骤形式组织，涵盖 Anaconda 安装、conda 创建 labelme 虚拟环境、pip 安装 Labelme，以及激活环境、启动工具、将 JSON 标注文件转换为可视化结果等完整流程，并区分 Python2 与 Python3 两套指令，便于对照操作。目前已有 15246 人学习下载，说明该教程在标注工具入门场景中具有较高参考价值。读者可据此独立完成环境搭建、图像标注与结果可视化，并理解图像分割、标注工具与 Anaconda 等基础概念，适合作为计算机视觉项目数据准备阶段的实操参考。
1. 从一张标注图说起：labelme 到底解决什么问题
如果你手头有一批图像数据，想拿去做分割训练，第一步往往不是写模型，而是把每张图里的目标轮廓描出来。这个活儿用代码硬写不现实，用 PS 又没法批量导出结构化数据。labelme 就是干这个的：它是一个基于 Python 和 Qt 的图形化标注工具，支持多边形、矩形、圆形、线段、点等多种标注方式，标注结果存成 JSON，里面记录了每个形状的类别和顶点坐标。它最常被用在语义分割、实例分割的数据准备阶段，也是很多开源分割数据集的事实标注格式之一。适合谁？做计算机视觉的算法工程师、需要自建数据集的在读同学、以及想把标注流程跑通再交给外包团队的人。这篇就把安装、标注、JSON 转数据集、以及几个我踩过的坑一次讲清。
2. 装 labelme：Anaconda 虚拟环境与两种 Python 版本的分叉
labelme 的安装本身不复杂，但它对 Python 版本和 Qt 绑定比较敏感，装错版本会出现窗口打不开、闪退、或者标注时画不出多边形。所以这一章先把环境搭对，再谈使用。
2.1 为什么用 Anaconda 而不是直接 pip
直接pip install labelme到系统 Python 里也能装，但 labelme 依赖 PyQt 和一系列科学计算包，版本冲突的概率不低。用 conda 单独建一个名为labelme的虚拟环境，好处是隔离：这个环境里只放 labelme 和它的依赖，不污染你跑模型的主环境。常见做法是装一个 Anaconda，安装时选对应自己 Python 版本的安装包，装完在开始菜单里能找到 Anaconda Prompt。
提示：如果你已经装了 Anaconda，跳过安装步骤，直接开 Anaconda Prompt 操作即可。Windows 下按 Win+R 输入 cmd 打开的是系统命令行，和 Anaconda Prompt 不是一回事，conda 命令在系统 cmd 里可能找不到。
2.2 Python2 与 Python3 的安装命令
原文给了两套命令，我按现在实际还能跑通的方式整理一下。Python2 那条路已经基本淘汰，但如果你维护的是老项目，可以照下面走。
Python2 版本：
conda create --name=labelme python=2.7 source activate labelme conda install pyqt pip install labelmePython3 版本：
conda create --name=labelme python=3.6 source activate labelme pip install pyqt5 pip install labelme逻辑说明：conda create --name=labelme python=3.6创建了一个名为 labelme 的独立环境，指定 Python 3.6；source activate labelme是 Linux/macOS 下的激活写法，Windows 的 Anaconda Prompt 里直接写activate labelme；pip install pyqt5装 Qt5 的 Python 绑定，labelme 的界面靠它；最后pip install labelme装主程序。
参数说明：--name后面跟环境名，你可以改成别的，但后面激活和调用都要跟着改。Python 版本这里写 3.6 是原文给的，实际用 3.7 到 3.9 通常也能装，但 3.10 以上有时会遇到 PyQt5 轮子不匹配，建议先用 3.6 到 3.8 之间的版本把流程跑通。
2.3 验证安装是否成功
装完别急着标数据，先确认命令能起来：
activate labelme labelme如果弹出一个带工具栏的窗口，说明装好了。如果报'labelme' 不是内部或外部命令，多半是环境没激活，或者 pip 装到了别的环境里。这时候用where labelme（Windows）或which labelme（Linux/macOS）看一下路径，确认它落在当前环境的 Scripts 目录下。
注意：有些机器上
pip install labelme会顺带升级 PyQt5 到不兼容的版本，导致启动时报 Qt 平台插件错误。遇到这种情况，先pip uninstall pyqt5，再pip install pyqt5==5.15.4这类明确版本，比盲目重装有效。
3. 标注与导出：从画多边形到 label_viz.png
环境跑通之后，真正的工作量在标注和格式转换上。这一章把标注操作、JSON 结构、以及labelme_json_to_dataset的用法拆开讲。
3.1 标注操作与 JSON 文件结构
打开 labelme 后，点 Open Dir 选中你的图像文件夹，然后 Create Polygons 开始描边。每描一个目标，输入类别名，比如 cat、dog、defect。标完一张点 Save，会在同目录生成一个同名 JSON。
JSON 里关键字段是shapes，每个元素包含label（类别）、points（多边形顶点坐标）、shape_type（polygon/rectangle/circle 等）。还有一个imagePath指向原图。这个结构决定了后面转数据集时能不能正确配对图像和标签。
常见做法是：图像放一个文件夹，JSON 也放同一个文件夹，文件名保持一致。这样转换脚本不用额外维护映射表。
3.2 用 labelme_json_to_dataset 转出可视化结果
原文给的命令是：
python labelme_json_to_dataset <文件名>.json实际执行时，先进到 labelme 的安装目录，或者确保这个脚本在 PATH 里。更稳的方式是直接用模块方式调用：
labelme_json_to_dataset your_image.json -o output_folder逻辑说明：这条命令读取 JSON，在输出目录里生成四个文件——img.png（原图）、label.png（标签掩码）、label_viz.png（叠加可视化）、label_names.txt（类别名列表）。label_viz.png就是你标好的数据长什么样的直观证据，检查标注质量时先看它。
参数说明：-o指定输出目录，不写的话默认在当前目录生成一个和 JSON 同名的文件夹。如果你的 JSON 里有多类，label.png里不同类别会用不同像素值表示，具体对应关系看label_names.txt。
3.3 批量转换与类别映射的注意点
单张转没问题，但实际项目里往往是几百上千张。写个循环：
for f in *.json; do labelme_json_to_dataset "$f" -o "output/${f%.json}" done逻辑说明：遍历当前目录所有 JSON，每个转到一个以文件名命名的子目录。${f%.json}是去掉后缀，保证输出目录名干净。
参数说明：批量转换时注意输出目录要先存在，或者脚本里加mkdir -p。另外，如果不同 JSON 的类别名不一致（比如有人写 cat，有人写 Cat），转出来的label_names.txt会对不上，后续训练时类别索引就乱了。我一般会在标注规范里强制统一小写，转之前用脚本扫一遍所有 JSON 的 label 字段去重检查。
提示：
label.png默认是 8 位调色板图，如果你要喂给训练框架，通常需要再转成单通道灰度或 one-hot。这一步别偷懒，否则读进去的标签可能是错的。
4. 避坑排查：labelme 从安装到转换的五个翻车点
这一章按「现象 → 原因 → 解决」列几条我实际遇到过的坑，都是能直接对号入座的。
现象一：输入 labelme 后窗口一闪而过，或者报 Qt 相关错误。原因：PyQt5 版本和 Python 版本不匹配，或者系统缺少 Qt 运行库。 解决：先确认当前环境是 labelme 环境，然后pip uninstall pyqt5 pyqt5-tools，再装一个明确版本，比如pip install pyqt5==5.15.4。Windows 上如果还报缺 dll，装一下 Visual C++ Redistributable。
现象二：标注时多边形画不出来，鼠标点了没反应。原因：图像太大或者缩放比例异常，也可能是 Qt 高 DPI 缩放导致坐标偏移。 解决：先按 Ctrl+滚轮调整一下视图，再试。如果还不行，在启动前设环境变量QT_AUTO_SCREEN_SCALE_FACTOR=0，或者换一张小图验证是不是图像本身的问题。
现象三：labelme_json_to_dataset报找不到命令。原因：这个脚本在 labelme 安装目录下，但当前工作目录不在那里，或者环境没激活。 解决：用python -m labelme.cli.json_to_dataset替代，或者先activate labelme再执行。最稳的是用完整路径调用。
现象四：转出来的 label.png 全黑，或者类别全变成 0。原因：JSON 里的 label 名和label_names.txt对不上，或者标注时用了中文类别名导致编码问题。 解决：统一用英文小写类别名；转之前打开 JSON 确认shapes里确实有内容；如果原图是灰度图，检查转换时有没有被当成三通道处理。
现象五：批量转换到一半报错退出，前面的结果还在，后面的没了。原因：某个 JSON 文件损坏，或者图像路径失效。 解决：在循环里加错误捕获，把失败的文件名记下来单独处理。别让一个坏文件打断整批任务。
注意：labelme 的 JSON 里存的是相对路径或绝对路径，换机器后如果图像路径变了，转换会找不到原图。迁移数据时把图像和 JSON 一起打包，保持相对位置不变。
5. 进阶技巧：把 labelme 标注接进训练流程的验证习惯
标注做完、转出label.png之后，很多人直接扔进训练脚本就开始跑，结果训了几轮发现指标不动，回头查才发现标签和图像没对齐。我自己的习惯是，在正式训练前强制走一遍可视化验证：随机抽 10 张label_viz.png，和原图并排看，确认每个目标的轮廓都贴合、类别名没错、没有漏标的多边形。
更进一步，如果你用的是语义分割框架，通常需要把label.png的调色板索引映射成 0 到 N-1 的连续整数。labelme 转出来的label_names.txt顺序就是索引顺序，但不同批次标注可能顺序不一致。我一般会写一个小脚本，读所有label_names.txt，取并集后重新映射，保证整个数据集类别索引统一。
import os import numpy as np from PIL import Image # 假设所有输出目录在 output/ 下 name_to_idx = {} for subdir in os.listdir('output'): names_file = os.path.join('output', subdir, 'label_names.txt') if not os.path.exists(names_file): continue with open(names_file) as f: names = [line.strip() for line in f if line.strip()] for n in names: if n not in name_to_idx: name_to_idx[n] = len(name_to_idx) print('统一类别映射:', name_to_idx) # 重新映射某张 label.png label = np.array(Image.open('output/sample/label.png')) new_label = np.zeros_like(label) for subdir in os.listdir('output'): names_file = os.path.join('output', subdir, 'label_names.txt') if not os.path.exists(names_file): continue with open(names_file) as f: names = [line.strip() for line in f if line.strip()] for i, n in enumerate(names): new_label[label == i] = name_to_idx[n] Image.fromarray(new_label).save('output/sample/label_unified.png')逻辑说明：先扫所有label_names.txt建立全局类别到索引的映射，再把每张label.png里的旧索引替换成全局索引。参数说明：label == i是布尔掩码，把旧索引 i 的像素位置赋成新索引。这一步做完，整个数据集的标签就一致了。
从那以后我每次拿到新标注数据，都强制先跑一遍类别映射检查和可视化抽检，再进训练。这个习惯帮我省过至少两次通宵排查。希望帮到你。
本文还有配套的精品资源，点击获取
