跳轉到

九、 其他工具

其他工具 模組整合了資料集規範化校驗與標註格式靈活轉換的實用工具,用於解決專案後期的資料冗餘與格式相容性問題。


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,全部歸一化)。
  • 自動標籤對映:
    • 第一輪掃描自動彙總所有唯一的 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 工業視覺處理流程):
    • 內外圓偵測(先外後內):
      1. 閾值 [0, 180] 提取暗區連通域;
      2. 按 Min Area = 70 過濾,取最大連通域作為外圓盤;
      3. 對外圓盤 fill_up 填洞得到實心外圓;
      4. 用「填洞結果 與 外圓盤」的單向差(A AND NOT B)得到內孔環帶;
      5. 再對內孔環帶取最大連通域,擬合得到內圓圓心與半徑;
      6. 最後對外圓盤單獨擬合一次,得到外圓圓心與半徑。
    • 極座標展開:按公式 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 畫素,否則極座標展開後高度極小,裁切結果可能為空。