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 mattersGaussian 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.LCCXGRIDS/其域场景容器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.SuperSplatPlayCanvas 的高斯泼溅编辑器/查看器生态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.SOGSuper-compressed Gaussian splatA 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 JSONviewer 配置文件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:

bash

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:

text

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:

bash

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:

bash

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 / 只转换资产#

bash

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 / 合并配置#

bash

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:

bash

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:

bash

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

For splat-transform 2.x LCC voxel:

bash

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:

bash

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:

bash

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

or:

bash

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.