name: splat-transform-workflow-for-lcc
description: Use when converting XGRIDS/其域 .lcc or PLY Gaussian splat scenes for SuperSplat, producing streamed LOD, SOG, voxel collision data, merging viewer settings, mounting local routes, or explaining LCC/SuperSplat workflow concepts to Chinese or English users.

Splat Transform Workflow for LCC / LCC 转 SuperSplat 工作流

Use this skill for LCC/PLY to SuperSplat conversion work. It explains the formats, chooses precision-preserving defaults, and uses the bundled scripts instead of retyping fragile splat-transform commands by hand.

本 skill 用于把 LCC 或 PLY 高斯泼溅场景转换成 SuperSplat 可加载的网页资产。它不仅记录命令，还解释每种格式的价值、坐标差异和默认参数，避免因为 1.9.x/2.x 行为变化导致场景转歪、精度降低或体素碰撞错位。

Language Policy / 多语言规则

• If the user writes in Chinese, answer in Chinese and keep command flags, file names, JSON keys, and format names in English.
• If the user writes in English, answer in English and optionally add short Chinese labels for domain terms when helpful.
• Preserve exact technical names: LCC, SuperSplat, SOG, PLY, streamed LOD, voxel, splat-transform.
• When introducing a format for a new user, explain both what it is and why it matters before giving commands.

Value / 作用和价值

This workflow turns trained or vendor-delivered Gaussian splat scenes into deployable SuperSplat viewer assets. It handles three practical problems that raw conversion commands do not solve by themselves:

• Precision: use original PLY for high-quality SOG and voxel output when available, because PLY usually preserves float32 training attributes while LCC may already be compressed or quantized.
• Delivery: use LCC for true streamed multi-LOD output when the web viewer needs progressive loading.
• Alignment: apply different rotations for PLY, LCC 1.9.2, and LCC 2.x so visual content and walkable voxel collision stay in the same space.

这个工作流的价值是把“能转换”变成“可稳定上线”：SOG 用于高质量显示，streamed LOD 用于大场景渐进加载，voxel 用于行走/碰撞，settings 用于保留 viewer 配置。skill 会帮用户判断应该从 PLY 还是 LCC 生成对应资产，并解释为什么。

Glossary / 名词解释

| Term | 中文解释 | What it means / Why it matters |
| --- | --- | --- |
| Gaussian splat / 3DGS | 三维高斯泼溅 | A scene representation made of many anisotropic Gaussian points. It is not a mesh; visual quality depends on attributes such as position, scale, rotation, opacity, color, and SH coefficients. |
| PLY | 原始训练点云/高斯属性文件 | Usually the highest-precision source produced by training. Prefer PLY for scene.sog and voxel generation when available. |
| LCC | XGRIDS/其域场景容器 | A vendor scene package used here as the source for true streamed LOD. It can include multiple LOD levels and environment data, but may already contain compressed or quantized attributes. |
| SuperSplat | PlayCanvas 的高斯泼溅编辑器/查看器生态 | The target viewer/editor ecosystem. It can load SOG, streamed LOD metadata, settings JSON, and this repo's voxel route integration. |
| splat-transform | 转换命令行工具 | Converts between PLY/LCC/SOG/LOD/voxel formats. This repo keeps both 1.9.2 and 2.1.1 because LCC coordinate handling and voxel flags changed. |
| SOG | Super-compressed Gaussian splat | A compact SuperSplat asset, commonly emitted as scene.sog or an unbundled meta.json plus binary chunks. Good for high-quality single-asset display. |
| streamed LOD | 流式多层级加载 | Output centered on lod-meta.json. It lets large scenes load progressively by LOD/chunks. Use LCC as the default source for real multi-LOD streamed output. |
| voxel / voxel collision | 体素碰撞数据 | Sparse voxel data, usually walk.voxel.json plus walk.voxel.bin, used by the viewer for walking and collision. It is not the visual splat itself. |
| settings JSON | viewer 配置文件 | SuperSplat viewer settings: camera, background, annotations, tonemapping, post effects, content paths, and optional voxel paths. |
| LOD0 | 最精细主层级 | The finest main LOD in legacy LCC workflows. It is often used as the LCC voxel source when reproducing older output. |
| environment layer | 环境层 | Optional sky/background/environment splat data inside LCC streamed output. Keep it unless the user explicitly asks to remove it. |
| baked rotation | 烘焙外参 | Rotation applied during conversion so the emitted asset is already aligned. Do not add viewer-side voxelRotation when voxel rotation is baked. |
| meta.json.version | 输出格式版本 | meta.json.version: 2 describes the SOG/LOD data format, not the installed splat-transform CLI version. |

