# CAD 采样工具（测试数据生成 · 与主算法隔离）

> **这是独立工具,不是主算法的一部分。** 它只用来把 CAD 的 STEP 模型采样成点云,
> 作为**模拟测试数据**。主测量算法 (`underframe_deflection`) **不会 import 本目录任何代码**,
> 也不依赖 `cadquery`。将来用真实扫描点云时,本工具完全可以不用。

## 作用

```
STEP (.stp)  ──►  step_to_pointcloud.py  ──►  整车点云 (.ply / .xyz) + metadata (.json)
                  (tessellate + 按三角面积加权采样)
```

输出坐标轴约定与主算法一致:`x=纵向, y=横向, z=高度`(脚本内部做了 `[0,2,1]` 轴重排,
因为 CAD 原始是 `x=纵向, y=高度, z=横向`)。

## 安装依赖

```bash
# 仅生成测试数据时才需要;主算法运行不需要它
pip install -e .[sampling]      # 安装 cadquery
```

## 用法

```bash
python tools/cad_sampling/step_to_pointcloud.py <模型.stp> \
    -n 800000 \                 # 采样点数(越大越密)
    --bottom-boost 4.0 \        # 对车底区域加密的权重(>1 时车底点更多)
    --bottom-band-height-ratio 0.24 \
    --output-prefix test_data/dense_800k
```

常用参数:

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| `-n / --num-points` | 100000 | 采样点总数 |
| `--bottom-boost` | 1.0 | 车底加密倍数(挠度测量建议 ≥ 3) |
| `--bottom-band-height-ratio` | 0.24 | 车底带的高度占比 |
| `--linear-deflection` | 1.0 | tessellation 线性精度(越小三角越细,越慢) |
| `--angular-deflection` | 0.1 | tessellation 角度精度 |
| `--seed` | 42 | 随机种子(可复现) |

## 与主算法的关系

```
[本工具] STEP → 点云            [主算法] 点云 + CAD + ROI(json) → 挠度报告
   (cadquery,仅测试)              (numpy+scipy,生产)
        └── 解耦 ──────────────────────┘
```

挠度测量对点云密度敏感:**车底纵梁区域过稀会导致样条拟合在端点不稳定**。
生成模拟测试数据时建议 `--bottom-boost ≥ 3` 且 `-n ≥ 8e5`。