Cinematics

Domain-level camera-shot builders, built on DazCamera and DazScene.

CinematicStaticShot

class dazpy.CinematicStaticShot(position, look_at=None, look_at_offset_cm=0.0, rotation=None, focal_length=50.0, depth_of_field=False, focal_distance=None, aspect_width=None, aspect_height=None, pixels_width=None, pixels_height=None)[source]

Bases: object

A single camera placement and optics configuration.

Parameters:

  • position (Vec3) – World-space camera position.

  • look_at (Vec3 | DazNode | None) – Aim target passed to aim_at(). A DazNode is resolved via its position, raised by look_at_offset_cm. Ignored if None; in that case rotation (if set) is used instead.

  • look_at_offset_cm (float) – Vertical offset (cm) applied when resolving look_at — see resolve_target(). Defaults to 0.0 since this API already takes an explicit position/look_at the caller fully controls.

  • rotation (tuple[float, float, float] | None) – Explicit (x, y, z) degrees passed to set_rotation(). Ignored if look_at is set.

  • focal_length (float) – Passed to focal_length.

  • depth_of_field (bool) – Passed to depth_of_field.

  • focal_distance (float | None) – Passed to focal_distance when not None; otherwise DAZ’s current value is untouched.

  • aspect_width (float | None) – Passed to aspect_width when not None.

  • aspect_height (float | None) – Passed to aspect_height when not None.

  • pixels_width (int | None) – Passed to pixels_width when not None.

  • pixels_height (int | None) – Passed to pixels_height when not None.

position: Vec3
look_at: Vec3 | DazNode | None = None
look_at_offset_cm: float = 0.0
rotation: tuple[float, float, float] | None = None
focal_length: float = 50.0
depth_of_field: bool = False
focal_distance: float | None = None
aspect_width: float | None = None
aspect_height: float | None = None
pixels_width: int | None = None
pixels_height: int | None = None
dazpy.apply_static_shot(scene, shot, *, camera=None, name=None)[source]

Place and configure a camera for shot in a single HTTP-round-trip set.

Parameters:

  • scene (DazScene) – A DazScene. Only used to create a new camera when camera is None.

  • shot (CinematicStaticShot) – The placement/optics configuration.

  • camera (DazCamera | None) – An existing DazCamera to reuse/mutate. When None (the default), a new camera is created via scene.create_camera(name).

  • name (str | None) – Optional name for a newly created camera. Ignored when camera is given.

Returns:

The configured DazCamera (either camera or the newly created one).

Return type:

DazCamera

OrbitCamera

class dazpy.OrbitCamera(target, radius, elevation_deg=15.0, start_azimuth_deg=0.0, end_azimuth_deg=360.0, frame_start=0, frame_end=90, focal_length=50.0, target_offset_cm=25.0)[source]

Bases: object

A camera sweeping around a target across a frame range.

Writes a static per-frame placement at each timeline frame — this is not a real interpolated keyframe animation (see the module docstring). Whether the sweep persists as visible motion when scrubbing the timeline afterward depends on DAZ Studio’s key/animation mode at call time; that’s the caller’s responsibility.

Parameters:

  • target (Vec3 | DazNode) – The point to orbit around, as a Vec3 world position or a DazNode (its position, raised by target_offset_cm, is used).

  • radius (float) – Orbit radius from the target, in DAZ Studio units (cm).

  • elevation_deg (float) – Constant elevation angle throughout the orbit — see spherical_offset().

  • start_azimuth_deg (float) – Azimuth at frame_start.

  • end_azimuth_deg (float) – Azimuth at frame_end. Azimuth is linearly interpolated between the two across the frame range. Note the class defaults sweep a full 0-360 degrees, which gives frame_start and frame_end the same azimuth (a duplicate endpoint) – callers wanting a seamless loop should use e.g. end_azimuth_deg=356.0 or frame_end=frame_start+89 instead of a full 360.

  • frame_start (int) – First timeline frame (inclusive).

  • frame_end (int) – Last timeline frame (inclusive). Must be >= frame_start.

  • focal_length (float) – Passed to focal_length once, before the per-frame sweep.

  • target_offset_cm (float) – Vertical offset (cm) applied when resolving target — see resolve_target(). Defaults to 25.0 (chest height) since a figure’s resolved position is generally its root/hip joint and a close orbit radius aimed straight at it risks clipping the head.

target: Vec3 | DazNode
radius: float
elevation_deg: float = 15.0
start_azimuth_deg: float = 0.0
end_azimuth_deg: float = 360.0
frame_start: int = 0
frame_end: int = 90
focal_length: float = 50.0
target_offset_cm: float = 25.0
dazpy.apply_orbit_camera(scene, orbit, *, camera=None, name=None)[source]

Sweep a camera around orbit.target across its frame range.

Side effects: this widens/sets the scene’s animation range to [orbit.frame_start, orbit.frame_end] via set_anim_range() – without this, DAZ Studio’s Scene.setFrame() clamps to the scene’s existing animation range (typically 0-30 on a fresh scene), silently overwriting later frames onto the clamped one. The scene’s timeline frame is also left parked at orbit.frame_end when this function returns – it is not restored to whatever frame was current beforehand.

