ScenicNL

ScenicNL 是一个面向毕业设计的“图像到仿真场景”实验项目，目标是把道路交通图片转换为结构化场景描述、Scenic 场景代码，并在 CARLA 中渲染验证。当前阶段的重点不是像素级复刻输入图片，而是验证以下主线是否可行：

输入图片 -> SceneInfo JSON -> Scenic 编译 -> CARLA 0.9.16 渲染 -> 可见性/位置关系评估

当前研究重点

近期工作已经把目标从“单图跑通”推进到“批量闭环 + 关系优先评估”。对于毕设当前阶段，最重要的评价目标是：

• 关键车辆大部分可见；
• 目标车辆数量正确或有明确失败原因；
• 左右、前后、队列、相邻车道等粗粒度相对位置关系正确；
• 输入图和 CARLA 输出图具备可解释的对比材料；
• 暂不把精确视角、道路拓扑、背景建筑、车型颜色和像素级相似度作为硬性目标。

环境

已验证的主要环境：

• Windows PowerShell
• Python 3.11，用于主项目和模型调用
• CARLA 0.9.16，路径通常为 E:\desktop\CARLA\CARLA_0.9.16
• Conda 环境 carla-0.9.16，用于 CARLA Python API 渲染
• 主要可用模型：gpt-4o、claude-opus-4-6-thinking

常用环境变量：

$env:SCENICNL_CARLA_RENDER_ENV='carla-0.9.16'
$env:SCENICNL_MODEL_REQUEST_TIMEOUT_SECONDS='180'
$env:SCENICNL_CAPTURE_VEHICLE_MASK='1'
$env:SCENICNL_ACCURACY_RETRIES='2'

项目默认从仓库根目录读取 .env。常用字段包括：

OPENAI_API_KEY=...
OPENAI_BASE_URL=...
OPENAI_REASONING_EFFORT=high

快速开始

安装项目：

python -m pip install -e .

运行测试：

$env:PYTEST_DISABLE_PLUGIN_AUTOLOAD='1'
python -m pytest tests -q

单图全流程示例：

python run_image_to_scenic.py --image_path prc\simple_scene\1.png --prompt_type static_relationship --vision_model gpt-4o --output_dir outputs\quick_pipeline_test --max_fix_attempts 2 --render

批量全流程示例：

python run_image_to_scenic.py --image_dir prc\ai_generated_view_test\batch_20260503 --prompt_type static_relationship --vision_model gpt-4o --output_dir outputs\batch_pipeline_test --max_fix_attempts 2 --render

近期工作总结

1. CARLA 0.9.16 渲染闭环

项目已完成 Windows 下 CARLA 0.9.16 的连接、渲染和调试链路。渲染结果会记录：

• render_output.png：CARLA RGB 输出图；
• render_projection.png：车辆投影 bbox 调试图；
• render_comparison.png：输入图片和输出图片的并排对比；
• render_details.json：车辆 spawn、camera、bbox 投影、可见性等细节；
• run_summary.md/json：单 case 汇总。

代表性实验：

• outputs/carla_0916_e2e_test
• outputs/carla_0916_full_pipeline_visibility_test
• outputs/carla_0916_batch_pipeline_visibility_eval

2. 批量可见性与粗粒度评估

在 simple_scene、regular_scene 和 AI 生成道路图上，项目加入了批量评估脚本，用于统计：

• visibility_pass
• 车辆可见数量
• 输入 bbox 数量和投影 bbox 数量
• bbox 中心误差、尺寸误差、IoU
• 左右顺序、前后顺序
• 渲染成功率和失败原因

主要脚本：

python scripts\evaluate_render_results.py --root <output_root> --output-dir <output_root>\render_report
python scripts\evaluate_render_accuracy.py --root <output_root> --output-dir <output_root>\accuracy_report
python scripts\evaluate_relationships.py --root <output_root> --labels <labels_csv> --output-dir <output_root>\relationship_report

3. AI 生成诊断图片

为了让测试数据更适合论文分析，项目使用图像生成接口构造了一批可控道路场景图片，车辆数量一般不超过 5 辆，覆盖：

• top-down 俯视道路；
• adjacent lanes 相邻车道；
• intersection 路口；
• rear-oblique 后斜视角；
• parking-lot 停车场；
• curved road 弯道。

相关输入数据：

prc/ai_generated_view_test/batch_20260503
prc/ai_generated_view_test/batch_20260506_relationship

