Getting started with spatialstudio

Installation

First, let's get spatialstudio installed on your system. We recommend using Python 3.8 or higher:

pip install spatialstudio

Once installed, you'll have access to the entire spatialstudio API for creating volumetric content.

Your first spatial video

Let's dive right in and create something visual! The following script demonstrates the core spatialstudio workflow. We'll create a spatial that shows a red cube moving through 3D space over time:

from spatialstudio import splv

# Set up the voxel volume dimensions
w = h = d = 128  # Create a 128x128x128 voxel space

# Create an encoder to generate our .splv file
enc = splv.Encoder(w, h, d, framerate=30.0, outputPath="example.splv")

# Generate 100 frames of animation
for i in range(100):
    # Create a new frame for this time step
    f = splv.Frame(w, h, d)
    
    # Draw a 20x20x20 red cube that moves diagonally
    f.fill(i, i, i, i+20, i+20, i+20, voxel=(255, 0, 0))
    
    # Encode this frame into our video
    enc.encode(f)

# Finalize and save the .splv file
enc.finish()

Let's break down what this code does step by step:

1. Setting up dimensions

w = h = d = 128

We define our voxel space as a 128×128×128 cube. This gives us plenty of room for our animation while keeping the file size manageable.

2. Creating the encoder

enc = splv.Encoder(w, h, d, framerate=30.0, outputPath="example.splv")

The encoder is your gateway to creating .splv files. It handles:

• Volume dimensions: our 128³ voxel space
• Temporal settings: 30 frames per second for smooth playback
• Output location: where to save the final .splv file

3. Frame-by-frame animation

for i in range(100):
    f = splv.Frame(w, h, d)
    f.fill(i, i, i, i+20, i+20, i+20, voxel=(255, 0, 0))
    enc.encode(f)

This loop creates 100 frames of animation. For each frame, we create a fresh frame object and use the fill() method to draw a 20×20×20 red cube. As i increases, the cube moves diagonally through 3D space.

4. Finalizing the output

enc.finish()

The finish() method completes the encoding process and writes the final .splv file to disk.

Running your first script

Save the code above as example.py and run it:

python example.py

You should see encoding progress information, and when complete, you'll have example.splv in your current directory. This file contains your first 4D voxel video!

Understanding the coordinate system

Spatialstudio uses a standard 3D coordinate system:

• X-axis: left to right (0 to width-1)
• Y-axis: bottom to top (0 to height-1)
• Z-axis: front to back (0 to depth-1)

When we call f.fill(i, i, i, i+20, i+20, i+20, voxel=(255, 0, 0)), we're defining a rectangular region from point (i, i, i) to point (i+20, i+20, i+20) and filling it with red voxels.

What you've accomplished

Congratulations! You've successfully:

• ✅ Installed spatialstudio and set up your development environment
• ✅ Created your first .splv voxel video file
• ✅ Learned the basic spatialstudio workflow: create encoder → generate frames → encode frames → finish
• ✅ Understood the 3D coordinate system and voxel positioning
• ✅ Implemented frame-by-frame animation with the fill() method

Your example.splv file is a fully-functional 4D voxel video that can be played back using spatialjs in web browsers or other compatible players.