45 lines
4.0 KiB
Markdown
45 lines
4.0 KiB
Markdown
# Copilot / AI agent instructions for this repo
|
||
|
||
目标：帮助 AI 编码代理快速上手此环视(surround-view)项目，聚焦可验证的代码模式、运行流程和常见修改点。
|
||
|
||
- **大体架构**：数据流为 Capture -> Undistort -> Project -> Flip -> Stitch -> WhiteBalance -> Display。主要线程/模块：
|
||
- `surround_view.capture_thread.CaptureThread`：采集摄像头帧（USB/CSI，可传 `api_preference`）。
|
||
- `surround_view.fisheye_camera.FisheyeCameraModel`：负责 `undistort()`, `project()`, `flip()` 和相机参数读写（yaml 文件）。
|
||
- `surround_view.process_thread.CameraProcessingThread`：每个摄像头的处理线程，调用相机模型并写入 `ProjectedImageBuffer`。
|
||
- `surround_view.birdview.BirdView`：融合/拼接、亮度匹配与白平衡，输出最终鸟瞰图。
|
||
- 同步/缓冲：`surround_view.imagebuffer.Buffer`、`MultiBufferManager` 与 `ProjectedImageBuffer`，通过 `sync()`/信号等待实现多流同步。
|
||
|
||
- **关键运行脚本（推荐顺序）**：
|
||
1. `python run_calibrate_camera.py`（标定/生成 camera yaml）
|
||
2. `python run_get_projection_maps.py -camera <front|back|left|right> -scale ... -shift ...`（选择投影点）
|
||
3. `python run_get_weight_matrices.py`（生成拼接权重/掩码）
|
||
4. `python run_live_demo.py`（车载/实时 demo）
|
||
- 调试摄像头采集：`python test_cameras.py`
|
||
|
||
- **项目约定 / 易错点（请严格遵循）**：
|
||
- 摄像头名称固定为 `front, back, left, right`，对应 yaml/param 中的配置；device id 需在本机环境中确认（参见 `test_cameras.py`）。
|
||
- yaml 文件（`yaml/*.yaml`）里保存的字段：`camera_matrix`, `dist_coeffs`, `resolution`, `project_matrix`, `scale_xy`, `shift_xy`。修改后用 `FisheyeCameraModel.save_data()` 写回。
|
||
- `param_settings.py` 用 cm 为单位构造 birdview 参数（`total_w/total_h`、`xl/xr/yt/yb` 等），birdview 的切片函数（`FI, FM, ...`）依赖这些常量。
|
||
- 镜头“翻转”策略在 `FisheyeCameraModel.flip()` 明确：`front` 不变，`back` 180°, `left/right` 用转置+翻转处理。
|
||
- 缓冲区 `Buffer.add(..., drop_if_full=True)` 会丢帧；修 bug 时注意是否因为丢帧导致状态不一致。
|
||
|
||
- **拼接与亮度调整实现要点**（参见 `surround_view/birdview.py` 与 `surround_view/utils.py`）：
|
||
- 权重计算：`get_weight_mask_matrix()` 提取重叠区域并基于点到多边形距离计算平滑权重 G。
|
||
- 亮度匹配通过 `mean_luminance_ratio()` 聚合重叠区域平均亮度并以几何/经验方式融合（见 `make_luminance_balance()`）。
|
||
- 白平衡用 `make_white_balance()` 简单按通道均值缩放。
|
||
|
||
- **如何修改/扩展（示例）**：
|
||
- 若加入新相机或改变布局：更新 `param_settings.py` 的 `camera_names`、`project_shapes` 与 `xl/xr/yt/yb`；更新 yaml 参数并通过 `FisheyeCameraModel` 测试 `undistort()`/`project()` 输出。
|
||
- 若替换采集后端（gstreamer / v4l2），优先修改 `surround_view.utils.gstreamer_pipeline()` 与 `CaptureThread.connect_camera()` 的 `api_preference` 分支，确保 `cap.isOpened()` 行为一致。
|
||
|
||
- **测试 / 调试建议**：
|
||
- 使用 `test_cameras.py` 确认设备索引与支持分辨率。
|
||
- 单线程走查：直接在 REPL 导入 `FisheyeCameraModel`，用已存在的 yaml 文件运行 `undistort()`、`project()` 并保存图片来验证投影矩阵。
|
||
- 帧同步问题优先检查 `MultiBufferManager.sync()` 与 `ProjectedImageBuffer.sync()` 的 `do_sync` 与 `sync_devices` 配置。
|
||
|
||
- **风格/约定**：
|
||
- 代码使用 Python 3、OpenCV、PyQt5，多线程依赖 `QThread` + Qt 同步原语；避免用 `time.sleep()` 作为同步手段。
|
||
- 尽量在修改后用现有脚本跑完整流程（calibrate -> get_projection -> get_weight -> live_demo）以捕获参数联动问题。
|
||
|
||
如果需要，我可以把这些点合并成更短或更详尽的版本，或者加入常见问题/故障排查列表；或者你希望我直接提交此文件为 PR？请告诉我想要的调整或遗漏的内容。
|