九、 其他工具
其他工具 模組整合了資料集規範化校驗與標註格式靈活轉換的實用工具,用於解決專案後期的資料冗餘與格式相容性問題。
1. 符號偵測遷移 (Filename Sanitizer)¶
功能說明: 在工業視覺軟體部署時,不規範的檔名(如包含特殊字元、空格或非法符號)往往會導致路徑解析崩潰或模型讀取失敗。
- 偵測範圍:
- 自動掃描資料集中的所有影像與 JSON 檔名。
- 識別隱藏的非法符號,即使是常見的英文橫槓
-、空格、或中文字元。
- 處理邏輯:
- 自動更名:一鍵將不規範檔名遷移到自定義的輸出目錄裡。
開發筆記
在 Windows 下看似正常的檔名,在 Linux 或某些嵌入式視覺運算子中可能會引起閃退。建議在模型訓練前,統一執行一次符號偵測。
2. JSON 多邊形轉矩形 (Polygon to BBox)¶
功能說明: 將精細的“多邊形(Polygon)”標註轉換為標準的“外接矩形框(Bounding Box)”標註。
- 轉換邏輯:
- 系統會自動提取多邊形所有頂點的最大/最小座標值。
- 自動計算出能夠完全包裹該多邊形的最小水平矩形。
- 適用場景:
- 演算法降級:當專案從分割演算法(Segmentation)切換為偵測演算法(Detection)時,無需重新標註。
- 格式統一:快速統一來自不同標註團隊或不同版本軟體的異構資料。
轉換特性
轉換過程為非破壞性轉換。生成的矩形框將嚴格遵循 YOLO 或標準 JSON 座標規範,方便直接投入訓練。
3. LabelMe JSON 轉 YOLO TXT (LabelMe to YOLO)¶
功能說明:
將 LabelMe 標註的 JSON 檔案一鍵轉換為 YOLO 系列訓練所需的 .txt 標註檔案,並自動生成資料集配置檔案 data.yaml。
- 支援的標註型別:
- rectangle:物件偵測(
class_id x_center y_center width height,全部歸一化)。 - polygon:例項分割(
class_id x1 y1 x2 y2 ... xn yn,全部歸一化)。 - obb:旋轉物件偵測(
class_id x1 y1 x2 y2 x3 y3 x4 y4,全部歸一化)。
- rectangle:物件偵測(
- 自動標籤對映:
- 第一輪掃描自動彙總所有唯一的
label,按字母序生成class_id。 - 第二輪掃描統一寫入
.txt,避免人工對照類別表的繁瑣步驟。
- 第一輪掃描自動彙總所有唯一的
- 配套產出:
- 自動複製對應的影像檔案(
jpg/png/jpeg/bmp/webp,自動嘗試常見大小寫字尾)。 - 在輸出目錄生成
data.yaml,直接可用於 YOLO 訓練框架。
- 自動複製對應的影像檔案(
使用建議
推薦配合「其他工具」模組中“符號偵測遷移”先行清洗檔名,可以減少 imagePath 欄位錯位、影像匹配失敗的情況。
4. JSON 多邊形智慧合併 (Polygon Merge)¶
功能說明: 針對工業場景中常見的“同一種缺陷被切成多個小段”標註情況,按類別對多邊形進行帶縫隙橋接的智慧合併,並把真正不相交的獨立缺陷保留為單獨個體。
- 核心策略:
- 微膨脹橋接:使用
buffer(bridge_distance)把距離非常近的相鄰多邊形粘合,再unary_union融合。 - 拆分恢復:融合結果若為
MultiPolygon,會逐一還原成獨立的多邊形(再buffer(-bridge_distance)收縮回原大小)。 - 拓撲簡化:用
simplify(simplify_tolerance, preserve_topology=True)去掉無用死點,避免訓練時模型學到“毛刺”。
- 微膨脹橋接:使用
- 可調引數:
bridge_distance:橋接縫隙的畫素距離。小於該值的會被融合,大於該值的會保持完全獨立。simplify_tolerance:拓撲簡化容差,數值越大頂點數越少(標註更“乾淨”)。
使用建議
bridge_distance 預設 2.0 適合 1080p 量級的工業圖。若解析度差異較大(如 4K 相機),建議按比例上調,避免“誤合併”獨立缺陷。
5. 環形圖展平裁切 (Circular Image Flatten & Crop)¶
功能說明: 針對環形工件(金屬軸承 / 法蘭 / 端面、玻璃瓶口、塑膠輪轂、橡膠密封圈、印刷標籤環、食品包裝圓環等任何可拍成俯視圓環的樣品)的俯拍圖,自動偵測內外圓,將環形區域極座標展開為矩形,再按指定寬度和重疊率做滑窗裁切,方便後續用常規的物件偵測/分割模型訓練(YOLO、U-Net、RT-DETR 等都直接吃矩形圖)。
- 演算法要點(
utils/cut.py,源自 HALCON 工業視覺處理流程):- 內外圓偵測(先外後內):
- 閾值
[0, 180]提取暗區連通域; - 按
Min Area = 70過濾,取最大連通域作為外圓盤; - 對外圓盤
fill_up填洞得到實心外圓; - 用「填洞結果 與 外圓盤」的單向差(
A AND NOT B)得到內孔環帶; - 再對內孔環帶取最大連通域,擬合得到內圓圓心與半徑;
- 最後對外圓盤單獨擬合一次,得到外圓圓心與半徑。
- 閾值
- 極座標展開:按公式
r = outer - (row / H) * (outer - inner) - 3反向取樣原圖,頂部 = 外圈、底部 = 內圈,符合視覺直覺;自動適配灰度圖與彩色圖(按通道分別cv2.remap後np.stack)。 - 滑窗裁切:預設
CropWidth = 600、Overlap = 150,相鄰視窗透過重疊率保證不漏檢。
- 內外圓偵測(先外後內):
- 可調引數(介面預設已填好):
CropWidth:每個子圖的橫向畫素。Overlap:相鄰子圖的重疊畫素,決定視窗滑動步長 =CropWidth - Overlap。
- 健壯性:
- 相容含中文、
&、()等特殊字元的路徑(用np.fromfile+cv2.imdecode讀圖,cv2.imencode+tofile寫圖,繞開 OpenCV 對非 ASCII 路徑的解碼 bug)。 - 輸出 BMP(
cv2.imencode在非 TIFF 編碼下最穩),檔名自動追加_part_NNN。
- 相容含中文、
使用建議
一次只處理一張圖,若環形孔洞接近外圈(薄環),建議先確認內外圓間距 ≥ 20 畫素,否則極座標展開後高度極小,裁切結果可能為空。