Scene State

class dazpy.DazSceneState(skeleton_poses, camera_transforms, light_transforms, light_extra, follow_targets=None)

Bases: object

A full snapshot of scene state, suitable for a save/restore checkpoint.

Captures every skeleton’s complete pose (bone rotations, morphs, and node-level properties – see DazPose) plus transform and a handful of key properties for every camera and light in the scene. Everything is captured and restored via each property’s raw (pre-ERC) value, so repeated capture/apply cycles are idempotent even for properties driven by DzERCLink controllers (e.g. a “Scale” dial fed by dozens of linked morphs) – see DazPose and raw_value for why this matters.

Skeletons, cameras, and lights are all keyed by their internal name (not display label), since labels are user-editable and not guaranteed unique.

Typical workflow:

from dazpy import DazScene, DazSceneState

scene = DazScene()
checkpoint = DazSceneState.capture(scene)
...  # experimental changes
checkpoint.apply(scene)

classmethod capture(scene)

Capture the current state of every skeleton, camera, and light in scene.

Parameters:

scene (DazScene) – The scene to capture.

Returns:

A new DazSceneState.

Return type:

DazSceneState

to_dict()

Return this snapshot as a plain, JSON-serialisable dict.

classmethod from_dict(data)

Reconstruct a snapshot from to_dict()’s output.

apply(scene, *, max_verify_retries=2, verify_tolerance=0.05)

Apply this snapshot’s skeleton poses, camera transforms, and light properties back onto scene in a small, fixed number of HTTP calls.

Nodes that no longer exist in the scene are skipped and reported in errors rather than raising – matching the behaviour of the registered-script checkpoint this class replaces.

Each skeleton restore is independently verified: after pose.apply_full(skel) returns, a fresh DazPose.capture() is taken and compared against the checkpoint. This guards against apply_full() reporting success for a restore DAZ Studio’s single-threaded main loop only partially executed under contention (see dpi-mxq) – the HTTP call can return normally even though some bone/morph/prop writes never happened. A skeleton whose read-back doesn’t match is retried (re-running apply_full and re-verifying) up to max_verify_retries times before being reported in errors instead of restored, so callers never trust an unverified result.

Parameters:

• scene (DazScene) – The scene to restore state into.

• max_verify_retries (int) – How many additional apply_full attempts to make for a skeleton whose read-back doesn’t verify, before giving up on it.

• verify_tolerance (float) – Per-channel tolerance (degrees for bones, raw value units for morphs/props) allowed between the checkpoint and the read-back before it’s considered a mismatch.

Returns:

{"restored": [name, ...], "errors": [message, ...]}.

Return type:

dict