简介这份资源是面向计算机视觉、机器学习初学者及数据标注从业者的 Labelme 安装与使用教程文档帮助读者快速搭建图像分割与标注环境解决从零配置工具链的入门难题。压缩包内共 1 个 docx 文件约 14KB以图文步骤形式组织内容便于按需查阅与本地留存。教程围绕 Anaconda 环境准备、Labelme 虚拟环境创建与安装、工具启动及 JSON 标注结果转换等环节展开区分 Python2 与 Python3 两套命令并给出 labelme_json_to_dataset 生成可视化结果的具体用法同时涉及图像分割、标注工具、Anaconda 等基础概念与应用场景说明。目前已有 15225 人学习下载适合需要系统掌握标注工具配置流程、对照实操与查漏补缺的入门及中级读者参考。1. 从一张标注图说起labelme 到底解决什么问题如果你手头有一批图片需要把里面的目标一个个框出来或者描出轮廓用来训练分割模型那 labelme 大概率是你绕不开的第一个工具。它做的事情很纯粹打开一张图用鼠标点出多边形、矩形、圆或者线段给每个区域打上类别名最后导出一个 JSON 文件。这个 JSON 里记录了每个点的坐标和标签后续脚本一转换就能变成模型能吃的掩码图或者标注文件。我见过太多人卡在第一步——装不上。不是 Python 版本对不上就是 pyqt 和 pyqt5 混着装再不然就是环境激活了但命令行找不到 labelme。这篇笔记就按我实际复现的流程走一遍从 Anaconda 建环境到标注、再到 JSON 转可视化结果把每个命令的含义和容易翻车的地方都摊开讲。适合刚接触图像标注的新手也适合想把这套流程固化到团队里的熟手。2. 环境搭建Anaconda 与 labelme 的版本对应关系2.1 为什么非要走 Anaconda 这条路直接 pip install labelme 行不行行但我不推荐。labelme 依赖 PyQt 做界面而 PyQt 在不同 Python 版本下的 wheel 包兼容性差异很大。系统里如果已经装了别的 Python 项目全局 pip 很容易把 PyQt 版本搞乱最后 labelme 启动就报Could not find or load the Qt platform plugin。用 Anaconda 建一个独立虚拟环境相当于给 labelme 划了一块自留地它爱装哪个版本的 PyQt 就装哪个不影响你其他项目。Anaconda 的下载地址在项目正文里给了去官网选对应操作系统的安装包就行。安装时有一个选项叫“Add Anaconda to my PATH environment variable”默认是不勾的。我建议不勾然后用 Anaconda Prompt 来操作这样环境变量不会和系统里已有的 Python 打架。如果你勾了后面 cmd 里 conda 命令也能用但偶尔会出现 conda 和系统 Python 混用的情况排查起来很烦。装完 Anaconda打开 Anaconda Prompt先确认 conda 可用conda --version # 输出类似 conda 23.x.x 即可这一步如果报“不是内部或外部命令”说明 Anaconda 的 Scripts 目录没进 PATH。要么重新安装时勾选 PATH 选项要么手动把 Anaconda 安装目录下的 Scripts 文件夹加到系统环境变量里。2.2 Python 2 与 Python 3 的安装命令拆解项目正文里给了两套命令分别对应 Python 2.7 和 Python 3.6。现在新项目基本都走 Python 3但有些老代码库还在 Python 2 上跑所以两套都保留着。我先把两套命令完整列出来再逐行解释。Python 2 版本conda create --namelabelme python2.7 source activate labelme conda install pyqt pip install labelmePython 3 版本conda create --namelabelme python3.6 source activate labelme pip install pyqt5 pip install labelme第一行conda create --namelabelme python2.7是创建一个名字叫 labelme 的虚拟环境里面预装 Python 2.7。--name可以简写成-n效果一样。环境名字你可以改成别的比如labelme_env但后面激活和切换时名字要对应上。第二行source activate labelme是激活环境。注意这是 Linux/macOS 下的写法Windows 的 cmd 里直接写activate labelme就行不需要source。如果你在 Windows 的 PowerShell 里操作可能要写成conda activate labelme。这几个写法差异是新手最容易懵的地方记住一条Anaconda Prompt 里用activate labelme最稳。第三行开始分叉。Python 2 环境装的是pyqtPython 3 环境装的是pyqt5。这个区别不能搞反Python 3 装 pyqt 会拉不到对应版本的包Python 2 装 pyqt5 同样会报错。conda install pyqt走的是 conda 源pip install pyqt5走的是 PyPI 源两者不冲突但同一个环境里不要重复装。第四行pip install labelme是真正安装 labelme 本体。这里有个细节如果你在 Python 3.6 环境里直接pip install labelmepip 可能会尝试装最新版 labelme而最新版可能要求 Python 3.7 以上。这时候要么把 Python 版本提到 3.7要么指定 labelme 版本比如pip install labelme4.5.6。我一般会先跑pip install labelme看它报不报版本错误报了就降级 Python 或者锁 labelme 版本。提示创建环境时 Python 版本不要选太新3.6 到 3.8 之间对 labelme 的兼容性最稳。3.9 以上偶尔会遇到 PyQt5 的 wheel 包缺失需要额外装编译工具。2.3 验证安装是否成功装完之后别急着开图形界面先在命令行里验证一下labelme --version # 正常会输出 labelme 的版本号比如 4.5.6如果这条命令报“不是内部或外部命令”说明 labelme 的可执行文件没进当前环境的 PATH。常见原因是 pip 安装时用了--user参数或者环境没激活成功。先conda list看一下 labelme 在不在列表里在的话就是 PATH 问题用python -m labelme也能启动但每次敲这么长不方便。解决办法是重新激活环境或者用where labelmeWindows/which labelmeLinux/macOS确认可执行文件位置。3. 标注实操从打开界面到导出 JSON3.1 启动 labelme 与界面初识激活环境后直接输入activate labelme labelme界面会弹出一个窗口左边是文件列表中间是图像显示区右边是标签列表。第一次打开时中间是空的点左上角“Open”选一张图片或者点“Open Dir”选整个文件夹。我一般用“Open Dir”这样标注完一张可以直接点下一张不用反复选文件。界面右侧有几个关键按钮Create Polygons画多边形Create Rectangle画矩形Create Circle画圆Create Line画线段Create Point画点。做语义分割标注最常用的是多边形做目标检测用矩形就够了。画完一个区域会弹出一个输入框让你填标签名比如“person”“car”“defect”之类的。标签名建议用英文避免中文在某些转换脚本里出现编码问题。3.2 标注过程中的快捷键与效率技巧标注是个体力活快捷键能省不少时间。我常用的几个Ctrl N下一张图Ctrl P上一张图Ctrl S保存当前标注Ctrl Z撤销上一个点D删除当前选中的多边形Space在画多边形时临时切换成移动模式画多边形的时候点最后一个点要双击或者按回车才能闭合。闭合之后如果发现某个点位置不对可以拖动那个点微调。如果整个多边形画歪了按D删掉重画比一个个点调更快。还有一个容易忽略的点labelme 默认不会自动保存。你画完一个区域必须按Ctrl S才会生成 JSON 文件。JSON 文件名和图片名一样只是后缀变成.json存在图片同目录下。如果你标了十几张图才发现没保存那真是血泪经验——养成画完一张就按一次Ctrl S的习惯。3.3 JSON 文件里到底存了什么随便打开一个标注好的 JSON 文件结构大概是这样{ version: 4.5.6, flags: {}, shapes: [ { label: person, points: [[100, 200], [150, 220], [180, 300]], group_id: null, shape_type: polygon, flags: {} } ], imagePath: example.jpg, imageData: null, imageHeight: 480, imageWidth: 640 }shapes数组里每个对象就是一个标注区域。label是你填的标签名points是多边形的顶点坐标shape_type是标注类型polygon/rectangle/circle/line/point。imagePath是图片相对路径imageHeight和imageWidth是图片尺寸。imageData默认是 null如果标注时勾选了“Save with image data”这里会存 base64 编码的图片文件会变大一般不建议勾。这个 JSON 结构决定了后续转换脚本怎么写。比如你要转成 COCO 格式就是遍历shapes把points转成 COCO 的 segmentation 字段要转成掩码图就用points画多边形填充。4. 数据转换labelme_json_to_dataset 的用法与参数4.1 单文件转换命令项目正文里给了一条命令python labelme_json_to_dataset 文件名.json这条命令会在当前目录下生成一个和 JSON 同名的文件夹里面包含五个文件文件名含义img.png原始图片的副本label.png标签掩码图每个类别对应一个像素值label_viz.png可视化结果不同类别用不同颜色叠加在原图上label_names.txt类别名称列表按像素值顺序排列info.yaml标注信息摘要包含类别数和图片尺寸label.png是训练分割模型时真正喂给网络的东西label_viz.png是给你肉眼检查标注对不对的。我一般先看label_viz.png颜色块和原图目标对得上再去看label.png的像素值。4.2 批量转换脚本单文件转换只适合调试实际项目里几百张图不可能一张张敲。我一般写个循环import os import subprocess json_dir ./annotations # JSON 文件所在目录 output_dir ./output # 转换结果输出目录 os.makedirs(output_dir, exist_okTrue) for file_name in os.listdir(json_dir): if file_name.endswith(.json): json_path os.path.join(json_dir, file_name) # 调用 labelme_json_to_dataset指定输出目录 subprocess.run([ labelme_json_to_dataset, json_path, -o, os.path.join(output_dir, file_name.replace(.json, )) ], checkTrue) print(f转换完成: {file_name})这段脚本的核心是subprocess.run调用labelme_json_to_dataset-o参数指定每个 JSON 对应的输出文件夹。checkTrue表示如果某张图转换失败就抛异常避免 silently fail。跑之前确认当前环境是 labelme 环境否则labelme_json_to_dataset这个命令找不到。4.3 转换时的常见参数调整labelme_json_to_dataset还有几个可选参数在批量转换时有用-o或--out指定输出目录不指定就默认在 JSON 同目录下建文件夹。--labels指定类别顺序文件比如你有一个labels.txt写着 person、car、dog转换时就会按这个顺序分配像素值。不指定的话labelme 按标注时出现的顺序自动分配。--nodata不生成label.png里的背景类默认背景是 0加了之后背景不占类别编号。如果你发现转换出来的label.png里类别像素值和预期对不上先检查有没有指定--labels。多人协作标注时不同人标注的类别出现顺序可能不一样导致同一批数据里“person”的像素值有的是 1 有的是 2。统一用--labels文件锁定顺序能避免这个坑。5. 避坑与排查标注和转换中的五个高频问题5.1 启动报错 “Qt platform plugin could not be initialized”现象命令行输入labelme后窗口没弹出来终端报This application failed to start because no Qt platform plugin could be initialized。原因PyQt5 的插件路径没被正确识别常见于 conda 环境和 pip 环境混装或者系统里装了多个 Qt 版本。解决先卸载再重装 PyQt5用 conda 统一管理pip uninstall pyqt5 conda install pyqt如果还不行在激活环境后手动设置环境变量set QT_QPA_PLATFORM_PLUGIN_PATH%CONDA_PREFIX%\Lib\site-packages\PyQt5\Qt5\pluginsWindows 下用setLinux/macOS 下用export。这个变量指向 PyQt5 的 plugins 目录告诉程序去哪里找平台插件。5.2 标注时中文标签导致转换乱码现象标签名用了中文转换出来的label_names.txt里是乱码或者label_viz.png颜色对应不上。原因labelme 的 JSON 默认用 UTF-8 存储但某些转换脚本在读取时用了系统默认编码Windows 下是 GBK导致解码错误。解决标注时尽量用英文标签。如果非要用中文转换脚本里显式指定编码import json with open(example.json, r, encodingutf-8) as f: data json.load(f)另外label_names.txt的读写也要统一用encodingutf-8。5.3 转换后的 label.png 全是黑色现象label_viz.png能看到彩色区域但label.png打开是全黑。原因label.png是单通道灰度图像素值范围是 0 到类别数。如果类别数很少比如只有 1 类像素值就是 0 和 1肉眼在普通看图软件里几乎看不出区别看起来像全黑。解决用 Python 读一下像素值分布import numpy as np from PIL import Image label np.array(Image.open(label.png)) print(np.unique(label)) # 输出 [0 1] 说明只有背景和一类只要np.unique里有非零值就说明标注信息在只是视觉上不明显。训练时模型读的是像素值不是肉眼看的颜色。5.4 批量转换时部分 JSON 报 “KeyError: ‘shapes’”现象大部分 JSON 转换正常个别文件报KeyError: shapes。原因那个 JSON 文件可能是空的或者标注时没保存成功文件内容不完整。labelme 在没画任何区域时按Ctrl S生成的 JSON 里shapes是空数组但有些版本会直接不写这个字段。解决转换前先检查 JSON 是否有效import json with open(example.json, r, encodingutf-8) as f: data json.load(f) if shapes not in data or len(data[shapes]) 0: print(空标注文件跳过) else: # 正常转换 pass批量脚本里加上这个判断避免因为一两个空文件中断整个流程。5.5 环境切换后 labelme 命令找不到现象昨天还能用labelme命令今天打开新的终端窗口输入labelme报“不是内部或外部命令”。原因conda 环境没有自动激活。每次打开新终端默认是 base 环境labelme 装在 labelme 环境里不激活就找不到。解决养成习惯打开终端先activate labelme。如果嫌麻烦可以把激活命令写进启动脚本或者用conda config --set auto_activate_base false关掉 base 自动激活然后手动激活目标环境。但我不建议自动激活 labelme 环境因为其他项目可能依赖 base 环境自动切换容易乱。6. 进阶技巧用 Python 脚本直接解析 JSON 生成自定义掩码labelme_json_to_dataset生成的label.png是单通道灰度图每个类别一个像素值。但有些训练框架要求掩码是 one-hot 编码或者要求特定颜色映射。这时候直接解析 JSON 自己画掩码更灵活。下面这段脚本读取 JSON用 OpenCV 画多边形填充生成和原图同尺寸的掩码import json import numpy as np import cv2 def json_to_mask(json_path, output_path): with open(json_path, r, encodingutf-8) as f: data json.load(f) h data[imageHeight] w data[imageWidth] mask np.zeros((h, w), dtypenp.uint8) # 类别名到像素值的映射按需修改 label_map {background: 0, person: 1, car: 2} for shape in data[shapes]: label shape[label] points np.array(shape[points], dtypenp.int32) color label_map.get(label, 0) # 填充多边形-1 表示实心填充 cv2.fillPoly(mask, [points], color) cv2.imwrite(output_path, mask) print(f掩码已保存: {output_path}) # 调用示例 json_to_mask(example.json, custom_mask.png)这段脚本的关键在cv2.fillPoly它把points围成的多边形区域填充成指定像素值。label_map是你自己定义的类别顺序比 labelme 自动分配的更可控。如果标注类型是矩形points只有两个对角点fillPoly同样能处理因为矩形本质就是四个点的多边形。圆和线段需要另外处理圆可以用cv2.circle线段用cv2.line。我一般会在转换后做一次校验把生成的掩码和原图叠加用cv2.addWeighted看一下区域对不对得上。这个步骤花不了几秒钟但能避免把标歪的数据喂进训练。从那以后我每次批量转换完都强制抽三张图做叠加检查确认没问题再往下一步走。希望帮到你。本文还有配套的精品资源点击获取