labelme 實(shí)例分割標(biāo)注與 VOC/COCO 數(shù)據(jù)集轉(zhuǎn)換實(shí)戰(zhàn)指南【免費(fèi)下載鏈接】labelmeImage annotation with Python. Supports polygon, rectangle, circle, line, point, and AI-assisted annotation.項(xiàng)目地址: https://gitcode.com/gh_mirrors/la/labelme本指南以倉(cāng)庫(kù)中的 examples/instance_segmentation 為例完整講解如何用 labelme 對(duì)圖片進(jìn)行實(shí)例分割標(biāo)注并將標(biāo)注結(jié)果一鍵轉(zhuǎn)換為 Pascal VOC 與 MS COCO 兩種主流數(shù)據(jù)格式。讀完本文你將掌握--validate-label、--label-flags、--config等關(guān)鍵命令行參數(shù)的實(shí)際用法理解labelme2voc.py與labelme2coco.py的轉(zhuǎn)換原理包括類別編號(hào)、實(shí)例合并、標(biāo)簽像素值約定并能獨(dú)立復(fù)現(xiàn)從原始圖片到可訓(xùn)練數(shù)據(jù)集的完整流水線。一、示例工程結(jié)構(gòu)總覽examples/instance_segmentation是一個(gè)完整的實(shí)例分割工作區(qū)同時(shí)包含標(biāo)注前與轉(zhuǎn)換后兩個(gè)階段的數(shù)據(jù)結(jié)構(gòu)如下examples/instance_segmentation/ ├── data_annotated/ # 標(biāo)注產(chǎn)物3 張圖片 3 個(gè) JSON 標(biāo)注文件 ├── data_dataset_voc/ # labelme2voc.py 的轉(zhuǎn)換輸出 ├── data_dataset_coco/ # labelme2coco.py 的轉(zhuǎn)換輸出 ├── labelme2voc.py # VOC 格式轉(zhuǎn)換腳本 ├── labelme2coco.py # COCO 格式轉(zhuǎn)換腳本 ├── labels.txt # 類別清單VOC 20 類 └── README.md # 本文對(duì)應(yīng)的官方說(shuō)明其中data_annotated內(nèi)含2011_000003.jpg、2011_000006.jpg、2011_000025.jpg三張示例圖片及其同名.json標(biāo)注文件data_dataset_voc與data_dataset_coco則是運(yùn)行轉(zhuǎn)換腳本后生成的成品數(shù)據(jù)集可直接對(duì)照驗(yàn)證你的轉(zhuǎn)換結(jié)果。轉(zhuǎn)換腳本依賴同目錄下示例所需的 examples/utils.py 與 examples/tutorial/draw_label_png.py 等輔助工具。二、數(shù)據(jù)準(zhǔn)備labels.txt 與標(biāo)注 JSON 格式2.1 類別清單 labels.txt實(shí)例分割的第一步是定義類別清單。本示例的 labels.txt 內(nèi)容如下__ignore__ _background_ aeroplane bicycle bird boat bottle bus car cat chair cow diningtable dog horse motorbike person potted plant sofa train tv/monitor前兩行是兩個(gè)特殊約定需要特別注意__ignore__占位類別在轉(zhuǎn)換時(shí)會(huì)被映射為忽略區(qū)域其像素值在 PNG 中記為255npy 中為-1用于遮蓋不希望參與訓(xùn)練的物體或區(qū)域_background_背景類別像素值恒為0。其余 20 行即標(biāo)準(zhǔn) Pascal VOC 的 20 個(gè)語(yǔ)義類別。標(biāo)注時(shí)形狀的 label 必須能在該清單中找到精確匹配否則后續(xù)轉(zhuǎn)換會(huì)報(bào)錯(cuò)。2.2 標(biāo)注 JSON 的結(jié)構(gòu)以 data_annotated/2011_000003.json 為例labelme 4.x 的標(biāo)注文件頂層結(jié)構(gòu)為{ version: 4.0.0, flags: {}, shapes: [ { label: person, points: [[250.8, 107.3], [229.8, 119.3], ..., [270.8, 121.3]], group_id: 0, shape_type: polygon, flags: {} } ], imagePath: 2011_000003.jpg, imageData: null, imageHeight: 338, imageWidth: 500 }每個(gè) shape 的關(guān)鍵字段含義字段含義實(shí)例分割中的角色label形狀所屬類別決定該形狀寫(xiě)入類別層class 層的編號(hào)points頂點(diǎn)坐標(biāo)列表定義多邊形/矩形/圓等幾何區(qū)域shape_type形狀類型polygon/rectangle/circle/line/point/linestrip 等決定柵格化方式group_id實(shí)例分組標(biāo)識(shí)可空實(shí)例分割的核心決定多個(gè)形狀是否屬于同一實(shí)例flags該形狀的自定義標(biāo)志不參與分割掩碼僅作屬性記錄group_id 與實(shí)例劃分是本例最值得注意的細(xì)節(jié)在2011_000003.json中前兩個(gè)person形狀共享group_id: 0說(shuō)明它們是同一個(gè)人的兩塊多邊形碎片轉(zhuǎn)換時(shí)會(huì)被合并為一個(gè)實(shí)例而第三個(gè)person的group_id為null會(huì)作為獨(dú)立實(shí)例處理。__ignore__形狀則用于圈出畫(huà)面中需要忽略的區(qū)域。這一約定直接決定了后續(xù)實(shí)例掩碼的生成邏輯。三、啟動(dòng)標(biāo)注命令行參數(shù)深度解析原文檔給出的標(biāo)注命令有兩條分別對(duì)應(yīng)兩種典型配置場(chǎng)景。3.1 指定類別清單與顏色自動(dòng)分配labelme data_annotated --labels labels.txt --validate-label exact --config {shape_color: {mode: auto, auto: {shift: -2}}}三個(gè)參數(shù)的作用--labels labels.txt指定類別清單文件。從 labelme/main.py 的解析邏輯看--labels既支持文件路徑也支持逗號(hào)分隔的內(nèi)聯(lián)文本--validate-label exact開(kāi)啟標(biāo)簽校驗(yàn)。在 labelme/_config/init.py 中可以看到validate_label配置項(xiàng)只接受None與exact兩種取值且啟用時(shí)必須同時(shí)提供--labels否則啟動(dòng)會(huì)直接報(bào)錯(cuò)。exact的含義是強(qiáng)制標(biāo)注標(biāo)簽必須與類別清單中的名稱完全一致從 labelme/_app.py 中的validate_label()實(shí)現(xiàn)可以看出它會(huì)拿用戶輸入的標(biāo)簽與已加載的類別集合做精確匹配匹配失敗則阻止創(chuàng)建/修改該形狀——這是保證轉(zhuǎn)換階段不出現(xiàn)未知類別異常的第一道防線--config {shape_color: {mode: auto, auto: {shift: -2}}}以 YAML 字符串形式覆蓋配置。shape_color.mode: auto表示形狀顏色自動(dòng)分配可選值為auto/uniform/by_label見(jiàn) labelme/_config/default_config.yamlauto.shift的默認(rèn)值是0這里設(shè)為-2表示在自動(dòng)生成的顏色序列上做偏移讓相鄰形狀呈現(xiàn)可區(qū)分的顏色漸變便于在畫(huà)布上快速分辨不同標(biāo)注對(duì)象。3.2 按標(biāo)簽規(guī)則批量配置標(biāo)志flagslabelme data_annotated --labels labels.txt --label-flags {.*: [occluded, truncated], person: [male]}--label-flags用于建立標(biāo)簽 → 可選標(biāo)志列表的映射采用 YAML 格式的正則表達(dá)式: [標(biāo)志...]結(jié)構(gòu).*: [occluded, truncated]所有形狀都可勾選occluded遮擋與truncated截?cái)鄡蓚€(gè)標(biāo)志person: [male]標(biāo)簽為person的形狀額外提供male標(biāo)志。從 labelme/main.py 的解析實(shí)現(xiàn)看該參數(shù)既可以是內(nèi)聯(lián) YAML 字符串如本例也可以是 YAML/JSON 文件的路徑。標(biāo)志最終會(huì)寫(xiě)入每個(gè) shape 的flags字段雖然不參與掩碼生成但可攜帶重要的屬性信息如遮擋、性別、天氣等供訓(xùn)練或后處理階段使用。標(biāo)注完成后data_annotated目錄下每個(gè)圖片都會(huì)生成同名.json文件這就是后續(xù)兩個(gè)轉(zhuǎn)換腳本的輸入。四、轉(zhuǎn)換為 VOC 格式數(shù)據(jù)集4.1 轉(zhuǎn)換命令與輸出目錄./labelme2voc.py data_annotated data_dataset_voc --labels labels.txt該命令生成如下目錄結(jié)構(gòu)data_dataset_voc/ ├── JPEGImages/ # 原圖RGB JPEG ├── SegmentationClass/ # 類別標(biāo)簽 PNG ├── SegmentationClassNpy/ # 類別標(biāo)簽 npyint32 數(shù)組 ├── SegmentationClassVisualization/ # 類別標(biāo)簽可視化疊加在灰度圖上的偽彩色 JPEG ├── SegmentationObject/ # 實(shí)例標(biāo)簽 PNG ├── SegmentationObjectNpy/ # 實(shí)例標(biāo)簽 npy ├── SegmentationObjectVisualization/ # 實(shí)例標(biāo)簽可視化 └── class_names.txt # 寫(xiě)入的類別清單4.2 命令行參數(shù)labelme2voc.py 支持三個(gè)可選開(kāi)關(guān)參數(shù)默認(rèn)行為作用--noobject生成實(shí)例層跳過(guò) SegmentationObject 系列目錄--nonpy生成 npy跳過(guò) SegmentationClassNpy / SegmentationObjectNpy--noviz生成可視化跳過(guò) SegmentationClassVisualization / SegmentationObjectVisualization注意輸出目錄已存在時(shí)腳本會(huì)直接報(bào)錯(cuò)退出Output directory already exists因此重復(fù)轉(zhuǎn)換需先清理或更換目錄名。4.3 轉(zhuǎn)換原理類別編號(hào)與實(shí)例合并理解轉(zhuǎn)換結(jié)果關(guān)鍵是看懂腳本內(nèi)部的編號(hào)約定見(jiàn) examples/utils.py 與 labelme2voc.py類別編號(hào)從 -1 開(kāi)始_load_class_names()中class_id i - 1因此__ignore__對(duì)應(yīng)-1、_background_對(duì)應(yīng)0、aeroplane對(duì)應(yīng)1以此類推語(yǔ)義層與實(shí)例層分別生成utils.shapes_to_label()對(duì)每個(gè)形狀調(diào)用shape_to_mask()柵格化出布爾掩碼然后寫(xiě)入兩個(gè) int32 數(shù)組——cls類別編號(hào)與ins實(shí)例編號(hào)從 1 開(kāi)始相同(label, group_id)組合共享同一編號(hào)即自動(dòng)合并碎片忽略區(qū)域清零ins[cls -1] 0將__ignore__區(qū)域的實(shí)例值置 0PNG 存 8-bitnpy 存 int32imgviz.io.lblsave()把標(biāo)簽寫(xiě)入 uint8 PNG因此負(fù)值-1會(huì)被存儲(chǔ)為255而 npy 保留原始 int32__ignore__仍為-1實(shí)例名按編號(hào)命名SegmentationObject的 label_names 為0, 1, 2, ...可視化時(shí)每個(gè)實(shí)例顯示其編號(hào)轉(zhuǎn)換同時(shí)把類別清單寫(xiě)回輸出目錄的class_names.txt供訓(xùn)練框架直接讀取。4.4 標(biāo)簽值約定為什么只有 0、4、14原文檔特別提醒查看生成的標(biāo)簽 PNG會(huì)發(fā)現(xiàn)其中只包含非常低的標(biāo)簽值例如0, 4, 14而255表示__ignore__標(biāo)簽值npy 中為-1。原因在于背景區(qū)域占絕大多數(shù)值為0畫(huà)面中實(shí)際出現(xiàn)的類別數(shù)量很少示例圖中只有 person、bottle 等少數(shù)類別因此編號(hào)4、14這類低值即可覆蓋全部前景像素255是 uint8 下對(duì)-1的編碼用于標(biāo)記被__ignore__形狀圈出的區(qū)域訓(xùn)練時(shí)通常應(yīng)將其排除在損失計(jì)算之外。4.5 查看標(biāo)簽 PNG../tutorial/draw_label_png.py data_dataset_voc/SegmentationClass/2011_000003.png # 左語(yǔ)義標(biāo)簽 ../tutorial/draw_label_png.py data_dataset_voc/SegmentationObject/2011_000003.png # 右實(shí)例標(biāo)簽注原文檔中該命令的../tutorial/是相對(duì)于examples/instance_segmentation的寫(xiě)法對(duì)應(yīng)的倉(cāng)庫(kù)根目錄路徑為 examples/tutorial/draw_label_png.py。draw_label_png.py 會(huì)讀取標(biāo)簽 PNG自動(dòng)把255還原為-1見(jiàn)其中UNLABELED_PNG_VALUE 255的處理邏輯打印標(biāo)簽值分布與標(biāo)簽名映射并用 matplotlib 疊加偽彩色可視化也可通過(guò)--image參數(shù)同時(shí)疊加原圖。下圖為本示例 VOC 轉(zhuǎn)換輸出的三張代表性產(chǎn)物左原始 JPEG中類別標(biāo)簽可視化右實(shí)例標(biāo)簽可視化來(lái)自 examples/instance_segmentation/data_dataset_voc五、轉(zhuǎn)換為 COCO 格式數(shù)據(jù)集5.1 轉(zhuǎn)換命令與輸出目錄./labelme2coco.py data_annotated data_dataset_coco --labels labels.txt該命令生成data_dataset_coco/ ├── JPEGImages/ # 原圖RGB JPEG ├── Visualization/ # 實(shí)例分割可視化每張圖一張 └── annotations.json # COCO 格式標(biāo)注文件同樣地輸出目錄已存在會(huì)直接退出?？蛇x的--noviz參數(shù)用于關(guān)閉可視化目錄的生成。前置依賴該腳本需要pycocotoolslabelme2coco.py 在缺失時(shí)會(huì)提示pip install pycocotools并退出以及imgviz、numpy。5.2 annotations.json 結(jié)構(gòu)與生成邏輯腳本首先構(gòu)造 COCO 頂層結(jié)構(gòu)labelme2coco.py 中main()的前半部分{ info: { year: 2026, date_created: 2026-09-20 07:24:57.000000 }, licenses: [{ id: 0, name: null }], type: instances, images: [], categories: [], annotations: [] }各部分的生成規(guī)則如下categories同樣按class_id i - 1編號(hào)__ignore__被跳過(guò)不進(jìn)入類別表_background_為0images每張圖一個(gè)條目包含file_name相對(duì)輸出目錄的路徑、height、width、id按文件排序的自增編號(hào)annotations每個(gè)實(shí)例一個(gè)條目包含id、image_id、category_id、segmentation、area、bbox、iscrowd。5.3 形狀到 COCO segmentation 的轉(zhuǎn)換細(xì)節(jié)COCO 的segmentation需要多邊形坐標(biāo)列表腳本對(duì)三種常見(jiàn)形狀做了專門(mén)處理polygon多邊形頂點(diǎn)坐標(biāo)直接展平為[x1, y1, x2, y2, ...]rectangle矩形兩個(gè)對(duì)角點(diǎn)排序后展開(kāi)為 4 個(gè)頂點(diǎn)[x1, y1, x2, y1, x2, y2, x1, y2]circle圓調(diào)用_circle_to_polygon_segmentation()做多邊形近似——從最少 12 個(gè)頂點(diǎn)開(kāi)始只要弦高誤差超過(guò) 1 像素容差CIRCLE_APPROXIMATION_TOLERANCE_PX 1.0就翻倍頂點(diǎn)數(shù)直至近似誤差在 1 像素以內(nèi)。5.4 實(shí)例合并與掩碼計(jì)算與 VOC 轉(zhuǎn)換一致實(shí)例劃分同樣以(label, group_id)為鍵group_id為null時(shí)生成uuid.uuid1()作為臨時(shí)分組同一實(shí)例的多個(gè)形狀掩碼按位OR合并masks[instance] masks[instance] | mask掩碼轉(zhuǎn)為 Fortran 序 uint8 后交給pycocotools.mask.encode()得到 RLE 編碼area與bbox也由pycocotools.mask.area()/pycocotools.mask.toBbox()從掩碼計(jì)算保證面積與包圍盒與掩碼嚴(yán)格一致iscrowd恒為0。5.5 可視化輸出每張圖還會(huì)生成一張實(shí)例可視化Visualization/basename.jpg通過(guò)imgviz.instances2rgb()在圖上疊加彩色實(shí)例掩碼、類別標(biāo)簽文字與邊框例如 examples/instance_segmentation/data_dataset_coco/Visualization/2011_000003.jpg可用于快速目檢標(biāo)注質(zhì)量與轉(zhuǎn)換正確性。六、運(yùn)行前提與依賴標(biāo)注工具按倉(cāng)庫(kù)常規(guī)方式安裝 labelme 本體后使用labelme命令轉(zhuǎn)換腳本依賴numpy、imgviz、PILVOC 與 COCO 共用COCO 轉(zhuǎn)換額外需要pycocotoolsexamples/utils.py 是自包含的 JSON 標(biāo)注讀取與柵格化工具其模塊注釋明確指出它刻意不依賴 labelme 包本身只依賴標(biāo)準(zhǔn)庫(kù)、numpy 與 PIL——這既是本示例的工作參考實(shí)現(xiàn)也可以直接復(fù)制到你自己的數(shù)據(jù)加載代碼中例如 PyTorch 的Dataset無(wú)論 labelme 內(nèi)部如何演進(jìn)都能穩(wěn)定工作。七、總結(jié)從本示例可以提煉出一條完整的實(shí)例分割數(shù)據(jù)生產(chǎn)流水線用labels.txt定義類別含__ignore__、_background_兩個(gè)特殊條目用labelme配合--validate-label exact與--label-flags完成高質(zhì)量標(biāo)注注意通過(guò)group_id表達(dá)同一實(shí)例的多個(gè)碎片用 labelme2voc.py 輸出 VOC 格式JPEGImages SegmentationClass/Object 的 PNG/npy/可視化供語(yǔ)義與實(shí)例分割模型使用用 labelme2coco.py 輸出 COCO 格式JPEGImages annotations.json供基于 COCO API 的檢測(cè)/分割框架直接消費(fèi)最后用 draw_label_png.py 或Visualization目錄核對(duì)標(biāo)簽值與實(shí)例劃分是否符合預(yù)期。理解class_id i - 1、255 -1ignore以及(label, group_id)實(shí)例合并這三條核心約定你就能完全掌握 labelme 實(shí)例分割數(shù)據(jù)在 VOC 與 COCO 兩大生態(tài)之間的自由轉(zhuǎn)換。【免費(fèi)下載鏈接】labelmeImage annotation with Python. Supports polygon, rectangle, circle, line, point, and AI-assisted annotation.項(xiàng)目地址: https://gitcode.com/gh_mirrors/la/labelme創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考