CCTV Vehicle Speed Playground

This repository is a playground for validating two steps of a CCTV-based vehicle speed workflow:

1. Record wall-clock-aligned MP4 segments from the freeway MJPEG stream.
2. Run Ultralytics YOLO speed estimation against recorded clips and compare parameter sets.

The code here is intentionally exploratory. The next step should be a separate production project that hardens configuration, adds ROI support, and formalizes outputs.

Files

• mjpeg_segment_recorder.py Records the MJPEG stream into wall-clock-aligned MP4 files.
• yolo_speed_test.py Runs Ultralytics solutions.SpeedEstimator on recorded videos and exports CSV summaries.
• start.bat Example command for the recorder.
• yolo_matrix.bat Example command for parameter sweep testing.

Recording

Install dependencies:

pip install requests opencv-python numpy

Example:

python mjpeg_segment_recorder.py ^
  --url "https://cctvn.freeway.gov.tw/abs2mjpg/bmjpg?camera=10002" ^
  --segment-seconds 60 ^
  --max-duration 300 ^
  --max-files 50 ^
  --max-failures 300 ^
  --insecure

Current recorder behavior:

• Waits until the next wall-clock boundary before starting.
• Default segment length is 60 seconds.
• Reconnects between segments.
• If the stream drops within a segment, reconnects and continues writing to the same MP4.
• Stores files under output_segments/YYYYMMDD/.

Speed Estimation

Install dependencies:

pip install ultralytics opencv-python shapely lap

Example single run:

python yolo_speed_test.py ^
  output_segments/20260330/capture_20260330_1431_00_0001.mp4 ^
  --device cpu ^
  --meter-per-pixel 0.18 ^
  --max-hist 8

Example parameter sweep:

python yolo_speed_test.py ^
  output_segments/20260330/capture_20260330_1431_00_0001.mp4 ^
  --device cpu ^
  --meter-per-pixel-list 0.12,0.15,0.18 ^
  --max-hist-list 5,8

Summary outputs include:

• valid_tracks
• mean_speed_kmh
• median_speed_kmh
• p25_speed_kmh
• p75_speed_kmh

Default summary statistics only include speeds between 20 and 120 km/h.

Current Findings

Tested on recorded tunnel footage with yolo26n.pt.

Working baseline:

• tracker=bytetrack.yaml
• classes=2,5,7
• meter_per_pixel=0.18
• max_hist=8

For public-facing display, median speed and interquartile range are more stable than mean speed.

Observed representative output for the tested clip:

• representative speed around 65 to 66 km/h
• main speed range around 53 to 82 km/h

Known Limitations

• No ROI filtering yet. Distant tracks can still create low-speed noise.
• meter_per_pixel is still empirically tuned, not camera-calibrated.
• Small trucks may still be missed or inconsistently classified by the base model.
• This repo is not structured as a deployable application.

Recommended Next Project Scope

The formal project should start from these learnings and add:

• ROI-based speed measurement
• camera calibration or better scene scaling
• batch processing pipeline and structured outputs
• configuration file support
• packaging, tests, and reproducible environments

---

中文說明

這個 repository 是用來驗證 CCTV 車速估算流程的 playground，主要做了兩件事：

1. 從高速公路 MJPEG 串流錄製對齊整點區段的 MP4 影片。
2. 使用 Ultralytics YOLO 的速度估算工具，對錄好的影片進行測試與參數比較。

這裡的程式碼以探索和驗證為主，不是正式產品。下一步應該另外建立正式專案，將設定、ROI、輸出格式與部署流程完整化。

檔案說明

• mjpeg_segment_recorder.py 從 MJPEG 串流錄製對齊系統時間的 MP4 影片。
• yolo_speed_test.py 使用 Ultralytics solutions.SpeedEstimator 對錄影檔做速度估算，並輸出 CSV 摘要。
• start.bat 錄影腳本的範例指令。
• yolo_matrix.bat 批次測試不同參數組合的範例指令。

錄影功能

安裝相依套件：

pip install requests opencv-python numpy

範例：

python mjpeg_segment_recorder.py ^
  --url "https://cctvn.freeway.gov.tw/abs2mjpg/bmjpg?camera=10002" ^
  --segment-seconds 60 ^
  --max-duration 300 ^
  --max-files 50 ^
  --max-failures 300 ^
  --insecure

目前錄影腳本行為：

• 啟動後會先等到下一個系統時間邊界再開始錄影。
• 預設每個檔案長度為 60 秒。
• 每段之間會主動斷線並重新連線。
• 若單一片段中途斷線，會重新連線並繼續寫入同一個 MP4。
• 輸出路徑格式為 output_segments/YYYYMMDD/。

車速估算功能

安裝相依套件：

pip install ultralytics opencv-python shapely lap

單支影片測試範例：

python yolo_speed_test.py ^
  output_segments/20260330/capture_20260330_1431_00_0001.mp4 ^
  --device cpu ^
  --meter-per-pixel 0.18 ^
  --max-hist 8

參數矩陣測試範例：

python yolo_speed_test.py ^
  output_segments/20260330/capture_20260330_1431_00_0001.mp4 ^
  --device cpu ^
  --meter-per-pixel-list 0.12,0.15,0.18 ^
  --max-hist-list 5,8

摘要輸出欄位包含：

• valid_tracks
• mean_speed_kmh
• median_speed_kmh
• p25_speed_kmh
• p75_speed_kmh

目前預設只統計 20 到 120 km/h 之間的速度，用來排除明顯異常值。

目前測試結論

測試素材為隧道路段錄影，模型使用 yolo26n.pt。

目前較穩定的基準參數：

• tracker=bytetrack.yaml
• classes=2,5,7
• meter_per_pixel=0.18
• max_hist=8

如果是面向一般公眾的顯示用途，中位數和四分位區間比平均值更穩定。

目前測得較代表性的輸出約為：

• 代表車速約 65 到 66 km/h
• 主要車速區間約 53 到 82 km/h

已知限制

• 尚未加入 ROI 篩選，遠端道路尾部仍可能產生低速雜訊。
• meter_per_pixel 目前仍是經驗調整值，不是相機標定後的正式尺度。
• 小貨車仍可能出現漏檢或分類不穩定。
• 此 repository 目前不是正式可部署的應用程式結構。

正式專案建議範圍

正式專案建議延續這裡的驗證結果，並補上：

• ROI 車速量測區域
• 相機標定或更完整的場景尺度校正
• 批次處理流程與結構化輸出
• 設定檔支援
• 打包、測試與可重現環境