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？请告诉我想要的调整或遗漏的内容。

4.0 KiB Raw Blame History Unescape Escape

Copilot / AI agent instructions for this repo

4.0 KiB

Raw Blame History