💾 File Format Compatibility & Conversion

StorySplat supports several 3D Gaussian Splat file formats. Understanding their characteristics and how StorySplat handles them is key to achieving the best results. Compatibility can vary based on the application used to generate the original file.

Supported Formats for Import

StorySplat can load Gaussian Splat data from the following formats:

• .ply (Polygon File Format): A widely used format for 3D data.
  • Can contain Spherical Harmonics (SH): Whether SH data is present depends entirely on the application that created the .ply file. Some tools include it, others don't.
  • StorySplat Loading: If SH data exists in the .ply file, StorySplat will load it.
• .splat: A compressed format specifically for Gaussian Splats.
  • Does not contain SH: This format typically omits Spherical Harmonics data.
• .spz: A compressed format based on the spz-js library.
  • Preserves SH: If the data used to create the .spz file contained SH, it will be preserved. Offers good compression.
• .glb / .gltf (GL Transmission Format): These are mesh formats. StorySplat can load traditional 3D mesh models from these files to be used as custom 3D elements within your scene (See Custom 3D Models Documentation). Gaussian Splat data cannot be imported from GLB/glTF files.

Format Conversion & Export Tools (File Menu)

The "File" menu provides tools for conversion during import/export:

• Convert PLY to SPLAT: Transforms a .ply file into the compressed .splat format. Warning: This conversion process within StorySplat currently removes any existing Spherical Harmonics (SH) data.
• Convert PLY to SPZ: Converts a .ply file into the compressed .spz format using spz-js. This process preserves SH data if it was present in the original PLY.
• Convert SPZ to PLY: Converts a .spz file back to .ply using spz-js, preserving SH data.
• Auto-Convert PLY to SPZ on Load: (Toggle in File Menu) If enabled, automatically converts .ply files to .spz upon loading them into the editor. This is useful for preserving SH data if your source PLY files contain it.
• Export Options (Save/Save As/Export): You can export your scene data from StorySplat into .ply, .splat, or .spz formats. The exported file will include Spherical Harmonics data (up to the band limit set in Export Settings) if the data currently loaded in the editor contains it.

Recommendations:

• For highest visual fidelity (preserving lighting detail):
  • Import .spz files directly if available.
  • Import .ply files that contain SH data. Enable the "Auto-Convert PLY to SPZ on Load" option to ensure SH data is kept during the editing session and subsequent saves/exports.
• For compatibility:
  • .splat is widely supported by viewers but lacks SH data.
  • .ply without SH is also common but can be large.
• For smaller file size with SH:
  • Use or convert to .spz.

Known Compatibility & Orientation Issues

Different tools export files with varying coordinate systems. This can lead to models appearing rotated or inverted upon import.

Source Application	Format	Editor Import Behavior	SH Data Included?	Notes
Scaniverse	PLY	Often inverted on Y-axis	✅ Yes	Preserves SH. Use "Invert Y Scale" in Settings menu if needed.
Scaniverse	SPZ	✅ Good	✅ Yes	Recommended format from Scaniverse.
Luma AI	PLY	✅ Good	❌ No	Generally imports correctly. Does not contain SH.
Luma AI	PLY → Editor .splat Conv	✅ Good	❌ No	Conversion via File Menu. SH data lost.
Luma AI	PLY → Editor .spz Conv	Inverted on Y-axis	❌ No	Conversion via File Menu (spz-js). SH wasn't present initially. Use "Invert Y Scale".
Polycam	PLY	✅ Good	❌ No	Generally imports correctly. Does not contain SH.
Polycam	PLY → Editor .splat Conv	✅ Good	❌ No	Conversion via File Menu. SH data lost.
Polycam	PLY → Editor .spz Conv	Need to test orientation	❌ No	Conversion via File Menu (spz-js). SH wasn't present initially.
PostShot	.splat/.ply/.spz	✅ Good	✅ Yes (if source had it)	Files saved/exported should load correctly. SH preserved if present.

Table based on current knowledge and typical export behavior; individual results may vary.

Fixing Orientation Issues

If your imported model appears upside down or incorrectly rotated:

1. Navigate to the Settings menu (⚙️ icon) in the editor.
2. Activate the "Invert Y Scale" toggle to flip the model vertically.
3. Activate the "Invert X Scale" toggle if horizontal flipping is needed (less common).
4. Fine-tune using the Rotation controls in the Transform panel if required.
5. Save your scene. The inversion settings are saved and applied during export.

Spherical Harmonics (SH) Explained

SH data stores information about how light interacts with each splat, leading to more realistic lighting and reflections.

• Sources WITH SH: Scaniverse PLY/SPZ, PostShot PLY, potentially other research tools.
• Sources typically WITHOUT SH: Luma AI PLY, Polycam PLY.
• Formats that PRESERVE SH: .spz. Standard .ply can store it.
• Formats that DO NOT STORE SH: .splat.
• StorySplat Conversions:
  • PLY -> SPZ (Manual or Auto): Preserves SH (if present in source PLY).
  • PLY -> SPLAT (Manual): Removes SH.
• StorySplat Exports: Exports (.ply, .splat, .spz) include SH (up to selected band limit) if the data currently loaded in the editor contains it.

---

Previous: Collision System | Next: File Menu