Add autoflow
This commit is contained in:
parent
7e323cf3e1
commit
1e42293896
173
.autoflow/00-onboarding/health-check.md
Normal file
173
.autoflow/00-onboarding/health-check.md
Normal file
@ -0,0 +1,173 @@
|
||||
# 專案健檢報告 — KNEO Academy
|
||||
|
||||
## 基本資訊
|
||||
- **專案名稱**：KNEO Academy（Innovedus AI Playground）
|
||||
- **版本**：v2.0
|
||||
- **程式碼來源**：本地路徑 `C:\Users\sungs\Documents\abin\KNEO-Academy`
|
||||
- **主要語言**：Python 3.12
|
||||
- **最後更新時間**：2026-04-04
|
||||
- **Git branch**：main
|
||||
|
||||
---
|
||||
|
||||
## 技術堆疊
|
||||
|
||||
| 層級 | 技術 | 版本 |
|
||||
|------|------|------|
|
||||
| GUI 框架 | PyQt5 | 5.15.11 |
|
||||
| 電腦視覺 | OpenCV | 4.10.0.84 |
|
||||
| AI 推論 SDK | KneronPLUS | 3.1.2 |
|
||||
| AI 推論（通用） | PyTorch, TensorFlow, ONNX Runtime | 最新 |
|
||||
| 音訊 | librosa, sounddevice | — |
|
||||
| 打包 | PyInstaller | 6.12.0 |
|
||||
| 加密 | PyArmor | — |
|
||||
|
||||
---
|
||||
|
||||
## 專案結構概覽
|
||||
|
||||
```
|
||||
KNEO-Academy/
|
||||
├── main.py # Entry point，AppController（QStackedWidget 管理頁面）
|
||||
├── src/
|
||||
│ ├── config.py # 全域常數、路徑、顏色、DeviceType enum
|
||||
│ ├── controllers/
|
||||
│ │ ├── device_controller.py # Kneron dongle 掃描、連接、韌體上傳
|
||||
│ │ ├── inference_controller.py # 推論工具選擇、model 載入、queue 管理
|
||||
│ │ └── media_controller.py # 相機、影片捕捉
|
||||
│ ├── models/
|
||||
│ │ ├── inference_worker.py # 標準推論 worker thread（動態載入 script.py）
|
||||
│ │ ├── custom_inference_worker.py # 自定義模型推論 worker（YOLOv5 後處理）
|
||||
│ │ └── video_thread.py # 相機影像擷取 thread
|
||||
│ ├── views/
|
||||
│ │ ├── mainWindows.py # 主應用視窗（推論結果顯示、工具選擇）
|
||||
│ │ ├── selection_screen.py # 首頁選擇畫面
|
||||
│ │ ├── login_screen.py # 工具程式登入頁
|
||||
│ │ └── utilities_screen.py # 裝置管理工具頁
|
||||
│ ├── services/
|
||||
│ │ ├── device_service.py # 掃描 Kneron 裝置（含 timeout 機制）
|
||||
│ │ ├── file_service.py # 檔案上傳服務
|
||||
│ │ └── script_service.py # 推論腳本執行服務
|
||||
│ └── utils/
|
||||
│ ├── config_utils.py # 設定工具
|
||||
│ └── image_utils.py # QImage ↔ NumPy 轉換
|
||||
├── uxui/ # 靜態 UI 資源（PNG、SVG、GIF）
|
||||
├── dist/
|
||||
│ └── test.iss # Inno Setup 安裝包設定
|
||||
├── flowchart.md # 裝置連接流程設計圖（Mermaid）
|
||||
└── env.txt # pip 套件清單
|
||||
```
|
||||
|
||||
**資料目錄（執行期，存在 %LOCALAPPDATA%/Kneron_Academy/）：**
|
||||
```
|
||||
uploads/ # 使用者上傳的圖片/影片
|
||||
utils/
|
||||
config.json # 全域 plugin 設定
|
||||
{mode}/{model}/
|
||||
script.py # 推論腳本
|
||||
config.json # 模型設定
|
||||
*.nef # 模型檔
|
||||
firmware/
|
||||
{device}/
|
||||
fw_scpu.bin
|
||||
fw_ncpu.bin
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 應用頁面流程
|
||||
|
||||
```
|
||||
SelectionScreen（首頁）
|
||||
├── → LoginScreen → UtilitiesScreen（裝置管理工具，需登入）
|
||||
└── → MainWindow（Demo AI App，直接進入）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 主要功能清單
|
||||
|
||||
| 功能 | 描述 | 狀態 |
|
||||
|------|------|------|
|
||||
| 頁面路由 | QStackedWidget 管理多頁面切換 | ✅ 完成 |
|
||||
| 裝置掃描 | 掃描連接的 Kneron dongle（KL520 / KL720） | ✅ 完成 |
|
||||
| 裝置連接 | 連接裝置並上傳 firmware | ✅ 完成 |
|
||||
| 裝置中斷 | 安全中斷連接 | ✅ 完成 |
|
||||
| Video 推論 | 相機即時推論（QThread + queue） | ✅ 完成 |
|
||||
| Image 推論 | 上傳圖片單次推論 | ✅ 完成 |
|
||||
| 動態 Script 載入 | 從 utils/ 目錄動態 import script.py | ✅ 完成 |
|
||||
| 自定義模型推論 | 上傳 .nef + firmware，使用 YOLOv5 後處理 | ✅ 完成 |
|
||||
| Plugin 系統 | 透過 config.json 定義 mode/model 結構 | ✅ 完成 |
|
||||
| APP 打包 | PyInstaller 打包 + Inno Setup 安裝包 | ✅ 有設定 |
|
||||
| 登入驗證 | Server 驗證（詳細流程見 flowchart.md） | 🔄 設計中（有 flowchart） |
|
||||
| Dongle 授權管理 | KN 號碼查詢、授權卡驗證 | 🔄 設計中（有 flowchart） |
|
||||
|
||||
---
|
||||
|
||||
## 文件完整度
|
||||
|
||||
| 文件類型 | 狀態 | 位置 | 備註 |
|
||||
|---------|------|------|------|
|
||||
| README | ✅ 有 | `README.md` | 完整，含安裝、架構、功能說明 |
|
||||
| 流程圖 | ⚠️ 部分 | `flowchart.md` | 僅有裝置連接/授權流程，缺主 App 完整流程 |
|
||||
| PRD / 需求文件 | ❌ 無 | — | 無正式產品需求文件 |
|
||||
| 架構設計文件 | ❌ 無 | — | 無正式架構文件 |
|
||||
| API 文件 | ❌ 無 | — | 無（script.py 介面未有規格文件） |
|
||||
| 設計稿 | ⚠️ 部分 | `uxui/` | 有 UI 資源圖，無 Wireframe 或設計規格 |
|
||||
| TDD（技術設計文件） | ❌ 無 | — | 無 |
|
||||
| 測試文件 | ❌ 無 | — | README 提到 tests/ 目錄，但實際不存在 |
|
||||
| 部署文件 | ⚠️ 部分 | `dist/test.iss` | 有 Inno Setup 設定，無完整部署指南 |
|
||||
|
||||
---
|
||||
|
||||
## 程式碼健康度
|
||||
|
||||
| 項目 | 狀態 | 備註 |
|
||||
|------|------|------|
|
||||
| 測試覆蓋率 | ❌ 無測試 | tests/ 目錄不存在 |
|
||||
| 程式碼組織 | ✅ 良好 | MVC 架構清晰，職責分明 |
|
||||
| Docstring 完整度 | ✅ 良好 | 主要類別和方法均有完整 docstring |
|
||||
| 錯誤處理 | ⚠️ 部分 | 多處使用 try/except，但部分只 print 不處理 |
|
||||
| Thread 安全 | ⚠️ 待確認 | Queue 管理有，但 UI 更新路徑需確認 |
|
||||
| 技術債 | ⚠️ 少量 | debug print 語句散落在 controller 中 |
|
||||
|
||||
---
|
||||
|
||||
## 基礎設施
|
||||
|
||||
| 項目 | 狀態 | 備註 |
|
||||
|------|------|------|
|
||||
| Docker | ❌ 無 | 桌面應用，暫不需要 |
|
||||
| CI/CD | ❌ 無 | 無自動化建置/測試流程 |
|
||||
| 打包 | ✅ 有 | PyInstaller + Inno Setup |
|
||||
| 加密 | ⚠️ 計畫中 | PyArmor 已列在計畫中 |
|
||||
| 監控 | ❌ 無 | 無 |
|
||||
|
||||
---
|
||||
|
||||
## 目前正在修改的檔案（git status）
|
||||
|
||||
以下檔案有未提交的修改：
|
||||
|
||||
- `src/controllers/device_controller.py`
|
||||
- `src/controllers/inference_controller.py`
|
||||
- `src/models/custom_inference_worker.py`
|
||||
- `src/models/video_thread.py`
|
||||
- `src/services/device_service.py`
|
||||
- `src/views/utilities_screen.py`
|
||||
|
||||
---
|
||||
|
||||
## 缺失項目摘要
|
||||
|
||||
**高優先：**
|
||||
- PRD / 需求文件（產品功能邊界不清晰）
|
||||
- 測試（完全沒有自動化測試）
|
||||
|
||||
**中優先：**
|
||||
- 架構文件 / TDD（plugin script.py 介面規格未文件化）
|
||||
- 完整流程圖（主 App 推論流程尚未有流程圖）
|
||||
|
||||
**低優先：**
|
||||
- 部署完整指南
|
||||
- 設計規格文件（Wireframe + Design Tokens）
|
||||
625
.autoflow/02-prd/PRD.md
Normal file
625
.autoflow/02-prd/PRD.md
Normal file
@ -0,0 +1,625 @@
|
||||
# KNEO Academy（Innovedus AI Playground）v2.0 — 產品需求文件（PRD）
|
||||
|
||||
> **文件性質說明**：本 PRD 為從既有程式碼與文件反向整理而成，已對照 README.md、flowchart.md、主要 controller、view 和 service 原始碼推導。標注「⚠️ 待確認」的項目為推斷內容，請產品負責人核實。
|
||||
|
||||
---
|
||||
|
||||
## 1. 產品概述
|
||||
|
||||
### 1.1 產品定位
|
||||
|
||||
**KNEO Academy**（對外名稱：**Innovedus AI Playground**）是一款 Windows 桌面應用程式，讓擁有 Kneron NPU USB Dongle 硬體的客戶能夠在本機端執行 AI 推論，無需雲端服務、無需自行撰寫程式碼。
|
||||
|
||||
**核心價值主張**：
|
||||
- 即插即用的 Edge AI 體驗——插上 Kneron dongle 即可執行 AI 模型
|
||||
- 支援多種推論模式（即時攝影機、圖片上傳、自定義模型）
|
||||
- 透過 Plugin 系統讓第三方或 Kneron 官方模型能被彈性載入
|
||||
- 提供硬體管理工具（韌體更新、驅動安裝、裝置授權）
|
||||
|
||||
### 1.2 目標使用者
|
||||
|
||||
**主要使用者（Persona A）：企業/研發客戶**
|
||||
- 角色：使用 Kneron NPU 硬體進行 AI PoC 或產品評估的工程師、研究人員
|
||||
- 目標：快速驗證 Kneron NPU 在特定任務上的推論效果
|
||||
- 技術素養：中等（懂 AI 概念，不一定熟悉 SDK 整合）
|
||||
- 痛點：Kneron SDK 入門門檻高，想要一個能快速展示能力的工具
|
||||
|
||||
**次要使用者（Persona B）：內部 Demo / 業務展示**
|
||||
- 角色：Kneron / Innovedus 業務或技術支援人員
|
||||
- 目標：向潛在客戶展示 Kneron NPU 的 AI 推論能力
|
||||
- 技術素養：低至中等
|
||||
- 痛點：需要一個無需開發、開箱即用的展示工具
|
||||
|
||||
**⚠️ 待確認**：上述 Persona 定義是從產品功能推斷。實際目標客群請與產品負責人確認。
|
||||
|
||||
### 1.3 應用名稱對照
|
||||
|
||||
| 名稱 | 用途 |
|
||||
|------|------|
|
||||
| KNEO Academy | 專案內部/開發用名稱 |
|
||||
| Innovedus AI Playground | 對外正式名稱（`APP_NAME` 常數定義） |
|
||||
|
||||
---
|
||||
|
||||
## 2. 支援的硬體裝置
|
||||
|
||||
應用程式目前支援以下 Kneron NPU Dongle 型號（來自 `config.py` 的 `DeviceType` Enum）：
|
||||
|
||||
| 裝置型號 | Product ID（Hex） | 支援狀態 |
|
||||
|---------|-----------------|---------|
|
||||
| KL520 | 0x100 | ✅ 已支援（有 icon、model map） |
|
||||
| KL720 | 0x720 | ✅ 已支援（有 icon、model map） |
|
||||
| KL720_L | 0x200 | ⚠️ Enum 有定義，但無 DongleModelMap 對應，**可能不完整** |
|
||||
| KL530 | — | ⚠️ Enum 有定義，但無 DongleModelMap 對應 |
|
||||
| KL832 | — | ⚠️ Enum 有定義，但無 DongleModelMap 對應 |
|
||||
| KL730 | — | ⚠️ Enum 有定義，但無 DongleModelMap 對應 |
|
||||
| KL630 | — | ⚠️ Enum 有定義，但無 DongleModelMap 對應 |
|
||||
| KL540 | — | ⚠️ Enum 有定義，但無 DongleModelMap 對應 |
|
||||
|
||||
**⚠️ 待確認**：KL520 和 KL720 以外的裝置是否已在計畫中支援？`DongleModelMap` 僅有這兩型。
|
||||
|
||||
---
|
||||
|
||||
## 3. 應用程式頁面架構
|
||||
|
||||
### 3.1 頁面流程圖
|
||||
|
||||
```
|
||||
應用程式啟動
|
||||
│
|
||||
▼
|
||||
SelectionScreen（首頁 / 入口選擇畫面）
|
||||
├── [Demo App 按鈕] ──────────────────→ MainWindow（AI Demo 推論主視窗）
|
||||
└── [Utilities 按鈕] → LoginScreen（登入畫面）
|
||||
│
|
||||
├── [登入成功] → UtilitiesScreen（裝置管理工具）
|
||||
└── [返回] → SelectionScreen
|
||||
```
|
||||
|
||||
### 3.2 各頁面功能摘要
|
||||
|
||||
| 頁面 | Class 名稱 | 主要用途 | 需要登入 |
|
||||
|------|-----------|---------|---------|
|
||||
| 首頁 | `SelectionScreen` | 選擇進入 Demo App 或 Utilities 工具 | 否 |
|
||||
| 登入畫面 | `LoginScreen` | Server 驗證，作為進入 Utilities 的門禁 | — |
|
||||
| 裝置管理工具 | `UtilitiesScreen` | 裝置掃描、韌體更新、驅動安裝、已購項目 | 是 |
|
||||
| AI Demo 主視窗 | `MainWindow` | AI 推論執行、攝影機顯示、工具選擇 | 否 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 功能需求
|
||||
|
||||
### 4.1 SelectionScreen（首頁選擇畫面）
|
||||
|
||||
**功能描述**：應用程式的入口，提供兩個主要路徑。
|
||||
|
||||
**功能清單**：
|
||||
- 顯示應用程式 Logo 與名稱
|
||||
- 「Demo App」按鈕：直接進入 AI 推論主視窗（不需登入）
|
||||
- 「Utilities」按鈕：跳轉到登入畫面，登入後才能進入裝置管理工具
|
||||
|
||||
**⚠️ 待確認**：首頁是否有其他 UI 元素（介紹文字、版本號等）？
|
||||
|
||||
---
|
||||
|
||||
### 4.2 LoginScreen（登入畫面）
|
||||
|
||||
**功能描述**：透過 Server 驗證機制保護 Utilities 功能的存取。
|
||||
|
||||
**功能清單**：
|
||||
- 帳號密碼輸入欄位
|
||||
- 登入按鈕 → 觸發 Server 驗證
|
||||
- 返回按鈕 → 回到 SelectionScreen
|
||||
|
||||
**登入結果處理**：
|
||||
| 情境 | 行為 |
|
||||
|------|------|
|
||||
| 驗證成功 | 發出 `login_success` signal → 進入 UtilitiesScreen |
|
||||
| 帳密錯誤 | 顯示「無效用戶名或密碼」提示 |
|
||||
| 多次錯誤 | Server 停止服務，顯示提示訊息 |
|
||||
| 返回 | 發出 `back_to_selection` signal → 回到 SelectionScreen |
|
||||
|
||||
**⚠️ 待確認**：
|
||||
- 登入 Server 的端點 URL 在哪裡設定？（程式碼中未見明確設定）
|
||||
- 是否有記住密碼/Token 快取機制？
|
||||
|
||||
---
|
||||
|
||||
### 4.3 UtilitiesScreen（裝置管理工具頁面）
|
||||
|
||||
**功能描述**：登入後才能存取的裝置管理介面，包含兩個子頁面。
|
||||
|
||||
#### 4.3.1 Utilities 子頁面（裝置管理）
|
||||
|
||||
**功能清單**：
|
||||
|
||||
**裝置掃描與列表**
|
||||
- 掃描當前連接的 Kneron dongle 裝置（呼叫 `check_available_device()`，含 5 秒 timeout）
|
||||
- 以表格（`QTableWidget`）顯示裝置清單，欄位包含：裝置型號、KN Number、狀態
|
||||
- 「Refresh」按鈕：重新掃描裝置
|
||||
- 未偵測到裝置時顯示提示
|
||||
|
||||
**裝置連接操作**
|
||||
- 選擇裝置後可執行連接（透過 `DeviceController.connect_device()`）
|
||||
- 連接過程：
|
||||
1. 驗證 firmware 檔案是否存在（`%LOCALAPPDATA%/Kneron_Academy/firmware/{device}/`）
|
||||
2. 呼叫 `kp.core.connect_devices()`
|
||||
3. 上傳 firmware（`fw_scpu.bin` + `fw_ncpu.bin`）
|
||||
- 中斷連接按鈕（`DeviceController.disconnect_device()`）
|
||||
|
||||
**Firmware 管理**
|
||||
- 顯示目前 Firmware 版本
|
||||
- 偵測到版本需要更新時，提示使用者是否更新
|
||||
- 支援從本機載入 firmware 檔案進行更新
|
||||
|
||||
**Driver 管理**（⚠️ 設計中，尚未完整實作）
|
||||
- 偵測 Kneron USB driver 是否已安裝
|
||||
- 尚未安裝時：提示安裝，詢問使用者是否執行安裝程序
|
||||
- 安裝失敗處理：顯示錯誤訊息
|
||||
|
||||
**Dongle 授權管理**（⚠️ 設計中，尚未完整實作）
|
||||
- 查詢 KN Number（Dongle 唯一識別號）
|
||||
- 授權卡（Authorization Card）驗證流程
|
||||
- 已授權裝置：顯示已授權提示
|
||||
- 未授權裝置：詢問是否啟動授權，執行授權流程
|
||||
- **詳細流程見 `flowchart.md`**
|
||||
|
||||
**狀態顯示**
|
||||
- `QProgressBar`：顯示操作進度（連接、韌體上傳等）
|
||||
- `QLabel`（status_label）：顯示目前狀態訊息
|
||||
|
||||
#### 4.3.2 Purchased Items 子頁面（已購項目）
|
||||
|
||||
**功能描述**：顯示用戶已購買的 AI 模型，可以下載到本機。
|
||||
|
||||
**功能清單**：
|
||||
- 表格顯示已購買項目，欄位：Select（勾選）、Product（產品名）、Model（模型名）、Current Version（版本）、Compatible Dongles（相容裝置）
|
||||
- 多選（Checkbox）功能
|
||||
- 「Refresh Items」按鈕：重新從 Server 取得已購列表
|
||||
- 「Download Selected」按鈕：下載所選項目到本機
|
||||
|
||||
**⚠️ 待確認**：
|
||||
- 目前程式碼中有 `populate_mock_purchased_items()` 方法，顯示此功能使用 Mock 資料，**尚未對接真實 API**
|
||||
- 下載後的模型存放路徑？（推斷為 `%LOCALAPPDATA%/Kneron_Academy/utils/`）
|
||||
- 購買平台/Store 是否已確定？
|
||||
|
||||
---
|
||||
|
||||
### 4.4 MainWindow（AI Demo 推論主視窗）
|
||||
|
||||
**功能描述**：核心的 AI 推論展示視窗，整合攝影機顯示、工具選擇與推論結果呈現。
|
||||
|
||||
#### 4.4.1 畫面布局組件
|
||||
|
||||
| 組件 | Class 名稱 | 功能 |
|
||||
|------|-----------|------|
|
||||
| 攝影機顯示區 | `CanvasArea` | 顯示攝影機畫面和推論結果（Bounding Box 等） |
|
||||
| 裝置清單 | `DeviceList` | 顯示可連接的 dongle，讓使用者選擇 |
|
||||
| 裝置連接彈窗 | `DevicePopup` | 彈出式裝置連接確認介面 |
|
||||
| 媒體控制面板 | `MediaPanel` | 攝影機開啟/暫停、圖片上傳按鈕 |
|
||||
| AI 工具箱 | `Toolbox` | 顯示可選擇的 AI 模型（來自 config.json） |
|
||||
| 自定義模型上傳 | `CustomModelBlock` | 上傳自定義 .nef 模型的 UI |
|
||||
|
||||
#### 4.4.2 AI 推論模式
|
||||
|
||||
##### 模式一：Video 模式（即時攝影機推論）
|
||||
|
||||
**流程**：
|
||||
1. 使用者選擇 Video 類型的 AI 工具
|
||||
2. 呼叫 `MediaController.start_camera()` 啟動相機
|
||||
3. `VideoThread` 持續擷取影像幀（640×480, 30fps），轉為 QImage 發出 signal
|
||||
4. 影像幀轉為 NumPy 陣列後，透過 `InferenceController.add_frame_to_queue()` 放入推論 queue（最大容量：5 幀）
|
||||
5. `InferenceWorkerThread` 從 queue 取出影像幀，呼叫對應的 `script.py` 執行推論
|
||||
6. 推論結果透過 `inference_result_signal` 傳回主視窗
|
||||
7. 主視窗在 `CanvasArea` 上繪製 Bounding Box 等視覺化結果
|
||||
|
||||
**效能優化機制**：
|
||||
- MSE（Mean Squared Error）幀差異偵測：若連續幀的 MSE 低於 `mse_threshold=500`，沿用上一次推論結果（避免重複計算靜止畫面）
|
||||
- 最短推論間隔：`min_interval=2` 秒（標準模式）
|
||||
- 模型超時設定：`MODEL_TIMEOUT = 5000` ms（`config.py`）
|
||||
|
||||
##### 模式二：Image 模式（上傳圖片單次推論）
|
||||
|
||||
**流程**：
|
||||
1. 使用者選擇 Image 類型的 AI 工具
|
||||
2. 使用者透過 `MediaPanel` 上傳圖片（存入 `%LOCALAPPDATA%/Kneron_Academy/uploads/`）
|
||||
3. 使用 `cv2.imread()` 讀取圖片，放入推論 queue（`once_mode=True`，只推論一次）
|
||||
4. `InferenceWorkerThread` 執行推論並回傳結果
|
||||
5. 切換到 Image 模式時，相機信號會暫時斷開（非停止），以避免 Video 模式的幀繼續進入 queue
|
||||
|
||||
**注意**：切回 Video 工具時，相機信號會重新連接，無需重新開啟相機。
|
||||
|
||||
##### 模式三：Custom Model（使用者自定義模型）
|
||||
|
||||
**流程**：
|
||||
1. 使用者透過 `CustomModelBlock` 上傳以下三個檔案：
|
||||
- `.nef` 模型檔
|
||||
- `fw_scpu.bin`（SCPU firmware）
|
||||
- `fw_ncpu.bin`（NCPU firmware）
|
||||
- （可選）自定義標籤清單（class labels）
|
||||
2. `InferenceController.select_custom_tool()` 被呼叫
|
||||
3. 啟動 `CustomInferenceWorkerThread`（與標準 worker 不同的實作）
|
||||
4. Custom worker 會在首次推論時自行完成：
|
||||
- 連接裝置（`kp.core.connect_devices()`）
|
||||
- 上傳 firmware
|
||||
- 上傳模型（`kp.core.load_model_from_file()`）
|
||||
5. 預處理：影像縮放至 640×640，轉為 BGR565 格式
|
||||
6. 後處理：使用 YOLOv5 演算法（NMS threshold=0.5）解析輸出
|
||||
7. 若有提供自定義標籤，使用自定義標籤；否則使用預設 COCO 80 類別
|
||||
|
||||
**Custom Model 預設行為**：
|
||||
- 輸入類型：Video（即時攝影機）
|
||||
- 後處理演算法：固定使用 YOLOv5（**⚠️ 待確認**：是否計畫支援其他後處理演算法？）
|
||||
- 預設偵測閾值：`thresh=0.2`
|
||||
- 推論間隔：`min_interval=0.5` 秒（比標準模式更頻繁）
|
||||
|
||||
#### 4.4.3 裝置相容性檢查
|
||||
|
||||
當使用者選擇 AI 工具時：
|
||||
- 讀取 `config.json` 中的 `compatible_devices` 欄位
|
||||
- 比對目前選中的 dongle 型號
|
||||
- 若不相容，彈出警告對話框並阻止推論啟動
|
||||
|
||||
---
|
||||
|
||||
### 4.5 Plugin 系統（Script & Model 配置）
|
||||
|
||||
**功能描述**：透過設定檔驅動的 Plugin 架構，讓 AI 模型能被動態載入，無需修改應用程式原始碼。
|
||||
|
||||
#### 4.5.1 檔案結構
|
||||
|
||||
```
|
||||
%LOCALAPPDATA%/Kneron_Academy/
|
||||
├── uploads/ # 使用者上傳的圖片/影片
|
||||
├── utils/
|
||||
│ ├── config.json # 全域 plugin 設定（必要）
|
||||
│ └── {mode}/ # 推論模式資料夾（e.g., face_recognition）
|
||||
│ └── {model}/ # 模型資料夾（e.g., face_detection）
|
||||
│ ├── config.json # 模型設定（必要）
|
||||
│ ├── script.py # 推論腳本（必要）
|
||||
│ └── *.nef # 模型檔（必要）
|
||||
└── firmware/
|
||||
└── {device}/ # 裝置型號資料夾（e.g., KL520）
|
||||
├── fw_scpu.bin
|
||||
└── fw_ncpu.bin
|
||||
```
|
||||
|
||||
#### 4.5.2 全域 config.json 格式
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
{
|
||||
"mode": "face_recognition",
|
||||
"display_name": "人臉辨識",
|
||||
"models": [
|
||||
{
|
||||
"name": "face_detection",
|
||||
"display_name": "人臉偵測 (ResNet-18)",
|
||||
"description": "基於ResNet-18的高精度人臉偵測",
|
||||
"compatible_devices": ["KL520", "KL720"]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.5.3 模型 config.json 格式
|
||||
|
||||
```json
|
||||
{
|
||||
"display_name": "人臉偵測 (ResNet-18)",
|
||||
"description": "使用ResNet-18架構的高精度人臉偵測模型",
|
||||
"model_file": "face_detection.nef",
|
||||
"input_info": {
|
||||
"type": "video",
|
||||
"supported_formats": ["mp4", "avi", "webm"]
|
||||
},
|
||||
"input_parameters": {
|
||||
"threshold": 0.75,
|
||||
"max_faces": 10,
|
||||
"tracking": true
|
||||
},
|
||||
"compatible_devices": ["KL520", "KL720"]
|
||||
}
|
||||
```
|
||||
|
||||
**`input_info.type` 的有效值**：
|
||||
- `"video"` — 啟動攝影機進行即時推論
|
||||
- `"image"` — 使用者上傳圖片進行單次推論
|
||||
- `"voice"` — 音訊輸入模式（⚠️ **程式碼中有對應處理路徑但未見完整實作**）
|
||||
|
||||
#### 4.5.4 script.py 介面規範
|
||||
|
||||
`InferenceWorkerThread` 會動態 import 各模型的 `script.py`。
|
||||
|
||||
**⚠️ 待確認（重要）**：`script.py` 的標準介面（函數名稱、參數格式、回傳格式）目前無正式文件。
|
||||
|
||||
從 `InferenceWorkerThread` 的呼叫方式推斷：
|
||||
- `script.py` 應提供一個可被 worker 呼叫的推論函數
|
||||
- 接收 `input_params` 字典（包含 `usb_port_id`、`device_group`、`model`、`scpu_path`、`ncpu_path`、`file_path` 等）
|
||||
- 回傳 Bounding Box 結果，格式為：
|
||||
```json
|
||||
{
|
||||
"num_boxes": 2,
|
||||
"bounding boxes": [[x1, y1, x2, y2], [x3, y3, x4, y4]],
|
||||
"results": ["label1", "label2"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 非功能需求
|
||||
|
||||
### 5.1 效能需求
|
||||
|
||||
| 項目 | 規格 | 來源 |
|
||||
|------|------|------|
|
||||
| 推論 Queue 大小 | 最大 5 幀 | `InferenceController.__init__` |
|
||||
| 標準模式最短推論間隔 | 2 秒 | `InferenceController.select_tool()` |
|
||||
| Custom Model 最短推論間隔 | 0.5 秒 | `InferenceController.select_custom_tool()` |
|
||||
| 模型推論超時 | 5,000 ms | `config.py MODEL_TIMEOUT` |
|
||||
| 裝置掃描超時 | 5 秒 | `device_service.check_available_device()` |
|
||||
| 攝影機開啟超時 | 5 秒 / 最多 3 次嘗試 | `VideoThread._camera_timeout` |
|
||||
| 攝影機解析度 | 640×480 | `VideoThread.run()` |
|
||||
| 攝影機目標幀率 | 30 fps | `VideoThread.run()` |
|
||||
| Custom Model 輸入大小 | 640×640 | `custom_inference_worker.preprocess_frame()` |
|
||||
| 模型推論設備超時（Custom） | 5,000 ms | `CustomInferenceWorkerThread.initialize_device()` |
|
||||
|
||||
### 5.2 平台相容性
|
||||
|
||||
| 項目 | 規格 |
|
||||
|------|------|
|
||||
| 作業系統 | Windows（使用 `%LOCALAPPDATA%`，PowerInstaller 打包） |
|
||||
| Python 版本 | Python 3.12 |
|
||||
| 視窗尺寸 | 1200×900 像素（固定，`WINDOW_SIZE` 常數） |
|
||||
|
||||
**⚠️ 待確認**：是否計畫支援 macOS 或 Linux？目前路徑處理和打包設定為 Windows 專屬。
|
||||
|
||||
### 5.3 應用程式打包
|
||||
|
||||
| 項目 | 工具 | 狀態 |
|
||||
|------|------|------|
|
||||
| 打包工具 | PyInstaller 6.12.0 | ✅ 已設定 |
|
||||
| 安裝包製作 | Inno Setup（`dist/test.iss`） | ✅ 有設定檔 |
|
||||
| 程式碼加密 | PyArmor | ⚠️ 計畫中 |
|
||||
|
||||
**打包注意事項**：
|
||||
- 需要包含 KneronPLUS SDK 的 `kp/lib` 資料夾
|
||||
- 需包含 `uxui/` 資源目錄和 `src/` 目錄
|
||||
|
||||
### 5.4 資料儲存
|
||||
|
||||
所有執行期資料存放於 `%LOCALAPPDATA%/Kneron_Academy/`：
|
||||
- **uploads/**：使用者上傳的圖片/影片
|
||||
- **utils/**：Plugin 設定與模型檔案
|
||||
- **firmware/**：裝置韌體檔案
|
||||
|
||||
**⚠️ 待確認**：安裝包是否會預先建立這些目錄，或由應用程式首次執行時自動建立？
|
||||
|
||||
---
|
||||
|
||||
## 6. 裝置連接與授權流程（詳細）
|
||||
|
||||
根據 `flowchart.md` 的設計（⚠️ 此流程尚未完整實作於程式碼中，為設計規格）：
|
||||
|
||||
```
|
||||
登入畫面
|
||||
│
|
||||
▼
|
||||
Server 驗證（帳密驗證）
|
||||
├── 成功 → 進入 Dongle 模組畫面
|
||||
└── 失敗 → 顯示錯誤（帳密錯誤 / 服務被暫停）
|
||||
|
||||
Dongle 模組畫面
|
||||
│
|
||||
▼
|
||||
連接 Dongle
|
||||
├── 未偵測到 → 顯示「未偵測到裝置」提示
|
||||
└── 偵測到 → 檢查 Driver 是否安裝
|
||||
|
||||
Driver 檢查
|
||||
├── 已安裝 → 檢查 FW 版本
|
||||
└── 未安裝 → 詢問是否安裝 Driver
|
||||
├── 使用者同意 → 執行安裝（可能失敗）
|
||||
└── 失敗 → 顯示錯誤
|
||||
|
||||
FW 版本檢查
|
||||
├── 版本符合 → 取得 Dongle KN Number
|
||||
└── 需要更新 → 詢問是否更新 FW
|
||||
├── 使用者同意 → 下載並安裝 FW
|
||||
└── 失敗 → 顯示錯誤
|
||||
|
||||
取得 KN Number
|
||||
└── 成功 → 檢查授權狀態
|
||||
|
||||
授權狀態檢查
|
||||
├── 已授權 → 顯示已授權提示 → 回到 App 主頁
|
||||
└── 未授權 → 詢問是否啟動授權
|
||||
├── 使用者同意 → 執行授權流程
|
||||
│ ├── 成功 → 顯示成功提示 → 回到主頁
|
||||
│ └── 失敗 → 顯示失敗提示
|
||||
└── 使用者不重試 → 顯示提示 → 回到主頁
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 已知限制與未完成功能
|
||||
|
||||
以下為從程式碼分析發現的限制與尚未完成的功能：
|
||||
|
||||
### 7.1 尚未完整實作
|
||||
|
||||
| 功能 | 狀態 | 說明 |
|
||||
|------|------|------|
|
||||
| 登入 Server 驗證 | 🔄 部分實作 | `LoginScreen` 存在，但 Server 端點設定不明確 |
|
||||
| Driver 自動安裝 | 🔄 設計中 | `flowchart.md` 有設計，程式碼中未見完整實作 |
|
||||
| Dongle 授權管理 | 🔄 設計中 | `flowchart.md` 有設計，程式碼中未見完整實作 |
|
||||
| 音訊（voice）推論模式 | 🔄 設計中 | `config.py` 有引入 `librosa`、`sounddevice`，但推論路徑不完整 |
|
||||
| Purchased Items API 對接 | 🔄 Mock 資料 | `utilities_screen.py` 有 `populate_mock_purchased_items()` 方法，使用假資料 |
|
||||
| 程式碼加密（PyArmor） | ⏳ 計畫中 | 僅列在 `env.txt`，尚未見到具體加密流程 |
|
||||
| KL520/KL720 以外裝置支援 | ⏳ 計畫中 | `DeviceType` enum 有定義，但 `DongleModelMap` 僅有這兩型 |
|
||||
|
||||
### 7.2 已知技術問題
|
||||
|
||||
| 問題 | 嚴重度 | 說明 |
|
||||
|------|--------|------|
|
||||
| Debug print 語句殘留 | 低 | 多個 controller 中有大量 `print()` debug 訊息 |
|
||||
| 錯誤處理不完整 | 中 | 部分 try/except 只 print 不處理（如 `device_controller.py`） |
|
||||
| 測試覆蓋率為零 | 高 | 完全沒有自動化測試 |
|
||||
| UI 更新 Thread 安全性 | 中 | 待確認推論結果回傳到主線程的路徑是否完全使用 Qt Signal |
|
||||
| `custom_inference_worker.py` 中引用未導入的 `kp` | 中 | `_boxes_scale()` 和 `post_process_yolo_v5()` 在模組頂層使用 `kp.HwPreProcInfo` 等型別，但 `import kp` 在函數內才執行 |
|
||||
|
||||
### 7.3 設計假設（未驗證）
|
||||
|
||||
- Custom Model 後處理固定使用 YOLOv5，未提供自定義後處理的擴充機制
|
||||
- 應用程式假設攝影機 index 為 0（第一個相機），無法選擇其他相機
|
||||
- 應用程式固定使用 Windows 路徑格式，不支援跨平台
|
||||
|
||||
---
|
||||
|
||||
## 8. 功能優先級（RICE 分析）
|
||||
|
||||
> ⚠️ 以下 RICE 分數為從現有程式碼功能狀態推斷，Effort 值基於程式碼完成度估算。**請與產品負責人及開發團隊確認 Reach、Impact 和 Confidence 的實際數值。**
|
||||
|
||||
| 功能 | Reach | Impact | Confidence | Effort（人天） | RICE 分數 | 階段 |
|
||||
|------|-------|--------|------------|--------------|----------|------|
|
||||
| Video 模式推論 | 100% | 3 | 90% | — | 高 | ✅ 已完成 |
|
||||
| Image 模式推論 | 90% | 2 | 90% | — | 高 | ✅ 已完成 |
|
||||
| Plugin 系統（config.json） | 100% | 3 | 85% | — | 高 | ✅ 已完成 |
|
||||
| Custom Model 推論 | 60% | 3 | 80% | — | 中高 | ✅ 已完成 |
|
||||
| 裝置掃描 / 連接 | 100% | 3 | 90% | — | 高 | ✅ 已完成 |
|
||||
| 登入驗證（完整實作） | 100% | 3 | 70% | 5 | 高 | 🔄 進行中 |
|
||||
| Dongle 授權管理 | 100% | 3 | 65% | 10 | 高 | 🔄 設計中 |
|
||||
| Purchased Items API 對接 | 80% | 2 | 70% | 7 | 中 | 🔄 設計中 |
|
||||
| Driver 自動安裝 | 70% | 2 | 60% | 5 | 中 | 🔄 設計中 |
|
||||
| 音訊推論模式 | 40% | 2 | 50% | 10 | 低中 | ⏳ 待實作 |
|
||||
| 多攝影機選擇 | 30% | 1 | 70% | 3 | 低 | ⏳ 未排期 |
|
||||
| 跨平台支援（macOS/Linux） | 50% | 2 | 50% | 20 | 中 | ⏳ 未排期 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 輸入資料格式規範
|
||||
|
||||
### 9.1 攝影機影像
|
||||
|
||||
- 擷取方式：OpenCV `cv2.VideoCapture`，DirectShow backend（Windows 優先）
|
||||
- 解析度：640×480
|
||||
- 格式：`QImage.Format_RGB888`（透過 `VideoThread` 發出），後轉為 NumPy 陣列 `(height, width, 3)`，通道順序 RGB888
|
||||
|
||||
### 9.2 上傳圖片
|
||||
|
||||
- 讀取方式：`cv2.imread()`
|
||||
- 格式：NumPy 陣列，BGR 格式（OpenCV 預設）
|
||||
- 儲存位置：`%LOCALAPPDATA%/Kneron_Academy/uploads/`
|
||||
|
||||
### 9.3 Custom Model 輸入（預處理後）
|
||||
|
||||
- 目標大小：640×640
|
||||
- 格式：BGR565（`cv2.COLOR_BGR2BGR565`）
|
||||
|
||||
### 9.4 input_params 字典格式
|
||||
|
||||
`InferenceWorkerThread` 接收的 `input_params` 標準結構：
|
||||
|
||||
```python
|
||||
{
|
||||
"usb_port_id": 32, # Dongle USB port ID
|
||||
"device_group": <kp.DeviceGroup>, # 已連接的裝置群組物件
|
||||
"scpu_path": "...\\firmware\\KL520\\fw_scpu.bin",
|
||||
"ncpu_path": "...\\firmware\\KL520\\fw_ncpu.bin",
|
||||
"fw_folder": "...\\firmware", # 全域 firmware 目錄
|
||||
"file_path": "...\\uploads\\image.jpg", # 圖片模式使用
|
||||
"model": "...\\utils\\{mode}\\{model}\\{model_file}.nef",
|
||||
"model_descriptor": <kp.ModelDescriptor>, # 已上傳的模型描述符
|
||||
# 以下為 config.json 中的 input_parameters 欄位（由模型設定決定）
|
||||
"threshold": 0.75,
|
||||
"max_faces": 10,
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 推論結果輸出格式
|
||||
|
||||
`script.py` 回傳或 `CustomInferenceWorkerThread` 發出的標準推論結果：
|
||||
|
||||
```json
|
||||
{
|
||||
"num_boxes": 2,
|
||||
"bounding boxes": [[x1, y1, x2, y2], [x3, y3, x4, y4]],
|
||||
"results": ["label1", "label2"]
|
||||
}
|
||||
```
|
||||
|
||||
其中座標為絕對像素值，對應原始影像尺寸（非縮放後的模型輸入尺寸）。
|
||||
|
||||
---
|
||||
|
||||
## 11. 安裝需求
|
||||
|
||||
### 11.1 開發環境安裝
|
||||
|
||||
```shell
|
||||
# 1. 安裝 KneronPLUS SDK
|
||||
cd ./external/kneron_plus_{version}/package/{platform}/
|
||||
pip install KneronPLUS-{version}-py3-none-any.whl
|
||||
|
||||
# 2. 安裝其他依賴
|
||||
pip install PyQt5 opencv-python pyinstaller pyarmor
|
||||
|
||||
# 3. 執行應用程式
|
||||
python main.py
|
||||
```
|
||||
|
||||
### 11.2 打包指令
|
||||
|
||||
```shell
|
||||
pyinstaller --onefile --windowed main.py \
|
||||
--additional-hooks-dir=hooks \
|
||||
--add-data "uxui;uxui" \
|
||||
--add-data "src;src" \
|
||||
--add-data "{conda_env}\\Lib\\site-packages\\kp\\lib;kp\\lib"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. 風險與緩解措施
|
||||
|
||||
| 風險 | 可能性 | 影響 | 緩解措施 |
|
||||
|------|--------|------|----------|
|
||||
| `script.py` 介面無標準文件，第三方難以開發 Plugin | 高 | 高 | 盡速制定並文件化 `script.py` 介面規範 |
|
||||
| Purchased Items 功能仍是 Mock 資料，影響客戶體驗 | 中 | 高 | 確認後端 API 規格，完成對接 |
|
||||
| 缺乏自動化測試，難以安全重構 | 高 | 中 | 補齊關鍵路徑的 unit test（推論 queue、裝置連接） |
|
||||
| `custom_inference_worker.py` 的 `kp` 引入問題，可能在非 kp 環境崩潰 | 中 | 中 | 修復模組頂層的型別引用問題 |
|
||||
| 硬體相依性強，無 dongle 時無法測試核心功能 | 高 | 中 | 建立 Mock/Stub 的 kp 測試層 |
|
||||
| Windows 專屬設計，未來擴展平台成本高 | 低 | 中 | 現階段維持 Windows 優先，抽象化路徑處理為未來鋪路 |
|
||||
|
||||
---
|
||||
|
||||
## 附錄 A：程式碼結構快速參照
|
||||
|
||||
| 模組 | 路徑 | 功能 |
|
||||
|------|------|------|
|
||||
| `AppController` | `main.py` | 應用程式入口，管理 QStackedWidget 頁面切換 |
|
||||
| `SelectionScreen` | `src/views/selection_screen.py` | 首頁選擇畫面 |
|
||||
| `LoginScreen` | `src/views/login_screen.py` | 登入驗證畫面 |
|
||||
| `UtilitiesScreen` | `src/views/utilities_screen.py` | 裝置管理工具頁面 |
|
||||
| `MainWindow` | `src/views/mainWindows.py` | AI 推論主視窗 |
|
||||
| `DeviceController` | `src/controllers/device_controller.py` | 裝置掃描、連接、中斷 |
|
||||
| `InferenceController` | `src/controllers/inference_controller.py` | 推論工具選擇、queue 管理 |
|
||||
| `MediaController` | `src/controllers/media_controller.py` | 攝影機操作 |
|
||||
| `InferenceWorkerThread` | `src/models/inference_worker.py` | 標準推論 Worker（動態載入 script.py） |
|
||||
| `CustomInferenceWorkerThread` | `src/models/custom_inference_worker.py` | Custom Model 推論 Worker（YOLOv5 後處理） |
|
||||
| `VideoThread` | `src/models/video_thread.py` | 攝影機影像擷取 Thread |
|
||||
| `check_available_device()` | `src/services/device_service.py` | 含 timeout 的裝置掃描服務 |
|
||||
| `DeviceType`, `DongleModelMap` | `src/config.py` | 支援裝置型號列舉與對應表 |
|
||||
|
||||
---
|
||||
|
||||
*本 PRD 版本：v1.0（從程式碼反推）*
|
||||
*建立日期：2026-04-04*
|
||||
*建立者：PM Agent（Autoflow）*
|
||||
*狀態：待產品負責人確認標注「⚠️ 待確認」的項目*
|
||||
729
.autoflow/03-design/design-spec.md
Normal file
729
.autoflow/03-design/design-spec.md
Normal file
@ -0,0 +1,729 @@
|
||||
# KNEO Academy（Innovedus AI Playground）設計規格文件
|
||||
|
||||
> **文件性質說明**：本設計規格從既有程式碼反向整理，涵蓋 `src/config.py`、各 View 檔案及 `uxui/` 目錄下的 UI 資源。標注「⚠️ 待確認」的項目為推斷內容或程式碼中資訊不足的部分。
|
||||
|
||||
---
|
||||
|
||||
## ① Design Tokens
|
||||
|
||||
> 以下 Token 直接從 `src/config.py` 及各 View 的 `setStyleSheet()` 提取。
|
||||
|
||||
### 1.1 色彩系統（Color Tokens）
|
||||
|
||||
#### Reference Tokens（原始值）
|
||||
|
||||
| Token 名稱 | 色碼 | 說明 |
|
||||
|-----------|------|------|
|
||||
| color.navy.900 | `#143058` | 深海軍藍（MainWindow 背景） |
|
||||
| color.blue.600 | `#005ED7` | 亮藍（SecondaryColor，Popup / 元件背景） |
|
||||
| color.blue.500 | `#3498DB` | 標準藍（UtilitiesScreen 按鈕、表格 Header） |
|
||||
| color.blue.400 | `#2980B9` | 藍 Hover 色 |
|
||||
| color.blue.300 | `#1F618D` | 藍 Pressed 色 |
|
||||
| color.slate.800 | `#2C3E50` | 深石板藍（LoginScreen/UtilitiesScreen Header 背景） |
|
||||
| color.slate.700 | `#34495E` | 石板藍（SelectionScreen Header、按鈕文字） |
|
||||
| color.gray.100 | `#F8F9FA` | 極淺灰（進度區塊背景） |
|
||||
| color.gray.50 | `#F5F7FA` | 淺灰（LoginScreen / UtilitiesScreen 頁面背景） |
|
||||
| color.gray.200 | `#E0E0E0` | 邊框灰（卡片、輸入框邊框） |
|
||||
| color.gray.400 | `#BDC3C7` | 中灰（非選中導航按鈕文字） |
|
||||
| color.gray.500 | `#95A5A6` | 灰（Footer 文字、Back 按鈕） |
|
||||
| color.gray.600 | `#7F8C8D` | 深灰（描述文字、次要標籤） |
|
||||
| color.green.500 | `#2ECC71` | 標準綠（Download 按鈕） |
|
||||
| color.green.600 | `#27AE60` | 綠 Hover |
|
||||
| color.green.700 | `#1E8449` | 綠 Pressed |
|
||||
| color.green.400 | `#4CAF50` | 成功狀態綠（Custom Model 上傳成功） |
|
||||
| color.orange.500 | `#F39C12` | 橘（Firmware Update 按鈕） |
|
||||
| color.orange.600 | `#D35400` | 橘 Hover |
|
||||
| color.orange.700 | `#A04000` | 橘 Pressed |
|
||||
| color.purple.500 | `#9B59B6` | 紫（Install Driver 按鈕） |
|
||||
| color.purple.600 | `#8E44AD` | 紫 Hover |
|
||||
| color.purple.700 | `#7D3C98` | 紫 Pressed |
|
||||
| color.red.500 | `#E74C3C` | 紅（錯誤訊息文字） |
|
||||
| color.red.400 | `#ff6b6b` | 亮紅（Stop 按鈕文字及邊框） |
|
||||
| color.white | `#FFFFFF` | 純白 |
|
||||
| color.black | `#000000` | 純黑（Canvas 背景） |
|
||||
| color.selection | `#F8F9FA` | 選取頁面背景 |
|
||||
|
||||
#### Semantic Tokens（語義映射）
|
||||
|
||||
| Semantic Token | Reference Token | 說明 |
|
||||
|---------------|----------------|------|
|
||||
| color.bg.primary | color.navy.900（`#143058`） | MainWindow 頁面背景 |
|
||||
| color.bg.light | color.gray.50（`#F5F7FA`） | Login / Utilities 頁面背景 |
|
||||
| color.bg.selection | color.selection（`#F8F9FA`） | SelectionScreen 頁面背景 |
|
||||
| color.bg.card | color.white | 卡片、表單容器背景 |
|
||||
| color.bg.header.dark | color.slate.800（`#2C3E50`） | Login / Utilities Header 背景 |
|
||||
| color.bg.header.alt | color.slate.700（`#34495E`） | SelectionScreen Header 背景 |
|
||||
| color.bg.component | color.blue.600（`#005ED7`） | 側邊欄元件背景（Device Panel、Custom Model Block、Media Panel、Popup） |
|
||||
| color.bg.canvas | color.black | Camera / 推論顯示區域背景 |
|
||||
| color.bg.mask | `rgba(0, 0, 0, 0.7)` | Device Popup 蒙版 |
|
||||
| color.border.default | color.gray.200（`#E0E0E0`） | 卡片、輸入框、表格邊框 |
|
||||
| color.text.primary | color.slate.700（`#34495E`） | 主要文字（深色背景上） |
|
||||
| color.text.secondary | color.gray.600（`#7F8C8D`） | 次要說明文字 |
|
||||
| color.text.on-dark | color.white | 深色背景上的文字 |
|
||||
| color.text.placeholder | color.gray.500（`#95A5A6`） | 輸入框 Placeholder |
|
||||
| color.text.error | color.red.500（`#E74C3C`） | 錯誤訊息 |
|
||||
| color.text.success | color.green.400（`#4CAF50`） | 成功狀態訊息 |
|
||||
| color.text.footer | color.gray.500（`#95A5A6`） | Footer 版權文字 |
|
||||
| color.action.primary | color.blue.500（`#3498DB`） | 主要 CTA 按鈕（Login、Refresh、Utilities Tab） |
|
||||
| color.action.primary.hover | color.blue.400（`#2980B9`） | |
|
||||
| color.action.primary.pressed | color.blue.300（`#1F618D`） | |
|
||||
| color.action.success | color.green.500（`#2ECC71`） | 下載、Register 按鈕 |
|
||||
| color.action.warning | color.orange.500（`#F39C12`） | Firmware Update 按鈕 |
|
||||
| color.action.danger | color.red.400（`#ff6b6b`） | Stop 按鈕 |
|
||||
| color.action.neutral | color.gray.500（`#95A5A6`） | Back 按鈕（中性） |
|
||||
| color.action.special | color.purple.500（`#9B59B6`） | Install Driver 按鈕 |
|
||||
| color.input.focus-border | color.blue.500（`#3498DB`） | 輸入框 Focus 狀態邊框 |
|
||||
| color.table.header | color.blue.500（`#3498DB`） | 表格 Header 背景 |
|
||||
| color.table.selected | color.blue.500（`#3498DB`） | 表格選中列背景 |
|
||||
|
||||
---
|
||||
|
||||
### 1.2 尺寸系統（Size Tokens）
|
||||
|
||||
#### 視窗尺寸
|
||||
|
||||
| Token | 數值 | 說明 |
|
||||
|-------|------|------|
|
||||
| window.width | 1200px | 固定視窗寬度（`WINDOW_SIZE`） |
|
||||
| window.height | 900px | 固定視窗高度（`WINDOW_SIZE`） |
|
||||
| popup.ratio | 0.67 | Device Popup 相對視窗的寬高比（`POPUP_SIZE_RATIO`） |
|
||||
| popup.width | ~804px | 計算值（1200 × 0.67） |
|
||||
| popup.height | ~603px | 計算值（900 × 0.67） |
|
||||
|
||||
#### 佈局尺寸
|
||||
|
||||
| Token | 數值 | 說明 |
|
||||
|-------|------|------|
|
||||
| layout.left-panel.width | 260px | MainWindow 左側面板固定寬度 |
|
||||
| layout.canvas.width | 900px | Camera Canvas 固定寬度 |
|
||||
| layout.canvas.height | 750px | Camera Canvas 固定高度 |
|
||||
| layout.canvas.inner.width | 880px | Canvas Label 最小寬度 |
|
||||
| layout.canvas.inner.height | 730px | Canvas Label 最小高度 |
|
||||
| layout.header.height | 60px | UtilitiesScreen Header 固定高度 |
|
||||
| layout.header.height.alt | 100px | LoginScreen / SelectionScreen Header 固定高度 |
|
||||
|
||||
#### 元件尺寸
|
||||
|
||||
| Token | 數值 | 說明 |
|
||||
|-------|------|------|
|
||||
| component.device-panel.width | 240px | Device Panel 固定寬度 |
|
||||
| component.device-panel.height | 200px | Device Panel 固定高度 |
|
||||
| component.custom-model.width | 240px | Custom Model Block 固定寬度 |
|
||||
| component.custom-model.height | 270px | Custom Model Block 固定高度 |
|
||||
| component.media-panel.width | 90px | Media Panel 固定寬度 |
|
||||
| component.media-panel.height | 290px | Media Panel 固定高度 |
|
||||
| component.selection-card.min-width | 300px | SelectionScreen 選項卡片最小寬度 |
|
||||
| component.selection-card.min-height | 250px | SelectionScreen 選項卡片最小高度 |
|
||||
|
||||
#### 按鈕尺寸
|
||||
|
||||
| Token | 數值 | 說明 |
|
||||
|-------|------|------|
|
||||
| button.standard.min-height | 40px | 標準操作按鈕最小高度（UtilitiesScreen） |
|
||||
| button.login.min-height | 45px | 登入頁按鈕最小高度 |
|
||||
| button.icon.size | 50×50px | Media Panel 圖示按鈕尺寸 |
|
||||
| button.icon.inner | 40×40px | Media Panel SVG 圖示尺寸 |
|
||||
| button.popup.size | 150×45px | Popup 中 Refresh / Done 按鈕尺寸 |
|
||||
| button.detail.size | 72×30px | Device Panel 中 Details 按鈕尺寸 |
|
||||
| button.back.size | 40×40px | Header Back 按鈕尺寸 |
|
||||
| button.file-upload.size | 28×22px | Custom Model 上傳按鈕（"..."）尺寸 |
|
||||
| button.custom-model-action.height | 32px | Custom Model Stop / Run 按鈕高度 |
|
||||
|
||||
#### 圖示尺寸
|
||||
|
||||
| Token | 數值 | 說明 |
|
||||
|-------|------|------|
|
||||
| icon.header.window | 35×35px | Popup 視窗 title 圖示 |
|
||||
| icon.nav | 20×20px | Device Panel title 圖示 |
|
||||
| icon.title.custom-model | 28×28px | Custom Model Block title 圖示 |
|
||||
| icon.card.selection | 64×64px | SelectionScreen 卡片圖示 |
|
||||
| icon.dongle.popup | 30×30px | Device Popup 中裝置圖示 |
|
||||
| icon.dongle.list | 30×30px | Device List 中裝置圖示容器 |
|
||||
| icon.logo.main | 104×40px | MainWindow / UtilitiesScreen 縮小 Logo |
|
||||
| icon.logo.selection | 150×60px | SelectionScreen / LoginScreen 大型 Logo |
|
||||
| icon.combo-arrow | 12×12px | QComboBox 下拉箭頭圖示 |
|
||||
|
||||
---
|
||||
|
||||
### 1.3 間距系統（Spacing Tokens）
|
||||
|
||||
| Token | 數值 | 使用場景 |
|
||||
|-------|------|---------|
|
||||
| spacing.xs | 2px | FileUploadRow 上下 margin |
|
||||
| spacing.sm | 5px | List item padding、button spacing（小） |
|
||||
| spacing.md | 10px | 容器內部間距、部分 Padding |
|
||||
| spacing.lg | 15px | 區塊內部間距（Device Panel、Custom Model Block） |
|
||||
| spacing.xl | 20px | 頁面主要 Margin（Popup、MainWindow canvas） |
|
||||
| spacing.xxl | 30px | 表單容器 Padding（Login、SelectionScreen） |
|
||||
| spacing.form | 40px | SelectionScreen 主要 Margin |
|
||||
| spacing.card | 40px | SelectionScreen 兩張卡片之間的間距 |
|
||||
| spacing.nav | 10px | Header 導航按鈕之間的間距 |
|
||||
|
||||
---
|
||||
|
||||
### 1.4 圓角系統（Border Radius Tokens）
|
||||
|
||||
| Token | 數值 | 使用場景 |
|
||||
|-------|------|---------|
|
||||
| radius.sm | 3px | 檔案上傳標籤、小型 UI 元素 |
|
||||
| radius.md | 5px | 按鈕（UtilitiesScreen）、輸入框、表格 |
|
||||
| radius.lg | 8px | 卡片區塊（Device Section、Purchased Items、Status Section） |
|
||||
| radius.xl | 10px | 主要卡片容器（SelectionScreen、LoginScreen form） |
|
||||
| radius.xxl | 15px | 選項卡片（SelectionScreen）、側邊欄元件（Device Panel、Custom Model Block） |
|
||||
| radius.pill | 20px | Popup、Media Panel（大圓角） |
|
||||
|
||||
---
|
||||
|
||||
### 1.5 字型系統（Typography Tokens）
|
||||
|
||||
> **注意**：程式碼中未定義全域字型 family，使用 PyQt5 系統預設字型（Windows 環境下通常為 Segoe UI）。以下為從程式碼提取的字型大小與字重規格。
|
||||
|
||||
| Token | 數值 | 使用場景 |
|
||||
|-------|------|---------|
|
||||
| font.size.xs | 10px | 檔案名稱標籤（FileUploadRow）、ComboBox 箭頭 |
|
||||
| font.size.sm | 11px | Custom Model 小型標籤、狀態訊息、Run 按鈕文字 |
|
||||
| font.size.body | 12px | Footer 文字、Device Popup 狀態標籤 |
|
||||
| font.size.md | 14px | 表單標籤、描述文字、按鈕文字（UtilitiesScreen）、輸入框、KN 號碼標籤 |
|
||||
| font.size.lg | 16px | 選項卡片描述、Device 標題標籤、Device Label（Popup 中）、Custom Model title |
|
||||
| font.size.xl | 18px | 區塊標題（Device Connection、Device Status、Purchased Items） |
|
||||
| font.size.xxl | 20px | Device Panel 標題 |
|
||||
| font.size.xxxl | 22px | 選項卡片標題 |
|
||||
| font.size.display | 24px | Canvas 載入文字、UtilitiesScreen Header title |
|
||||
| font.size.h2 | 28px | LoginScreen title、SelectionScreen APP title |
|
||||
| font.size.h1 | 32px | Device Popup title |
|
||||
| font.weight.normal | normal | 一般文字 |
|
||||
| font.weight.bold | bold | 標題、按鈕文字、重要標籤 |
|
||||
|
||||
---
|
||||
|
||||
### 1.6 按鈕狀態樣式（Button State Tokens）
|
||||
|
||||
#### 全域按鈕樣式（`BUTTON_STYLE` — 深色背景通用）
|
||||
|
||||
```
|
||||
背景：透明（transparent）
|
||||
文字顏色：白色
|
||||
邊框：2px solid white
|
||||
圓角：15px
|
||||
Padding：5px 10px
|
||||
|
||||
Hover：background-color: rgba(255, 255, 255, 50)（約 20% 白色透明）
|
||||
Pressed：background-color: rgba(255, 255, 255, 100)（約 39% 白色透明）
|
||||
```
|
||||
|
||||
#### 主要 CTA 按鈕（藍色，淺色背景場景）
|
||||
|
||||
```
|
||||
背景：#3498DB
|
||||
文字：白色
|
||||
邊框：none（或 2px solid #2980B9）
|
||||
圓角：5px
|
||||
MinHeight：40-45px
|
||||
Padding：10px 15px
|
||||
|
||||
Hover：#2980B9
|
||||
Pressed：#1F618D
|
||||
Disabled：#3498DB（同 Default，視覺不變）⚠️
|
||||
```
|
||||
|
||||
#### 成功/下載按鈕（綠色）
|
||||
|
||||
```
|
||||
背景：#2ECC71
|
||||
文字：白色
|
||||
邊框：2px solid #27AE60
|
||||
圓角：5px
|
||||
|
||||
Hover：#27AE60
|
||||
Pressed：#1E8449
|
||||
```
|
||||
|
||||
#### 警告按鈕（橘色 Firmware Update）
|
||||
|
||||
```
|
||||
背景：#F39C12
|
||||
文字：白色
|
||||
邊框：2px solid #D35400
|
||||
圓角：5px
|
||||
|
||||
Hover：#D35400
|
||||
Pressed：#A04000
|
||||
```
|
||||
|
||||
#### 特殊功能按鈕（紫色 Install Driver）
|
||||
|
||||
```
|
||||
背景：#9B59B6
|
||||
文字：白色
|
||||
邊框：2px solid #8E44AD
|
||||
圓角：5px
|
||||
|
||||
Hover：#8E44AD
|
||||
Pressed：#7D3C98
|
||||
```
|
||||
|
||||
#### 中性返回按鈕（灰色）
|
||||
|
||||
```
|
||||
背景：#95A5A6
|
||||
文字：白色
|
||||
圓角：5px
|
||||
|
||||
Hover：#7F8C8D
|
||||
Pressed：#616A6B
|
||||
```
|
||||
|
||||
#### Custom Model — Run 按鈕（綠色半透明）
|
||||
|
||||
```
|
||||
背景：rgba(76, 175, 80, 0.3)
|
||||
文字：白色
|
||||
邊框：1px solid #4CAF50
|
||||
圓角：8px
|
||||
高度：32px
|
||||
|
||||
Hover：rgba(76, 175, 80, 0.5)
|
||||
Disabled：rgba(128, 128, 128, 0.2)，文字 #666，邊框 #666
|
||||
```
|
||||
|
||||
#### Custom Model — Stop 按鈕（紅色透明）
|
||||
|
||||
```
|
||||
背景：透明
|
||||
文字：#ff6b6b
|
||||
邊框：1px solid #ff6b6b
|
||||
圓角：8px
|
||||
高度：32px
|
||||
|
||||
Hover：rgba(255, 107, 107, 0.2)
|
||||
```
|
||||
|
||||
#### Media Panel 圖示按鈕
|
||||
|
||||
```
|
||||
背景：透明
|
||||
邊框：1px transparent
|
||||
圓角：10px
|
||||
尺寸：50×50px
|
||||
|
||||
Hover：rgba(255, 255, 255, 50)
|
||||
Pressed：rgba(255, 255, 255, 100)
|
||||
```
|
||||
|
||||
#### Header Back 按鈕（圖示透明按鈕）
|
||||
|
||||
```
|
||||
背景：透明
|
||||
邊框：none
|
||||
尺寸：40×40px
|
||||
|
||||
Hover：rgba(255, 255, 255, 0.1)，圓角 20px
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ② UI 資源清單
|
||||
|
||||
> 路徑：`uxui/`
|
||||
|
||||
### 2.1 PNG 圖片（`Assets_png/`）
|
||||
|
||||
| 檔名 | 推斷用途 | 使用位置 |
|
||||
|------|---------|---------|
|
||||
| `kneron_logo.png` | Kneron / Innovedus 品牌 Logo | MainWindow 歡迎畫面、所有頁面 Header、MainWindow 左側面板 |
|
||||
| `ic_dongle_520.png` | KL520 Dongle 裝置圖示 | Device Popup、Device List（裝置列表項） |
|
||||
| `ic_dongle_720.png` | KL720 Dongle 裝置圖示 | Device Popup、Device List（裝置列表項） |
|
||||
|
||||
> **⚠️ 待確認**：程式碼中 `create_header()` 呼叫 `Assets_png/back_arrow.png` 作為 Back 按鈕圖示，但此檔案**不在 `Assets_png/` 目錄中**。此按鈕目前可能顯示為空白或破圖。
|
||||
|
||||
---
|
||||
|
||||
### 2.2 SVG 圖示（`Assets_svg/`）
|
||||
|
||||
#### 功能按鈕圖示（`bt_function_*`）
|
||||
|
||||
| 檔名 | 狀態 | 推斷用途 |
|
||||
|------|------|---------|
|
||||
| `bt_function_camera_disabled.svg` | disabled | 相機功能按鈕（停用） |
|
||||
| `bt_function_mic_disabled.svg` | disabled | 麥克風功能按鈕（停用） |
|
||||
| `bt_function_mic_hover.svg` | hover | 麥克風功能按鈕 |
|
||||
| `bt_function_mic_normal.svg` | normal | 麥克風功能按鈕 |
|
||||
| `bt_function_mic_pressed.svg` | pressed | 麥克風功能按鈕 |
|
||||
| `bt_function_recording_hover.svg` | hover | 錄製功能按鈕 |
|
||||
| `bt_function_recording_normal.svg` | normal | 錄製功能按鈕 |
|
||||
| `bt_function_recording_pressed.svg` | pressed | 錄製功能按鈕 |
|
||||
| `bt_function_screencapture_disabled.svg` | disabled | 螢幕截圖按鈕（停用） |
|
||||
| `bt_function_screencapture_hover.svg` | hover | 螢幕截圖按鈕 |
|
||||
| `bt_function_screencapture_normal.svg` | normal | 螢幕截圖按鈕（Media Panel 第一個按鈕） |
|
||||
| `bt_function_screencapture_pressed.svg` | pressed | 螢幕截圖按鈕 |
|
||||
| `bt_function_upload_disabled.svg` | disabled | 上傳檔案按鈕（停用） |
|
||||
| `bt_function_upload_hover.svg` | hover | 上傳檔案按鈕 |
|
||||
| `bt_function_upload_normal.svg` | normal | 上傳檔案按鈕（Media Panel 第二個按鈕） |
|
||||
| `bt_function_upload_pressed.svg` | pressed | 上傳檔案按鈕 |
|
||||
| `bt_function_video_hover.svg` | hover | 影片/恢復播放按鈕（暫停→恢復時切換） |
|
||||
| `bt_function_video_normal.svg` | normal | 影片按鈕 |
|
||||
| `bt_function_video_pressed.svg` | pressed | 影片按鈕 |
|
||||
|
||||
> **⚠️ 待確認**：目前 Media Panel「暫停/恢復」按鈕使用 `btn_result_image_delete_hover.svg` 作為暫停狀態圖示，切換後顯示 `bt_function_video_hover.svg`。此對應關係看起來不是最終設計，圖示使用可能有誤。
|
||||
|
||||
#### 對話框按鈕（`btn_dialog_*`）
|
||||
|
||||
| 檔名 | 狀態 | 推斷用途 |
|
||||
|------|------|---------|
|
||||
| `btn_dialog_customization_delete_hover.svg` | hover | 自定義對話框刪除按鈕 |
|
||||
| `btn_dialog_customization_delete_normal.svg` | normal | 自定義對話框刪除按鈕 |
|
||||
| `btn_dialog_customization_delete_pressed.svg` | pressed | 自定義對話框刪除按鈕 |
|
||||
| `btn_dialog_customization_upload_hover.svg` | hover | 自定義對話框上傳按鈕 |
|
||||
| `btn_dialog_customization_upload_normal.svg` | normal | 自定義對話框上傳按鈕 |
|
||||
| `btn_dialog_customization_upload_pressed.svg` | pressed | 自定義對話框上傳按鈕 |
|
||||
| `btn_dialog_device_disconnect_hover.svg` | hover | 裝置斷線按鈕 |
|
||||
| `btn_dialog_device_disconnect_normal.svg` | normal | 裝置斷線按鈕 |
|
||||
| `btn_dialog_device_disconnect_pressed.svg` | pressed | 裝置斷線按鈕 |
|
||||
|
||||
> **⚠️ 待確認**：`btn_dialog_*` 系列圖示在目前的程式碼中**找不到對應的呼叫位置**（自定義對話框的刪除/上傳、裝置斷線按鈕），可能屬於尚未實作的功能 UI，或被移除但資源保留。
|
||||
|
||||
#### 結果區域按鈕（`btn_result_*`）
|
||||
|
||||
| 檔名 | 狀態 | 推斷用途 |
|
||||
|------|------|---------|
|
||||
| `btn_result_edit_hover.svg` | hover | 推論結果編輯按鈕 |
|
||||
| `btn_result_edit_normal.svg` | normal | 推論結果編輯按鈕 |
|
||||
| `btn_result_edit_pressed.svg` | pressed | 推論結果編輯按鈕 |
|
||||
| `btn_result_image_delete_hover.svg` | hover | 推論結果圖片刪除按鈕（目前被借用為暫停圖示） |
|
||||
| `btn_result_image_delete_normal.svg` | normal | 推論結果圖片刪除按鈕 |
|
||||
| `btn_result_image_delete_pressed.svg` | pressed | 推論結果圖片刪除按鈕 |
|
||||
|
||||
> **⚠️ 待確認**：`btn_result_*` 在程式碼中僅 `btn_result_image_delete_hover.svg` 被使用（且用途有疑問），其他均未見使用。
|
||||
|
||||
#### 設定與下載（單一圖示）
|
||||
|
||||
| 檔名 | 推斷用途 | 使用位置 |
|
||||
|------|---------|---------|
|
||||
| `btn_setting.svg` | 設定按鈕 | ⚠️ 程式碼中未見呼叫 |
|
||||
| `ic_result_download_diabled.svg` | 結果下載（停用） | ⚠️ 程式碼中未見呼叫 |
|
||||
| `ic_result_download_hover.svg` | 結果下載 Hover | ⚠️ 程式碼中未見呼叫 |
|
||||
| `ic_result_download_normal.svg` | 結果下載 Normal | ⚠️ 程式碼中未見呼叫 |
|
||||
| `ic_result_download_pressed.svg` | 結果下載 Pressed | ⚠️ 程式碼中未見呼叫 |
|
||||
| `ic_result_folder_hover.svg` | 結果資料夾 Hover | ⚠️ 程式碼中未見呼叫（除被借用為 ComboBox 下拉箭頭） |
|
||||
| `ic_result_folder_normal.svg` | 結果資料夾 Normal | 被用作 LoginScreen QComboBox 下拉箭頭 |
|
||||
| `ic_result_folder_pressed.svg` | 結果資料夾 Pressed | ⚠️ 程式碼中未見呼叫 |
|
||||
|
||||
#### 通用圖示（`ic_*`）
|
||||
|
||||
| 檔名 | 推斷用途 | 使用位置 |
|
||||
|------|---------|---------|
|
||||
| `ic_customization_upload_folder.svg` | 自定義模型上傳資料夾圖示 | ⚠️ 程式碼中未見呼叫 |
|
||||
| `ic_dialog_customization.svg` | 自定義對話框圖示 | ⚠️ 程式碼中未見呼叫 |
|
||||
| `ic_dialog_device.svg` | 裝置對話框圖示 | SelectionScreen Utilities 卡片圖示 |
|
||||
| `ic_dialog_missing_camera.svg` | 找不到攝影機圖示 | ⚠️ 程式碼中未見呼叫（應用於相機找不到的提示） |
|
||||
| `ic_dongle_520.svg` | KL520 Dongle 圖示（SVG 版） | ⚠️ 程式碼中未見呼叫（PNG 版本被使用） |
|
||||
| `ic_recording_camera.svg` | 攝影機/錄影圖示 | SelectionScreen Demo App 卡片圖示；Media Panel 第五個按鈕（錄影） |
|
||||
| `ic_recording_voice.svg` | 錄音圖示 | Media Panel 第四個按鈕（錄音） |
|
||||
| `ic_window_customization.svg` | 自定義視窗圖示 | ⚠️ 程式碼中未見呼叫 |
|
||||
| `ic_window_device.svg` | 裝置視窗圖示 | Device Popup 標題列；Device Panel 標題列 |
|
||||
| `ic_window_toolbox.svg` | 工具箱視窗圖示 | Custom Model Block 標題列 |
|
||||
|
||||
---
|
||||
|
||||
### 2.3 動態圖（`Assets_gif/`）
|
||||
|
||||
| 檔名 | 用途 | 使用位置 |
|
||||
|------|------|---------|
|
||||
| `no_device_temp.gif` | 無裝置狀態動態提示圖 | `MainWindow.show_no_device_gif()`（無裝置時在主視窗顯示） |
|
||||
|
||||
---
|
||||
|
||||
### 2.4 根目錄 SVG 資源
|
||||
|
||||
| 檔名 | 推斷用途 | 使用位置 |
|
||||
|------|---------|---------|
|
||||
| `canvas_background.svg` | 攝影機畫布背景 SVG | ⚠️ 程式碼中未見呼叫 |
|
||||
| `usb_dongle.svg` | USB Dongle 圖示 | ⚠️ 程式碼中未見呼叫 |
|
||||
|
||||
---
|
||||
|
||||
## ③ 頁面元件清單
|
||||
|
||||
### 3.1 SelectionScreen（首頁選擇畫面）
|
||||
|
||||
**背景色**：`#F8F9FA`（淺灰白）
|
||||
**佈局**：QVBoxLayout，Margin 40px 全周，Spacing 20px
|
||||
|
||||
| 元件 | Class/類型 | 尺寸/規格 | 樣式摘要 |
|
||||
|------|-----------|---------|---------|
|
||||
| 頁面背景 | QWidget | 1200×900px | `background: #F8F9FA` |
|
||||
| Header Frame | QFrame | 全寬 × 100px 固定高 | `background: #34495E; border-radius: 10px` |
|
||||
| Kneron Logo | QLabel + QPixmap | 縮放至 150×60px | 水平居中 |
|
||||
| 內容容器 | QFrame | 彈性高（填充剩餘空間）| `background: white; border-radius: 10px; border: 1px solid #E0E0E0`，Padding 30px |
|
||||
| APP 名稱標題 | QLabel | — | `font-size: 28px; font-weight: bold; color: #34495E`，水平居中 |
|
||||
| 副標題 | QLabel | — | `font-size: 16px; color: #7F8C8D`，水平居中，文字：「請選擇您要使用的功能」 |
|
||||
| 按鈕容器 | QWidget + QHBoxLayout | — | Margin 20px 左右，Spacing 40px |
|
||||
| **Utilities 卡片** | QFrame | min 300×250px | `background: white; border-radius: 15px; border: 1px solid #E0E0E0`；Hover：`background: #F5F9FF; border: #5DADE2`；cursor: PointingHand |
|
||||
| Utilities 卡片圖示 | QLabel + QPixmap | 64×64px | `ic_dialog_device.svg`，水平居中 |
|
||||
| Utilities 卡片標題 | QLabel | — | `font-size: 22px; font-weight: bold; color: #34495E`，居中 |
|
||||
| Utilities 卡片說明 | QLabel | — | `font-size: 14px; color: #7F8C8D`，居中，換行 |
|
||||
| **Demo App 卡片** | QFrame | min 300×250px | `background: white; border-radius: 15px; border: 1px solid #E0E0E0`；Hover：`background: #F5FFF7; border: #7DCEA0`；cursor: PointingHand |
|
||||
| Demo App 卡片圖示 | QLabel + QPixmap | 64×64px | `ic_recording_camera.svg`，水平居中 |
|
||||
| Demo App 卡片標題 | QLabel | — | `font-size: 22px; font-weight: bold; color: #34495E`，居中 |
|
||||
| Demo App 卡片說明 | QLabel | — | `font-size: 14px; color: #7F8C8D`，居中，換行 |
|
||||
| Footer | QLabel | — | `font-size: 12px; color: #95A5A6`，居中，文字：「© 2025 Innovedus Inc. All rights reserved.」 |
|
||||
|
||||
---
|
||||
|
||||
### 3.2 LoginScreen（登入畫面）
|
||||
|
||||
**背景色**：`#F5F7FA`（淺灰）
|
||||
**佈局**：QVBoxLayout，Margin 40px 全周，Spacing 20px
|
||||
|
||||
| 元件 | Class/類型 | 尺寸/規格 | 樣式摘要 |
|
||||
|------|-----------|---------|---------|
|
||||
| 頁面背景 | QWidget | 1200×900px | `background: #F5F7FA` |
|
||||
| Header Frame | QFrame | 全寬 × 100px 固定高 | `background: #2C3E50; border-radius: 10px` |
|
||||
| Kneron Logo | QLabel + QPixmap | 縮放至 150×60px | 水平居中 |
|
||||
| 表單容器 | QFrame | 彈性高（填充剩餘空間）| `background: white; border-radius: 10px; border: 1px solid #E0E0E0`，Padding 30px |
|
||||
| 登入標題 | QLabel | — | `font-size: 28px; font-weight: bold; color: #2C3E50; margin-bottom: 10px`，居中，文字："Login" |
|
||||
| Server 驗證標籤 | QLabel | — | `font-size: 14px; font-weight: bold; color: #2C3E50`，文字："Server Authentication Type" |
|
||||
| **驗證類型 ComboBox** | QComboBox | min-height 40px | `border: 1px solid #E0E0E0; border-radius: 5px; padding: 5px 10px; font-size: 14px; color: #2C3E50`；下拉箭頭使用 `ic_result_folder_normal.svg` 12×12px |
|
||||
| 帳號標籤 | QLabel | — | `font-size: 14px; font-weight: bold; color: #2C3E50`，文字："Username" |
|
||||
| **帳號輸入框** | QLineEdit | min-height 40px | `border: 1px solid #E0E0E0; border-radius: 5px; padding: 5px 10px; font-size: 14px; color: #2C3E50`；Focus：`border: 1px solid #3498DB`；Placeholder："Enter your username" |
|
||||
| 密碼標籤 | QLabel | — | `font-size: 14px; font-weight: bold; color: #2C3E50`，文字："Password" |
|
||||
| **密碼輸入框** | QLineEdit | min-height 40px | 同帳號輸入框；EchoMode: Password；Placeholder："Enter your password" |
|
||||
| 錯誤訊息 | QLabel | — | `color: #E74C3C; font-size: 14px`；預設隱藏（`hide()`），驗證失敗時顯示 |
|
||||
| Back 按鈕 | QPushButton | min-height 45px | `background: #95A5A6; color: white; border-radius: 5px; font-size: 14px; font-weight: bold`；Hover：`#7F8C8D`；Pressed：`#616A6B` |
|
||||
| Login 按鈕 | QPushButton | min-height 45px | `background: #3498DB; color: white; border-radius: 5px; font-size: 14px; font-weight: bold`；Hover：`#2980B9`；Pressed：`#1F618D` |
|
||||
| Footer | QLabel | — | `font-size: 12px; color: #95A5A6`，居中 |
|
||||
|
||||
---
|
||||
|
||||
### 3.3 UtilitiesScreen（裝置管理工具）
|
||||
|
||||
**背景色**：`#F5F7FA`（淺灰）
|
||||
**佈局**：QVBoxLayout，Margin 20px 全周，Spacing 20px
|
||||
|
||||
#### 3.3.1 Header
|
||||
|
||||
| 元件 | 類型 | 尺寸/規格 | 樣式摘要 |
|
||||
|------|------|---------|---------|
|
||||
| Header Frame | QFrame | 全寬 × 60px 固定高 | `background: #2C3E50; border-radius: 0px` |
|
||||
| Back 按鈕 | QPushButton | 40×40px | 圖示按鈕（`Assets_png/back_arrow.png`⚠️ 檔案缺失）；Hover：`rgba(255,255,255,0.1) border-radius 20px` |
|
||||
| 頁面標題 | QLabel | — | `color: white; font-size: 24px; font-weight: bold`，文字："Utilities" |
|
||||
| **Utilities 導航按鈕**（選中） | QPushButton | padding 5px 10px | `background: #3498DB; color: white; border: none; border-radius: 5px; font-weight: bold` |
|
||||
| **Purchased Items 導航按鈕**（未選） | QPushButton | padding 5px 10px | `background: transparent; color: #BDC3C7; border: none; border-radius: 5px; font-weight: bold`；Hover：`color: white` |
|
||||
| Kneron Logo | QLabel + QPixmap | 縮放至 104×40px | 靠右對齊 |
|
||||
|
||||
#### 3.3.2 Utilities 子頁面 — 裝置管理區塊
|
||||
|
||||
| 元件 | 類型 | 規格 | 樣式摘要 |
|
||||
|------|------|------|---------|
|
||||
| 區塊容器 | QFrame | — | `background: white; border-radius: 8px; border: 1px solid #E0E0E0`，Padding 15px |
|
||||
| 區塊標題 | QLabel | — | `font-size: 18px; font-weight: bold; color: #2C3E50`，文字："Device Connection" |
|
||||
| 區塊說明 | QLabel | — | `font-size: 14px; color: #7F8C8D`，文字："Connect and manage your Kneron devices" |
|
||||
| **裝置資料表** | QTableWidget | min-height 可捲動 | 6 欄：Device Type / Port ID / Firmware Version / KN Number / Link Speed / Status；Header `background: #3498DB; color: white; font-weight: bold; padding: 8px`；Item padding 8px；Selected `background: #3498DB; color: white`；gridline `#E0E0E0` |
|
||||
| Refresh Devices 按鈕 | QPushButton | min-height 40px | `background: #3498DB; border: 2px solid #2980B9; border-radius: 5px; font-size: 14px; font-weight: bold`；狀態色如前 |
|
||||
| Register Device 按鈕 | QPushButton | min-height 40px | `background: #2ECC71; border: 2px solid #27AE60`；狀態色如前 |
|
||||
| Update Firmware 按鈕 | QPushButton | min-height 40px | `background: #F39C12; border: 2px solid #D35400`；狀態色如前 |
|
||||
| Install Driver 按鈕 | QPushButton | min-height 40px | `background: #9B59B6; border: 2px solid #8E44AD`；狀態色如前 |
|
||||
|
||||
#### 3.3.3 Utilities 子頁面 — 狀態區塊
|
||||
|
||||
| 元件 | 類型 | 規格 | 樣式摘要 |
|
||||
|------|------|------|---------|
|
||||
| 區塊容器 | QFrame | — | `background: white; border-radius: 8px; border: 1px solid #E0E0E0`，Padding 15px |
|
||||
| 區塊標題 | QLabel | — | `font-size: 18px; font-weight: bold; color: #2C3E50`，文字："Device Status" |
|
||||
| 狀態訊息 | QLabel | — | `font-size: 14px; color: #7F8C8D`，預設文字："No devices found" |
|
||||
| 進度區塊（隱藏） | QFrame | — | `background: #F8F9FA; border-radius: 5px; border: 1px solid #E0E0E0; padding: 10px`；預設 `setVisible(False)` |
|
||||
| 進度標題 | QLabel | — | `font-size: 14px; font-weight: bold; color: #2C3E50` |
|
||||
| **進度條** | QProgressBar | height 20px | `border: 1px solid #E0E0E0; border-radius: 5px; background: white; text-align: center`；Chunk：`background: #3498DB; border-radius: 5px` |
|
||||
|
||||
#### 3.3.4 Purchased Items 子頁面
|
||||
|
||||
| 元件 | 類型 | 規格 | 樣式摘要 |
|
||||
|------|------|------|---------|
|
||||
| 區塊容器 | QFrame | — | `background: white; border-radius: 8px; border: 1px solid #E0E0E0`，Padding 15px |
|
||||
| 區塊標題 | QLabel | — | `font-size: 18px; font-weight: bold; color: #2C3E50`，文字："Your Purchased Items" |
|
||||
| 區塊說明 | QLabel | — | `font-size: 14px; color: #7F8C8D`，文字："Select items to download to your device" |
|
||||
| **已購項目表格** | QTableWidget | min-height 300px | 5 欄：Select（Checkbox）/ Product / Model / Current Version / Compatible Dongles；樣式同裝置表格（藍色 Header，選中藍色） |
|
||||
| Refresh Items 按鈕 | QPushButton | min-height 40px | `background: #3498DB; border: none; border-radius: 5px; font-size: 14px; font-weight: bold`；Hover：`#2980B9`；Pressed：`#1F618D` |
|
||||
| Download Selected 按鈕 | QPushButton | min-height 40px | `background: #2ECC71; border: none; border-radius: 5px; font-size: 14px; font-weight: bold`；Hover：`#27AE60`；Pressed：`#1E8449` |
|
||||
|
||||
---
|
||||
|
||||
### 3.4 MainWindow（AI Demo 推論主視窗）
|
||||
|
||||
**背景色**：`#143058`（深海軍藍）
|
||||
**佈局**：QVBoxLayout 外層，啟動時先顯示歡迎畫面（Logo），500ms 後切換至主頁面
|
||||
|
||||
#### 3.4.1 歡迎畫面（500ms 轉場）
|
||||
|
||||
| 元件 | 類型 | 規格 | 說明 |
|
||||
|------|------|------|------|
|
||||
| 歡迎 Logo | QLabel + QPixmap | 原始尺寸 | `kneron_logo.png`，水平居中 |
|
||||
|
||||
#### 3.4.2 主頁面佈局（QHBoxLayout）
|
||||
|
||||
左右兩欄佈局：
|
||||
- **左欄**：固定寬度 260px，QVBoxLayout，Margin 10px，Spacing 10px
|
||||
- **右欄**：彈性寬度（stretch factor 2），QGridLayout，Margin 0px
|
||||
|
||||
#### 3.4.3 左欄元件
|
||||
|
||||
| 元件 | 類型 | 規格 | 樣式摘要 |
|
||||
|------|------|------|---------|
|
||||
| Kneron Logo | QLabel + QPixmap | 縮放至 104×40px | — |
|
||||
| **Device Panel** | QFrame | 240×200px 固定 | `background: #005ED7; border-radius: 15px; border: none` |
|
||||
| — Device 圖示 | QSvgWidget | 20×20px | `ic_window_device.svg` |
|
||||
| — Device 標題 | QLabel | — | `color: white; font-size: 20px; font-weight: bold` |
|
||||
| — 裝置列表 | QListWidget | — | 透明背景；Item：padding 5px，Selected：`rgba(255,255,255,0.2)`；無 Scrollbar |
|
||||
| — Details 按鈕 | QPushButton | 72×30px | 全域 `BUTTON_STYLE`（透明背景、白色邊框） |
|
||||
| **Custom Model Block** | QFrame | 240×270px 固定 | `background: #005ED7; border-radius: 15px; border: none` |
|
||||
| — 工具箱圖示 | QSvgWidget | 28×28px | `ic_window_toolbox.svg` |
|
||||
| — Custom Model 標題 | QLabel | — | `color: white; font-size: 16px; font-weight: bold` |
|
||||
| — 分隔線 | QFrame HLine | 1px 高 | `background: rgba(255,255,255,0.2)` |
|
||||
| — Model 上傳列（.nef） | FileUploadRow | — | 標籤 50px 寬；檔案框 22px 高；上傳按鈕 28×22px |
|
||||
| — SCPU 上傳列（.bin） | FileUploadRow | — | 同上 |
|
||||
| — NCPU 上傳列（.bin） | FileUploadRow | — | 同上 |
|
||||
| — Labels 上傳列（.txt） | FileUploadRow | — | 同上 |
|
||||
| — 狀態標籤 | QLabel | — | `color: #4CAF50; font-size: 11px`；成功綠色，錯誤時 `#ff6b6b` |
|
||||
| — Stop 按鈕 | QPushButton | 高 32px | 透明背景，紅色邊框文字（`#ff6b6b`） |
|
||||
| — Run Inference 按鈕 | QPushButton | 高 32px | 半透明綠色（`rgba(76,175,80,0.3)`），綠色邊框 |
|
||||
|
||||
#### 3.4.4 右欄元件
|
||||
|
||||
| 元件 | 類型 | 規格 | 樣式摘要 |
|
||||
|------|------|------|---------|
|
||||
| **Canvas Area** | QFrame | 900×750px 固定 | `border: 1px solid gray; background: black; border-radius: 20px`，Padding 10px |
|
||||
| Canvas Label（顯示區）| QLabel | 880×730px 最小 | 黑色背景，透明邊框；顯示攝影機 QImage 或靜態圖片 |
|
||||
| **Media Panel**（浮動右下）| QFrame | 90×290px 固定 | `background: #005ED7; border-radius: 20px`；使用 `Qt.AlignBottom | Qt.AlignRight` 疊加在 Canvas 右下 |
|
||||
| — 截圖按鈕 | QPushButton | 50×50px | 圖示 `bt_function_screencapture_normal.svg`，40×40px |
|
||||
| — 上傳按鈕 | QPushButton | 50×50px | 圖示 `bt_function_upload_normal.svg`，40×40px |
|
||||
| — 暫停/恢復按鈕 | QPushButton | 50×50px | 暫停時：`btn_result_image_delete_hover.svg`；恢復時：`bt_function_video_hover.svg` |
|
||||
| — 錄音按鈕 | QPushButton | 50×50px | 圖示 `ic_recording_voice.svg`，40×40px |
|
||||
| — 錄影按鈕 | QPushButton | 50×50px | 圖示 `ic_recording_camera.svg`，40×40px |
|
||||
|
||||
#### 3.4.5 Device Popup（蒙版彈出視窗）
|
||||
|
||||
| 元件 | 類型 | 規格 | 樣式摘要 |
|
||||
|------|------|------|---------|
|
||||
| 蒙版 Overlay | QWidget | 1200×900px（全視窗） | `background: rgba(0, 0, 0, 0.7)` |
|
||||
| **Device Popup** | QWidget | 804×603px（視窗 × 0.67） | `background: #005ED7; border-radius: 20px; padding: 20px` |
|
||||
| — 裝置圖示 | QSvgWidget | 35×35px | `ic_window_device.svg` |
|
||||
| — 彈窗標題 | QLabel | — | `color: white; font-size: 32px; font-weight: bold`，文字："Device Connection" |
|
||||
| — 裝置列表（Popup） | QListWidget | min-height 250px | `background: rgba(255,255,255,0.1); border-radius: 10px; color: white`；Item Selected：`rgba(52,152,219,0.5)` |
|
||||
| — 裝置列表項 | 自訂 QWidget | 60px 固定高 | 圖示容器 30×30px（`#182D4B` 背景，border-radius 5px）+ 裝置名（16px bold）+ KN 號碼（14px）+ 狀態（12px 右對齊） |
|
||||
| — Refresh 按鈕 | QPushButton | 150×45px | 全域 `BUTTON_STYLE` |
|
||||
| — Done 按鈕 | QPushButton | 150×45px | 全域 `BUTTON_STYLE` |
|
||||
|
||||
---
|
||||
|
||||
## ④ 互動規格
|
||||
|
||||
### 4.1 頁面切換方式（Signal/Slot）
|
||||
|
||||
```
|
||||
SelectionScreen.open_utilities → 主程式切換到 LoginScreen
|
||||
SelectionScreen.open_demo_app → 主程式切換到 MainWindow
|
||||
|
||||
LoginScreen.login_success → 主程式切換到 UtilitiesScreen
|
||||
LoginScreen.back_to_selection → 主程式切換到 SelectionScreen
|
||||
|
||||
UtilitiesScreen.back_to_selection → 主程式切換到 SelectionScreen
|
||||
```
|
||||
|
||||
> **⚠️ 待確認**：頁面切換的具體實作（是否使用 QStackedWidget，還是直接 hide/show）需查看 `main.py` 或應用程式進入點。
|
||||
|
||||
### 4.2 MainWindow 啟動流程
|
||||
|
||||
```
|
||||
1. 顯示歡迎畫面（Kneron Logo）
|
||||
2. 500ms 後 → 清除歡迎畫面，建立主頁面
|
||||
3. 100ms 後 → 呼叫 device_controller.refresh_devices()
|
||||
4. 顯示 Device Popup（蒙版覆蓋主頁面）
|
||||
5. 500ms 後 → 自動啟動攝影機（auto_start_camera）
|
||||
```
|
||||
|
||||
### 4.3 按鈕 Enabled/Disabled 條件
|
||||
|
||||
| 按鈕 | 停用條件 | 啟用條件 |
|
||||
|------|---------|---------|
|
||||
| Media Panel 圖示按鈕（相機） | 相機功能不可用時（`bt_function_camera_disabled.svg` 存在暗示） | ⚠️ 未在程式碼中找到明確的 setEnabled 邏輯 |
|
||||
| Custom Model — Run Inference | 無（任何時候都可點擊，但點擊後會驗證檔案） | 有效檔案選擇後 |
|
||||
| Custom Model — Stop | 無推論進行時重置檔案選擇 | — |
|
||||
| UtilitiesScreen 操作按鈕 | ⚠️ 未找到明確的停用條件（選取裝置後才應啟用的邏輯有待確認） | — |
|
||||
|
||||
### 4.4 對話框觸發條件
|
||||
|
||||
| 對話框 | 觸發條件 | 類型 |
|
||||
|--------|---------|------|
|
||||
| Device Popup | MainWindow 啟動時自動顯示 | 自訂 QWidget 蒙版 |
|
||||
| Inference Result | 推論回傳非 Bounding Box 結果（分類等）時 | QMessageBox |
|
||||
| Device 相容性警告 | 選擇不相容裝置的 AI 工具時 | QMessageBox（推斷） |
|
||||
| 無裝置 GIF | 推斷：無裝置連接時 | QLabel + QMovie |
|
||||
| Download Complete | 所有選中項目下載完成 | QMessageBox.information |
|
||||
| No Selection 警告 | 點擊 Download 但未勾選任何項目 | QMessageBox.warning |
|
||||
| 相機失敗提示 | 相機開啟失敗 | ⚠️ 程式碼中有 `ic_dialog_missing_camera.svg` 資源，但未見對應邏輯 |
|
||||
|
||||
### 4.5 UtilitiesScreen 頁面切換
|
||||
|
||||
| 觸發 | 行為 |
|
||||
|------|------|
|
||||
| 點擊「Utilities」導航按鈕 | `utilities_page.show()`；`purchased_items_page.hide()`；Utilities 按鈕樣式變為選中（`#3498DB`）；Purchased 按鈕變為未選中（透明） |
|
||||
| 點擊「Purchased Items」導航按鈕 | `purchased_items_page.show()`；`utilities_page.hide()` |
|
||||
|
||||
> **⚠️ 待確認**：目前程式碼中未見導航按鈕選中/未選中狀態的動態切換邏輯（按鈕樣式可能沒有在切換時更新）。
|
||||
|
||||
### 4.6 Custom Model 檔案上傳互動
|
||||
|
||||
| 步驟 | 互動 | 視覺變化 |
|
||||
|------|------|---------|
|
||||
| 點擊「...」按鈕 | 開啟系統檔案選擇器 | — |
|
||||
| 選擇檔案成功 | 顯示檔案名稱（超過 15 字截斷加「...」） | 標籤顏色從 `#aaa` 變為 `#4CAF50`；邊框 `#4CAF50`；背景 `rgba(76,175,80,0.1)` |
|
||||
| 點擊 Run Inference（缺少必要檔案） | — | 狀態標籤文字更新為錯誤提示，顏色變為 `#ff6b6b` |
|
||||
| 點擊 Run Inference（所有必要檔案已選） | 啟動推論 | 狀態標籤顯示 "Running: {model_name}"，顏色 `#4CAF50` |
|
||||
| 點擊 Stop（有推論進行中） | 停止推論 | 狀態標籤顯示 "Stopped & Disconnected"，顏色 `#ff6b6b` |
|
||||
| 點擊 Stop（無推論） | 重置所有檔案選擇 | 所有 FileUploadRow 回復到「未選擇」狀態 |
|
||||
|
||||
---
|
||||
|
||||
## ⑤ 缺失的設計規格
|
||||
|
||||
### 5.1 互動細節（程式碼中看不出）
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| Bounding Box 繪製樣式 | 推論結果繪製在 Canvas 上的 Bounding Box 顏色、線條粗細、Label 字型樣式均無 Design Spec；從程式碼僅知座標格式 |
|
||||
| 相機找不到時的 UI | 有 `ic_dialog_missing_camera.svg` 資源，但找不到對應的顯示邏輯 |
|
||||
| 推論進行中的 Loading 狀態 | Canvas 載入文字為 "Starting camera..."，但推論進行中是否有 Loading indicator 不清楚 |
|
||||
| UtilitiesScreen 導航按鈕切換動態 | 頁面切換時按鈕選中狀態的樣式切換邏輯不完整 |
|
||||
| 相機暫停後的 Canvas 顯示 | 暫停時 Canvas 顯示最後一幀還是空白？未知 |
|
||||
| MSE 幀差異偵測的視覺提示 | 技術機制存在，但使用者是否看到任何提示？未知 |
|
||||
| 推論 Queue 滿時的提示 | Queue 最大 5 幀，滿時的行為是靜默丟棄，無視覺提示 |
|
||||
|
||||
### 5.2 未完整實作的 UI 功能
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| Driver 安裝 UI | `Install Driver` 按鈕存在，但 `install_drivers()` 方法的實際 UI 流程未見完整實作 |
|
||||
| Register Device UI | `Register Device` 按鈕存在，`register_device()` 方法實作未確認 |
|
||||
| Dongle 授權管理 UI | PRD 中有完整描述，但 UtilitiesScreen 中未見對應 UI 元素 |
|
||||
| Toolbox（原始工具箱）| `create_ai_toolbox()` 元件存在但在 MainWindow 中已被 `CustomModelBlock` 取代，Toolbox 功能未整合 |
|
||||
| 購買模型下載（真實 API）| 目前為 Mock 資料，`populate_mock_purchased_items()` 方法，無真實下載邏輯 |
|
||||
| 自定義對話框 UI | `btn_dialog_customization_*` 和 `ic_dialog_customization.svg` 資源存在，但無對應 UI 元件 |
|
||||
| 裝置斷線按鈕 UI | `btn_dialog_device_disconnect_*` 資源存在，但無對應 UI 元件 |
|
||||
| 結果下載/資料夾 UI | `ic_result_download_*`、`ic_result_folder_*`、`btn_result_edit_*` 資源存在，但程式碼中大多未呼叫 |
|
||||
| 設定頁面 | `btn_setting.svg` 存在，但無對應的設定頁面 |
|
||||
|
||||
### 5.3 設計一致性問題（觀察到的設計債）
|
||||
|
||||
| 問題 | 說明 | 嚴重程度 |
|
||||
|------|------|---------|
|
||||
| 兩種截然不同的設計語言 | MainWindow 使用深海軍藍（`#143058`）為主的深色設計；SelectionScreen、LoginScreen、UtilitiesScreen 使用淺色（`#F5F7FA`）設計。同一個應用存在兩套視覺語言，缺乏統一感 | High |
|
||||
| Back 按鈕圖示資源缺失 | UtilitiesScreen Header 使用的 `Assets_png/back_arrow.png` 不存在於 `uxui/Assets_png/` 目錄，按鈕為空白 | High |
|
||||
| 暫停按鈕圖示錯誤 | Media Panel 暫停按鈕使用 `btn_result_image_delete_hover.svg`（刪除圖示）作為暫停狀態，語意不正確 | Medium |
|
||||
| 未定義系統字型 | 無明確的 `font-family` 定義，依賴 Windows 系統預設字型，跨平台（若未來支援）可能不一致 | Low |
|
||||
| Dark Mode 未規劃 | 完全無 Dark Mode 設計 | Low |
|
||||
| Disabled 按鈕視覺未完整定義 | UtilitiesScreen 按鈕幾乎未定義 Disabled 狀態樣式 | Medium |
|
||||
| Focus 狀態不完整 | 大多數按鈕無 Focus ring 設計（僅 LoginScreen QLineEdit 有 Focus 邊框） | Medium |
|
||||
|
||||
---
|
||||
|
||||
*本文件由 Design Agent 從既有程式碼反向整理，版本日期：2026-04-04*
|
||||
970
.autoflow/04-architecture/TDD.md
Normal file
970
.autoflow/04-architecture/TDD.md
Normal file
@ -0,0 +1,970 @@
|
||||
# 技術設計文件（TDD）— KNEO Academy v2.0
|
||||
|
||||
**作者**：Architect Agent
|
||||
**狀態**：Draft（從既有程式碼反向整理）
|
||||
**日期**：2026-04-04
|
||||
**對應 Design Doc**：`04-architecture/design-doc.md`
|
||||
|
||||
---
|
||||
|
||||
## 目錄
|
||||
|
||||
1. [模組 API 規格](#1-模組-api-規格)
|
||||
- 1.1 [config.py — 全域設定](#11-configpy--全域設定)
|
||||
- 1.2 [AppController（main.py）](#12-appcontrollermainpy)
|
||||
- 1.3 [DeviceController](#13-devicecontroller)
|
||||
- 1.4 [InferenceController](#14-inferencecontroller)
|
||||
- 1.5 [MediaController](#15-mediacontroller)
|
||||
- 1.6 [InferenceWorkerThread](#16-inferenceworkerthread)
|
||||
- 1.7 [CustomInferenceWorkerThread](#17-custominferenceworkerthread)
|
||||
- 1.8 [VideoThread](#18-videothread)
|
||||
- 1.9 [DeviceService](#19-deviceservice)
|
||||
- 1.10 [FileService](#110-fileservice)
|
||||
- 1.11 [ConfigUtils](#111-configutils)
|
||||
- 1.12 [image_utils](#112-image_utils)
|
||||
2. [InferenceWorkerThread 與 script.py 介面規範](#2-inferenceworkerthread-與-scriptpy-介面規範)
|
||||
3. [裝置連接 API 流程（kp SDK 呼叫順序）](#3-裝置連接-api-流程kp-sdk-呼叫順序)
|
||||
4. [推論 Queue 設計](#4-推論-queue-設計)
|
||||
5. [Signal/Slot 對應表](#5-signalslot-對應表)
|
||||
6. [config.json 完整 Schema 定義](#6-configjson-完整-schema-定義)
|
||||
7. [已知限制與邊界條件](#7-已知限制與邊界條件)
|
||||
|
||||
---
|
||||
|
||||
## 1. 模組 API 規格
|
||||
|
||||
### 1.1 config.py — 全域設定
|
||||
|
||||
**路徑**：`src/config.py`
|
||||
|
||||
#### 常數
|
||||
|
||||
| 常數名稱 | 型別 | 說明 |
|
||||
|---------|------|------|
|
||||
| `APPDATA_PATH` | str | `%LOCALAPPDATA%` 環境變數值 |
|
||||
| `PROJECT_ROOT` | str | 專案根目錄絕對路徑 |
|
||||
| `UXUI_ASSETS` | str | `{PROJECT_ROOT}/uxui/` |
|
||||
| `UTILS_DIR` | str | `%LOCALAPPDATA%/Kneron_Academy/utils` |
|
||||
| `SCRIPT_CONFIG` | str | `{UTILS_DIR}/config.json` |
|
||||
| `UPLOAD_DIR` | str | `%LOCALAPPDATA%/Kneron_Academy/uploads` |
|
||||
| `FW_DIR` | str | `%LOCALAPPDATA%/Kneron_Academy/firmware` |
|
||||
| `APP_NAME` | str | `"Innovedus AI Playground"` |
|
||||
| `WINDOW_SIZE` | tuple[int, int] | `(1200, 900)` |
|
||||
| `BACKGROUND_COLOR` | str | `"#143058"` |
|
||||
| `MODEL_TIMEOUT` | int | `5000`（毫秒） |
|
||||
| `FIRMWARE_PATHS` | dict | `{"scpu": "../../res/firmware/fw_scpu.bin", "ncpu": "..."}` ⚠️ 見備注 |
|
||||
|
||||
> **⚠️ 備注**：`FIRMWARE_PATHS` 使用相對路徑，但在打包後此相對路徑可能無效，實際運作中 `DeviceController.connect_device()` 改用 `os.path.join(FW_DIR, dongle, "fw_scpu.bin")` 計算路徑。`FIRMWARE_PATHS` 常數目前**未被使用**。
|
||||
|
||||
#### DeviceType Enum
|
||||
|
||||
```python
|
||||
class DeviceType(Enum):
|
||||
KL520 = 256 # product_id hex: 0x100
|
||||
KL720 = 1824 # product_id hex: 0x720
|
||||
KL720_L = 512 # product_id hex: 0x200（⚠️ 無 DongleModelMap 對應）
|
||||
KL530 = 530 # （⚠️ 無 DongleModelMap 對應）
|
||||
KL832 = 832 # （⚠️ 無 DongleModelMap 對應）
|
||||
KL730 = 732 # （⚠️ 無 DongleModelMap 對應）
|
||||
KL630 = 630 # （⚠️ 無 DongleModelMap 對應）
|
||||
KL540 = 540 # （⚠️ 無 DongleModelMap 對應）
|
||||
```
|
||||
|
||||
#### DongleModelMap（product_id → model name）
|
||||
|
||||
```python
|
||||
DongleModelMap = {
|
||||
"0x100": "KL520",
|
||||
"0x720": "KL720",
|
||||
}
|
||||
# 注意：key 為 lowercase hex string（含 0x 前綴），如 "0x100"
|
||||
```
|
||||
|
||||
#### DongleIconMap（product_id → icon 檔名）
|
||||
|
||||
```python
|
||||
DongleIconMap = {
|
||||
"0x100": "ic_dongle_520.png",
|
||||
"0x720": "ic_dongle_720.png",
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.2 AppController（main.py）
|
||||
|
||||
**路徑**：`main.py`
|
||||
|
||||
#### Class: AppController
|
||||
|
||||
```python
|
||||
class AppController:
|
||||
app: QApplication
|
||||
stack: QStackedWidget
|
||||
selection_screen: SelectionScreen
|
||||
login_screen: LoginScreen
|
||||
utilities_screen: UtilitiesScreen
|
||||
main_window: MainWindow
|
||||
```
|
||||
|
||||
| 方法 | 參數 | 回傳 | 說明 |
|
||||
|------|------|------|------|
|
||||
| `__init__()` | — | — | 初始化 QApplication、QStackedWidget、所有頁面，並連接 Signal |
|
||||
| `init_screens()` | — | None | 建立四個頁面物件並加入 stack |
|
||||
| `connect_signals()` | — | None | 連接頁面間的 Signal/Slot |
|
||||
| `show_selection_screen()` | — | None | 切換到 SelectionScreen |
|
||||
| `show_login_screen()` | — | None | 切換到 LoginScreen |
|
||||
| `show_utilities_screen()` | — | None | 切換到 UtilitiesScreen |
|
||||
| `show_demo_app()` | — | None | 切換到 MainWindow |
|
||||
| `run()` | — | int | 啟動 Qt event loop，回傳 exit code |
|
||||
|
||||
**⚠️ 已知問題**：所有頁面在 `init_screens()` 時一次性建立，包含 `MainWindow`（內部會啟動相機等重資源操作）。若希望延遲初始化，需要重構。
|
||||
|
||||
---
|
||||
|
||||
### 1.3 DeviceController
|
||||
|
||||
**路徑**：`src/controllers/device_controller.py`
|
||||
|
||||
#### Class: DeviceController
|
||||
|
||||
```python
|
||||
class DeviceController:
|
||||
main_window: QWidget # 持有 UI 參考（用於更新 device_list_widget）
|
||||
selected_device: dict | None # 當前選中的裝置（dict 格式）
|
||||
connected_devices: list[dict] # 已解析的裝置列表
|
||||
device_group: kp.DeviceGroup | None # kp SDK 連接的裝置群組
|
||||
```
|
||||
|
||||
| 方法 | 參數 | 回傳 | 說明 |
|
||||
|------|------|------|------|
|
||||
| `__init__(main_window)` | main_window: QWidget | — | 初始化 |
|
||||
| `refresh_devices()` | — | bool | 掃描裝置並更新 UI；True = 找到裝置 |
|
||||
| `parse_and_store_devices(devices)` | devices: list | None | 解析 descriptor 存入 `connected_devices` |
|
||||
| `display_devices(devices)` | devices: list | None | 更新 `main_window.device_list_widget` |
|
||||
| `get_devices()` | — | list | 呼叫掃描並回傳 descriptor list |
|
||||
| `get_selected_device()` | — | dict \| None | 回傳目前選中的裝置 |
|
||||
| `select_device(device, list_item, list_widget)` | device, item, widget | None | 選取裝置，更新 UI 高亮 |
|
||||
| `connect_device()` | — | bool | 連接 selected_device 並上傳 firmware |
|
||||
| `disconnect_device()` | — | bool | 中斷連接，釋放 device_group |
|
||||
| `get_device_group()` | — | kp.DeviceGroup \| None | 回傳目前的 device_group |
|
||||
|
||||
#### connected_devices 元素格式
|
||||
|
||||
```python
|
||||
{
|
||||
"usb_port_id": int, # USB port 編號（唯一識別）
|
||||
"product_id": int, # 數字形式的 product_id
|
||||
"kn_number": int | str, # KN number（裝置序號）
|
||||
"dongle": str # 裝置型號名稱，如 "KL520"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.4 InferenceController
|
||||
|
||||
**路徑**：`src/controllers/inference_controller.py`
|
||||
|
||||
#### Class: InferenceController
|
||||
|
||||
```python
|
||||
class InferenceController:
|
||||
main_window: QWidget
|
||||
device_controller: DeviceController
|
||||
inference_worker: InferenceWorkerThread | CustomInferenceWorkerThread | None
|
||||
inference_queue: queue.Queue # maxsize=5
|
||||
current_tool_config: dict | None
|
||||
previous_tool_config: dict | None
|
||||
_camera_was_active: bool
|
||||
original_frame_width: int # 預設 640
|
||||
original_frame_height: int # 預設 480
|
||||
model_descriptor: kp.ModelDescriptor | None
|
||||
```
|
||||
|
||||
| 方法 | 參數 | 回傳 | 說明 |
|
||||
|------|------|------|------|
|
||||
| `__init__(main_window, device_controller)` | — | — | 初始化，建立 inference_queue（maxsize=5） |
|
||||
| `select_tool(tool_config)` | tool_config: dict | bool | 選擇標準工具，建立 InferenceWorkerThread |
|
||||
| `select_custom_tool(tool_config)` | tool_config: dict | bool | 選擇自定義模型，建立 CustomInferenceWorkerThread |
|
||||
| `_clear_inference_queue()` | — | None | 清空 inference_queue 中所有幀 |
|
||||
| `add_frame_to_queue(frame)` | frame: np.ndarray | None | 若 queue 未滿，加入幀；同時更新 original_frame_width/height |
|
||||
| `stop_inference()` | — | None | 停止 inference_worker |
|
||||
| `process_uploaded_image(file_path)` | file_path: str | None | 清空 queue 後加入指定圖片，供 Image 模式使用 |
|
||||
|
||||
#### select_tool() 的 tool_config 期望格式
|
||||
|
||||
```python
|
||||
{
|
||||
"display_name": str, # 顯示名稱
|
||||
"mode": str, # 推論模式目錄名稱（對應 utils/{mode}/）
|
||||
"model_name": str, # 模型目錄名稱（對應 utils/{mode}/{model_name}/）
|
||||
"input_info": {
|
||||
"type": "video" | "image" | "voice"
|
||||
},
|
||||
"input_parameters": dict, # 傳入 script.py 的 params
|
||||
"compatible_devices": list[str], # 如 ["KL520", "KL720"]
|
||||
"model_file": str, # .nef 檔名（可選，若有則自動上傳模型）
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.5 MediaController
|
||||
|
||||
**路徑**：`src/controllers/media_controller.py`
|
||||
|
||||
#### Class: MediaController
|
||||
|
||||
```python
|
||||
class MediaController:
|
||||
main_window: QWidget
|
||||
inference_controller: InferenceController
|
||||
video_thread: VideoThread | None
|
||||
recording: bool
|
||||
recording_audio: bool
|
||||
recorded_frames: list[np.ndarray]
|
||||
_signal_was_connected: bool
|
||||
_inference_paused: bool
|
||||
```
|
||||
|
||||
| 方法 | 參數 | 回傳 | 說明 |
|
||||
|------|------|------|------|
|
||||
| `start_camera()` | — | None | 建立 VideoThread 並連接 Signal；若已運行則跳過 |
|
||||
| `stop_camera()` | — | None | 斷開 Signal，停止並銷毀 VideoThread |
|
||||
| `update_image(qt_image)` | qt_image: QImage | None | 接收相機幀，繪製 Bounding Box，更新 canvas，加入 inference_queue |
|
||||
| `reconnect_camera_signal()` | — | None | 重新連接已斷開的 change_pixmap_signal |
|
||||
| `record_video(button=None)` | button: QPushButton \| None | None | 切換錄影狀態；停止時彈出儲存對話框 |
|
||||
| `record_audio(button=None)` | button: QPushButton \| None | None | 切換錄音狀態 |
|
||||
| `take_screenshot()` | — | None | 儲存 canvas 當前幀為圖片 |
|
||||
| `toggle_inference_pause()` | — | bool | 切換推論暫停狀態，回傳新狀態 |
|
||||
| `is_inference_paused()` | — | bool | 回傳目前是否暫停推論 |
|
||||
|
||||
---
|
||||
|
||||
### 1.6 InferenceWorkerThread
|
||||
|
||||
**路徑**：`src/models/inference_worker.py`
|
||||
|
||||
#### 模組函數
|
||||
|
||||
```python
|
||||
def load_inference_module(mode: str, model_name: str) -> module:
|
||||
"""
|
||||
動態載入 {UTILS_DIR}/{mode}/{model_name}/script.py 並回傳 module 物件。
|
||||
若檔案不存在，importlib 會拋出 FileNotFoundError。
|
||||
"""
|
||||
```
|
||||
|
||||
#### Class: InferenceWorkerThread（QThread）
|
||||
|
||||
```python
|
||||
class InferenceWorkerThread(QThread):
|
||||
inference_result_signal = pyqtSignal(object) # 回傳 dict | None
|
||||
|
||||
frame_queue: queue.Queue
|
||||
mode: str
|
||||
model_name: str
|
||||
min_interval: float # 最小推論間隔（秒）
|
||||
mse_threshold: float # MSE 閾值，低於此值視為相似幀
|
||||
_running: bool
|
||||
once_mode: bool # True = 處理一幀後停止（Image 模式）
|
||||
last_inference_time: float
|
||||
last_frame: np.ndarray | None
|
||||
cached_result: object | None
|
||||
input_params: dict
|
||||
inference_module: module # 動態載入的 script.py module
|
||||
```
|
||||
|
||||
| 方法 | 參數 | 回傳 | 說明 |
|
||||
|------|------|------|------|
|
||||
| `__init__(frame_queue, mode, model_name, min_interval=0.5, mse_threshold=500, once_mode=False)` | — | — | 初始化並立即載入 inference_module |
|
||||
| `run()` | — | None | 主迴圈：取幀 → MSE 判斷 → 推論 → emit 結果 |
|
||||
| `stop()` | — | None | 設 `_running=False` 並 `wait()` |
|
||||
|
||||
**⚠️ 注意**：`InferenceController.select_tool()` 建立 Worker 時，`min_interval` 設定為 **2 秒**（非預設的 0.5 秒）：
|
||||
```python
|
||||
self.inference_worker = InferenceWorkerThread(
|
||||
...,
|
||||
min_interval=2,
|
||||
mse_threshold=500,
|
||||
once_mode=once_mode
|
||||
)
|
||||
```
|
||||
|
||||
#### run() 主迴圈邏輯
|
||||
|
||||
```
|
||||
while _running:
|
||||
1. frame_queue.get(timeout=0.1) — 若 0.1 秒內無幀則 continue
|
||||
2. 時間間隔檢查：current_time - last_inference_time < min_interval → continue
|
||||
3. MSE 比較（若 last_frame 不為 None 且尺寸相同）：
|
||||
- mse < mse_threshold AND cached_result 不為 None → emit cached_result → continue
|
||||
4. inference_module.inference(frame, params=input_params) → result
|
||||
5. 更新 last_inference_time、last_frame、cached_result
|
||||
6. result 不為 None → inference_result_signal.emit(result)
|
||||
7. once_mode = True → _running = False，break
|
||||
quit()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.7 CustomInferenceWorkerThread
|
||||
|
||||
**路徑**：`src/models/custom_inference_worker.py`
|
||||
|
||||
#### 輔助 Classes
|
||||
|
||||
```python
|
||||
class ExampleBoundingBox:
|
||||
x1: int; y1: int; x2: int; y2: int
|
||||
score: float
|
||||
class_num: int
|
||||
|
||||
def get_member_variable_dict() -> dict
|
||||
|
||||
class ExampleYoloResult:
|
||||
class_count: int
|
||||
box_count: int
|
||||
box_list: list[ExampleBoundingBox]
|
||||
|
||||
def get_member_variable_dict() -> dict
|
||||
```
|
||||
|
||||
#### 模組函數
|
||||
|
||||
```python
|
||||
def preprocess_frame(frame: np.ndarray, target_size: int = 640) -> tuple[np.ndarray, int, int]:
|
||||
"""
|
||||
Args:
|
||||
frame: BGR 格式 numpy array
|
||||
target_size: 縮放目標尺寸（預設 640）
|
||||
Returns:
|
||||
(frame_bgr565, original_width, original_height)
|
||||
- frame_bgr565: cv2 BGR565 格式
|
||||
"""
|
||||
|
||||
def postprocess(output_list, hw_preproc_info, original_width, original_height,
|
||||
target_size=640, thresh=0.2) -> ExampleYoloResult:
|
||||
"""
|
||||
YOLO V5 後處理主入口
|
||||
- 呼叫 post_process_yolo_v5()
|
||||
- 將 bounding box 座標縮放回原始影像尺寸
|
||||
"""
|
||||
|
||||
def post_process_yolo_v5(inference_float_node_output_list, hardware_preproc_info,
|
||||
thresh_value, with_sigmoid=True) -> ExampleYoloResult:
|
||||
"""
|
||||
完整 YOLO V5 後處理：
|
||||
- sigmoid 激活
|
||||
- anchor 解碼（使用內建 YOLO_V5_ANCHERS）
|
||||
- padding/縮放補償
|
||||
- 分數閾值過濾
|
||||
- NMS（per-class，IoU threshold=0.5）
|
||||
回傳 ExampleYoloResult
|
||||
"""
|
||||
```
|
||||
|
||||
#### Class: CustomInferenceWorkerThread（QThread）
|
||||
|
||||
```python
|
||||
class CustomInferenceWorkerThread(QThread):
|
||||
inference_result_signal = pyqtSignal(object) # 回傳 dict | None
|
||||
|
||||
frame_queue: queue.Queue
|
||||
min_interval: float
|
||||
mse_threshold: float
|
||||
_running: bool
|
||||
last_inference_time: float
|
||||
last_frame: np.ndarray | None
|
||||
cached_result: object | None
|
||||
input_params: dict
|
||||
|
||||
device_group: kp.DeviceGroup | None # Worker 內部管理的裝置連接
|
||||
model_descriptor: kp.ModelDescriptor | None
|
||||
is_initialized: bool
|
||||
custom_labels: list[str] | None
|
||||
```
|
||||
|
||||
| 方法 | 參數 | 回傳 | 說明 |
|
||||
|------|------|------|------|
|
||||
| `__init__(frame_queue, min_interval=0.5, mse_threshold=500)` | — | — | 初始化 |
|
||||
| `initialize_device()` | — | bool | 連接裝置、上傳 firmware 和模型（從 input_params 讀取路徑） |
|
||||
| `run_single_inference(frame)` | frame: np.ndarray | dict \| None | 執行單次 YOLOv5 推論，回傳結果 dict |
|
||||
| `run()` | — | None | 主迴圈（類似 InferenceWorkerThread，但無 once_mode） |
|
||||
| `cleanup()` | — | None | 斷開 device_group |
|
||||
| `stop()` | — | None | 設 `_running=False`，`wait()`，然後 `cleanup()` |
|
||||
|
||||
#### initialize_device() 的 input_params 期望 Keys
|
||||
|
||||
```python
|
||||
input_params = {
|
||||
"custom_model_path": str, # .nef 完整路徑
|
||||
"custom_scpu_path": str, # fw_scpu.bin 完整路徑
|
||||
"custom_ncpu_path": str, # fw_ncpu.bin 完整路徑
|
||||
"usb_port_id": int, # USB port 編號
|
||||
"custom_labels": list[str] | None # 自定義類別名稱（可選）
|
||||
}
|
||||
```
|
||||
|
||||
#### run_single_inference() 回傳格式
|
||||
|
||||
```python
|
||||
{
|
||||
"num_boxes": int,
|
||||
"bounding boxes": [[x1, y1, x2, y2], ...], # 注意：key 有空格
|
||||
"results": ["label1", "label2", ...]
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 注意**：key 為 `"bounding boxes"`（有空格），`MainWindow.handle_inference_result()` 中對應的處理 key 也是 `"bounding boxes"`（有空格），需保持一致。
|
||||
|
||||
#### YOLOv5 後處理常數
|
||||
|
||||
```python
|
||||
YOLO_V3_CELL_BOX_NUM = 3
|
||||
NMS_THRESH_YOLOV5 = 0.5
|
||||
YOLO_MAX_DETECTION_PER_CLASS = 100
|
||||
YOLO_V5_ANCHERS = np.array([
|
||||
[[10, 13], [16, 30], [33, 23]],
|
||||
[[30, 61], [62, 45], [59, 119]],
|
||||
[[116, 90], [156, 198], [373, 326]]
|
||||
])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.8 VideoThread
|
||||
|
||||
**路徑**：`src/models/video_thread.py`
|
||||
|
||||
#### Class: VideoThread（QThread）
|
||||
|
||||
```python
|
||||
class VideoThread(QThread):
|
||||
change_pixmap_signal = pyqtSignal(QImage) # 每幀觸發
|
||||
camera_error_signal = pyqtSignal(str) # 目前未被任何 Slot 連接
|
||||
|
||||
_run_flag: bool
|
||||
_camera_open_attempts: int
|
||||
_max_attempts: int # = 3
|
||||
_camera_timeout: int # = 5（秒）
|
||||
```
|
||||
|
||||
| 方法 | 參數 | 回傳 | 說明 |
|
||||
|------|------|------|------|
|
||||
| `_open_camera_with_timeout(camera_index, backend=None)` | camera_index: int, backend | cv2.VideoCapture \| None | 在 daemon thread 中開啟相機，5 秒 timeout |
|
||||
| `run()` | — | None | 嘗試最多 3 次開啟相機；成功後進入幀擷取迴圈 |
|
||||
| `stop()` | — | None | 設 `_run_flag=False` 並 `wait()` |
|
||||
|
||||
#### 相機設定
|
||||
|
||||
```python
|
||||
cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)
|
||||
cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)
|
||||
cap.set(cv2.CAP_PROP_FPS, 30)
|
||||
cap.set(cv2.CAP_PROP_BUFFERSIZE, 1) # 最小緩衝以降低延遲
|
||||
```
|
||||
|
||||
開啟順序：
|
||||
1. 優先嘗試 DirectShow backend（`cv2.CAP_DSHOW`）
|
||||
2. 失敗則嘗試預設 backend
|
||||
3. 兩者都失敗則等 1 秒後重試（最多 3 次）
|
||||
|
||||
幀格式轉換：
|
||||
```
|
||||
BGR（OpenCV 預設） → RGB（cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)）
|
||||
→ QImage.Format_RGB888
|
||||
→ change_pixmap_signal.emit(qt_image.copy())
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.9 DeviceService
|
||||
|
||||
**路徑**：`src/services/device_service.py`
|
||||
|
||||
#### Class: EmptyDescriptor
|
||||
|
||||
```python
|
||||
class EmptyDescriptor:
|
||||
device_descriptor_number: int = 0
|
||||
device_descriptor_list: list = []
|
||||
```
|
||||
|
||||
#### 函數
|
||||
|
||||
```python
|
||||
def check_available_device(timeout: float = 5.0) -> kp.DeviceDescriptors | EmptyDescriptor:
|
||||
"""
|
||||
在 daemon thread 中執行 kp.core.scan_devices()，設 timeout=5.0 秒。
|
||||
|
||||
Returns:
|
||||
- 成功：kp.DeviceDescriptors（含 device_descriptor_number 和 device_descriptor_list）
|
||||
- 失敗/Timeout/無裝置：EmptyDescriptor（device_descriptor_number = 0）
|
||||
|
||||
注意事項：
|
||||
- 使用 threading.Thread（非 QThread）
|
||||
- thread 設為 daemon=True，即使 timeout 後 thread 仍可能繼續執行
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.10 FileService
|
||||
|
||||
**路徑**：`src/services/file_service.py`
|
||||
|
||||
#### Class: FileService
|
||||
|
||||
```python
|
||||
class FileService:
|
||||
main_window: QWidget
|
||||
upload_dir: str # = UPLOAD_DIR（%LOCALAPPDATA%/Kneron_Academy/uploads）
|
||||
destination: str | None # 最近上傳的檔案完整路徑
|
||||
_camera_was_active: bool
|
||||
```
|
||||
|
||||
| 方法 | 參數 | 回傳 | 說明 |
|
||||
|------|------|------|------|
|
||||
| `upload_file()` | — | str \| None | 開啟檔案選擇器，複製檔案，觸發推論；回傳目的路徑 |
|
||||
| `show_message(icon, title, message)` | — | None | 顯示自訂樣式的 QMessageBox |
|
||||
|
||||
#### upload_file() 完整流程
|
||||
|
||||
```
|
||||
1. 若相機正在運行：
|
||||
a. 暫停推論（toggle_inference_pause()）
|
||||
b. 斷開 change_pixmap_signal（保留 VideoThread，不停止）
|
||||
2. QFileDialog.getOpenFileName()
|
||||
3. 若使用者取消 → return None
|
||||
4. 確認/建立 upload_dir
|
||||
5. 檢查來源檔案存在
|
||||
6. 測試目的地寫入權限
|
||||
7. shutil.copy2(source, destination)
|
||||
8. 更新 main_window.destination
|
||||
9. 若 inference_controller.current_tool_config 存在：
|
||||
a. 讀取並顯示圖片於 canvas_label
|
||||
b. inference_controller.process_uploaded_image(destination)
|
||||
10. finally：若相機之前活動，重新連接 Signal 並恢復推論
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.11 ConfigUtils
|
||||
|
||||
**路徑**：`src/utils/config_utils.py`
|
||||
|
||||
#### Class: ConfigUtils
|
||||
|
||||
| 方法 | 參數 | 回傳 | 說明 |
|
||||
|------|------|------|------|
|
||||
| `generate_global_config()` | — | dict | 掃描 UTILS_DIR，產生 config.json |
|
||||
| `create_model_config_template(model_path)` | model_path: str | bool | 為指定模型目錄建立 config.json 範本 |
|
||||
|
||||
#### generate_global_config() 輸出範例
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
{
|
||||
"mode": "object_detection",
|
||||
"display_name": "Object Detection",
|
||||
"models": [
|
||||
{
|
||||
"name": "yolov5_coco",
|
||||
"display_name": "Yolov5 Coco",
|
||||
"description": "YOLOv5 COCO object detection",
|
||||
"compatible_devices": ["KL520", "KL720"]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.12 image_utils
|
||||
|
||||
**路徑**：`src/utils/image_utils.py`
|
||||
|
||||
```python
|
||||
def qimage_to_numpy(qimage: QImage) -> np.ndarray:
|
||||
"""
|
||||
將 QImage 轉換為 numpy array。
|
||||
|
||||
先強制轉換為 QImage.Format_RGB888（確保格式一致）。
|
||||
|
||||
Returns:
|
||||
np.ndarray，形狀 (H, W, 3)，dtype=uint8，RGB 格式
|
||||
|
||||
注意：使用 qimage.bits() 直接存取記憶體，需確保 qimage 在 array 使用期間有效。
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. InferenceWorkerThread 與 script.py 介面規範
|
||||
|
||||
### 2.1 script.py 必須實作的函數
|
||||
|
||||
每個 Plugin 的 `script.py` **必須** 實作以下函數：
|
||||
|
||||
```python
|
||||
def inference(frame: np.ndarray, params: dict) -> dict | None:
|
||||
...
|
||||
```
|
||||
|
||||
`InferenceWorkerThread` 呼叫方式：
|
||||
```python
|
||||
result = self.inference_module.inference(frame, params=self.input_params)
|
||||
```
|
||||
|
||||
### 2.2 `frame` 參數規格
|
||||
|
||||
| 屬性 | 值 |
|
||||
|------|-----|
|
||||
| 型別 | `np.ndarray` |
|
||||
| 形狀 | `(H, W, 3)` |
|
||||
| dtype | `uint8` |
|
||||
| 色彩空間 | RGB（VideoThread 輸出）|
|
||||
| 典型尺寸 | 640 x 480 |
|
||||
|
||||
### 2.3 `params` 字典完整 Keys
|
||||
|
||||
以下 keys 由 `InferenceController.select_tool()` 注入，加上 model `config.json` 的 `input_parameters`：
|
||||
|
||||
| Key | 型別 | 必填 | 說明 |
|
||||
|-----|------|------|------|
|
||||
| `device_group` | kp.DeviceGroup \| None | 是 | kp SDK 連接的裝置群組 |
|
||||
| `usb_port_id` | int | 是 | USB port 編號 |
|
||||
| `scpu_path` | str | 否 | SCPU firmware 完整路徑 |
|
||||
| `ncpu_path` | str | 否 | NCPU firmware 完整路徑 |
|
||||
| `model` | str | 否 | .nef 模型完整路徑（若 config.json 有 model_file） |
|
||||
| `model_descriptor` | kp.ModelDescriptor \| None | 否 | 已上傳的模型描述（若有 model_file） |
|
||||
| `file_path` | str | 否 | image/voice 模式的上傳檔案路徑 |
|
||||
| （自訂）| any | 否 | 來自 model config.json 的 `input_parameters` 欄位 |
|
||||
|
||||
### 2.4 回傳值格式
|
||||
|
||||
#### 格式 A：無 Bounding Box（分類/其他結果）
|
||||
|
||||
觸發 `QMessageBox` 顯示：
|
||||
```python
|
||||
return {
|
||||
"result": "class_name",
|
||||
# 任意 key-value 對
|
||||
}
|
||||
```
|
||||
|
||||
#### 格式 B：單一 Bounding Box（舊格式，仍相容）
|
||||
|
||||
直接繪製於畫面：
|
||||
```python
|
||||
return {
|
||||
"bounding box": [x1, y1, x2, y2], # 整數，像素座標
|
||||
"result": "class_label" # 可選
|
||||
}
|
||||
```
|
||||
|
||||
#### 格式 C：多個 Bounding Box（推薦格式）
|
||||
|
||||
直接繪製於畫面：
|
||||
```python
|
||||
return {
|
||||
"bounding boxes": [ # 注意 key 有空格
|
||||
[x1, y1, x2, y2], # 整數，像素座標
|
||||
[x1, y1, x2, y2],
|
||||
...
|
||||
],
|
||||
"results": [ # 可選，與 bounding boxes 對應
|
||||
"label1",
|
||||
"label2",
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 回傳 None
|
||||
|
||||
表示此幀跳過，不更新 Bounding Box，不顯示 QMessageBox。
|
||||
|
||||
---
|
||||
|
||||
## 3. 裝置連接 API 流程（kp SDK 呼叫順序）
|
||||
|
||||
### 3.1 DeviceController.connect_device() 流程
|
||||
|
||||
```python
|
||||
# 1. 掃描（在 refresh_devices() 時已完成）
|
||||
descriptors = kp.core.scan_devices()
|
||||
# descriptors.device_descriptor_number: int
|
||||
# descriptors.device_descriptor_list: list
|
||||
|
||||
# 2. 連接
|
||||
device_group = kp.core.connect_devices(usb_port_ids=[usb_port_id])
|
||||
|
||||
# 3. 上傳 firmware
|
||||
kp.core.load_firmware_from_file(
|
||||
device_group=device_group,
|
||||
scpu_fw_path=scpu_path, # 完整路徑
|
||||
ncpu_fw_path=ncpu_path # 完整路徑
|
||||
)
|
||||
|
||||
# 4. 上傳模型（在 InferenceController.select_tool() 中，非 DeviceController）
|
||||
model_descriptor = kp.core.load_model_from_file(
|
||||
device_group=device_group,
|
||||
file_path=model_file_path
|
||||
)
|
||||
```
|
||||
|
||||
### 3.2 CustomInferenceWorkerThread.initialize_device() 流程
|
||||
|
||||
```python
|
||||
# 完整的連接 + firmware + model 上傳
|
||||
device_group = kp.core.connect_devices(usb_port_ids=[port_id])
|
||||
kp.core.set_timeout(device_group=device_group, milliseconds=5000)
|
||||
kp.core.load_firmware_from_file(device_group, scpu_path, ncpu_path)
|
||||
model_descriptor = kp.core.load_model_from_file(device_group, file_path=model_path)
|
||||
```
|
||||
|
||||
### 3.3 推論 API 呼叫順序（CustomInferenceWorkerThread）
|
||||
|
||||
```python
|
||||
# 建立推論描述符
|
||||
descriptor = kp.GenericImageInferenceDescriptor(
|
||||
model_id=model_descriptor.models[0].id,
|
||||
inference_number=0,
|
||||
input_node_image_list=[
|
||||
kp.GenericInputNodeImage(
|
||||
image=img_bgr565,
|
||||
image_format=kp.ImageFormat.KP_IMAGE_FORMAT_RGB565,
|
||||
resize_mode=kp.ResizeMode.KP_RESIZE_ENABLE,
|
||||
padding_mode=kp.PaddingMode.KP_PADDING_CORNER,
|
||||
normalize_mode=kp.NormalizeMode.KP_NORMALIZE_KNERON
|
||||
)
|
||||
]
|
||||
)
|
||||
|
||||
# 非同步發送推論請求
|
||||
kp.inference.generic_image_inference_send(device_group, descriptor)
|
||||
|
||||
# 接收推論結果（阻塞式）
|
||||
result = kp.inference.generic_image_inference_receive(device_group)
|
||||
# result.header.num_output_node: int
|
||||
# result.header.hw_pre_proc_info_list: list
|
||||
|
||||
# 取得每個輸出節點的 float 值
|
||||
for node_idx in range(result.header.num_output_node):
|
||||
node_output = kp.inference.generic_inference_retrieve_float_node(
|
||||
node_idx=node_idx,
|
||||
generic_raw_result=result,
|
||||
channels_ordering=kp.ChannelOrdering.KP_CHANNEL_ORDERING_CHW
|
||||
)
|
||||
# node_output.shape: (batch, channels, height, width)
|
||||
# node_output.ndarray: numpy array
|
||||
```
|
||||
|
||||
### 3.4 中斷連接
|
||||
|
||||
```python
|
||||
kp.core.disconnect_devices(device_group=device_group)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 推論 Queue 設計
|
||||
|
||||
### 4.1 基本規格
|
||||
|
||||
| 屬性 | 值 |
|
||||
|------|-----|
|
||||
| 類型 | `queue.Queue` |
|
||||
| maxsize | **5** |
|
||||
| 生產者 | `MediaController.update_image()`（VideoThread 幀）、`InferenceController.process_uploaded_image()`（圖片）、`InferenceController.select_tool()`（初始圖片） |
|
||||
| 消費者 | `InferenceWorkerThread.run()` 或 `CustomInferenceWorkerThread.run()` |
|
||||
|
||||
### 4.2 滿了怎麼辦（drop policy）
|
||||
|
||||
當 queue 滿時，**新幀被靜默丟棄**：
|
||||
|
||||
```python
|
||||
# add_frame_to_queue() 的邏輯
|
||||
if not self.inference_queue.full():
|
||||
self.inference_queue.put(frame)
|
||||
else:
|
||||
print("Warning: inference queue is full") # 只有 print，UI 不更新
|
||||
```
|
||||
|
||||
**⚠️ 問題**：這是 `put_nowait` 語意，但實際上是 `if not full` 檢查後再 `put`，在多執行緒環境中存在微小的 race window（check-then-act）。
|
||||
|
||||
### 4.3 清空時機
|
||||
|
||||
以下情況會清空 queue：
|
||||
|
||||
| 觸發 | 方法 | 說明 |
|
||||
|------|------|------|
|
||||
| 切換工具 | `InferenceController.select_tool()` 開頭 | 避免舊工具的幀被新 Worker 處理 |
|
||||
| 切換自定義工具 | `InferenceController.select_custom_tool()` 開頭 | 同上 |
|
||||
| 上傳圖片 | `InferenceController.process_uploaded_image()` 開頭 | 確保只處理最新上傳的圖片 |
|
||||
|
||||
### 4.4 Worker 從 Queue 取幀的行為
|
||||
|
||||
```python
|
||||
frame = self.frame_queue.get(timeout=0.1)
|
||||
# - 若 0.1 秒無幀，拋出 queue.Empty → continue
|
||||
# - 不 blocking（僅等 0.1 秒）
|
||||
# - 不呼叫 task_done()（queue 未使用 join 功能）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Signal/Slot 對應表
|
||||
|
||||
### 5.1 頁面導航 Signal（AppController 層）
|
||||
|
||||
| Signal | 發出 Class | Slot | 說明 |
|
||||
|--------|-----------|------|------|
|
||||
| `open_utilities` | SelectionScreen | AppController.show_login_screen | 點擊 Utilities 卡片 |
|
||||
| `open_demo_app` | SelectionScreen | AppController.show_demo_app | 點擊 Demo App 卡片 |
|
||||
| `login_success` | LoginScreen | AppController.show_utilities_screen | 登入成功 |
|
||||
| `back_to_selection` | LoginScreen | AppController.show_selection_screen | 點擊 Back |
|
||||
| `back_to_selection` | UtilitiesScreen | AppController.show_selection_screen | 點擊 Back |
|
||||
|
||||
### 5.2 媒體與推論 Signal（MainWindow 層）
|
||||
|
||||
| Signal | 型別 | 發出 Class | Slot | 說明 |
|
||||
|--------|------|-----------|------|------|
|
||||
| `change_pixmap_signal` | QImage | VideoThread | MediaController.update_image | 相機每幀 |
|
||||
| `camera_error_signal` | str | VideoThread | **未連接** | ⚠️ 無 Slot 接收 |
|
||||
| `inference_result_signal` | object | InferenceWorkerThread | MainWindow.handle_inference_result | 推論完成 |
|
||||
| `inference_result_signal` | object | CustomInferenceWorkerThread | MainWindow.handle_inference_result | 推論完成 |
|
||||
|
||||
**⚠️ 注意**：`VideoThread.camera_error_signal` 目前沒有任何 Slot 連接，相機錯誤不會通知 UI。
|
||||
|
||||
### 5.3 UtilitiesScreen 內部 Signal
|
||||
|
||||
| Signal | 發出 Class | 說明 |
|
||||
|--------|-----------|------|
|
||||
| `back_to_selection` | UtilitiesScreen | 點擊 Back 按鈕 |
|
||||
|
||||
---
|
||||
|
||||
## 6. config.json 完整 Schema 定義
|
||||
|
||||
### 6.1 全域 config.json（SCRIPT_CONFIG）
|
||||
|
||||
路徑：`%LOCALAPPDATA%/Kneron_Academy/utils/config.json`
|
||||
由 `ConfigUtils.generate_global_config()` 自動產生，不應手動修改。
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
{
|
||||
"mode": "string", // 模式目錄名稱（如 "object_detection"）
|
||||
"display_name": "string", // UI 顯示名稱（自動從 mode 名稱產生）
|
||||
"models": [
|
||||
{
|
||||
"name": "string", // 模型目錄名稱（如 "yolov5_coco"）
|
||||
"display_name": "string", // UI 顯示名稱（來自 model config.json）
|
||||
"description": "string", // 描述（來自 model config.json）
|
||||
"compatible_devices": ["string"] // 如 ["KL520", "KL720"]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 模型層級 config.json
|
||||
|
||||
路徑：`%LOCALAPPDATA%/Kneron_Academy/utils/{mode}/{model_name}/config.json`
|
||||
由 Plugin 開發者提供。
|
||||
|
||||
```json
|
||||
{
|
||||
"display_name": "string", // 必填：UI 顯示名稱
|
||||
"description": "string", // 選填：模型描述
|
||||
"model_file": "string", // 選填：.nef 檔名（若有則 InferenceController 自動上傳）
|
||||
"input_info": {
|
||||
"type": "video" | "image" | "voice", // 必填：輸入類型
|
||||
"supported_formats": ["string"] // 選填：支援的格式（目前主要用於文件）
|
||||
},
|
||||
"input_parameters": {
|
||||
// 選填：任意 key-value，會被合併進 input_params 傳給 script.py
|
||||
"threshold": 0.5,
|
||||
// 可包含任何 script.py 需要的參數
|
||||
},
|
||||
"compatible_devices": ["string"] // 必填：如 ["KL520", "KL720"]
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 ConfigUtils.create_model_config_template() 產生的範本
|
||||
|
||||
```json
|
||||
{
|
||||
"display_name": "Model Name",
|
||||
"description": "AI model for model_name",
|
||||
"model_file": "model_name.nef",
|
||||
"input_info": {
|
||||
"type": "video",
|
||||
"supported_formats": ["mp4", "avi"]
|
||||
},
|
||||
"input_parameters": {
|
||||
"threshold": 0.5
|
||||
},
|
||||
"compatible_devices": ["KL520", "KL720"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 已知限制與邊界條件
|
||||
|
||||
### 7.1 裝置相關限制
|
||||
|
||||
| 限制 | 描述 |
|
||||
|------|------|
|
||||
| 僅支援 KL520 / KL720 | `DongleModelMap` 只有這兩個映射；其他型號被標注為 "unknown" |
|
||||
| 單一裝置 | `connect_devices(usb_port_ids=[single_id])`，不支援多裝置並行推論 |
|
||||
| Firmware 必須預先放置 | `connect_device()` 不自動下載 firmware；若 `%LOCALAPPDATA%/Kneron_Academy/firmware/{dongle}/` 下不存在，回傳 False |
|
||||
| kp SDK timeout | `CustomInferenceWorkerThread.initialize_device()` 設定 timeout=5000ms；但 `DeviceController.connect_device()` 未設定 timeout |
|
||||
|
||||
### 7.2 相機相關限制
|
||||
|
||||
| 限制 | 描述 |
|
||||
|------|------|
|
||||
| 僅支援 camera index 0 | `cv2.VideoCapture(0, cv2.CAP_DSHOW)` — 硬體寫死 |
|
||||
| 最多嘗試 3 次 | `_max_attempts=3`；若 3 次後仍無法開啟，Worker 靜默退出，無 UI 通知 |
|
||||
| 解析度固定 640x480 | `cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)` 固定設定 |
|
||||
| camera_error_signal 未連接 | 相機錯誤只有 print，使用者不知道相機失敗 |
|
||||
|
||||
### 7.3 推論相關限制
|
||||
|
||||
| 限制 | 描述 |
|
||||
|------|------|
|
||||
| Custom Model 僅支援 YOLOv5 | `CustomInferenceWorkerThread` 的後處理 hardcode 了 YOLOv5 的 anchor 和 NMS 邏輯 |
|
||||
| COCO 80 類 | 預設使用 COCO 80 類別；需自定義類別時必須傳入 `custom_labels` |
|
||||
| Voice 模式未完整實作 | `input_info.type = "voice"` 的路徑只傳 `file_path`，無音訊處理邏輯在主程式 |
|
||||
| Image 模式一次只能處理一張 | `once_mode=True` 後 Worker 自動停止，需重新建立才能推論下一張 |
|
||||
| MSE 比較跨 frame 尺寸變化 | 若相機解析度切換，MSE 比較因形狀不一致而 reset（功能正確，但可能不符預期） |
|
||||
| Script module 快取問題 | `load_inference_module()` 每次切換工具都重新 `exec_module()`；若同一模組切換多次，Python module cache 可能有舊版本 |
|
||||
|
||||
### 7.4 Plugin 開發注意事項
|
||||
|
||||
| 事項 | 說明 |
|
||||
|------|------|
|
||||
| script.py 執行在 Worker Thread 中 | 不可在 script.py 中直接呼叫 PyQt UI 方法 |
|
||||
| script.py 不應長時間阻塞 | 若推論超過 `min_interval`，下一幀會等待 queue 中的幀累積 |
|
||||
| Bounding Box 座標系 | 座標為相對於 `frame`（QImage 轉出的 numpy array）的像素座標；若輸入解析度是 640x480，座標範圍為 0-639 / 0-479 |
|
||||
| script.py 例外處理 | `InferenceWorkerThread` 的 `try/except` 會捕捉 `script.inference()` 的例外，設 result=None 並繼續；不會中斷 Worker |
|
||||
|
||||
### 7.5 打包相關邊界條件
|
||||
|
||||
| 條件 | 問題 |
|
||||
|------|------|
|
||||
| PyInstaller + kp SDK | kp 為 C Extension，需在 `.spec` 中手動設定 `hiddenimports` |
|
||||
| UXUI_ASSETS 路徑 | 開發模式下透過 `__file__` 計算；打包後需改用 `sys._MEIPASS` |
|
||||
| `FIRMWARE_PATHS` 常數 | 使用相對路徑，打包後無效；實際使用的是 `FW_DIR` + dongle 名稱（正確） |
|
||||
| script.py 動態載入 | Plugin 的 `script.py` 必須放在 `%LOCALAPPDATA%`（外部目錄），不能打包進 exe |
|
||||
569
.autoflow/04-architecture/design-doc.md
Normal file
569
.autoflow/04-architecture/design-doc.md
Normal file
@ -0,0 +1,569 @@
|
||||
# Design Doc: KNEO Academy（Innovedus AI Playground）v2.0
|
||||
|
||||
**作者**：Architect Agent
|
||||
**狀態**：Draft（從既有程式碼反向整理）
|
||||
**日期**：2026-04-04
|
||||
**產品版本**：v2.0
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景與目標
|
||||
|
||||
### 1.1 產品概述
|
||||
|
||||
KNEO Academy（對外名稱：Innovedus AI Playground）是一套 Windows 桌面應用程式，讓擁有 Kneron NPU USB Dongle 的使用者能夠在本機端執行 Edge AI 推論，無需雲端服務、無需撰寫程式碼。
|
||||
|
||||
**核心使用情境**：
|
||||
- 業務展示：即插即用，開箱展示 AI 推論能力
|
||||
- 研發驗證：快速測試 Kneron NPU 在特定任務的推論效果
|
||||
- 客戶自訂：上傳自訂 `.nef` 模型進行推論測試
|
||||
|
||||
### 1.2 設計目標
|
||||
|
||||
- **即插即用**：連接 Kneron dongle 後，數秒內可開始推論
|
||||
- **Plugin 化架構**：透過目錄結構 + `config.json` + `script.py` 新增模型，不需修改主程式
|
||||
- **Thread 隔離**：UI 執行緒與推論執行緒完全分離，確保畫面不卡頓
|
||||
- **PyInstaller 相容**：可打包為單一可執行檔，方便分發
|
||||
|
||||
### 1.3 非目標（Out of Scope）
|
||||
|
||||
- 雲端推論或 API 服務
|
||||
- 多裝置同時推論
|
||||
- 行動平台支援
|
||||
|
||||
---
|
||||
|
||||
## 2. 整體架構概覽
|
||||
|
||||
### 2.1 設計模式
|
||||
|
||||
本應用程式採用 **MVC（Model-View-Controller）** 架構，搭配 Qt 的 **Signal/Slot** 機制實現跨執行緒通訊。
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Views（呈現層） │
|
||||
│ SelectionScreen LoginScreen MainWindow UtilitiesScreen │
|
||||
│ QWidget QWidget QWidget QWidget │
|
||||
└────────────────────────────┬────────────────────────────────────┘
|
||||
│ Signal/Slot
|
||||
┌────────────────────────────▼────────────────────────────────────┐
|
||||
│ AppController（main.py） │
|
||||
│ QStackedWidget — 頁面路由中樞 │
|
||||
└──────┬──────────────────┬───────────────────┬───────────────────┘
|
||||
│ │ │
|
||||
┌──────▼──────┐ ┌────────▼────────┐ ┌──────▼──────────┐
|
||||
│ Device │ │ Inference │ │ Media │
|
||||
│ Controller │ │ Controller │ │ Controller │
|
||||
│ （裝置管理） │ │ （推論管理） │ │ （相機/媒體） │
|
||||
└──────┬──────┘ └───────┬─────────┘ └──────┬──────────┘
|
||||
│ │ │
|
||||
┌──────▼──────┐ ┌───────▼─────────┐ ┌──────▼──────────┐
|
||||
│ device_ │ │ InferenceWorker │ │ VideoThread │
|
||||
│ service.py │ │ Thread │ │ （QThread） │
|
||||
│ （kp SDK） │ │ （QThread） │ │ （OpenCV 擷取） │
|
||||
└─────────────┘ └────────┬────────┘ └─────────────────┘
|
||||
│ 動態載入
|
||||
┌────────▼────────┐
|
||||
│ script.py │
|
||||
│ （Plugin 推論） │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### 2.2 頁面導航架構
|
||||
|
||||
AppController 使用 `QStackedWidget` 作為根容器，所有頁面在啟動時一次性初始化，透過 `setCurrentWidget()` 切換顯示，不需重新建立物件。
|
||||
|
||||
```
|
||||
AppController
|
||||
└── QStackedWidget（stack）
|
||||
├── [index 0] SelectionScreen ← 預設顯示
|
||||
├── [index 1] LoginScreen
|
||||
├── [index 2] UtilitiesScreen
|
||||
└── [index 3] MainWindow
|
||||
```
|
||||
|
||||
**Signal 連接關係（頁面切換）**：
|
||||
|
||||
| 發出者 | Signal | 接收者（Slot） | 效果 |
|
||||
|--------|--------|--------------|------|
|
||||
| SelectionScreen | `open_utilities` | `AppController.show_login_screen` | 跳至登入頁 |
|
||||
| SelectionScreen | `open_demo_app` | `AppController.show_demo_app` | 跳至主視窗 |
|
||||
| LoginScreen | `login_success` | `AppController.show_utilities_screen` | 登入成功，進入工具頁 |
|
||||
| LoginScreen | `back_to_selection` | `AppController.show_selection_screen` | 返回首頁 |
|
||||
| UtilitiesScreen | `back_to_selection` | `AppController.show_selection_screen` | 返回首頁 |
|
||||
|
||||
### 2.3 MainWindow 內部架構
|
||||
|
||||
MainWindow 是 AI Demo 推論的核心容器，內部持有三個 Controller 組成協作關係：
|
||||
|
||||
```
|
||||
MainWindow（QWidget）
|
||||
├── DeviceController — 管理 kp SDK 裝置連接
|
||||
├── InferenceController — 管理推論 Worker Thread 與 Queue
|
||||
│ └── inference_queue（queue.Queue, maxsize=5）
|
||||
└── MediaController — 管理相機擷取與畫面更新
|
||||
└── VideoThread（QThread）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 模組依賴圖
|
||||
|
||||
```
|
||||
main.py（AppController）
|
||||
├── views/selection_screen.py（SelectionScreen）
|
||||
│ └── config.py
|
||||
├── views/login_screen.py（LoginScreen）
|
||||
│ └── config.py
|
||||
├── views/utilities_screen.py（UtilitiesScreen）
|
||||
│ ├── config.py
|
||||
│ ├── controllers/device_controller.py（DeviceController）
|
||||
│ └── services/device_service.py（check_available_device）
|
||||
└── views/mainWindows.py（MainWindow）
|
||||
├── config.py
|
||||
├── controllers/device_controller.py（DeviceController）
|
||||
│ ├── config.py
|
||||
│ └── services/device_service.py
|
||||
├── controllers/inference_controller.py（InferenceController）
|
||||
│ ├── config.py
|
||||
│ ├── models/inference_worker.py（InferenceWorkerThread）
|
||||
│ │ ├── config.py
|
||||
│ │ └── [動態載入] utils/{mode}/{model}/script.py
|
||||
│ └── models/custom_inference_worker.py（CustomInferenceWorkerThread）
|
||||
├── controllers/media_controller.py（MediaController）
|
||||
│ ├── models/video_thread.py（VideoThread）
|
||||
│ └── utils/image_utils.py
|
||||
├── services/file_service.py（FileService）
|
||||
└── utils/config_utils.py（ConfigUtils）
|
||||
```
|
||||
|
||||
**注意**：`UtilitiesScreen` 建立了**自己的** `DeviceController` 實例（與 `MainWindow` 的是不同物件），兩者不共享裝置狀態。
|
||||
|
||||
---
|
||||
|
||||
## 4. 資料流程圖
|
||||
|
||||
### 4.1 Video 即時推論流程
|
||||
|
||||
```
|
||||
相機硬體
|
||||
│ 每幀（~30fps）
|
||||
▼
|
||||
VideoThread.run()
|
||||
│ QImage
|
||||
│ change_pixmap_signal.emit(qt_image)
|
||||
▼
|
||||
MediaController.update_image(qt_image)
|
||||
├── 1. 繪製 Bounding Box → canvas_label.setPixmap(pixmap)
|
||||
└── 2. qimage_to_numpy(qt_image) → frame_np
|
||||
│
|
||||
▼
|
||||
InferenceController.add_frame_to_queue(frame_np)
|
||||
│ 若 queue 未滿（maxsize=5）
|
||||
▼
|
||||
inference_queue.put(frame_np)
|
||||
│
|
||||
▼
|
||||
InferenceWorkerThread.run()
|
||||
├── 1. MSE 比較（與前一幀）→ 差異不大時，emit 快取結果
|
||||
├── 2. 時間間隔檢查（min_interval=2秒）
|
||||
└── 3. script.inference(frame, params) → result
|
||||
│
|
||||
│ inference_result_signal.emit(result)
|
||||
▼
|
||||
MainWindow.handle_inference_result(result)
|
||||
├── 若有 "bounding box"/"bounding boxes"
|
||||
│ → 更新 current_bounding_boxes（下一幀繪製）
|
||||
└── 若無 bounding box → QMessageBox 彈出顯示
|
||||
```
|
||||
|
||||
### 4.2 Image 推論流程
|
||||
|
||||
```
|
||||
使用者點擊「Upload」
|
||||
│
|
||||
▼
|
||||
FileService.upload_file()
|
||||
├── 1. 暫停相機 Signal（disconnect change_pixmap_signal）
|
||||
├── 2. QFileDialog 選檔
|
||||
├── 3. shutil.copy2() → %LOCALAPPDATA%/Kneron_Academy/uploads/
|
||||
├── 4. 顯示圖片於 canvas_label
|
||||
└── 5. InferenceController.process_uploaded_image(file_path)
|
||||
│
|
||||
▼
|
||||
_clear_inference_queue()
|
||||
inference_queue.put(img)
|
||||
│
|
||||
▼
|
||||
InferenceWorkerThread（once_mode=True）
|
||||
│ 只處理一幀後停止
|
||||
▼
|
||||
script.inference(frame, params) → result
|
||||
│
|
||||
│ inference_result_signal.emit(result)
|
||||
▼
|
||||
MainWindow.handle_inference_result(result)
|
||||
```
|
||||
|
||||
### 4.3 Custom Model 推論流程
|
||||
|
||||
```
|
||||
使用者提供：
|
||||
- custom_model_path（.nef 檔）
|
||||
- custom_scpu_path（fw_scpu.bin）
|
||||
- custom_ncpu_path（fw_ncpu.bin）
|
||||
- custom_labels（可選）
|
||||
│
|
||||
▼
|
||||
InferenceController.select_custom_tool(tool_config)
|
||||
│
|
||||
▼
|
||||
CustomInferenceWorkerThread（QThread）
|
||||
│
|
||||
├── initialize_device()（首次執行時）
|
||||
│ ├── kp.core.connect_devices([port_id])
|
||||
│ ├── kp.core.load_firmware_from_file(scpu, ncpu)
|
||||
│ └── kp.core.load_model_from_file(model_path)
|
||||
│
|
||||
└── run_single_inference(frame)
|
||||
├── preprocess_frame()（resize to 640, BGR → BGR565）
|
||||
├── kp.GenericImageInferenceDescriptor
|
||||
├── kp.inference.generic_image_inference_send()
|
||||
├── kp.inference.generic_image_inference_receive()
|
||||
├── kp.inference.generic_inference_retrieve_float_node()
|
||||
└── post_process_yolo_v5() → ExampleYoloResult
|
||||
│
|
||||
│ inference_result_signal.emit(result_dict)
|
||||
▼
|
||||
MainWindow.handle_inference_result()
|
||||
```
|
||||
|
||||
**注意**：`CustomInferenceWorkerThread` 在 Worker Thread 內部**自行連接/重置裝置**，與 `DeviceController` 管理的 `device_group` 是**不同的連接**。這是一個雙重連接問題（見第 8 節技術問題）。
|
||||
|
||||
---
|
||||
|
||||
## 5. Thread 架構
|
||||
|
||||
### 5.1 執行緒關係圖
|
||||
|
||||
```
|
||||
Qt Main Thread（UI Thread）
|
||||
├── AppController（QStackedWidget 管理）
|
||||
├── MainWindow（UI 事件處理）
|
||||
│ ├── handle_inference_result() ← 由 Signal 呼叫（執行在主執行緒）
|
||||
│ └── update_image() via MediaController ← 由 Signal 呼叫（執行在主執行緒）
|
||||
│
|
||||
├── VideoThread（QThread #1）
|
||||
│ └── 職責：相機擷取、QImage 轉換、emit change_pixmap_signal
|
||||
│ └── 內部：threading.Thread（用於相機開啟 timeout 機制）
|
||||
│
|
||||
├── InferenceWorkerThread（QThread #2）
|
||||
│ └── 職責：從 queue 取幀、MSE 比較、呼叫 script.inference()、emit 結果
|
||||
│
|
||||
└── CustomInferenceWorkerThread（QThread #3，替代 InferenceWorkerThread）
|
||||
└── 職責：device init、kp 推論、YOLOv5 後處理、emit 結果
|
||||
```
|
||||
|
||||
### 5.2 裝置掃描的執行緒
|
||||
|
||||
`check_available_device()` 使用 `threading.Thread`（非 QThread）執行 `kp.core.scan_devices()`，並設 5 秒 timeout：
|
||||
|
||||
```
|
||||
check_available_device() in Main Thread
|
||||
└── threading.Thread（daemon=True）
|
||||
└── kp.core.scan_devices()（阻塞式 SDK 呼叫）
|
||||
thread.join(timeout=5.0)
|
||||
```
|
||||
|
||||
同樣地，`VideoThread._open_camera_with_timeout()` 也使用 `threading.Thread` 開啟相機，timeout 為 5 秒。
|
||||
|
||||
### 5.3 跨執行緒通訊
|
||||
|
||||
所有跨執行緒通訊均透過 Qt Signal/Slot 機制，Qt 保證跨執行緒的 Signal 會在接收執行緒的 Event Loop 中排隊執行：
|
||||
|
||||
| Signal | 發出執行緒 | 接收執行緒（Slot） |
|
||||
|--------|-----------|----------------|
|
||||
| `VideoThread.change_pixmap_signal` | VideoThread | Main Thread（`MediaController.update_image`） |
|
||||
| `InferenceWorkerThread.inference_result_signal` | InferenceWorkerThread | Main Thread（`MainWindow.handle_inference_result`） |
|
||||
| `CustomInferenceWorkerThread.inference_result_signal` | CustomInferenceWorkerThread | Main Thread（`MainWindow.handle_inference_result`） |
|
||||
|
||||
---
|
||||
|
||||
## 6. Plugin 系統設計
|
||||
|
||||
### 6.1 架構概念
|
||||
|
||||
Plugin 系統讓 Kneron 或第三方可以透過放置目錄和設定檔來新增 AI 工具，完全不需修改主程式碼。
|
||||
|
||||
### 6.2 目錄結構
|
||||
|
||||
```
|
||||
%LOCALAPPDATA%/Kneron_Academy/utils/
|
||||
├── config.json ← 全域 Plugin 索引（自動產生）
|
||||
├── {mode_name}/ ← 推論模式目錄（如 object_detection）
|
||||
│ └── {model_name}/ ← 模型目錄（如 yolov5_person）
|
||||
│ ├── config.json ← 模型設定
|
||||
│ ├── script.py ← 推論腳本（Plugin 核心）
|
||||
│ └── {model_name}.nef ← Kneron 模型檔
|
||||
```
|
||||
|
||||
### 6.3 Plugin 載入流程
|
||||
|
||||
```
|
||||
應用程式啟動
|
||||
│
|
||||
▼
|
||||
ConfigUtils.generate_global_config()
|
||||
├── 掃描 utils/ 下所有 mode 目錄（跳過 _ 開頭的目錄）
|
||||
├── 掃描每個 mode 下所有 model 目錄
|
||||
├── 讀取每個 model/config.json
|
||||
└── 輸出 utils/config.json（Plugin 索引）
|
||||
|
||||
使用者選擇工具
|
||||
│
|
||||
▼
|
||||
InferenceController.select_tool(tool_config)
|
||||
│
|
||||
▼
|
||||
InferenceWorkerThread.__init__()
|
||||
└── load_inference_module(mode, model_name)
|
||||
└── importlib.util.spec_from_file_location()
|
||||
→ 動態 import utils/{mode}/{model}/script.py
|
||||
```
|
||||
|
||||
### 6.4 `script.py` 介面規範
|
||||
|
||||
每個 Plugin 的 `script.py` 必須實作以下介面：
|
||||
|
||||
```python
|
||||
def inference(frame: np.ndarray, params: dict) -> dict | None:
|
||||
"""
|
||||
Args:
|
||||
frame: 影像幀，numpy array，形狀 (H, W, 3)，RGB 格式
|
||||
params: 推論參數字典（詳見 config.json schema）
|
||||
|
||||
Returns:
|
||||
dict 或 None（None 表示跳過此幀）
|
||||
|
||||
支援的回傳格式（在 handle_inference_result 中處理）：
|
||||
|
||||
格式 A：單一 Bounding Box
|
||||
{
|
||||
"bounding box": [x1, y1, x2, y2],
|
||||
"result": "class_label"
|
||||
}
|
||||
|
||||
格式 B：多個 Bounding Box（推薦）
|
||||
{
|
||||
"bounding boxes": [[x1, y1, x2, y2], ...],
|
||||
"results": ["label1", "label2", ...]
|
||||
}
|
||||
|
||||
格式 C：任意分類結果（彈出 QMessageBox 顯示）
|
||||
{
|
||||
"key": "value",
|
||||
...
|
||||
}
|
||||
"""
|
||||
```
|
||||
|
||||
### 6.5 `params` 字典的內容
|
||||
|
||||
`InferenceController.select_tool()` 在建立 `InferenceWorkerThread` 前，會將以下資訊注入 `input_params`：
|
||||
|
||||
| Key | 型別 | 來源 |
|
||||
|-----|------|------|
|
||||
| `device_group` | kp.DeviceGroup | DeviceController |
|
||||
| `usb_port_id` | int | 已連接裝置 |
|
||||
| `scpu_path` | str | firmware 路徑 |
|
||||
| `ncpu_path` | str | firmware 路徑 |
|
||||
| `model` | str | model .nef 完整路徑 |
|
||||
| `model_descriptor` | kp.ModelDescriptor | 已上傳的模型描述 |
|
||||
| `file_path` | str | 圖片/聲音模式的上傳檔案路徑 |
|
||||
| （其他） | any | 來自 model config.json 的 `input_parameters` |
|
||||
|
||||
---
|
||||
|
||||
## 7. 資料存放設計
|
||||
|
||||
### 7.1 執行期資料目錄
|
||||
|
||||
全部存放於 Windows 的 `%LOCALAPPDATA%\Kneron_Academy\`：
|
||||
|
||||
```
|
||||
%LOCALAPPDATA%\Kneron_Academy\
|
||||
├── utils\
|
||||
│ ├── config.json ← Plugin 全域索引（啟動時自動產生）
|
||||
│ ├── {mode}\
|
||||
│ │ └── {model}\
|
||||
│ │ ├── config.json ← 模型設定
|
||||
│ │ ├── script.py ← 推論腳本
|
||||
│ │ └── *.nef ← 模型檔
|
||||
│ └── ...
|
||||
├── uploads\ ← 使用者上傳的圖片（不自動清理）
|
||||
│ └── *.jpg / *.png / *.wav / ...
|
||||
└── firmware\
|
||||
├── KL520\
|
||||
│ ├── fw_scpu.bin
|
||||
│ └── fw_ncpu.bin
|
||||
└── KL720\
|
||||
├── fw_scpu.bin
|
||||
└── fw_ncpu.bin
|
||||
```
|
||||
|
||||
### 7.2 靜態 UI 資源
|
||||
|
||||
打包在應用程式內（`uxui/` 目錄），路徑透過 `PROJECT_ROOT` 常數計算：
|
||||
|
||||
```python
|
||||
PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
UXUI_ASSETS = os.path.join(PROJECT_ROOT, "uxui", "")
|
||||
```
|
||||
|
||||
**PyInstaller 注意**：打包後 `__file__` 的位置會改變，需確認 `UXUI_ASSETS` 路徑在打包後仍正確（詳見第 8.3 節）。
|
||||
|
||||
---
|
||||
|
||||
## 8. 打包架構（PyInstaller）
|
||||
|
||||
### 8.1 打包工具鏈
|
||||
|
||||
- **PyInstaller 6.12.0**：將 Python 應用打包為 Windows .exe
|
||||
- **Inno Setup**（`dist/test.iss`）：製作 Windows 安裝包 (.exe installer)
|
||||
- **PyArmor**（計畫中）：混淆/加密 Python 原始碼
|
||||
|
||||
### 8.2 打包注意事項
|
||||
|
||||
| 項目 | 問題 | 解決方向 |
|
||||
|------|------|---------|
|
||||
| `kp` SDK | kp 是 C Extension，需確認是否能被 PyInstaller 正確打包 | 需設定 `hiddenimports` 或 `binaries` |
|
||||
| 動態 import | `importlib.util.spec_from_file_location()` 在打包後需從外部路徑載入 | `script.py` 必須放在 `%LOCALAPPDATA%`，不能打包進 exe |
|
||||
| `UXUI_ASSETS` 路徑 | 打包後 `__file__` 指向臨時目錄 | 需在 `.spec` 中設定 `datas`，並使用 `sys._MEIPASS` 處理路徑 |
|
||||
| OpenCV | OpenCV 需包含 DLL | 通常 PyInstaller 能自動偵測 |
|
||||
|
||||
### 8.3 目錄結構（打包後）
|
||||
|
||||
```
|
||||
安裝目錄/
|
||||
├── Innovedus AI Playground.exe ← 主執行檔
|
||||
├── uxui/ ← 靜態資源（需隨 exe 一起安裝）
|
||||
└── ...
|
||||
|
||||
%LOCALAPPDATA%\Kneron_Academy\ ← 使用者資料（安裝時建立）
|
||||
├── utils/
|
||||
├── uploads/
|
||||
└── firmware/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 已知技術問題 / 技術債
|
||||
|
||||
### 9.1 雙重裝置連接（⚠️ 嚴重）
|
||||
|
||||
**問題**：`CustomInferenceWorkerThread` 在 Worker Thread 內部調用 `kp.core.connect_devices()`，但 `DeviceController` 可能已經對同一個 `usb_port_id` 建立了連接（在 MainWindow 流程中）。
|
||||
|
||||
**影響**：可能導致 kp SDK 報告「裝置已被連接」的錯誤，或產生未定義行為。
|
||||
|
||||
**建議**：`CustomInferenceWorkerThread` 應改為接受外部傳入的 `device_group`，而非自行連接。
|
||||
|
||||
### 9.2 UtilitiesScreen 的 DeviceController 孤立問題（⚠️ 中度）
|
||||
|
||||
**問題**：`UtilitiesScreen` 建立了自己的 `DeviceController(self)` 實例，與 `MainWindow` 的 `DeviceController` 完全獨立，兩者各自管理自己的 `device_group`。
|
||||
|
||||
**影響**：使用者在 UtilitiesScreen 連接裝置後，切換到 MainWindow 並不知道裝置已連接；反之亦然。
|
||||
|
||||
**建議**：將 `DeviceController` 提升到 `AppController` 層級，作為共享的單例。
|
||||
|
||||
### 9.3 推論 Queue 丟幀而不通知（⚠️ 中度）
|
||||
|
||||
**問題**：`inference_queue` 的 `maxsize=5`，當 queue 滿時，`add_frame_to_queue()` 靜默丟棄幀（只印 print，不通知 UI）。
|
||||
|
||||
**影響**：在高推論延遲時，使用者不知道有幀被丟棄，可能誤以為推論仍在即時進行。
|
||||
|
||||
**建議**：新增 UI 指示推論 queue 壓力（如幀率顯示、lag 指示）。
|
||||
|
||||
### 9.4 LoginScreen 的驗證邏輯未實作（⚠️ 中度）
|
||||
|
||||
**問題**：`LoginScreen.attempt_login()` 的實際 Server 驗證邏輯未實作，目前只要輸入任何非空帳密就會成功登入。
|
||||
|
||||
```python
|
||||
# 目前實作（不安全）
|
||||
if not username or not password:
|
||||
self.show_error("Please enter both username and password")
|
||||
return
|
||||
self.login_success.emit() # 永遠成功
|
||||
```
|
||||
|
||||
**建議**：需補齊 Server 端驗證 API 呼叫。
|
||||
|
||||
### 9.5 debug print 語句散落各處（低優先）
|
||||
|
||||
**問題**：各 Controller 和 Thread 中有大量 `print()` 呼叫作為 debug 輸出，打包後仍會執行（輸出被丟棄，但有效能成本）。
|
||||
|
||||
**建議**：改用 Python 的 `logging` 模組，並設定適當的 log level。
|
||||
|
||||
### 9.6 `custom_inference_worker.py` 中的 `kp` 全域引用問題（⚠️ 中度）
|
||||
|
||||
**問題**：`_boxes_scale()` 和 `post_process_yolo_v5()` 函數的型別標注直接引用 `kp.HwPreProcInfo`、`kp.InferenceFloatNodeOutput`（如 `def _boxes_scale(boxes, hardware_preproc_info: kp.HwPreProcInfo)`），但 `kp` 在模組頂層未被 import。實際 kp import 是在函數內部的 `run_single_inference()` 中延遲進行的。
|
||||
|
||||
**影響**：型別標注在模組載入時會被解析（在 Python 3.10+ 以下），可能導致 `NameError`。
|
||||
|
||||
**建議**：在頂層加入 `if TYPE_CHECKING: import kp`，或改用字串型別標注 `"kp.HwPreProcInfo"`。
|
||||
|
||||
### 9.7 VideoThread 的 `threading.Thread` 記憶體洩漏風險（低優先）
|
||||
|
||||
**問題**：`_open_camera_with_timeout()` 啟動了 `daemon=True` 的 `threading.Thread` 並等待最多 5 秒，但如果 thread 仍存活（timeout），其仍會繼續嘗試開啟相機，可能導致相機資源被不正確佔用。
|
||||
|
||||
**建議**：使用 cv2 的 nonblocking 方式或設定相機 timeout 參數，避免 daemon thread 的不確定行為。
|
||||
|
||||
### 9.8 MSE 計算的效能問題（低優先）
|
||||
|
||||
**問題**：`InferenceWorkerThread` 和 `CustomInferenceWorkerThread` 的 MSE 計算會把整個 frame 轉成 float32 進行運算：
|
||||
```python
|
||||
mse = np.mean((frame.astype(np.float32) - self.last_frame.astype(np.float32)) ** 2)
|
||||
```
|
||||
對於 640x480 的 3 通道影像，每次計算需要處理 ~921,600 個浮點數。
|
||||
|
||||
**建議**：可改為縮小解析度後再計算 MSE，或使用 histogram 比較等更快速的方式。
|
||||
|
||||
---
|
||||
|
||||
## 10. 容量與效能估算
|
||||
|
||||
### 10.1 系統需求（桌面應用）
|
||||
|
||||
| 資源 | 需求 | 備註 |
|
||||
|------|------|------|
|
||||
| CPU | 雙核心以上 | 主要用於影像轉換和後處理 |
|
||||
| RAM | 2GB 以上 | kp SDK + OpenCV + PyQt5 |
|
||||
| USB | USB 3.0 | KL720 需要 USB 3.0 |
|
||||
| GPU | 不需要 | 推論在 NPU 執行 |
|
||||
| 磁碟 | 500MB 以上 | 安裝包 + 模型檔 |
|
||||
|
||||
### 10.2 推論速度特性
|
||||
|
||||
- **Queue maxsize**：5 幀
|
||||
- **VideoThread 輸出**：~30fps（640x480）
|
||||
- **InferenceWorkerThread min_interval**：2 秒（標準模式）/ 0.5 秒（Custom 模式）
|
||||
- **MSE threshold**：500（低於此值視為相似幀，使用快取結果）
|
||||
- **相機開啟 timeout**：5 秒 × 最多 3 次嘗試
|
||||
|
||||
---
|
||||
|
||||
## 11. 安全性設計
|
||||
|
||||
### 11.1 目前狀態
|
||||
|
||||
| 項目 | 狀態 | 說明 |
|
||||
|------|------|------|
|
||||
| Server 登入驗證 | ❌ 未實作 | `attempt_login()` 永遠成功 |
|
||||
| 程式碼保護 | ⚠️ 計畫中 | PyArmor 列在計畫中 |
|
||||
| 自定義模型驗證 | ❌ 無 | 任何 .nef 檔都能上傳 |
|
||||
| 網路通訊加密 | ❌ 未知 | Server 驗證端點未見 TLS 設定 |
|
||||
|
||||
### 11.2 Plugin 安全風險
|
||||
|
||||
`load_inference_module()` 使用 `importlib` 動態執行 `script.py`，等同於執行任意 Python 程式碼。若 `%LOCALAPPDATA%` 中的 `script.py` 被惡意替換，攻擊者可以完整控制推論行為。
|
||||
|
||||
**建議**：考慮對 `script.py` 進行簽章驗證，或限制其沙盒執行環境。
|
||||
39
.autoflow/progress.md
Normal file
39
.autoflow/progress.md
Normal file
@ -0,0 +1,39 @@
|
||||
# 專案進度 — KNEO Academy
|
||||
|
||||
## 目的：既有專案接入 → 補齊文件
|
||||
## 當前階段：文件補齊完成，待使用者確認下一步
|
||||
## 當前狀態：待審核
|
||||
## 最後更新：2026-04-05
|
||||
|
||||
## 進度表
|
||||
| 階段 | 狀態 | 完成時間 | 備註 |
|
||||
|------|------|----------|------|
|
||||
| 既有專案接入 | ✅ 已完成 | 2026-04-04 | 本地路徑 |
|
||||
| 專案健檢 | ✅ 已完成 | 2026-04-04 | 見 00-onboarding/health-check.md |
|
||||
| 確認目的與策略 | ✅ 已完成 | 2026-04-04 | 客戶產品，補齊 PRD + 架構文件 + 設計規格 |
|
||||
| PRD（PM Agent 反推） | ✅ 已完成 | 2026-04-04 | 見 02-prd/PRD.md，⚠️ 項目保留待確認 |
|
||||
| 架構文件 + TDD（Architect Agent） | ✅ 已完成 | 2026-04-04 | 見 04-architecture/design-doc.md + TDD.md |
|
||||
| 設計規格（Design Agent） | ✅ 已完成 | 2026-04-05 | 見 03-design/design-spec.md |
|
||||
| 使用者確認各文件 | ✅ 已完成 | 2026-04-05 | PRD + 架構文件已確認；設計規格待確認 |
|
||||
|
||||
## 當前待辦
|
||||
- [ ] 使用者審核設計規格（03-design/design-spec.md）
|
||||
- [ ] 決定下一步（新增功能 / 修 bug / 其他）
|
||||
|
||||
## 未解決問題
|
||||
- PRD 中 ⚠️ 待確認項目（保留待日後確認）
|
||||
- 技術問題（Architect Agent 標注）：
|
||||
- 🔴 CustomInferenceWorkerThread 雙重裝置連接風險
|
||||
- 🔴 LoginScreen 驗證未實作
|
||||
- 🟡 UtilitiesScreen DeviceController 孤立
|
||||
- 設計問題（Design Agent 標注）：
|
||||
- 兩套設計語言（深色 vs 淺色）共存，視覺不統一
|
||||
- back_arrow.png 缺失，返回按鈕空白
|
||||
- 暫停按鈕使用語意錯誤的刪除圖示
|
||||
|
||||
## 重要決策紀錄
|
||||
- 程式碼來源：本地路徑 C:\Users\sungs\Documents\abin\KNEO-Academy
|
||||
- 專案類型：客戶產品（Python + PyQt5 桌面 AI 推論應用）
|
||||
- 設計稿：無 Figma，僅 uxui/ 資源
|
||||
- 測試計畫：暫不需要
|
||||
- PRD 待確認項目：保留現狀，不強迫確認
|
||||
Loading…
x
Reference in New Issue
Block a user