使用指南
IAGaussianRenderer 通过一个场景 Actor 加载 .ply 高斯泼溅文件并实时渲染。基本流程：放置 Actor → 设置 PLY 路径与坐标系 → 运行（PIE / 打包游戏）即加载渲染。
1. 放置 Gaussian Splat Actor
- 打开关卡，从 Place Actors（放置 Actor） 面板搜索 Gaussian Splat Actor（类
AIAGSActor），拖入场景。 - 选中该 Actor，在 Details（细节） 面板的 GaussianSplat 分类下配置参数（见下表）。
- Actor 的世界变换（位置 / 旋转 / 缩放）即整团点云的变换——移动、旋转、缩放 Actor，点云随之变换。
:::info 何时加载
点云可在编辑器或运行时加载。进入 PIE（Play） 或打包游戏后，若 bAutoLoadOnBeginPlay 为真且路径非空，则在 BeginPlay 自动加载并渲染。编辑器中可直接使用 Details 面板的 Load Ply / Unload Ply 按钮，无需进入 PIE。
:::
2. Actor 属性参考
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
PlyFilePath | String | 空 | PLY 文件路径。绝对路径直接使用；相对路径相对工程根目录（<工程>/...）解析。文件不存在则加载失败并报错。 |
bAutoLoadOnBeginPlay | bool | true | 运行时是否在 BeginPlay 自动加载 PlyFilePath。 |
bEnabled | bool | true | 是否渲染该点云。运行中可随时切换显隐。 |
CoordSystem | 枚举 | ZUp_RightHand | 源数据坐标系，决定加载时的轴变换（见坐标系转换）。 |
UnitScale | float | 100.0 | 单位缩放（最小 0.01）。默认把米转换为 UE 厘米。 |
bReferenceColorMode | bool | true | 忠实复现 3DGS 训练参考照片的颜色口径；关闭后融入 UE 场景光照与后处理。 |
bDepthOcclusion | bool | true | 允许场景网格遮挡 splat。 |
bDisableBlurringPostProcess | bool | false | 是否在运行时全局关闭 TAA/Bloom/MotionBlur（见后处理交互）。 |
3. 设置 PLY 路径
PlyFilePath 支持两种写法：
- 绝对路径：如
D:/Scans/room.ply，直接读取。 - 相对路径：相对工程根目录解析。推荐把 PLY 放在工程内（例如
Content/GS/room.ply或自建GSData/room.ply），填GSData/room.ply这类相对路径，便于随工程迁移。
加载时机：
- 自动：保持
bAutoLoadOnBeginPlay = true，运行即加载。 - 手动（蓝图）：
| 接口 | 说明 |
|---|---|
LoadPly() | 按当前 PlyFilePath 加载。 |
LoadPlyFromPath(Path) | 用给定路径加载，并把 PlyFilePath 更新为该路径。 |
UnloadPly() | 卸载当前点云。 |
GetNumSplats() | 返回当前已加载的 splat 数量（0 表示未加载）。 |
OnPlyLoaded | 编辑器或运行时异步加载完成后触发的事件。 |
:::tip 编辑器操作 Details 面板提供 Load Ply / Unload Ply 按钮，可在不进入 PIE 的情况下加载或卸载当前 Actor 的点云。 :::
:::note 多 Actor 同一关卡可放置多个 Gaussian Splat Actor，每个 Actor 持有独立点云、PLY 路径与世界变换。 :::
4. 对 PLY 的处理要求
文件格式
| 项 | 支持 |
|---|---|
| 头部 | 标准 PLY 文本头（element vertex N + property ...） |
| 数据体编码 | ASCII 或 binary_little_endian |
| 不支持 | binary_big_endian、未知格式 → 直接报错 |
| 属性类型 | float/float32、double/float64、uchar/uint8、short/int16、int/int32 |
仅解析
vertex元素内的property。uchar数值会按/255归一化。
必需 / 可选属性
- 必需（所有文件）：
x、y、z（缺失直接报错）。 - 3DGS 文件：需同时具备三组属性才会被识别为高斯泼溅——
- SH 颜色：
f_dc_0、f_dc_1、f_dc_2 - 缩放：
scale_0、scale_1、scale_2 - 旋转四元数：
rot_0、rot_1、rot_2、rot_3（顺序为 w, x, y, z） opacity可选（缺失按完全不透明处理）。
- SH 颜色：
- 点云文件（缺少上述任一组 3DGS 属性）：使用
red、green、blue作为颜色；splat 尺寸按点密度自动估算（约束在 0.1–20 cm）。
数据变换（加载时自动完成）
| 数据 | 处理 |
|---|---|
| 位置 | 按 CoordSystem 做轴变换，再 × UnitScale |
| 不透明度（3DGS） | PLY 存逆 sigmoid 值 → sigmoid() → [0,1] |
| 缩放（3DGS） | PLY 存 log 值 → exp() → × UnitScale |
| 颜色（3DGS） | 原始 SH DC 系数（在 shader 内按 SH_C0·x + 0.5 转换） |
| 颜色（点云） | uchar [0,255] → [0,1]，再按 (c − 0.5) / SH_C0 伪造为 SH DC |
:::info 球谐颜色
插件支持 SH degree 0–3，并默认启用高阶系数。包含 f_rest_* 的标准 3DGS 模型可呈现视角相关颜色。
:::
加载校验
加载后会做有限性 / 退化校验并尽量清洗：
- NaN/Inf 位置、退化缩放（≤0）、非法四元数的 splat 会被清洗为安全默认值。
- 若超过 50% 的 splat 无效或有效数为 0 → 判定不可渲染，加载失败（日志报错）。
- 包围盒异常会给出提示：范围 > 10 km 提示检查
UnitScale；范围 < 1 cm 提示单位可能不对；最大缩放 > 10000 cm 提示可能产生渲染瑕疵。
排查时请查看 Output Log 中的
=== Validation Report ===（含总数 / 有效 / 剔除数、包围盒与缩放区间）。
坐标系转换
通过 Actor 的 CoordSystem 选择源坐标系：
| 源坐标系 | 适用数据 |
|---|---|
| ZUp_RightHand（默认） | Z-Up 右手系 3DGS 数据 |
| YUp_RightHand | OpenGL / Blender 等 Y-Up 右手系数据 |
| YDown_RightHand | COLMAP / 3DGS 数据集，例如 Tanks and Temples tandt；等效于 ZUp 预设再绕 X 轴旋转 −90° |
| UE_Native | 已采用 UE 原生坐标系的数据，不做转换 |
选择与源数据一致的预设即可。UnitScale 默认 100，用于把米转换为 UE 厘米。
后处理交互
默认的 reference 颜色模式按训练参考照片的颜色口径输出，splat 不受 TAA、Bloom、MotionBlur 影响，因此无需为了保持锐利度而全局关闭这些效果。这也是 bDisableBlurringPostProcess 现在默认关闭的原因。
关闭 reference 模式后，splat 会进入场景的光照与后处理链，以获得与周围 UE 网格更一致的观感，但颜色会偏离源参考照片。如果确需排除全局模糊效果，可手动开启 bDisableBlurringPostProcess；该选项会影响整个场景，而不只当前 Actor。
全景（ERP）或立方体贴图采集需要关闭 reference 模式，具体采集方式请参阅 IADataSDG 文档。
已知限制
- LOD 默认关： 近景保真走全量；大场景远距需显式打开
bLod（依赖bClip）。VRAM 仍按全量常驻。 - 极端 FOV： 投影近似存在 EWA 泼溅的固有误差。
- 非方形像素： UE 相机只有单一 FOV 标量，无法表达标定中
fx≠fy的情况；Truck benchmark 数据集约有 0.6% 差异，属于引擎固有限制。 - 全景采集： ERP / 立方体贴图采集需使用非 reference 颜色口径。
- 版本状态： 0.1，Beta / Experimental。
:::caution 实验状态 IAGaussianRenderer 为 0.1 Beta / Experimental 版本，上述限制属当前已知范围，后续版本可能调整。 :::