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 / 名词解释

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/\x3Cscene>.
• Explain why PLY, LCC, SOG, streamed LOD, and voxel outputs are different.
• Package or publish this workflow as a reusable Codex/OpenClaw/ClawHub skill.

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. If old PLY -> SOG conversion needed -r 90,0,0 for viewer alignment, keep using it.
• 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.
• 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; legacy LCC and PLY use 90,0,0.
• --sog-rotation auto: PLY uses 90,0,0; LCC on 2.x uses no extra -r.
• --voxel-rotation auto: PLY on 2.x uses -90,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.

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/\x3Cscene>.

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 input.ply -r 90,0,0 output/scene.sog
splat-transform --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 input.lcc output/lod-meta.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/\x3Cscene>/settings-merged.json or the original settings filename
• public/\x3Cscene>/streamed/
• public/\x3Cscene>/voxel/walk.voxel.json
• public/\x3Cscene>/voxel/walk.voxel.bin
• public/\x3Cscene>/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.

Publishing Notes / 发布说明

• Keep this file usable as a standalone SKILL.md; ClawHub publishes from a skill folder that contains this file.
• Keep the repo-local plugin metadata in plugins/splat-transform-for-lcc/.codex-plugin/plugin.json aligned with this skill.
• The top-level skills/splat-transform-workflow-for-lcc/SKILL.md mirrors this plugin skill for scanners that expect a repository-level skills/ directory.
• Tencent SkillHub is treated as the China-optimized discovery/mirror layer for ClawHub content. Publish to ClawHub first, then verify whether SkillHub has mirrored or accepted the listing.