Skip to main content
This API documentation is provisional. WorldStereo code and model weights are not yet publicly released. The API described here represents the expected interface based on the research framework.

​
Overview

The Camera Control Interface enables precise specification of camera trajectories for video generation in WorldStereo. This interface allows you to define camera poses, movements, and parameters that guide the video generation process while maintaining 3D consistency.

​
Camera Trajectory Specification

​
CameraTrajectory

Define a camera trajectory for video generation.
​
poses
List[CameraPose]
required
A sequence of camera poses defining the trajectory. Each pose specifies the camera position and orientation at a specific frame.
​
num_frames
int
required
Total number of frames to generate along the trajectory.
​
interpolation
str
default:"linear"
Interpolation method between poses. Options:
  • linear: Linear interpolation
  • spline: Smooth spline interpolation
  • bezier: Bezier curve interpolation
​
fps
int
default:"24"
Frames per second for the generated video.

​
CameraPose

Represents a single camera pose in 3D space.
​
position
List[float]
required
Camera position in 3D space as [x, y, z] coordinates.
​
rotation
Union[List[float], Dict]
required
Camera orientation. Can be specified as:
  • Quaternion: [w, x, y, z]
  • Euler angles: {"roll": float, "pitch": float, "yaw": float} (in degrees)
  • Rotation matrix: 3x3 nested list
​
frame_index
int
required
Frame index where this pose should be applied.
​
fov
float
default:"60.0"
Field of view in degrees.

​
Camera Intrinsics

​
CameraIntrinsics

Define camera intrinsic parameters.
​
focal_length
float
required
Focal length in pixels.
​
principal_point
List[float]
default:"[width/2, height/2]"
Principal point coordinates as [cx, cy].
​
width
int
required
Image width in pixels.
​
height
int
required
Image height in pixels.
​
distortion
List[float]
default:"[0, 0, 0, 0, 0]"
Lens distortion coefficients [k1, k2, p1, p2, k3].

​
Usage Examples

​
Basic Camera Trajectory

from worldstereo.camera import CameraTrajectory, CameraPose

# Define keyframe poses
poses = [
    CameraPose(
        position=[0, 0, 0],
        rotation={"roll": 0, "pitch": 0, "yaw": 0},
        frame_index=0
    ),
    CameraPose(
        position=[1, 0, 0],
        rotation={"roll": 0, "pitch": 0, "yaw": 0},
        frame_index=30
    ),
    CameraPose(
        position=[2, 0.5, 0],
        rotation={"roll": 0, "pitch": 10, "yaw": 0},
        frame_index=60
    )
]

# Create trajectory
trajectory = CameraTrajectory(
    poses=poses,
    num_frames=60,
    interpolation="spline",
    fps=24
)

​
Circular Camera Motion

import numpy as np
from worldstereo.camera import CameraTrajectory, CameraPose

# Generate circular trajectory
num_frames = 120
radius = 2.0
height = 1.0

poses = []
for i in range(0, num_frames, 10):
    angle = 2 * np.pi * i / num_frames
    x = radius * np.cos(angle)
    z = radius * np.sin(angle)
    yaw = np.degrees(angle + np.pi/2)
    
    poses.append(CameraPose(
        position=[x, height, z],
        rotation={"roll": 0, "pitch": 0, "yaw": yaw},
        frame_index=i
    ))

trajectory = CameraTrajectory(
    poses=poses,
    num_frames=num_frames,
    interpolation="spline"
)

​
Custom Intrinsics

from worldstereo.camera import CameraIntrinsics

intrinsics = CameraIntrinsics(
    focal_length=800.0,
    principal_point=[512, 512],
    width=1024,
    height=1024,
    distortion=[0.1, -0.05, 0, 0, 0]
)

​
Trajectory Utilities

​
load_trajectory()

Load camera trajectory from file.
​
path
str
required
Path to trajectory file. Supported formats:
  • .json: JSON trajectory specification
  • .txt: COLMAP-style camera poses
  • .xml: OpenCV camera calibration format
​
format
str
default:"auto"
Format specification. Auto-detected from file extension if not provided.
Returns:
​
trajectory
CameraTrajectory
Loaded camera trajectory object.

​
save_trajectory()

Save camera trajectory to file.
​
trajectory
CameraTrajectory
required
Camera trajectory to save.
​
path
str
required
Output file path.
​
format
str
default:"json"
Output format (json, colmap, or opencv).

​
interpolate_poses()

Interpolate between camera poses.
​
start_pose
CameraPose
required
Starting camera pose.
​
end_pose
CameraPose
required
Ending camera pose.
​
num_steps
int
required
Number of interpolation steps.
​
method
str
default:"slerp"
Interpolation method for rotations:
  • slerp: Spherical linear interpolation (recommended)
  • linear: Linear interpolation
Returns:
​
poses
List[CameraPose]
List of interpolated camera poses.

​
Example Usage

from worldstereo.camera import load_trajectory, save_trajectory

# Load trajectory from COLMAP format
trajectory = load_trajectory(
    "camera_poses.txt",
    format="colmap"
)

# Save as JSON
save_trajectory(
    trajectory,
    "trajectory.json",
    format="json"
)

​
Coordinate System

WorldStereo uses a right-handed coordinate system:
  • X-axis: Right
  • Y-axis: Up
  • Z-axis: Backward (into the scene)
Camera looks along the negative Z-axis by default.

​
Best Practices

Smooth trajectories: Use spline interpolation with sufficient keyframes for smooth camera motion.Consistent scale: Maintain consistent position scales across poses to ensure proper geometric memory integration.Reasonable motion: Avoid extreme camera velocities between frames to maintain video quality and 3D consistency.Frame spacing: Space keyframes 10-30 frames apart for optimal interpolation quality.

Build docs developers (and LLMs) love

Get started for freeTalk to us