Parameters:

  • scene (DazScene) – A DazScene. Used to create a new camera when camera is None, and to widen the animation range to cover the orbit’s frame range.

  • orbit (OrbitCamera) – The orbit configuration.

  • camera (DazCamera | None) – An existing DazCamera to reuse/mutate. When None (the default), a new camera is created via scene.create_camera(name).

  • name (str | None) – Optional name for a newly created camera. Ignored when camera is given.

Returns:

The configured DazCamera.

Raises:

ValueError – If orbit.frame_end is less than orbit.frame_start.

Return type:

DazCamera

FrameSubject

class dazpy.FrameSubject(subject, shot_type='medium', azimuth_deg=0.0, elevation_deg=10.0, focal_length=50.0, target_offset_cm=None)[source]

Bases: object

A camera framing a subject at a named shot distance.

Parameters:

  • subject (Vec3 | DazNode) – The point to frame, as a Vec3 world position or a DazNode (its position, raised by target_offset_cm, is used).

  • shot_type (str) – One of "close_up", "medium", "full_body" — maps to a preset distance via a module-level table.

  • azimuth_deg (float) – Camera azimuth around the subject — see spherical_offset().

  • elevation_deg (float) – Camera elevation around the subject.

  • focal_length (float) – Passed to focal_length.

  • target_offset_cm (float | None) – Vertical offset (cm) applied when resolving subject — see resolve_target(). None (the default) uses the shot_type’s entry in _SHOT_TARGET_OFFSETS_CM (tighter shots aim higher, to compensate for a figure’s resolved position being its root/hip joint rather than chest/head height).

subject: Vec3 | DazNode
shot_type: str = 'medium'
azimuth_deg: float = 0.0
elevation_deg: float = 10.0
focal_length: float = 50.0
target_offset_cm: float | None = None
dazpy.apply_frame_subject(scene, frame, *, camera=None, name=None)[source]

Place and aim a camera to frame frame.subject at its shot distance.

Parameters:

  • scene (DazScene) – A DazScene. Only used to create a new camera when camera is None.

  • frame (FrameSubject) – The framing configuration.

  • camera (DazCamera | None) – An existing DazCamera to reuse/mutate. When None (the default), a new camera is created via scene.create_camera(name).

  • name (str | None) – Optional name for a newly created camera. Ignored when camera is given.

Returns:

The configured DazCamera.

Raises:

ValueError – If frame.shot_type is not one of "close_up", "medium", "full_body".

Return type:

DazCamera

CinematicAnimatedShot

class dazpy.CameraKeyframe(frame, position, look_at=None, look_at_offset_cm=0.0, rotation=None)[source]

Bases: object

A single waypoint in an animated camera move (see CinematicAnimatedShot).

Parameters:

  • frame (int) – Timeline frame number for this waypoint.

  • position (Vec3) – World-space camera position at frame.

  • look_at (Vec3 | DazNode | None) – Aim target at frame, resolved the same way as CinematicStaticShot.look_at. Ignored if None; in that case rotation (if set) is used instead.

  • look_at_offset_cm (float) – Vertical offset (cm) applied when resolving look_at — see resolve_target().

  • rotation (tuple[float, float, float] | None) – Explicit (x, y, z) degrees for this waypoint. Ignored if look_at is set.

frame: int
position: Vec3
look_at: Vec3 | DazNode | None = None
look_at_offset_cm: float = 0.0
rotation: tuple[float, float, float] | None = None
class dazpy.CinematicAnimatedShot(keyframes, focal_length=50.0, depth_of_field=False, focal_distance=None)[source]

Bases: object

A camera move driven by real DAZ Studio keyframes.

Unlike OrbitCamera (which bakes a value on every timeline frame), this writes one keyframe per CameraKeyframe waypoint and lets DAZ Studio interpolate the frames in between via its own animation curves.

Parameters:

  • keyframes (tuple[CameraKeyframe, ...]) – The waypoints, in ascending, unique frame order (at least two). Either every waypoint must specify an orientation (look_at or rotation) or none must — a partial mix would leave the rotation curve keyed at only some waypoints, holding a stale orientation between them.

  • focal_length (float) – Passed to focal_length once, before the keyframes are written.

  • depth_of_field (bool) – Passed to depth_of_field once.

  • focal_distance (float | None) – Passed to focal_distance once, when not None; otherwise DAZ’s current value is untouched.

keyframes: tuple[CameraKeyframe, ...]
focal_length: float = 50.0
depth_of_field: bool = False
focal_distance: float | None = None
dazpy.apply_animated_shot(scene, shot, *, camera=None, name=None)[source]

Write shot.keyframes as real DAZ Studio keyframes on a camera.

Side effects: clears any existing keys on the camera’s position controls (via clear_position_keys()) before writing the new curve — a freshly created camera can already carry a default key from creation time, which would otherwise distort interpolation/extrapolation around the new keyframes. Rotation controls are cleared the same way, but only if at least one keyframe specifies an orientation.

Parameters:

  • scene (DazScene) – A DazScene. Only used to create a new camera when camera is None.

  • shot (CinematicAnimatedShot) – The keyframe sequence and optics configuration.

  • camera (DazCamera | None) – An existing DazCamera to reuse/mutate. When None (the default), a new camera is created via scene.create_camera(name).

  • name (str | None) – Optional name for a newly created camera. Ignored when camera is given.

Returns:

The configured DazCamera.

Raises:

ValueError – If fewer than two keyframes are given, if their frame values are not strictly ascending, or if only some keyframes specify an orientation (look_at/rotation).

Return type:

DazCamera