When to Use / 什么时候用

Use this skill when a user needs to:

• Convert .lcc into true streamed LOD output for SuperSplat.
• Generate high-precision scene.sog from original PLY.
• Generate walk.voxel.json and walk.voxel.bin from original PLY.
• Merge a simple settings.json with a version 2 settings JSON.
• Mount streamed LOD, SOG, and voxel files into supersplat-viewer/public/<scene>.
• Explain why PLY, LCC, SOG, streamed LOD, and voxel outputs are different.
• Reuse this workflow from a repo-local Codex skill or a top-level skills/ directory.

Coordinate-Space Rules / 坐标规则

• PLY, SOG, SPZ, KSplat, and splat inputs are PLY-space sources.
• In splat-transform 2.x, LCC is read with an internal source transform of 90,0,180; do not blindly add the old LCC 90,0,0 rotation on top of it.
• PLY did not receive that LCC-specific reader correction. In this workflow, splat-transform 2.x PLY -> SOG and PLY -> streamed LOD use baked -r -90,0,0.
• For splat-transform 2.x LCC -> voxel, the empirically aligned single conversion rotation is -r 0,0,180. Do not infer this by multiplying only the explicit query rotations: the viewer's unrotated voxel path and explicit voxelRotation=0,0,0 path differ because the viewer has a default content rotation of 0,0,180.
• meta.json.version: 2 is the output data format version, not the splat-transform CLI version.
• Per-file transforms must come after the input file:

splat-transform input.ply -r -90,0,0 -t 0,0,0 output.sog

Preferred Defaults / 推荐默认策略

• --splat-transform: repo-local splat-transform-2.1.1/ when available, unless SPLAT_TRANSFORM_DIR or an explicit flag overrides it.
• Prefer GPU. Run splat-transform --list-gpus first when possible, then pass -g 0 for the first GPU adapter. Use -g cpu only when GPU enumeration or GPU conversion fails.
• Streamed source: LCC for true multi-LOD streamed output.
• SOG source: original PLY when available.
• Voxel source: original PLY when available.
• --stream-rotation auto: LCC on 2.x uses no extra -r; PLY on 2.x uses -90,0,0; legacy LCC and PLY use 90,0,0.
• --sog-rotation auto: PLY on 2.x uses -90,0,0; LCC on 2.x uses no extra -r; legacy PLY uses 90,0,0.
• --voxel-rotation auto: PLY on 2.x uses -90,0,180; LCC on 2.x uses 0,0,180; legacy inputs use 90,0,0.
• Voxel defaults: size 0.08, opacity threshold 0.20.
• Mounted voxel names: walk.voxel.json and walk.voxel.bin.
• Mounted LOD directory name: streamed.

2.x rotation table:

LCC -> streamed: no extra -r
PLY -> SOG:      -r -90,0,0
PLY -> streamed: -r -90,0,0
PLY -> voxel:    -r -90,0,180
LCC -> voxel:    -r 0,0,180

Preferred Scripts / 推荐脚本

End-to-end deployment / 完整部署

Use:

python3 ../../scripts/scene_workflow.py deploy-scene ...

This will merge settings, convert streamed LOD, generate SOG, generate voxel output, and mount the result into supersplat-viewer/public/<scene>.

When original PLY exists, pass it as both SOG and voxel input:

python3 ../../scripts/scene_workflow.py deploy-scene \
  scene-key \
  /path/to/meta.lcc \
  /path/to/output \
  /path/to/supersplat-viewer/public \
  /path/to/settings.json \
  --sog-input /path/to/point_cloud.ply \
  --voxel-input /path/to/point_cloud.ply

The positional input remains the streamed LOD source. Use LCC there for true multi-LOD streamed output. Use PLY there only when single-layer streamed output is acceptable, or when the PLY already has a lod column.

Standalone conversion / 只转换资产

python3 ../../scripts/scene_workflow.py convert-scene \
  /path/to/meta.lcc \
  /path/to/output \
  --sog-input /path/to/point_cloud.ply \
  --voxel-input /path/to/point_cloud.ply

Settings merge / 合并配置

python3 ../../scripts/merge_settings.py v1.json output.json --base-v2 base-v2.json

Use the base v2 file when you need to preserve annotations, post effects, tonemapping, and other viewer configuration.

Direct splat-transform Examples / 直接命令示例

For splat-transform 2.x with original PLY:

splat-transform -g 0 input.ply -r -90,0,0 output/scene.sog
splat-transform -g 0 input.ply -l 0 -r -90,0,0 output/lod-meta.json
splat-transform -g 0 --voxel-params 0.08,0.20 input.ply -r -90,0,180 output/walk.voxel.json

For splat-transform 2.x with LCC streamed LOD:

splat-transform -g 0 input.lcc output/lod-meta.json

For splat-transform 2.x LCC voxel:

splat-transform -g 0 --lod-select 0 --voxel-params 0.08,0.20 input.lcc -r 0,0,180 output/walk.voxel.json

For legacy 1.9.2 LCC:

splat-transform input.lcc -r 90,0,0 output/lod-meta.json
splat-transform -O 0 -R 0.08 -A 0.20 input.lcc -r 90,0,0 output/walk.voxel.json

First-Use Parameters / 首次使用参数说明

• --sog-input: high-precision source for scene.sog; use original PLY when available.
• --voxel-input: high-precision source for walk.voxel.json; use original PLY when available.
• --splat-transform: use splat-transform-2.1.1/ for new conversions. Use splat-transform-1.9.2/ only when reproducing legacy results.
• positional stream input: source for streamed LOD. Use LCC for true multi-LOD. PLY streamed output is single-layer unless the PLY already has LOD labels.
• --stream-ply-lod = 0: when streamed input is PLY, the script tags it with -l 0 by default so lod-meta.json can be written.
• --voxel-resolution = 0.08: voxel size in meters. Smaller values are more detailed but produce larger collision files.
• --voxel-alpha = 0.20: alpha threshold for voxelization. Higher values ignore more weak or semi-transparent edges.

Settings Workflows / 配置工作流

Two settings workflows are supported:

• v1 + base v2 -> merged version 2 settings
• v1 -> version 2 settings

Use:

python3 ../../scripts/merge_settings.py settings.json settings-merged.json --base-v2 settings-v2.json

or:

python3 ../../scripts/merge_settings.py settings.json settings-v2.json

When to Remove Environment / 什么时候移除环境层

Add --remove-environment only when the user explicitly wants the environment stripped. Otherwise keep the generated env/ directory and environment entry in lod-meta.json.

Generated Viewer Route / 生成的查看器路由

The mount step creates:

• public/<scene>/settings-merged.json or the original settings filename
• public/<scene>/streamed/
• public/<scene>/voxel/walk.voxel.json
• public/<scene>/voxel/walk.voxel.bin
• public/<scene>/index.html

The route redirects to the root viewer with settings, content, and voxel query params. Do not append a voxelRotation query param when using baked PLY voxel output. For 2.x LCC voxel, prefer the single baked conversion (input.lcc -r 0,0,180) instead of relying on a viewer-side voxelRotation.

Skill Locations / Skill 文件位置

• Plugin skill: plugins/splat-transform-for-lcc/skills/splat-transform-workflow-for-lcc/SKILL.md
• Top-level copy: skills/splat-transform-workflow-for-lcc/SKILL.md
• Keep these two files in sync when updating workflow guidance.