112 lines
5.3 KiB
Markdown
112 lines
5.3 KiB
Markdown
# TrapMap完整图片导出与终端日志开关设计
|
||
|
||
## 目标
|
||
|
||
为`MovementTest.Trapmaptest.cs`增加两个相互独立的测试开关：
|
||
|
||
- 成功建图后，将完整栅格地图独立渲染为300 DPI PNG，不依赖Clumsy当前视口、缩放或其他Painter。
|
||
- 控制TrapMap调试信息是否同步打印到宿主进程终端，同时始终保留`DLog`日志。
|
||
|
||
现有`TrapMapTest` Painter初始化和清理已经使用世界坐标调用`UI.GetPainter("TrapMapTest")`，本次不重复修改。两腿检测ROI继续使用车体局部Painter及`false`参数。
|
||
|
||
## 用户开关与默认值
|
||
|
||
在`TrapMapTest`手动编辑区增加：
|
||
|
||
```csharp
|
||
private const bool _saveFullMapImage = true;
|
||
private const bool _enableTerminalDebugLog = true;
|
||
```
|
||
|
||
两个值传入`TrapMapBuilder`或共享日志/导出组件。关闭图片开关时不得创建目录、临时文件或PNG。关闭终端开关时只抑制`Console.WriteLine`，不得抑制`DLog`和必要的UI提示。
|
||
|
||
## 图片内容
|
||
|
||
图片从最终发布的`GridMapData`离屏渲染，包含完整地图边界而不是屏幕截图：
|
||
|
||
- 白色背景。
|
||
- 浅灰色完整栅格线，确保每个小格可见。
|
||
- 红色占用栅格。
|
||
- 蓝色车辆轮廓、几何中心和朝向。
|
||
- 绿色工作站目标标记。
|
||
- 黑色地图外边界。
|
||
- 标题/图例区域，显示世界边界、分辨率、行列数、占据率、障碍物数量、轮胎层状态和输入来源。
|
||
|
||
世界X轴在图片中向右；世界Y轴向上，因此从`Cells[row,col]`映射到位图时反转图像Y方向。工作站仅绘制标记，不写入占用数据。
|
||
|
||
## 图片尺寸与文件约束
|
||
|
||
- 每个栅格使用`4×4`像素。
|
||
- PNG水平和垂直DPI都设置为`300`。
|
||
- 包含边距和标题后，任一图片边长不得超过`4000`像素。
|
||
- 最终PNG文件大小不得超过`50 * 1024 * 1024`字节。
|
||
|
||
尺寸在分配RGBA像素缓冲区前检查。若超过4000像素，跳过导出并报告明确原因。编码先写入同目录临时文件，完成后检查实际字节数；超过50MB时删除临时文件，不留下超限最终文件。只有所有检查通过后，才原子移动/重命名为最终PNG。
|
||
|
||
典型`327×139`地图的栅格主体约为`1308×556`像素，另加标题和边距。
|
||
|
||
## 保存位置与命名
|
||
|
||
输出根目录使用宿主进程当前工作目录：
|
||
|
||
```text
|
||
TrapMapExports\TrapMap_yyyyMMdd_HHmmss_fff.png
|
||
```
|
||
|
||
毫秒时间戳避免同一秒多次测试覆盖。目录只在图片开关打开且地图成功后创建。临时文件使用同目录、同文件名加`.tmp`后缀，以保证最终重命名不跨磁盘。
|
||
|
||
## 日志行为
|
||
|
||
引入TrapMap专用日志入口，其行为为：
|
||
|
||
```text
|
||
所有消息 -> DLog.Log(message, "TrapMapTest")
|
||
终端开关开启 -> 额外Console.WriteLine("[TrapMapTest] " + message)
|
||
```
|
||
|
||
至少覆盖测试开始、输入参数、Detour位姿、车辆尺寸、地图边界/尺寸、轮胎层状态、图片保存成功/跳过/失败、最终统计和测试停止。图片错误不得因终端开关关闭而静默，仍必须进入`DLog`。
|
||
|
||
## 组件边界
|
||
|
||
图片导出放在独立文件`ClumsyPilot/TrapMapImageExporter.cs`，避免继续扩大已经较长的MovementTest文件。组件只消费不可变的导出请求数据：地图、车辆位姿、工作站、轮胎层元数据和目标文件路径；它不读取Detour、雷达或UI，也不修改栅格。
|
||
|
||
`MovementTest.Trapmaptest.cs`负责开关、调用时机、日志和错误降级。导出发生在地图成功生成之后；导出失败不改变`TrapMapBuilder.Succeeded`或`GridMap`。
|
||
|
||
实现使用内部纯C# RGBA光栅器绘制栅格、车辆、工作站和5×7位图文字，再由精确版本`StbImageWriteSharp` 1.16.7编码PNG。编码后立即在`IHDR`后插入`pHYs=11811/11811/unit1`，以保留300 DPI元数据。运行时不依赖平台绘图程序集或原生图形资产；除单个托管Stb编码程序集外，光栅、元数据和文件流程均只使用BCL。
|
||
|
||
## 错误处理
|
||
|
||
以下情况只导致图片导出失败，不导致建图失败：
|
||
|
||
- 图片开关关闭。
|
||
- 图片尺寸超过4000像素。
|
||
- 输出目录创建失败。
|
||
- RGBA缓冲区创建、绘制或PNG编码异常。
|
||
- 临时文件超过50MB。
|
||
- 临时文件重命名失败。
|
||
|
||
异常路径必须尽力删除本次临时文件，不得删除已有的成功PNG。
|
||
|
||
## 验证要求
|
||
|
||
至少验证：
|
||
|
||
1. 图片开关关闭时不创建文件和目录。
|
||
2. 小型已知栅格导出的PNG由BCL测试解码器重新读取；所有chunk CRC有效，`IHDR`为RGBA8，`pHYs`表示300 DPI，像素尺寸符合4像素/格及布局规则。
|
||
3. PNG中占用格、车辆和工作站采样位置颜色正确，Y轴没有上下颠倒。
|
||
4. 超过4000像素的请求在RGBA缓冲区分配前失败。
|
||
5. 最终路径使用毫秒时间戳且不覆盖旧文件。
|
||
6. 成功文件严格小于或等于50MB，超限临时文件被删除。
|
||
7. 终端开关开启时消息同时进入DLog和终端；关闭时仍进入DLog但不写终端。
|
||
8. 图片失败时地图仍为成功状态。
|
||
9. 现有源码契约、栅格行为、生命周期测试及`ClumsyPilot`编译继续通过。
|
||
|
||
## 非目标
|
||
|
||
- 不截取Clumsy/CycleGUI窗口。
|
||
- 不保存紫色UI背景、小车3D模型、绿色两腿ROI或橙色检测猜测线。
|
||
- 不改变栅格数据格式或地图边界计算。
|
||
- 不接入新的点云来源。
|
||
- 不修改`TrajPlanner`。
|
||
- 不提交或暂存本次工作区改动。
|