stage_add_shot
Define camera movement paths and time ranges for 3D scenes to create cinematographic shots with orbit, static, chase, dolly, flythrough, crane, or track modes.
Instructions
Add a camera shot to the scene.
Defines a camera movement path and time range for cinematography.
Args:
scene_id: Scene identifier
shot_id: Unique shot name (e.g., "intro-orbit", "close-up")
camera_mode: "orbit", "static", "chase", "dolly", "flythrough", "crane", "track"
start_time: Shot start time in seconds
end_time: Shot end time in seconds
focus_object: Object ID to focus on (for orbit/chase modes)
orbit_radius: Distance from focus object (orbit mode)
orbit_elevation: Camera elevation angle in degrees (orbit mode)
orbit_speed: Rotation speed in revolutions per second (orbit mode)
static_position_x, static_position_y, static_position_z: Camera position (static mode)
look_at_x, look_at_y, look_at_z: Point to look at
easing: Easing function - "linear", "ease-in-out", "spring", etc.
Returns:
AddShotResponse with shot details
Tips for LLMs:
- Orbit mode: Great for product shots, object inspection
- Static mode: Fixed camera, good for observing motion
- Chase mode: Follow moving objects
- Multiple shots can be sequenced for different camera angles
Example:
# Orbiting shot around falling ball
await stage_add_shot(
scene_id=scene_id,
shot_id="orbit-shot",
camera_mode="orbit",
focus_object="ball",
orbit_radius=8.0,
orbit_elevation=30.0,
orbit_speed=0.1,
start_time=0.0,
end_time=10.0
)Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scene_id | Yes | ||
| shot_id | Yes | ||
| camera_mode | Yes | ||
| start_time | Yes | ||
| end_time | Yes | ||
| focus_object | No | ||
| orbit_radius | No | ||
| orbit_elevation | No | ||
| orbit_speed | No | ||
| static_position_x | No | ||
| static_position_y | No | ||
| static_position_z | No | ||
| look_at_x | No | ||
| look_at_y | No | ||
| look_at_z | No | ||
| easing | No | ease-in-out-cubic |
Implementation Reference
- src/chuk_mcp_stage/server.py:304-399 (handler)Main handler function for stage_add_shot tool. Decorated with @requires_auth() and @tool decorators. Accepts scene_id, shot_id, camera_mode, time parameters, and optional camera parameters (orbit, static position, look_at, easing). Builds CameraPath and Shot objects, adds them to scene via SceneManager, and returns AddShotResponse.
@requires_auth() @tool # type: ignore[arg-type] async def stage_add_shot( scene_id: str, shot_id: str, camera_mode: str, start_time: float, end_time: float, focus_object: Optional[str] = None, orbit_radius: Optional[float] = None, orbit_elevation: Optional[float] = None, orbit_speed: Optional[float] = None, static_position_x: Optional[float] = None, static_position_y: Optional[float] = None, static_position_z: Optional[float] = None, look_at_x: Optional[float] = None, look_at_y: Optional[float] = None, look_at_z: Optional[float] = None, easing: str = "ease-in-out-cubic", ) -> AddShotResponse: """Add a camera shot to the scene. Defines a camera movement path and time range for cinematography. Args: scene_id: Scene identifier shot_id: Unique shot name (e.g., "intro-orbit", "close-up") camera_mode: "orbit", "static", "chase", "dolly", "flythrough", "crane", "track" start_time: Shot start time in seconds end_time: Shot end time in seconds focus_object: Object ID to focus on (for orbit/chase modes) orbit_radius: Distance from focus object (orbit mode) orbit_elevation: Camera elevation angle in degrees (orbit mode) orbit_speed: Rotation speed in revolutions per second (orbit mode) static_position_x, static_position_y, static_position_z: Camera position (static mode) look_at_x, look_at_y, look_at_z: Point to look at easing: Easing function - "linear", "ease-in-out", "spring", etc. Returns: AddShotResponse with shot details Tips for LLMs: - Orbit mode: Great for product shots, object inspection - Static mode: Fixed camera, good for observing motion - Chase mode: Follow moving objects - Multiple shots can be sequenced for different camera angles Example: # Orbiting shot around falling ball await stage_add_shot( scene_id=scene_id, shot_id="orbit-shot", camera_mode="orbit", focus_object="ball", orbit_radius=8.0, orbit_elevation=30.0, orbit_speed=0.1, start_time=0.0, end_time=10.0 ) """ from .models import CameraPathMode, EasingFunction, Vector3 manager = get_scene_manager() # Build camera path camera_path = CameraPath( mode=CameraPathMode(camera_mode), focus=focus_object, radius=orbit_radius, elevation=orbit_elevation, speed=orbit_speed, position=Vector3( x=static_position_x or 0, y=static_position_y or 0, z=static_position_z or 0 ) if static_position_x is not None else None, look_at=Vector3(x=look_at_x or 0, y=look_at_y or 0, z=look_at_z or 0) if look_at_x is not None else None, ) # Create shot shot = Shot( id=shot_id, camera_path=camera_path, start_time=start_time, end_time=end_time, easing=EasingFunction(easing), ) # Add to scene await manager.add_shot(scene_id, shot) duration = end_time - start_time return AddShotResponse(shot_id=shot_id, scene_id=scene_id, duration=duration) - src/chuk_mcp_stage/models.py:421-427 (schema)AddShotResponse schema defining the return type with shot_id, scene_id, duration, and success message fields.
class AddShotResponse(BaseModel): """Response from adding a shot.""" shot_id: str scene_id: str duration: float message: str = "Shot added successfully" - src/chuk_mcp_stage/models.py:241-266 (schema)CameraPath schema defining camera animation parameters including mode, focus object, position, look_at, orbit parameters (radius, elevation, speed), dolly parameters, chase parameters, and waypoints for different camera movement types.
class CameraPath(BaseModel): """Camera animation path definition.""" mode: CameraPathMode focus: Optional[str] = Field( default=None, description="Object ID to focus on (for orbit/chase modes)" ) position: Optional[Vector3] = None # For static mode look_at: Optional[Vector3] = None # For static/dolly modes # Orbit parameters radius: Optional[float] = None elevation: Optional[float] = None # Degrees speed: Optional[float] = None # Revolutions per second # Dolly parameters from_position: Optional[Vector3] = None to_position: Optional[Vector3] = None # Chase parameters offset: Optional[Vector3] = None # Offset from target damping: Optional[float] = None # Smoothing factor # Flythrough/track parameters waypoints: Optional[list[Vector3]] = None - src/chuk_mcp_stage/models.py:268-276 (schema)Shot schema combining camera_path with time range and easing function. Core data model for individual camera shots.
class Shot(BaseModel): """A shot defines camera path + time range.""" id: str = Field(description="Unique shot identifier") camera_path: CameraPath start_time: float = Field(ge=0.0, description="Start time in seconds") end_time: float = Field(gt=0.0, description="End time in seconds") easing: EasingFunction = EasingFunction.EASE_IN_OUT_CUBIC label: Optional[str] = None - src/chuk_mcp_stage/models.py:66-89 (schema)Supporting enums: CameraPathMode (orbit, chase, dolly, flythrough, crane, static, track) and EasingFunction (linear, ease-in/out variants, spring) used for type validation in stage_add_shot.
class CameraPathMode(str, Enum): """Camera movement modes.""" ORBIT = "orbit" # Circular orbit around focus point CHASE = "chase" # Follow target with offset DOLLY = "dolly" # Linear move from A to B FLYTHROUGH = "flythrough" # Follow spline path CRANE = "crane" # Arc movement STATIC = "static" # Fixed position TRACK = "track" # Follow custom path class EasingFunction(str, Enum): """Motion easing functions (compatible with chuk-motion).""" LINEAR = "linear" EASE_IN = "ease-in" EASE_OUT = "ease-out" EASE_IN_OUT = "ease-in-out" EASE_IN_CUBIC = "ease-in-cubic" EASE_OUT_CUBIC = "ease-out-cubic" EASE_IN_OUT_CUBIC = "ease-in-out-cubic" SPRING = "spring"