pchang718
166 lines
12 KiB
Markdown
166 lines
12 KiB
Markdown
# DSP Bode Plot 專案進度總結 (2026-05-15)
|
||
|
||
## 1. 核心功能優化 (DSP & 定點數運算)
|
||
- **細部微調 (Fine-tuning)**：實施了基於 $\delta$ (Delta) 與 $r$ (Radius) 的參數化微調。
|
||
- **定點數精確度修正**：採用「兩倍值整數運算」邏輯，解決了 $0.5$ 步階在浮點數圓整時產生的「按鍵沒反應」Bug。
|
||
- **防止漂移 (Oscillation Logic)**：針對數位微調，實施了奇偶震盪平衡邏輯。當調整 $\delta$ 導致 $r$ 必須隨動時，採用震盪補償防止 $r$ 產生單向累積誤差。
|
||
- **參數連動策略**：在 $0.5$ 步階時，採取「優先滿足目標變動」原則。若調整 $\delta$，則 $r$ 隨動；反之亦然。
|
||
|
||
## 2. UI/UX 介面調整
|
||
- **側邊欄優化**：
|
||
- 將 $r$ 與 $\delta$ 的調整區域改為**垂直堆疊**，適應 21rem 的窄邊欄。
|
||
- 移除冗餘的 $a1, a2$ 預覽方塊，僅保留帶有數學公式標籤的 $r, \delta$ 預覽。
|
||
- **步階序列**：數位微調步階改為自訂序列：`[0.5, 1, 2, 4, 8, 32, 256, 1024, 4096, 16384, 65536]`。
|
||
- **微調量顯示**：統一使用 `±` 符號並帶空格（例如 `± 0.5`）。
|
||
- **智能禁用**：當數位步階為 $0.5$ 時，自動禁用 $r$ 的控制項，確保以 $\delta$ 為主導。
|
||
|
||
## 3. 繪圖系統 (Bode Plot)
|
||
- **幅值圖 (Magnitude)**：
|
||
- 初始範圍：基於 $systemGain \times 3$，涵蓋 $70 \text{ dB}$。
|
||
- 保留手動彈性：設定為 `fixedrange: false`，支援滑鼠縮放與 Auto Scale。
|
||
- 狀態保持：使用 `uirevision`，確保微調參數時不會跳回初始縮放。
|
||
- **相位圖 (Phase)**：
|
||
- 絕對鎖死：固定範圍為 $[-180^\circ, 180^\circ]$。
|
||
- 禁止縮放：設定為 `fixedrange: true`，提供穩定的絕對參考。
|
||
- **座標軸連動**：幅值圖與相位圖的 **X 軸（頻率）已完全同步**。不論在哪一張圖進行橫向縮放，兩者都會連動。
|
||
|
||
## 4. 數學公式參考
|
||
- **理想空間**：
|
||
- $a1 = -1 - r + \delta$
|
||
- $a2 = r + \delta$
|
||
- **定點數空間 (Q14 為例)**：
|
||
- $a0 = 2^{14} = 16384$
|
||
- $a1 = -a0 - r + \delta$
|
||
- $a2 = r + \delta$
|
||
- $2\delta = a1 + a2 + a0$
|
||
- $2r = a2 - a1 - a0$
|
||
|
||
## 5. 目前 Git 狀態
|
||
- **當前分支**：`dev-v2-rounding-fix-20260517` (已推送到 origin)。
|
||
- **同步說明**：此版本包含了 Rounding 功能、Vite proxy 修復與 production build。
|
||
- **同事試用指令**：
|
||
```bash
|
||
git fetch
|
||
git checkout dev-v2-rounding-fix-20260517
|
||
```
|
||
|
||
---
|
||
*Last Updated: 2026-05-15 17:47*
|
||
|
||
---
|
||
|
||
# DSP Bode Plot 專案進度更新 (2026-05-17)
|
||
|
||
## 6. 定點數 Rounding 模擬 (V2 Feature)
|
||
- **Round (+0.5 補償) 功能**：在 `integer_lfilter()` 中實作了硬體級四捨五入模擬，使用 `(acc + (1 << (shift - 1))) >> shift` 取代傳統的 `acc >> shift` (Floor)。
|
||
- **UI 控制**：於「定點數模擬設定」區塊新增 **Floor (SRA) / Round (+0.5)** 互斥按鈕（與「階數 Order」相同風格），放置於 Q_in / Q_out 同列。預設為 Round。
|
||
- **API 參數**：`/api/filter` 與 `/api/filter/download` 端點已支援 `use_round` 參數。
|
||
- **高精度狀態變數架構**：前饋 (Feed-forward) 不右移，保留完整 $Q_{in+b}$ 精度；僅回授 (Feedback) 與最終輸出做位移縮放。
|
||
|
||
## 7. Vite Proxy 修正
|
||
- **Bug 修正**：`vite.config.js` 的 proxy target 從 `https://` 修正為 `http://`，與 uvicorn 的實際 HTTP 協議一致。
|
||
|
||
---
|
||
|
||
## ⚠️ 踩雷紀錄 (Lessons Learned)
|
||
|
||
### 🔴 Production Build 未同步 (2026-05-17)
|
||
**症狀**：修改了 `src/app-options.js` 與 `src/App.vue` 後，UI 按鈕有出現但功能完全不生效（Round/Floor 切換後濾波器輸出完全沒變化）。花了大量時間除錯。
|
||
|
||
**根因**：使用者透過 `http://localhost:8000/ui/` 存取系統。FastAPI 直接 serve `static/build/app.js`，而該檔案停留在 5 月 15 日的舊版（距今超過一天）。所有前端修改都只存在於 `src/` 原始碼，從未被 `npm run build` 編譯輸出。
|
||
|
||
**解法**：修改 `src/` 後務必執行 `npm run build`，再 `Ctrl+Shift+R` 硬重新整理瀏覽器。
|
||
|
||
**預防措施**：
|
||
1. 開發時優先使用 `http://localhost:5173/` (Vite dev server，自動 HMR)。
|
||
2. 若使用 port 8000，每次修改前端程式碼後必須 build。
|
||
3. 詳見 `ARCHITECTURE.md` 的「Development Environment Notes」章節。
|
||
|
||
### 🟡 Vite Proxy https/http 不匹配 (2026-05-17)
|
||
**症狀**：Vite dev server 的 API 轉發全部失敗 (502)，uvicorn 日誌大量出現 `Invalid HTTP request received.`。
|
||
|
||
**根因**：`vite.config.js` 設定了 `target: 'https://127.0.0.1:8000'`，但 uvicorn 以 HTTP 模式啟動。Vite proxy 嘗試發送 TLS 握手封包到純 HTTP 伺服器。
|
||
|
||
**解法**：將 proxy target 改為 `http://127.0.0.1:8000`，移除 `secure: false`。
|
||
|
||
---
|
||
*Last Updated: 2026-05-17 00:43*
|
||
|
||
---
|
||
|
||
# DSP Bode Plot 專案進度更新 (2026-05-17 - 第二階段重構與優化)
|
||
|
||
## 8. 回授變數命名重構與物理意義釐清
|
||
- **變數命名精確化**：為消除舊版回授項以 `fb_` 開頭容易讓工程師誤解為 `b` 係數的命名混淆，將 `dea/csv_processing.py` 的變數全面更名：
|
||
- `fb_sum` $\rightarrow$ **`sum_a`** (回授 a 累加項)
|
||
- `fb_shifted` $\rightarrow$ **`sum_a_scaled`** (已除以 $A_0$ 歸一化後的回授項)
|
||
- `acc` 運算直接更新為直觀的 `acc = sum_b - sum_a_scaled`，完全與數學公式鏡像對齊。
|
||
- **明確白話文檔指引**：在根目錄與 bodeplot 目錄下的 `INTEGER_FILTER_IMPLEMENTATION.md` 文件中，新增了兩項白話物理意義說明：
|
||
1. **為什麼回授部分除以 $A_0$？**（假設 $A_0 = 1$，放大後即為 $2^{Q_a}$，除以 $A_0$ 等同於算術右移 `shift_a`，旨在消去 $Q_a$ 放大的效應以防數值爆炸）。
|
||
2. **為什麼輸入訊號 $x$ 與前饋 $b$ 不用中間歸一化？**（說明為了防止小數精度因中間右移而被截斷丟棄，故意將高精度一路鎖在歷史狀態變數中，延遲至最終輸出時才進行一次性對齊，藉此獲得最大 SNR 與最佳效能）。
|
||
3. **加註 Floor 模式的警告**：加註 `（無條件捨去，非常不建議）`，指引工程師優先使用 Round 補償。
|
||
|
||
## 9. 韌體 C 語言實作最佳化 (32-bit MCU Optimization)
|
||
- **32位元整數重構**：為避免 64 位元除法/乘法在 32 位元微處理器（如 ARM Cortex-M 或是 RISC-V RV32I）上引發昂貴的軟體模擬消耗，將 `INTEGER_FILTER_IMPLEMENTATION.md` 中提供的 C 語言 Process 範例全部改為由 **`int32_t`** 為核心的高效能版本。
|
||
|
||
## 10. Vite HTTPS Proxy & SSL 完全對齊
|
||
- **HTTPS 代理修復**：為同時支援 Web Serial API（瀏覽器實體連接埠，要求 HTTPS 協議）與 Vite 5173 的自動熱更新開發，將 `vite.config.js` 的 proxy target 更新為 **`https://127.0.0.1:8000`**，並加上 **`secure: false`**（允許繞過自簽憑證限制），徹底解決了前端對代理伺服器發送明文請求所導致的 `Failed to execute 'json' on 'Response': Unexpected end of JSON input` 報錯。
|
||
|
||
## 11. 目前 Git 狀態與 GitLab 同步
|
||
- **當前分支**：`dev-v2-integretimedomain`
|
||
- **提交與推送**：已經將最新的變數重構、32-bit C 代碼優化、Vite HTTPS Proxy 更新成功 commit 並 Push 至 GitLab 遠端儲存庫，分支版控狀態極其乾淨。
|
||
|
||
---
|
||
*Last Updated: 2026-05-17 14:26*
|
||
|
||
---
|
||
|
||
# DSP Bode Plot 專案進度更新 (2026-05-21 - 多級串聯濾波器支援)
|
||
|
||
## 12. 實作多級串聯濾波器 (Cascade of Biquads / SOS)
|
||
- **UI/UX 升級**：前端新增多階段 (Stages) 濾波器管理介面，支援動態新增、刪除、上下排序以及單一 Stage 的啟用與禁用。
|
||
- **API 擴充**：後端新增 `/api/bode/compare_cascade` 支援串聯頻率響應計算，並修改 `/api/filter` 與 `/api/filter/download` 以支援時域訊號的串聯處理。
|
||
- **工程對齊**：徹底落實 `INTEGER_FILTER_IMPLEMENTATION.md` 第 7 節強調的「二階級聯黃金法則」，避免了直接將高階濾波器展開成 Direct Form 所帶來的極點靈敏度暴增及數值不穩定問題。
|
||
|
||
## 13. 目前 Git 狀態與 GitLab 同步
|
||
- **當前分支**：`cascadedfilters` (基於 `dev-v2-integretimedomain` 建立)
|
||
- **分支策略**：為了繼承並保留「定點數時域模擬」的核心邏輯，特別選擇從 `dev-v2-integretimedomain` 岔出建立新分支，而非從 `main` 分支。這樣確保了時域整數運算功能與多級串聯功能的完美結合。
|
||
- **提交與推送**：已將多級串聯 (Cascade) 的完整實作獨立建立為 `cascadedfilters` 分支，並推送至 GitLab 以供同事試用與後續整合。
|
||
|
||
---
|
||
*Last Updated: 2026-05-21 14:19*
|
||
|
||
---
|
||
|
||
# DSP Bode Plot 專案進度更新 (2026-05-22 - UI/UX 微調與測試工具)
|
||
|
||
## 14. 時域繪圖 (Time Plot) X 軸真實時間單位
|
||
- **直覺化顯示**：將原本時域繪圖橫軸的「Sample Index (取樣點索引)」替換為「真實時間 (Time)」。
|
||
- **動態單位切換**：系統利用已知的取樣率 (`fs`)，會根據波形總時間長度自動選擇最適合的顯示單位（包含秒 `s`、毫秒 `ms`、以及微秒 `μs`），使波形觀察更符合硬體工程師的直覺。
|
||
- **全面升級**：此改動已同步套用於新版 Vue.js 介面 (`src/app-options.js`) 以及舊版 Streamlit 介面 (`dea_legacy.py`)。
|
||
|
||
## 15. 測試訊號產生器擴充
|
||
- **步階訊號腳本**：新增了 `generate_step_signal.py`，支援自動產生精確時間長度 (預設 30 ms) 與多種動態範圍 (0 to 1, 0.1 to 0.9, 0.2 to 0.8 等) 的步階函數測試 CSV 檔，方便快速驗證濾波器的步階響應 (Step Response) 與穩定時間 (Settling Time)。
|
||
|
||
*Last Updated: 2026-05-22 06:15*
|
||
|
||
---
|
||
|
||
# DSP Bode Plot 專案進度更新 (2026-05-26 - 時域動態高畫質縮放與全新 CSV 匯出架構)
|
||
|
||
## 16. 時域動態高畫質重取樣與時序縮放對齊 (Adaptive LOD & Scaling Lock)
|
||
- **區域高畫質重取樣**：在時域圖表實作了動態重取樣。當使用者對圖表進行 Zoom / Pan 時，前端會抓取可視時間範圍，轉換為取樣點索引，向後端 `/api/filter` 發送動態 sliced 請求。後端在**保證完整濾波歷史狀態（IIR 記憶狀態）正確**的前提下，對該可視區域重新進行 5,000 點高畫質重取樣，讓微端細節（量化雜訊、步階過渡漣波）在 Zoom In 後纖毫畢現！
|
||
- **座標軸比例對齊鎖定**：修正了 Plotly `uirevision` 保留舊秒數範圍但新資料縮放到毫秒導致的座標 clashing 錯誤。我們將時間單位與乘數在**首次全波形載入時進行鎖定**，不論使用者如何縮放，座標系皆保持絕對一致與對齊。
|
||
- **無窮迴圈與 Lag 消除**：新增重繪鎖定旗標 `isRedrawingTimePlot`。在 `Plotly.react()` 執行佈局重繪時，自動忽略同步 layout 產生的 recursive 迴圈，CPU 佔用率大減，介面縮放達到極致流暢！
|
||
|
||
## 17. 限縮數據全新 CSV 匯出 (Restructured CSV Export)
|
||
- **數據專屬匯出**：改寫了 `/api/filter/download` 匯出行為。取代以往冗餘附加到原始大檔案的作法，系統現在會產生一個**乾淨的全新 4 欄 CSV 檔案**：`Time (s)`、`[輸入欄位]`、`[輸入欄位]_filtered_ideal` 以及 `[輸入欄位]_filtered_fixed`。
|
||
- **實體時間重構**：由前端將當前取樣率 `fs` 傳送至後端，後端根據實際有效點數的 Index 對應 `fs` 計算出精確的 `Time (s)` 列，確保匯出的時間軸與繪圖完全一致。
|
||
- **支援不同欄位長度 (NaN-Dropping)**：後端支援對每一欄位獨立進行尾部 `NaN` 截斷，使 `Step (0 to 1)` 預設訊號自動限縮至 `100 ms`（10,001 行），`McDonald's Wave` 縮短至 `200 ms`，匯出的 CSV 點數與實際有效長度 100% 精準對齊，無任何多餘空白或零填充。
|
||
|
||
## 18. UI/UX 緊湊排版與側欄空間釋放
|
||
- **側邊欄寬度縮小 17%**：將左側控制欄寬度從 `410px` 精簡至 `340px`，釋放出水平螢幕空間給右側響應圖表，使其在大螢幕與筆電上看起來更寬闊、視覺效果極為 premium。
|
||
- **匯出按鈕移至預覽上方一列化**：為了最大化利用垂直空間，將「匯出串聯濾波 CSV」按鈕移到「級聯時域訊號模擬」的說明文字右側，以水平 Flex Row 對齊，並將說明文字更新為「可上傳時域輸入訊號的 CSV 檔案 。訊號將循序通過 (Cascade) 所有啟用 (Active) 的濾波器階段。」。
|
||
|
||
*Last Updated: 2026-05-26 14:43*
|