面向遙測 / 衛星 / 航空影像之船舶偵測研究的 PyQt6 資料工程 GUI 工作台。
支援多類別 HBB 標註、YOLO 格式匯入匯出、prediction overlay、error analysis、dataset QC、tile sliding-window 視圖、copy-paste augmentation、屬性標註、統計分析,以及 autosave 和 project config 持久化。
- Python 3.10+
- 作業系統:macOS / Windows / Linux
在終端機執行以下指令,並保持工作目錄位於儲存庫根目錄:
git clone https://github.com/samhung1205/DetectionData_Engine.git
cd DetectionData_Engine
python -m venv .venv啟用虛擬環境:
# macOS / Linux
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1python -m pip install -r requirements.txt依賴套件:
| 套件 | 版本 | 用途 |
|---|---|---|
| numpy | >=1.20.0 | 影像矩陣運算 |
| opencv-python | >=4.5.0 | 影像讀取、resize、rotation |
| PyQt6 | >=6.4.0 | GUI 框架 |
| PyYAML | >=6.0.0 | classes.yaml / project_config.yaml 讀寫 |
python GUI.py- 啟動後使用 Open Image 或 Open Folder 選取自己的影像。
- 開啟 File → Class mapping,確認類別名稱與 class id 對應。
- 使用 Create RectBox 畫框,或透過 File → Load Label 載入已有標註。
- 在 Labels / Attributes / Paste 分頁查看標註、設定研究屬性或建立合成樣本。
- 使用 Save Label 輸出標註;若有貼圖合成,也使用 Save Image 儲存合成影像。
- 需要模型輔助時,載入 prediction txt 或安裝選用推論套件並載入模型,再逐筆 Accept / Reject。
- 點擊左側 Open Image 按鈕,或選單 File → Open Image(Windows / Linux:
Ctrl+O;macOS:Cmd+O) - 也可用選單 File → Open Folder… 載入整個資料夾,之後用 Previous image / Next image 逐張瀏覽
- 支援 JPG / JPEG / PNG / GIF / BMP / TIFF 格式
- 開圖後畫布自動顯示,可用 zoom in / zoom out 或拖曳 slider 縮放
- 滑鼠移到主圖上時,會出現浮動 local zoom preview,方便檢查小船、邊界與密集區細節
- 點擊左側 Class mapping 按鈕,或選單 File → Class mapping(Windows / Linux:
Ctrl+I;macOS:Cmd+I) - 開啟對話框可新增、刪除、編輯類別(class_id / class_name / super_category)
- 主路徑為
ClassMappingDialog + classes.yaml - 若目前有載入
project_config.yaml,會優先使用該 project 指定的classes_yaml - 儲存後更新目前 project 對應的
classes.yaml,YOLO 匯入匯出的 class index 即依此對照 - 標註 rename、paste rename、prediction accept/rewrite 都以目前
classes.yaml為準;若要新增新類別,需先到 Class mapping 更新 catalog - 啟動時自動從工作目錄讀取
project_config.yaml;若有設定classes_yaml,就從該路徑載入 class catalog
- 點擊 Create RectBox 按鈕進入標註模式
- 在畫布上點擊確定框的第一角,再點擊對角完成框
- 彈出對話框選擇類別名稱
- 標註會即時顯示在 Box Labels 列表和畫布上(綠色框線)
- 選取
Box Labels中的既有框後,可在畫布上拖曳框內部移動,或拖曳四個角點手動縮放 - 勾選 Hide Box 可暫時隱藏所有框
- 右鍵點擊列表項目可 Rename(改類別)或 Delete(刪除單筆)
- Delete all 按鈕清除所有標註
每個標註框可設定以下研究屬性(右側面板):
| 屬性 | 選項 | 說明 |
|---|---|---|
| size_tag | small / medium / large | 依 COCO 面積閾值自動計算,可手動改 |
| crowded | false / true | 是否在擁擠場景 |
| hard_sample | false / true | 是否作為 hard example / hard sample |
| occluded | false / true | 是否有遮擋 |
| truncated | false / true | 是否被截斷 |
| blurred | false / true | 是否模糊 |
| difficulty_tag | normal / hard / uncertain | 標註難度 |
| difficult_background | false / true | 是否屬於背景複雜的難例 |
| low_contrast | false / true | 是否屬於低對比難例 |
| scene_tag | near_shore / offshore / unknown | 場景類型 |
選擇列表中的框後,右側面板會載入該框的屬性,修改後即時同步。
其中 hard_sample / occluded / truncated / blurred / difficult_background / low_contrast 以 checkbox 呈現,方便快速做研究屬性與難例標記。
- Load Label:選單或左側按鈕,支援:
- YOLO HBB 格式 txt(
class_id xc yc w h,歸一化座標) - COCO bbox JSON(會依目前開啟影像的檔名選出對應 image/annotations)
- annotation metadata JSON(支援本專案匯出的 research metadata records,會還原 bbox 與屬性)
- 預設會從
project_config.yaml的label_root開始選檔 - 載入前可選擇 Append GT 或 Replace GT
Append GT:把載入結果追加到目前 GT 標註Replace GT:用載入結果覆蓋目前 GT 標註(paste annotations 不受影響)
- YOLO HBB 格式 txt(
- Save Label:彈出對話框,選擇格式:
- YOLO(v5~10):歸一化中心座標
class_id xc yc w h - Bounding Boxes:絕對座標
class_id x1 y1 x2 y2 - COCO JSON:單張影像的
images / annotations / categories結構,bbox 為[x, y, w, h] - Pascal VOC XML:單張影像的
annotation/object/bndboxXML
- YOLO(v5~10):歸一化中心座標
Save Label會把目前影像中的 GT + committed paste annotations 一起輸出Save Label對話框的預設格式會跟project_config.yaml的default_export_format一致- 若目前影像位於
image_root之下,預設輸出路徑會映射到label_root對應位置,例如images/train/a.jpg -> labels/train/a.txt - Show Label:在新視窗中預覽當前標註疊圖
- Load preds(左側按鈕)或選單 File → Load predictions…
- 讀取 YOLO 格式 txt,支援第 6 欄 confidence:
class_id xc yc w h [conf] - 若目前影像位於
images/資料夾,prediction 檔案選擇器會優先從相鄰的predictions/資料夾開啟,例如dataset/test/images→dataset/test/predictions - 也可用選單 File → Load prediction folder… 指定一個 prediction sidecar 資料夾;之後在資料夾瀏覽模式下切換影像時,會自動讀取同 basename 的
.txtprediction 檔 - 會建立 session 內的 review queue 狀態:
pending / partial / reviewed - 下方狀態列會顯示目前 queue 摘要,例如 pending 數量與當前影像的 accepted / rejected / remaining
- 選單 File → Next review image 可直接跳到下一張尚未 reviewed且有 prediction sidecar 的影像
- review queue 會以「目前 image folder + prediction folder」為 key 持久化到 sidecar state;重新載入同一組資料夾時,可選擇 Resume review 或 Start fresh
- 選單 File → Clear saved review state… 可清除目前這組 image folder + prediction folder 的已存 review 狀態,並立刻用 sidecar predictions 重建一輪新的 queue
- 選單 Analysis → Prediction review summary… 可對 Current folder 或 Current project 產生 review 報表
- 若目前已載入 prediction folder,會直接使用該路徑
- 若尚未載入 prediction folder,才會要求選擇
- 結果會顯示
reviewed / partial / pending / no_predictions的影像數,以及 accepted / rejected / remaining prediction 總數 - Export CSV… / Export JSON… 可匯出逐影像 review summary,方便做 project-level review 進度追蹤
- 也可用選單 File → Load YOLO model… 載入模型,再用左側 Run model 按鈕或 File → Run model prediction 直接對當前影像推論
- 模型直推論目前為 optional 功能,需要額外安裝
ultralytics與torch - 預測框以橘色虛線顯示在畫布上(與 GT 綠色實線區分)
- 勾選 Show preds 控制是否顯示
- 右上方 Pred conf >= slider 可調整顯示門檻(
0.00~1.00),同步影響 prediction list、畫布 overlay 與 error analysis 使用的 prediction 集合 - 選取左側 prediction list 中的一筆後,可在畫布上直接拖曳移動或拖四角調整大小;被修改過的 prediction 會在列表中標示為
[edited] - prediction list 右鍵可 Change class…,先修正類別再決定是否接受
- 左側預測列表中選取一筆後:
- Accept:轉為正式 GT 標註(綠色框),從預測列表移除
- Reject:刪除該筆預測
- 選單 File → Accept all visible predictions / Reject all visible predictions 可對目前 conf threshold 下可見的 prediction 批次處理
- 當當前影像的 predictions 全部處理完畢並進入
reviewed狀態時,review queue 會自動跳到下一張待審影像 - 選單 File → Clear predictions 清空所有預測
- 選單 Analysis → Run error analysis…
- 可選 scope:
- Current image:分析目前開啟影像的 GT 與目前載入的 predictions
- Current folder:掃描目前影像所在資料夾內的所有支援影像,並要求指定一個 prediction folder;若目前 project config 可解析
image_root,會先找prediction_root/<image 相對路徑>/<basename>.txt,找不到再 fallback 到prediction_root/<basename>.txt - Current project:若已載入
project_config.yaml,會以image_root為遞迴掃描範圍,並依label_root/ 選定的prediction root以相對路徑配對
- 選單 Analysis → Show GT/Pred IoU overlay 可把 IoU 配對結果直接疊在主畫布上:
- 已配對 GT / prediction 之間會畫出連線並標示
TP / WrongClass / Localization / Duplicate與 IoU - 未配對 prediction 會在框旁標示
FP - 未配對 GT 會在框旁標示
FN
- 已配對 GT / prediction 之間會畫出連線並標示
- 自動以 greedy IoU matching 比對當前 GT 與 predictions
- 顯示表格:Type / IoU / GT class / Pred class / Confidence
- 可用 Type 下拉選單快速篩選
TP / FP / FN / WrongClass / Localization / Duplicate - 可勾選 Bookmarked only 只瀏覽已收藏案例
- 若 GT 有屬性標註,還可依 Size / Scene / Difficulty / Crowded / Hard sample / Occluded / Truncated / Blurred 篩選錯誤案例,方便分析 small ship、near_shore、hard sample、遮擋或模糊樣本等研究情境
- 表格也會直接顯示這些 GT 屬性欄位,方便快速比對 error case 與資料特性
- 分類規則:
| 類型 | 條件 |
|---|---|
| TP | IoU ≥ 0.5 且類別相同 |
| WrongClass | IoU ≥ 0.5 且類別不同 |
| Localization | 0.1 ≤ IoU < 0.5 |
| Duplicate | pred 重疊已匹配的 GT |
| FP | 未匹配的 pred |
| FN | 未匹配的 GT |
- 可勾選 Bookmark、填寫 Notes
- 大量 folder / project cases 時,結果表格會限制實際渲染的前幾千筆,避免 Qt table 一次建立過多 row 造成記憶體暴增;上方 summary 仍會顯示完整 case 數
- Export CSV… 仍會匯出所有錯誤案例,不只匯出表格目前顯示的前幾千筆
- committed paste annotations 也會納入目前影像的 GT 集合一起分析,避免與實際匯出的 label 不一致
Current folder也會顯示 Image 欄位,方便在多張圖之間追 caseCurrent folder只有在目前影像真的有 live GT / committed paste,或已載入並審核過的 live prediction 狀態時,才會用 GUI 內的狀態覆蓋該張圖;若目前 GUI 狀態是空的,會回到磁碟上的 label / prediction sidecar,避免 summary 把已存在的檔案誤算成 missingCurrent folder會顯示 Predictions matched 與 Label root,方便確認實際掃描到多少 prediction sidecar,以及 GT label 是從哪個目錄解析而來- 在真正打開 folder error analysis 結果前,會先顯示一個 summary,列出
Images found / Labels matched / Predictions matched / Images analyzable / Confidence threshold Current project也會在真正打開結果前顯示相同型態的 summary,但 scope 會改成整個image_root- 若選到的 prediction folder 沒有任何同 basename 的
.txtprediction sidecar,會先提示你結果只會使用 GT labels - Analysis → Start FP-to-label review… 可直接用 folder / project error analysis 的
FProws 建立補標 queue:- 先選 scope 與 prediction folder,GUI 會依目前
Pred conf >=門檻掃描 FP candidates - 建立 queue 後會跳到第一個 FP 影像並選中對應 prediction
- Analysis → Next FP 跳到下一個 FP candidate;若下一個 candidate 仍在同一張影像,不會重新載圖,避免清掉尚未儲存的補標
- 可沿用 prediction list 的 Change class… / Accept / Reject;確認漏標後按 Accept 轉正式 GT,再補屬性並 Save Label
- FP review 期間不會觸發原本 prediction review 的自動跳下一張,避免干擾補標 queue
- 先選 scope 與 prediction folder,GUI 會依目前
- 選單 Analysis → Dataset statistics…
- 可選 scope:
- Current image:分析目前開啟影像的 GT + committed paste annotations
- Current folder:掃描目前影像所在資料夾內的所有支援影像,按 basename 尋找對應 label sidecar
- Current project:若已載入
project_config.yaml,會以image_root為遞迴掃描範圍,並依label_root以相對路徑配對 GT labels
- 多個分頁:
- Overview:總影像數、總標註數、平均每張圖標註數、類別數
- Class dist:各類別標註數量
- Size dist:small / medium / large 分布
- Scene dist:near_shore / offshore / unknown 的數量與比例
- Bbox stats:寬 / 高 / 面積 / 長寬比的 min / max / mean / std
- 若 metadata 中有
rotation_deg/angle_deg,也會一併統計旋轉角度分布
- 若 metadata 中有
- Class × Size:類別 × 尺度交叉表
- Export JSON… / Export CSV… 匯出統計結果
- Overview 也會顯示 Labeled images / Unlabeled images
Current folder目前優先讀取與影像同 basename 的.json/.txtlabel sidecar;若project_config.yaml中有設定image_root / label_root,也會嘗試依相對路徑對應到 label 目錄- 若沒有
project_config.yaml,但目前資料夾結構符合常見的images/與 siblinglabels/佈局,也會自動推斷 GT label 位置 - folder-level statistics / error analysis 讀影像尺寸時會優先只讀常見格式(BMP/JPEG/PNG/GIF/TIFF)的檔頭,不會為了拿寬高而完整解碼整張影像,避免大量 BMP 掃描時記憶體暴增
- 在真正打開 folder statistics 結果前,會先顯示一個 summary,列出
Images found / Labels matched / Annotations found Current project也會先顯示同型態的 summary,但 scope 會改成整個image_root- 若目前開啟影像有尚未另存的新標註、committed paste,或曾載入後被清空的標註狀態,
Current folder會以當前 GUI 內的 live annotations 覆蓋該張圖的磁碟 label;若目前沒有 live annotation override,則會讀取磁碟上的 label sidecar
- 選單 Analysis → Dataset QC…
- 可選 scope:
- Current folder:掃描目前影像所在資料夾內的所有支援影像
- Current project:若已載入
project_config.yaml,會以image_root為遞迴掃描範圍
- 執行前可選擇:
- Include predictions…:額外指定 prediction folder,一起檢查 prediction sidecar
- Labels only:只檢查 GT labels
- 會先顯示 summary,列出:
Images foundLabels matchedPredictions matchedIssues found
- 結果表格會列出:
ImageSource(label / prediction)Issue typeLineDetailFile
- 結果視窗另提供:
- Overview:總影像數、matched labels / predictions、clean images、images with issues
- Issue types:各 issue type 的數量與受影響影像數
- 目前內建檢查:
- missing label / missing prediction
- empty label / empty prediction
- YOLO 欄位數錯誤
- 無法解析數值
- 非法 class id
- normalized center / width / height 超出範圍
- bbox 超出
[0, 1] - prediction confidence 超出
[0, 1] - 無法讀取或不支援的 label 格式
- Export CSV… 可匯出所有逐筆 issue
- Export Summary JSON… 可匯出聚合 summary,方便做 dataset health 檢查、研究紀錄與後續自動化報表
- 左下角 Tile view 面板
- 設定 Size(tile 邊長,預設 640)和 Stride(步幅,預設 480)
- 勾選 Enable 啟用分格視圖:
- 畫布上顯示綠色 tile 邊框,tile 外區域暗化
- 方向箭頭可切換上下左右鄰近 tile,index 標籤顯示
3 / 16 - 也可用
Alt + Arrow快速切換目前 tile 的上下左右鄰居 - 勾選 Overview 可回到全圖查看 tile 分布,並高亮目前 tile;在 overview 上直接點選某個 tile 可跳入該 tile
- Tile 面板會提示 Boundary 數量;若顯示
Boundary: 2,代表目前 tile 內有 2 個 GT 框跨越 tile 邊界,需留意重複標註或截斷漏標
- tile 只是視角,所有標註始終寫回全圖座標,切換 tile 不會造成框漂移
- 點擊 Paste Image 按鈕進入貼圖模式
- 右下方 Choose Image 選擇 PNG asset(含 alpha 透明通道)
- 可在 Mode 切換
Manual / Smart zone;Smart zone會要求先用 Set zone 在畫布上框出可貼圖區域,只有完整落在該區域內的 paste 才能 Add - Target 可選
small / medium / large,右側會顯示目前 zoom/export 比例下的建議縮放範圍與目前 paste 尺度 - 用 7 個 slider 調整:Resize / Rotation / Brightness / Contrast / Blur / Opacity / Feather
- Effects (n) 可開啟進階效果對話框,設定陰影強度、距離與方向,以及動態模糊的長度與角度;已有貼圖預覽時,調整會即時顯示,按 Cancel 回復原先設定
- 勾選 HorizontalFlip / VerticalFlip 控制翻轉
- 在畫布上點擊放置,自動偵測 alpha 邊界產生 bbox
- 若最終 alpha 幾乎為空(例如 opacity 太低),預覽仍會更新,但 Add 會保持 disabled,避免提交空貼圖
- 每次貼圖自動記錄
PasteRecord(含 asset 路徑、flip / blur / opacity / feather 等 transform 參數、bbox、timestamp) - 選單 File → Export paste metadata (JSON/CSV) 匯出完整操作紀錄
- 一旦 Add 成功,該 paste annotation 會視為正式可匯出標註,並納入 metadata export / statistics / error analysis
- Save Image 會以原圖解析度重建合成結果,不會直接把當前 GUI 縮放畫面存出去;若想避免 JPEG 再壓縮,建議存成 PNG / BMP
- 選單 File → Export annotation metadata (JSON)… / (CSV)…
- 匯出每筆標註的完整欄位:image_path / class_id / class_name / super_category / x1 / y1 / x2 / y2 / size_tag / crowded / hard_sample / occluded / truncated / blurred / difficulty_tag / difficult_background / low_contrast / scene_tag / annotation_source
annotation_source會標記來源為gt或paste- metadata export 目前會把 GT + committed paste annotations 一起匯出
- 選單 Edit → Undo(Windows / Linux:
Ctrl+Z;macOS:Cmd+Z) / Redo(Windows / Linux:Ctrl+Shift+Z或Ctrl+Y;macOS:Cmd+Shift+Z) - 最多保留 50 步操作紀錄
- 支援:新增框、刪除框、清除全部、重新命名、批次載入 label
- 開圖後自動啟動定時器(預設 60 秒),週期性存檔到
.autosave/目錄 - 存檔格式:
<圖片名>.autosave.json(含 real_data + box_attributes + object_list) - 下次開同一張圖時,若偵測到 autosave 檔,自動詢問是否恢復
- 手動 Save Label 成功後自動清除 autosave 檔
- 狀態列顯示 "Autosaved" / "Restored from autosave" / "Saved (autosave cleared)"
- 選單 File → Open project config… / Save project config…
- 設定檔格式為
project_config.yaml,包含:
project_name: ship_detection_project
project_root: "."
image_root: dataset
label_root: dataset
classes_yaml: classes.yaml
default_export_format: yolo_hbb
autosave_seconds: 60
recent_images: []
tile_size: 640
tile_stride: 480- 啟動時自動讀取工作目錄下的
project_config.yaml(如果存在) - 開圖時自動加入
recent_images project_config.yaml現在會實際控制:classes_yaml:啟動時 class catalog 的載入位置,以及 class mapping dialog 的預設讀寫位置image_root:Open Image / Open Folder 的預設起始目錄label_root:Load Label 的預設起始目錄,以及 Save Label 的預設輸出根目錄default_export_format:Save Label 對話框的預設格式autosave_seconds/tile_size/tile_stride
project_root與其他相對路徑會以project_config.yaml所在位置解析,因此每個研究專案都可以攜帶自己的一套 classes / images / labels / export defaults
| 快捷鍵 | 功能 |
|---|---|
W |
Create RectBox |
D |
Delete selected box |
S |
Save Label |
H |
Hide / Show boxes |
Ctrl+O / Cmd+O |
Open Image |
Ctrl+I / Cmd+I |
Class mapping |
Ctrl+L / Cmd+L |
Load Label |
Ctrl+Z / Cmd+Z |
Undo |
Ctrl+Shift+Z / Ctrl+Y / Cmd+Shift+Z |
Redo |
Alt+Arrow |
Tile 上下左右導航 |
Alt+G |
Toggle tile overview |
GUI.py:應用程式啟動入口。gui/:操作介面與應用程式圖示。sdde/:標註、匯入匯出、預測審核與分析服務。classes.yaml:預設類別;可透過 Class mapping 修改。tests/:自動化測試。docs/manual_smoke_test.md:進階功能的手動驗證清單。
此儲存庫提供 SDDE GUI 原始碼。研究影像、標註資料集、透明貼圖素材、模型權重、分類器研究子專案與論文素材未隨程式散布;請使用自行取得且有使用權限的資料。
- 模型推論不可用:在同一 Python 環境額外安裝
ultralytics與torch,並在介面選取可信來源的模型檔案。模型權重未附在儲存庫中。 - 沒有影像或貼圖可選:自行準備影像資料夾;Copy-Paste 使用含 alpha 透明通道的 PNG 素材。
- 類別或匯出編號不符:先檢查 Class mapping,確保
classes.yaml與資料集的 class id 定義一致。 - 分享研究輸出:annotation / paste metadata、review state 和 project config 可能含影像路徑、素材路徑、最近開啟檔案與備註。分享前請檢查並移除私人內容。
- 自動儲存的限制:autosave 保存 GT 標註;貼圖合成結果與其相關資料請另外使用 Save Image、Save Label 和 metadata export 儲存。
project_name: ship_detection_project
classes:
- class_id: 0
class_name: naval
super_category: vessel
- class_id: 1
class_name: merchant
super_category: vessel0 0.5125 0.3200 0.0850 0.1200
1 0.7800 0.6500 0.1200 0.0900
每行:class_id x_center y_center width height(相對於圖片寬高的 0~1 值)
0 0.5125 0.3200 0.0850 0.1200 0.87
1 0.7800 0.6500 0.1200 0.0900 0.62
第 6 欄為信心分數(可略,預設 1.0)
project_name: ship_detection_project
project_root: "."
image_root: dataset
label_root: dataset
classes_yaml: classes.yaml
default_export_format: yolo_hbb
autosave_seconds: 60
recent_images: []
tile_size: 640
tile_stride: 480此工具提供研究使用。目前儲存庫尚未附正式授權條款;若需再散布、修改後發布或用於其他用途,請先向專案維護者確認授權範圍。研究資料、模型與外部素材須另行遵守各自授權。