labelme 图像标注工具完全指南安装配置、标注使用与 VOC/COCO 数据集导出【免费下载链接】labelmeImage annotation with Python. Supports polygon, rectangle, circle, line, point, and AI-assisted annotation.项目地址: https://gitcode.com/gh_mirrors/la/labelmelabelme 是一个用 Python 编写、基于 Qt 图形界面的开源图像标注工具支持多边形、矩形、圆、线段、点等基础图元标注并提供图像级 flag 标注、视频标注、GUI 定制以及基于 SAM 系列模型的 AI 辅助标注能力。本文以项目 README.md 为骨架结合仓库源码CLI 入口、配置 schema、JSON 标注格式实现等深入讲解从安装、标注到导出 VOC/COCO 数据集的完整工作流读完后你将能够独立部署 labelme、按需定制~/.labelmerc配置、读懂并二次消费 JSON 标注文件。项目概览与核心特性labelme 的设计灵感来源于 MIT 的 LabelMe 在线标注项目定位是一款图形化图像标注应用而非 Python 库。它用 Qt 提供跨平台 GUI把标注结果以 JSON 文件形式落盘官方给出的核心特性如下对应 README.md多边形、矩形、圆、线段、点五种基础图元的图像标注教程见 examples/tutorial图像级 flag 标注用于图像分类与数据清洗如过曝/模糊/遮挡等标记视频标注对视频拆帧后的图像序列逐帧标注GUI 深度定制预定义 labels / flags、自动保存、标签校验等导出 VOC 格式数据集支持语义分割examples/semantic_segmentation与实例分割examples/instance_segmentation导出 COCO 格式数据集用于实例分割基于 SAM / EfficientSAM 模型的 AI 辅助点提示 → 多边形/掩膜标注基于 YOLO-world、SAM3 模型的 AI 文本提示标注text-to-annotation。此外labelme 内置 20 种语言的界面翻译含简体中文、繁体中文、日文、韩文等可通过设置LANG环境变量切换例如LANGja_JP.UTF-8 labelme。安装方式README 提供了三种安装路径分别面向不同使用场景。方式一pip 安装推荐pip install labelme # 想安装 GitHub 上的最新开发版 # pip install githttps://github.com/wkentaro/labelme.git方式二独立可执行程序最简单如果不想安装 Python 与 Qt 依赖可以下载官方提供的独立可执行程序跨平台免依赖运行。需要注意这是付费一次性购买终身使用收入用于维护项目——仓库 README 中明确说明了这一点。方式三Linux 发行版系统包部分 Linux 发行版如 Debian/Ubuntu 等的官方软件源中已经打包了 labelme可直接用发行版自带包管理器安装具体哪些发行版提供了哪个版本可参考 repology 的 packaging status 页面README 中以徽章形式给出了跟踪链接。支持的 Python 版本与平台v7.x / v6.3.x项目Supportedv7.xMaintenancev6.3.xPython3.12 – 3.143.10 – 3.11QtQt6PySide6Qt5OS64-bit macOS / Windows / Linux更老的系统labelme 跟随科学 Python 生态的 SPEC 0NEP 29 的继任者策略逐步淘汰旧 Python 版本与其核心科学依赖numpy、scipy、scikit-image保持同步。v6.3.x 是 Qt5 与 Python 3.10/3.11 用户的维护分支仅接收关键修复安全漏洞、数据丢失或标注损坏类缺陷、因上游依赖漂移导致的安装/启动问题不做功能回移植所有新功能开发都发生在 v7.x 上。从 v6.x 升级到 v7 的注意事项v7.0.0 抬高了平台基线升级时需关注四点README.mdQt 绑定变更GUI 从 PyQt5Qt5迁移到 PySide6Qt6pip install labelme现在拉取的是 PySide6Python 最低版本提高到 3.123.10/3.11 被放弃操作系统要求Qt6 需要 64 位 macOS / Windows / Linux不再有公开 Python APIlabelme 是应用而非库v7 将内部模块全部私有化改为下划线前缀命名因此import labelme.app、labelme.utils、labelme.widgets等旧式导入均失效。若你此前依赖这些内部模块应固定labelme7并把所需代码自行拷贝进项目examples/utils.py 提供了不依赖 labelme 即可读取 JSON 标注格式的可参考实现。需要停留在 PyQt5/Qt5、Python 3.10/3.11 或老系统上的用户请固定 v6.3.x 维护线pip install labelme7所有历史版本在 PyPI 上仍可安装旧的版本固定约束继续有效。v7 的配置解析变更v7.0.0 同时改变了配置解析~/.labelmerc现在使用 ruamel.yamlYAML 1.2 规范解析因此布尔值的拼写yes/no/on/off任意大小写会被当作字符串而不是布尔值。如果你用这些写法设置过布尔选项请改为true/false。公开接口边界labelme 明确将以下三样东西作为稳定接口README.md命令行接口labelme ...磁盘上的 JSON 标注格式~/.labelmerc配置文件格式。除此之外的一切包括 Python 导入面都属于内部实现可能随时改名或变更。要自行消费标注数据应直接读取 JSON 格式参考 examples/utils.py 的写法。快速上手命令行标注基础用法labelme # 直接打开 GUI # 单图教程示例 cd examples/tutorial labelme apc2016_obj3.jpg # 指定单个图像文件 labelme apc2016_obj3.jpg --output annotations/ # 把标注 JSON 保存到指定目录 labelme apc2016_obj3.jpg --with-image-data # 把图像数据一并内嵌进 JSON 文件 labelme apc2016_obj3.jpg \ --labels highland_6539_self_stick_notes,mead_index_cards,kong_air_dog_squeakair_tennis_ball # 指定标签列表 # 语义分割示例 cd examples/semantic_segmentation labelme data_annotated/ # 打开目录标注其中所有图像 labelme data_annotated/ --labels labels.txt # 用文件指定标签列表所有标注结果都会保存为 JSON 文件更完整的参数列表请运行labelme --help。命令行参数详解源码级CLI 入口位于 labelme/main.py由argparse构建主要参数如下参数说明path位置参数可选的图像文件、标注 JSON 文件或目录--version,-V显示版本号后退出--reset-config重置窗口几何与 dock 布局--logger-level日志级别可选debug/info/warning/error/critical默认debug--output标注 JSON 输出目录必须是目录若传入带.json后缀的路径会直接报错--config配置文件路径或 YAML 格式的配置字符串默认~/.labelmerc--with-image-data将图像数据以 base64 内嵌进 JSON--no-auto-save关闭自动保存--no-sort-labels停止对标签排序旧拼写--nosortlabels已弃用触发FutureWarning--flags逗号分隔的 flag 列表或包含 flags 的文件路径--label-flags标签正则 → flag 名称的 YAML 映射内联或文件路径旧拼写--labelflags已弃用--labels逗号分隔的标签列表或包含标签的文件路径--validate-label标签校验类型目前仅exact旧拼写--validatelabel已弃用--keep-prev保留上一帧的标注视频标注用--epsilon画布上查找最近顶点的容差浮点数几个值得注意的源码细节列表类参数智能解析_parse_list_arglabelme/main.py会先判断传入值是否为存在的文件——是文件则按行读取跳过空行否则按逗号切分。所以--labels既能接a,b,c也能接labels.txt。--config支持 YAML 字符串_resolve_config_sourcelabelme/main.py先用_yaml.safe_load尝试解析若结果是字典则直接当作配置覆盖项使用无需落盘文件。命令行优先级最高main()会把除version/reset_config/path/output/logger_level之外的所有参数并入config_overrides在加载配置文件之后覆盖之config_overrides.update(config_from_args)实现配置文件兜底、命令行覆盖的合并语义。--output校验若--output传入的值看起来像.json文件会调用parser.error拒绝并提示去掉.json后缀labelme/main.py。常见问题FAQ如何把 JSON 转成 numpy 数组参见 examples/tutorial。如何加载标注 PNG 文件参见 examples/tutorial。如何获得语义分割标注参见 examples/semantic_segmentation。如何获得实例分割标注参见 examples/instance_segmentation。配置文件~/.labelmerc完全解读labelme 的用户配置文件默认位于~/.labelmerc首次启动时若不存在会自动创建见 labelme/_config/init.py运行时先读取内置默认配置 labelme/_config/default_config.yaml再以用户配置、命令行参数逐层覆盖load_config实现于 labelme/_config/init.py。以下逐节说明各配置项的含义与默认值。保存与文件行为auto_save: true # 是否自动保存标注 with_image_data: false # 是否将图像 base64 内嵌进 JSON对应 --with-image-data file_search: # 文件搜索相关配置默认留空界面外观与语言# UI 语言为 locale 代码如 ja_JPnull 表示跟随系统 locale。 language: # 颜色主题system 跟随系统外观或强制 light / dark。 color_theme: systemcolor_theme的可选值在 labelme/_config/_schema.py 中定义为枚举system/light/dark。该配置在QApplication创建之前就被读取并应用见 labelme/main.py确保翻译器与调色板在任何控件构建前生效。标注图元与画布display_label_popup: true # 新建图元时是否弹出标签输入框 flags: # 预定义的图像级 flags逗号分隔或文件 label_flags: # 标签正则 - flags 的映射 labels: # 预定义标签列表 sort_labels: true # 标签列表按字母排序而非保持提供顺序 validate_label: # 标签校验类型None 或 exact shape_color: mode: auto # auto / uniform / by_label auto: shift: 0 # 自动调色板偏移量 uniform: color: [0, 255, 0] # uniform 模式统一颜色RGB by_label: colors: # 各标签专属颜色 fallback: [0, 255, 0] # by_label 模式的兜底颜色 shape: # 绘制状态颜色RGBA line_color: [0, 255, 0, 128] fill_color: [0, 0, 0, 64] vertex_fill_color: [0, 255, 0, 255] # 选中/悬停状态颜色RGBA select_line_color: [255, 255, 255, 255] select_fill_color: [0, 255, 0, 64] hvertex_fill_color: [255, 255, 255, 255] point_size: 8 # 顶点/点图元大小 show_labels: false # 是否在画布上显示图元标签BETA mask_polygonization: detail: 80 # AI 掩膜转多边形细节度0-100 # canvas epsilon: 10.0 # 画布顶点命中容差对应 --epsilon canvas: fill_drawing: true # 绘制过程中填充多边形 double_click: close # 双击行为None 不处理 / close 闭合多边形 num_backups: 10 # 撤销备份栈保留的编辑数最大撤销深度 allow_out_of_bounds_points: false # 允许标注点超出图像边界BETA crosshair: # 各图元绘制时的十字光标默认矩形与 AI 框开启 polygon: false rectangle: true oriented_rectangle: false circle: false line: false point: false linestrip: false ai_points_to_shape: false ai_box_to_shape: trueshape_color.mode的三种模式语义labelme/_config/_schema.pyauto自动分配调色板颜色可用shift平移起始色相uniform所有图元同色by_label同一标签同色可用colors为每个标签指定专属颜色未指定的标签回退到fallback。注意mask_polygonization.detail与label_flags有严格的类型校验labelme/_config/init.pydetail 必须是 0–100 的整数label_flags必须是字符串模式 → 字符串列表的映射。快捷键shortcuts: close: CtrlW open: CtrlO open_dir: CtrlU quit: CtrlQ save: CtrlS save_as: CtrlShiftS save_to: # 留空表示未绑定 delete_file: CtrlDelete open_next: [D, CtrlShiftD] open_prev: [A, CtrlShiftA] zoom_in: [Ctrl, Ctrl] zoom_out: Ctrl- zoom_to_original: Ctrl0 fit_window: CtrlF fit_width: CtrlShiftF create_polygon: CtrlN create_rectangle: CtrlR create_oriented_rectangle: create_circle: create_line: create_point: create_linestrip: edit_shape: CtrlJ delete_shape: Delete duplicate_shape: CtrlD copy_shape: CtrlC paste_shape: CtrlV undo: CtrlZ undo_last_point: CtrlZ edit_label: CtrlE toggle_keep_prev_mode: remove_selected_point: [MetaH, Backspace] show_all_shapes: hide_all_shapes: toggle_all_shapes: T select_shape_up: CtrlUp select_shape_down: CtrlDown select_shape_left: CtrlLeft select_shape_right: CtrlRight每个键位既可绑定单个组合键如CtrlW也可绑定列表如[D, CtrlShiftD]留空表示不绑定。界面 Dock 布局flag_dock: { show: true, closable: true, movable: true, floatable: true } label_dock: { show: true, closable: true, movable: true, floatable: true } shape_dock: { show: true, closable: true, movable: true, floatable: true } file_dock: { show: true, closable: true, movable: true, floatable: true } # label_dialog show_label_text_field: true label_completion: startswith # 标签补全策略startswith / contains fit_to_content: column: true row: falseAI 辅助标注配置ai: default: Sam2 (balanced) # AI 辅助默认模型按显示名 text_model: yoloworld:latest # AI 文本标注模型 suppress_existing_shape_matches: false # 候选与已有图元匹配时高亮已有图元而非新建ai.default的可选模型与ai.text_model的可选模型都定义在 labelme/_ai_models.pyAI 辅助点提示模型efficientsam:10mEfficientSam 速度版、efficientsam:latest精度版、sam:100m速度、sam:300m均衡、sam:latest精度、sam2:small速度、sam2:latest均衡、sam2:large精度、sam3:latest。除 SAM3 外均支持点提示supports_point_promptsAI 文本标注模型sam3:latestSAM3智能、yoloworld:latestYOLO-World快速。注意ai.text_model的值必须来自上述列表否则load_config会直接报配置错误labelme/_config/init.py。配置校验规则load_config在校验阶段强制了几条约束labelme/_config/init.pylabels列表不允许出现重复项启用了validate_label时必须提供labels配置中出现未知键、节section被标量覆盖等情况都会抛出明确错误而不是静默忽略。GUI 侧还提供了对应的设置对话框Settings dialog其可配置项与 schema 中的分组一一对应分组包括 Appearance and language、Files and saving、Drawing and canvas、Continue between images、Label sources、Label behavior、AI assist见 labelme/_config/_schema.py。JSON 标注格式与二次消费labelme 的标注以 JSON 文件落盘读写实现在 labelme/_label_file.py。顶层结构为{ version: 7.x.y, flags: {}, shapes: [ { label: person, points: [[x1, y1], [x2, y2]], group_id: null, description: , shape_type: rectangle, flags: {}, mask: null } ], imagePath: 2011_000006.jpg, imageData: null, imageHeight: 375, imageWidth: 500 }关键字段说明依据 labelme/_label_file.py 的读写逻辑shapes[].shape_type支持polygon、rectangle、line、circle、point、linestrip、oriented_rectangle、mask八种ShapeType定义于 labelme/_shape 模块未知类型在读取时会报错labelme/_label_file.py点数约束point必须 1 个点、rectangle/line/circle/mask必须 2 个点、oriented_rectangle必须 4 个点、polygon至少 3 个点labelme/_label_file.py且所有坐标必须有限finiteimageData--with-image-data开启时是 base64 编码的图像数据否则为null此时imagePath指向相对 JSON 所在目录的图像文件读取时会用PureWindowsPath.as_posix()兼容 Windows 风格分隔符mask仅shape_typemask允许携带为 base64 编码的 PNG 单通道掩膜读取时通过img_b64_to_arr解码并转成布尔数组group_id整型或 null用于实例分割时区分同标签的不同实例flags必须是str → bool的字典承载形状级属性保留键version、imageData、imagePath、shapes、flags、imageHeight、imageWidth为保留顶层键用户自定义元数据存放在其余键中写入时被原样透传labelme/_label_file.py。写入侧write_label_filelabelme/_label_file.py有几个工程化细节JSON 键保持 camelCase 以兼容存量文件采用先写临时文件再os.replace原子替换策略保存失败不会破坏原文件写入时校验声明的imageHeight/imageWidth与实际解码尺寸一致。由于 labelme 不提供稳定 Python API官方在 examples/utils.py 给出了不依赖 labelme的参考实现仅依赖标准库、numpy 与 PIL可直接拷到自己的工程里使用核心能力包括load_label_file(filename)读取 JSON 并返回图像字节与归一化后的 shapes 列表自动处理内嵌图像与外部图像两种情形shape_to_mask(img_shape, points, shape_type, ...)按图元类型栅格化为布尔掩膜圆、矩形、线段、折线、点、旋转矩形、多边形均有对应分支examples/utils.pyshapes_to_label(img_shape, shapes, label_name_to_value)把全部 shapes 渲染为类别图cls与实例图ins两个 int32 数组同(label, group_id)组合共享同一实例 idexamples/utils.py。典型应用场景五类标注任务仓库的 examples 目录为每类任务提供了可复现的标注命令与转换脚本。图像分类与数据清洗flag 标注参考 examples/classification。这类任务不画图元而是给整张图打 flag如光照、角度、遮挡等配合--flags参数与预定义 labels 使用标注产出可直接用于分类模型的数据筛选与标签。目标检测bbox参考 examples/bbox_detection使用矩形图元框出目标配套 labelme2voc.py 可转换为 VOC 检测格式。语义分割参考 examples/semantic_segmentationlabelme data_annotated/ --labels labels.txt ./labelme2voc.py data_annotated data_dataset_voc --labels labels.txt转换脚本会生成JPEGImages、SegmentationClass、SegmentationClassNpy、SegmentationClassVisualization等目录。教程 examples/tutorial 演示了单图全流程标注 →./draw_json.py apc2016_obj3.json可视化 →./export_json.py apc2016_obj3.json导出img.png、label.pnguint8 标签图、label_viz.png标签可视化与label_names.txt。注意label.png的加载推荐使用PIL.Image.openscipy.misc.imread、skimage.io.imread可能行为异常 import numpy as np import PIL.Image lbl np.asarray(PIL.Image.open(apc2016_obj3/label.png)) lbl.dtype dtype(uint8) np.unique(lbl) array([0, 1, 2, 3], dtypeuint8) lbl.shape (907, 1210)实例分割VOC COCO 双格式导出参考 examples/instance_segmentation标注命令演示了配置字符串与 label-flags 的典型组合labelme data_annotated --labels labels.txt --validate-label exact --config {shape_color: {mode: auto, auto: {shift: -2}}} labelme data_annotated --labels labels.txt --label-flags {.*: [occluded, truncated], person: [male]}--label-flags的正则语法^car$精确匹配car、car匹配前缀、.*匹配所有标签该模式定义也见 labelme/_config/_schema.py 的提示文案。VOC 转换./labelme2voc.py data_annotated data_dataset_voc --labels labels.txt生成JPEGImages、SegmentationClass、SegmentationClassNpy、SegmentationClassVisualization、SegmentationObject、SegmentationObjectNpy、SegmentationObjectVisualization七类产物。其中标签图只包含很低的标签值如0, 4, 14255表示__ignore__标签值npy 文件中对应-1可用draw_label_png.py可视化查看。COCO 转换./labelme2coco.py data_annotated data_dataset_coco --labels labels.txt生成data_dataset_coco/JPEGImages与data_dataset_coco/annotations.json。下图展示了实例分割的 VOC 转换产物原图、类别标签可视化、实例标签可视化视频标注参考 examples/video_annotation。核心是配合--keep-prev在帧间延续上一帧标注适合语义分割类的逐帧标注labelme data_annotated --labels labels.txt --keep-prev --config {shape_color: {mode: auto, auto: {shift: -2}}}视频转图像序列可使用社区工具video-clipip install video-cli video-toimg your_video.mp4 # 生成 your_video/ 目录 ls your_video/ labelme your_video/AI 辅助标注labelme 将 AI 辅助能力分成两条管线模型清单见 labelme/_ai_models.pyAI 点提示辅助AI Assist点击图像给出点提示由 SAM / EfficientSAM / SAM2 / SAM3 系列模型推理出掩膜再经多边形化mask_polygonization.detail0–100越高保留越多的掩膜边界细节转换为可编辑的多边形或掩膜图元AI 文本提示标注AI Text-to-Annotation输入自然语言文本提示由 YOLO-World快速或 SAM3智能直接生成一批候选标注。配合ai.suppress_existing_shape_matches: true时若 AI 候选与已有图元匹配会高亮已有图元而不是重复新建避免重复标注该语义定义于 labelme/_config/_schema.py。AI 相关的 GUI 组件位于 labelme/_widgets/_ai_assisted_annotation_widget.py 与 labelme/_widgets/_ai_text_to_annotation_widget.py自动化核心逻辑在 labelme/_automation 目录含掩膜多边形化、形状构建、候选抑制等子模块并有配套单测如 tests/unit/_automation/_suppression_test.py。构建独立可执行程序README 提供了基于 PyInstaller 的构建脚本README.md打包时需一并携带配置默认值、图标、翻译文件与 YOLO-World 的 CLIP 词表LABELME_PATH./labelme OSAM_PATH$(python -c import os, osam; print(os.path.dirname(osam.__file__))) pyinstaller labelme/labelme/__main__.py \ --nameLabelme \ --windowed \ --noconfirm \ --specpathbuild \ --add-data$(OSAM_PATH)/_models/yoloworld/clip/bpe_simple_vocab_16e6.txt.gz:osam/_models/yoloworld/clip \ --add-data$(LABELME_PATH)/_config/default_config.yaml:labelme/_config \ --add-data$(LABELME_PATH)/icons/*:labelme/icons \ --add-data$(LABELME_PATH)/translate/*:translate \ --icon$(LABELME_PATH)/icons/icon-256.png \ --onedir注意__main__.py末尾的if __name__ __main__:块labelme/main.py是 PyInstaller 生成可执行文件所必需的并调用了multiprocessing.freeze_support()以支持打包环境下的多进程。开发与测试开发者环境要求安装 just1.58.0 及以上与 uvjustfile中的配方默认使用 BashWindows 上需安装 Git for Windows 并把其 Bash 加入PATH。常用命令just # 列出全部命令与参数 just setup # 初始化开发环境 just lint # 运行代码检查 just test # 运行测试仓库测试覆盖全面tests/unit涵盖配置 schema / 迁移 / 写入tests/unit/_config、形状合并、JSON 标注文件读写tests/unit/_label_file_test.py等单元测试tests/e2e则包含基于真实 GUI 的端到端测试标注、缩放、撤销、自动保存、AI 文本标注、亮度对比度等几十个场景例如 tests/e2e/annotation_test.py、tests/e2e/ai_text_to_annotation_test.py。翻译文件的同步可由 tools/update_translate.py 辅助完成。小结labelme 是应用而非库的定位决定了它的使用范式一切通过 CLI 与配置文件驱动标注结果以 JSON 为唯一事实来源任何自定义消费都应直接读取 JSON参照 examples/utils.py。从本文覆盖的内容可以看到无论你是要做分类 flag、bbox、语义/实例分割还是视频逐帧标注都能在仓库 examples 中找到开箱即用的命令组合从 v7 开始请务必留意 PySide6/Qt6、Python 3.12、true/false布尔配置与私有化模块这四个关键变化即可平滑完成从 v6 到 v7 的迁移。【免费下载链接】labelmeImage annotation with Python. Supports polygon, rectangle, circle, line, point, and AI-assisted annotation.项目地址: https://gitcode.com/gh_mirrors/la/labelme创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考