点云体素、DDA 与指标
将用户给定的分类点云、游览视点和体素边长落实为三阶段成果。使用本包的 scripts/run_pipeline.py 和 scripts/engine/，不依赖任何固定盘符或历史项目路径。
先确认输入有效
识别真实数据来源：读取点云摘要、属性表与输入出处，确认坐标系、分类字段与点数。目录名或他人转述的「已完成」不足以证明步骤有效；点数每次重新读取，不沿用历史常数。
本包默认按六类语义处理：1 岩壁、2 现代设施、3 石刻、4 石龛、5 植被、7 地面。检查 LAS 的标准 classification 字段；不要采用四分类训练配置或错误的合并标签。若数据类别不同，先在配置与统计口径中明确映射。不自动增加去噪、训练、Poisson 重建、体素删内部或补洞步骤。
配置并运行
读取 references/workflow.md，复制 assets/pipeline_config.json 到项目工作目录，填写路径与 voxel.size_m。统一体素尺寸可自定义；混合模型用粗细 2:1 层级且空间互斥。需要指标公式时读取 references/metrics.md。
选用已具备 numpy、laspy、numba、matplotlib 的 Python；依赖见 scripts/requirements.txt。本包不预置解释器路径——先用目标环境核实这些包可导入，再把真实存在的路径写进执行命令。
& "<python.exe>" "<skill目录>\scripts\run_pipeline.py" --config "<配置.json>" --stage all
all执行三步；voxel、dda、metrics可单独运行。- 已有模型：配置
existing_model_directory，运行--stage dda；随后--stage metrics使用 manifest 记录的射线成果。 - 已有 DDA：配置
existing_dda_run，运行--stage metrics。不重新体素化或重新发射射线。 --resume只复用同配置、产物 SHA256 仍一致的已完成阶段。失败与部分输出留档，检查失败记录后换新输出目录，不自动覆盖。
每步必须有可用产物
| 阶段 | 必需成果与验证 |
|---|---|
| 01_voxel | 立方体 PLY、逐体素 CSV、分类统计 CSV、网格原点/尺寸/来源 JSON；完整处理输入，CSV 行数与体素数一致 |
| 02_dda | 配置、逐射线 ray_hits.csv、observation_points.csv、view_metrics.csv、run_summary.json；首交场景验证、串并行一致、逐点射线数及状态总数对账 |
| 03_metrics | ray_hits_analysis.csv、逐视点 view_metrics.csv、metrics_summary.json、指标说明、PNG/SVG 变化图；保留原始字段、类别分母和每项有效 n |
每个成功阶段另有 stage_audit.json；总流程有 pipeline_manifest.json，记录配置、实际产物位置、大小、SHA256 和状态。出现异常写 failure.json，保留已完成产物，停在出错阶段。
常用操作口径
默认前向 yaw −60°～+60° 每 2°、pitch −30°～+45° 每 3°、最长 120 m，即 1586 条/点；研究范围用 expected_viewpoints 指定前 N 点。方位北 0° 东 90°，仰角相对全局水平。保留完整视点输入用于计算三点路线切线，再运行指定前 N 点。
若采用未命中默认天空，设 metrics.sky_mode="assumed"，派生 analysis_status=sky_assumed，并保留 ray_status、终止原因与原质量字段。若改用实证天空，设 evidence 并提供人工确认的天空扇区；未经确认的方向保留未知，上部存在未知时天空加权指标留空。不得把操作定义更名成实测确认。
起点占用体素时保留行但排除趋势；不要自动平移视点。无水平命中时平均视距为空，不填最大距离。类别首见占比的分母是命中射线；完整网格占比的分母是全部射线。两种上部加权指标分别命名，均限前向上部角域。目标表面可见率需目标表面分母，本包不替代它。
完成前核实三步产物与 manifest、真实计数、图像字体和断点。交付运行目录和配置位置，说明实际执行到哪一步及失败/缺失项。用 scripts/smoke_test.py --output <新目录> 可生成独立小场景验证三步。
