Skip to content

🔁 SplatSwap: Dynamic Scene Switching

SplatSwap is a powerful StorySplat feature that allows you to dynamically switch between different Gaussian Splat models (.splat, .ply, or .spz files) as the user progresses along the defined camera path. This enables the creation of evolving environments, transitions between different states of a scene, or showcasing variations of an object within a single interactive experience.

How SplatSwap Works

  1. Define an Initial Splat: Your scene starts with a primary splat model loaded via the File Menu or drag-and-drop.
  2. Add Additional Splats: You upload supplementary splat files that you want to transition to.
  3. Set Trigger Points: For each additional splat, you define a specific point along the camera path where StorySplat should switch from the previous splat to this new one.
  4. Automatic Switching: As the user scrolls or autoplay progresses through the scene in Tour or Hybrid mode, StorySplat monitors the current position along the path. When a trigger point is reached, it automatically loads and displays the corresponding splat, hiding the previous one.

Accessing SplatSwap Controls

  1. In the StorySplat editor, locate the vertical toolbar on the left.
  2. Click the "Splat Swap" button (겹 icon).
  3. The SplatSwap Controls panel will appear.

Configuring SplatSwap

1. The Initial Splat

  • The panel displays the currently loaded primary splat at the top. This is the scene that viewers will see from the beginning of the path until the first trigger point.
  • You cannot change the initial splat directly from this panel; load a different primary model via the File Menu if needed.

2. Adding Swap Points

  • Upload New Splat:
    • Click "Choose Splat File" to select a .splat, .ply, or .spz file from your computer. Note: Uploaded splats count towards your storage quota.
    • (Optional) Splat Name: Give the new splat a descriptive name. If left blank, the filename will be used.
  • Set Trigger Type: Choose how the swap will be triggered:
    • Waypoint: Select a specific waypoint index from the dropdown. The swap will occur precisely when the camera path calculation reaches this waypoint number. (Requires waypoints to be defined).
    • Percentage: Enter a value between 0 and 100. The swap will occur when the camera path reaches this percentage of its total length.
  • Click "Add Splat": Uploads the file (if chosen locally) and adds the new splat and its trigger point to the list.

3. Managing Swap Points

  • The panel lists all configured swap points below the initial splat.
  • Each item shows the splat name and its trigger condition (e.g., "Waypoint 3" or "50%").
  • Edit Trigger: You can change the trigger type (Waypoint/Percentage) and the specific waypoint index or percentage value for any added splat directly in its item controls.
  • Rename: Modify the name of any added splat.
  • Remove: Click the "Remove" button on an item to delete that swap point and the associated splat file from your storage (freeing up quota).

Important Trigger Logic: * The system determines the "active" splat based on the highest trigger value (waypoint index or percentage) that the current scroll position has passed. * If multiple triggers exist (e.g., Waypoint 2 and 30%), the one corresponding to the later point in the path progression takes precedence once that point is reached. * If the scroll position is before the first trigger point, the initial splat is displayed.

Performance & Preloading

SplatSwap includes features to manage performance during transitions:

  • Keep Meshes in Memory (Toggle):
    • Enabled: Once a splat is loaded (either initially or via a swap), its mesh data is kept in the computer's memory (RAM/VRAM). When swapping back to a previously loaded splat, the transition is nearly instant as it only involves showing/hiding meshes. Uses significantly more memory, potentially impacting performance on lower-end devices if many large splats are used.
    • Disabled (Default): Only the currently active splat (and potentially the next one being preloaded) is kept fully in memory. When swapping, the previous splat's meshes are disposed of to save memory. Swapping back to it will require reloading it from storage/cache. Recommended for most scenarios to conserve resources.
  • Background Preloader: StorySplat attempts to preload the next splat in the sequence in the background before its trigger point is reached. This minimizes loading delays during transitions, especially when "Keep Meshes in Memory" is disabled. This preloading happens automatically without showing the main loading screen.
  • Splat Fade Effect (Settings Menu): If enabled in the main Settings Menu, a visual fade transition occurs between splats (using node materials). This does not apply if either the incoming or outgoing splat is a GLB/GLTF mesh (which shouldn't be used in SplatSwap anyway). Disable this effect if you prefer instant cuts or encounter visual issues.

Best Practices & Use Cases

  • Logical Progression: Ensure your trigger points are ordered sequentially along the path.
  • Consistent Orientation: Try to ensure swapped splats have similar origins or orientations to avoid jarring visual jumps, unless that jump is intentional.
  • Use Cases:
    • Showing architectural changes over time (e.g., construction phases).
    • Transitioning between different scans of the same object/area (e.g., different lighting conditions, before/after).
    • Creating "portals" where moving past a certain point reveals a completely different environment.
    • Displaying variations of a product or model.
  • Test Thoroughly: Preview your scene and scroll back and forth through the swap points to ensure transitions work smoothly and as expected with your chosen performance settings.

Previous: Skybox | Next: Troubleshooting