图片生成方法记录：

doc/design/in-progress/ai_generated_test_image_method.md

4. 模型对比

已对 gpt-4o 和 claude-opus-4-6-thinking 做过同批样本对比。不可用或不稳定的模型不再作为后续重点。

代表性输出：

outputs/gpt4o_claude46_batch20260503_eval_20260506
outputs/gpt4o_claude46_relationship_layout_fix_20260506

当前结论：两个可用模型都能支撑全流程测试，但 SceneInfo 中 bbox_norm、depth_rank、lane_index 的质量会直接影响后续 CARLA 车辆布局和位置关系评估。

5. 复杂视角下的位置关系修复

最近一次关键改进是 relationship-first layout。问题来源是：在 top-down、intersection、rear-oblique、parking-lot 等复杂视角下，直接把车辆交给 CARLA waypoint/lane 逻辑可能会破坏图像中的左右/前后关系。

当前解决方案：

• 复杂视角下优先使用 bbox_norm 图像中心确定横向关系；
• 使用 depth_rank 确定前后顺序；
• 使用 lane_index 作为补充关系信号；
• 避免 CARLA lane waypoint 自动换道或 spawn fallback 扭曲关系；
• 在 render_details.json 中记录 relationship_layout 和 layout_adjustment。

最新结果：

输出目录: outputs/gpt4o_claude46_relationship_layout_fix_20260506
gpt-4o: relationship pass 8/8, visibility pass 8/8, actor visibility 28/28
claude-opus-4-6-thinking: relationship pass 8/8, visibility pass 8/8, actor visibility 28/28
单元测试: 59 passed

实验文档：

doc/experiments/relationship_layout_fix_20260506.md

关键输出目录

outputs/README.md 是当前输出数据索引，写论文前应优先阅读。

最重要的输出目录：

• outputs/gpt4o_claude46_relationship_layout_fix_20260506：当前最强证据，复杂视角关系保持修复后的双模型结果。
• outputs/gpt4o_claude46_batch20260503_eval_20260506：修复前双模型 baseline，用于对比说明问题来源。
• outputs/ai_generated_view_pipeline_eval：AI 生成多视角图的早期全流程评估。
• outputs/ai_generated_relationship_pipeline_eval_20260506_prompt_fix：prompt 修复后的简单关系场景实验。
• outputs/carla_0916_batch_pipeline_visibility_eval：simple/regular 批量可见性和粗 bbox 评估。
• outputs/carla_0916_accuracy_quality_eval：vehicle mask、semantic segmentation、bbox accuracy 首轮增强实验。

文档索引

论文和答辩准备优先看：

• doc/design/completed/overall_experiment_design.md：整体实验设计归档。
• doc/experiments/relationship_layout_fix_20260506.md：复杂视角关系修复实验。
• doc/experiments/ai_generated_view_pipeline_eval_20260503.md：AI 生成多视角图片评估。
• doc/experiments/carla_0916_batch_pipeline_visibility_eval_20260502.md：批量可见性实验。
• doc/experiments/carla_0916_accuracy_quality_eval_20260502.md：渲染准确率和代码质量增强实验。
• outputs/README.md：输出数据维护说明。

论文写作建议

当前项目适合在论文中按以下逻辑组织：

1. 任务定义：从道路图像生成结构化仿真场景。
2. 方法流程：图像理解、SceneInfo 抽取、Scenic 生成、CARLA 渲染、可见性和关系评估。
3. 工程实现：模型调用、schema 校验、Scenic 编译修复、CARLA 0.9.16 渲染、bbox 投影和 mask 证据。
4. 实验设计：从单图到小批量，再到 AI 生成诊断图和双模型对比。
5. 关键问题：复杂视角下 CARLA lane placement 会破坏图像空间关系。
6. 改进方案：relationship-first layout。
7. 结果分析：车辆可见性和粗粒度位置关系达到当前阶段目标。
8. 局限性：不解决像素级相似度、真实道路拓扑、背景复刻、精确车型颜色。
9. 后续工作：扩大样本量，增强 SceneInfo 稳定性，细化关系类别和失败分析。

当前最适合写入论文结果章节的核心结论是：在可控诊断样本上，经过 relationship-first layout 改进后，gpt-4o 和 claude-opus-4-6-thinking 均达到 8/8 关系通过和 28/28 车辆可见，说明该系统已经能够在复杂视角下保持关键车辆可见和粗粒度相对位置关系。