Scene

class dazpy.DazScene(client=None)[source]

Bases: object

High-level proxy for the active DAZ Studio scene (Scene global).

This is the primary entry point for inspecting and manipulating the scene. All methods execute DazScript on the server and return Python objects.

Parameters:: client (DazClient | None) – Optional DazClient to use. A default client connecting to 127.0.0.1:18811 is created when omitted.

Example:

from dazpy import DazScene

scene = DazScene()
print(scene.num_nodes(), "nodes in scene")
figure = scene.find_skeleton_by_label("Genesis 9")

nodes()[source]

Return all top-level and child nodes in the scene.

The returned list contains typed subclass instances: DazSkeleton for figures, DazCamera, DazLight, and DazNode for everything else.

Returns:: Ordered list of scene nodes (same order as DAZ Studio’s scene panel).
Return type:: list[DazNode]

find_node(name)[source]

Find a scene node by its internal name.

Parameters:: name (str) – The getName() string of the node.
Returns:: A DazNode proxy for the node.
Raises:: NodeNotFoundError – If no node with that name exists in the scene.
Return type:: DazNode

find_node_by_label(label)[source]

Find a scene node by its user-visible label.

The returned proxy is anchored to the node’s internal name so it remains stable if the label is later changed.

Parameters:: label (str) – The getLabel() string shown in the Scene panel.
Returns:: A DazNode proxy.
Raises:: NodeNotFoundError – If no node with that label exists.
Return type:: DazNode

num_nodes()[source]

Return the total number of nodes in the scene.

cameras()[source]

Return all camera nodes in the scene.

lights()[source]

Return all light nodes in the scene.

find_camera_by_label(label)[source]

Find a camera by its user-visible label.

Parameters:: label (str) – The label shown in the Scene panel (e.g. "Camera 1"). This is the same value accepted by the camera parameter of render().
Returns:: A DazCamera proxy.
Raises:: NodeNotFoundError – If no camera with that label exists.
Return type:: DazCamera

find_light_by_label(label)[source]

Find a light by its user-visible label.

Parameters:: label (str) – The label shown in the Scene panel (e.g. "Distant Light 1").
Returns:: A DazLight proxy.
Raises:: NodeNotFoundError – If no light with that label exists.
Return type:: DazLight

skeletons()[source]

Return all skeleton (figure) nodes in the scene.

find_skeleton(name)[source]

Find a skeleton by its internal name.

Parameters:: name (str) – Internal name of the skeleton node (e.g. "Genesis9"). To look up by the user-visible label shown in the Scene panel (e.g. "Genesis 9"), use find_skeleton_by_label().
Returns:: A DazSkeleton proxy.
Raises:: NodeNotFoundError – If no skeleton with that name exists.
Return type:: DazSkeleton

find_skeleton_by_label(label)[source]

Find a skeleton by its user-visible label.

Parameters:: label (str) – Label shown in the Scene panel.
Returns:: A DazSkeleton proxy.
Raises:: NodeNotFoundError – If no skeleton with that label exists.
Return type:: DazSkeleton

num_skeletons()[source]

Return the total number of skeleton nodes in the scene.

scene_snapshot(skeleton_labels=None)[source]

Return full skeleton and bone metadata for the scene in one HTTP call.

Each entry in the returned list represents one skeleton and contains: name, label, and bones — a list of dicts with name, label, parent_name, rotation_order, local_position, world_position, and local_euler.

Pass to build_rig_profiles_from_snapshot() to build solver-ready FigureRigProfile objects without any additional HTTP calls.

Parameters:: skeleton_labels (list[str] | None) – Optional list of skeleton names or labels to include. None returns every skeleton in the scene.
Returns:: List of skeleton snapshot dicts, one per matching skeleton.
Return type:: list[dict]

all_node_transforms()[source]

Return world-space transforms for every node in a single call.

Returns:: A list of dicts, each with keys "name", "label", "position" ([x, y, z]), "rotation" ([x, y, z]), and "visible".
Return type:: list[dict]

node_tree()[source]

Return the full scene hierarchy as a nested list of dicts.

Returns:: Root-level nodes, each a dict with "name", "label", and "children" (recursively nested).
Return type:: list[dict]

selected_nodes()[source]

Return the currently selected nodes.

primary_selection()[source]

Return the primary selected node, or None if nothing is selected.

set_primary_selection(node)[source]

Set the primary selection to node.

Parameters:: node (DazNode) – The node to select.

apply_interaction_recipe(recipe, *, rig_profiles=None, align_limb_targets=False, max_iterations=None, step_degrees=1.0, damping=0.25, tolerance=0.15)[source]

Prepare and apply an interaction recipe against the current scene.

select_all(on=True)[source]

Select or deselect all nodes.

Parameters:: on (bool) – True to select all, False to deselect all.

undo(label)[source]

Return a context manager that groups all enclosed changes into a single undo step.

Parameters:: label (str) – The label shown in DAZ Studio’s Edit > Undo menu.
Returns:: A UndoGroup context manager.
Return type:: UndoGroup

Example:

with scene.undo("Move figure"):
    node.set_position(100, 0, 0)

frame()[source]

Return the current timeline frame number.

set_frame(frame)[source]

Jump to a specific timeline frame.

Parameters:: frame (int) – Zero-based frame number.

load(path)[source]

Load a scene file (merge mode — does not clear the existing scene).

Parameters:: path (str) – Absolute path to the .daz or .duf file on the server host.

save(path)[source]

Save the scene to a file.

Parameters:: path (str) – Absolute destination path on the server host.

save_copy(path)[source]

Save a copy of the scene to path without changing the scene’s current file or dirty state — equivalent to a “Save a Copy As…” operation.

For clean scenes the plugin performs a simple file copy (zero DAZ state change). For scenes with unsaved changes it serialises via Scene.saveScene() and immediately restores the original filename; as a side effect unsaved changes are also written to the original file (unavoidable without the doSave(saveOnly=true) API, which is compiled out of current DAZ Studio 4.x builds).

Parameters:

path (str) – Absolute destination path on the server host (e.g. "C:/backups/scene_v2.duf").

Returns:

{"ok": True, "path": str, "source": str, "method": str} where method is "copy" (file copy, no serialisation) or "serialize" / "serialize+restore" (required when the scene has unsaved changes).

Raises:

DazError – on server-side failure (non-2xx response).
AuthenticationError – on HTTP 401/403.
ConnectionError – if the server is unreachable.

Return type:

dict

filename()[source]

Return the file path of the currently loaded scene, or an empty string.

needs_save()[source]

Return True if the scene has unsaved changes.

play_range()[source]

Return the playback range as {"start": int, "end": int} (frames).

set_play_range(start, end)[source]

Set the playback range in frames.

Parameters:

start (int) – First frame of the play range.
end (int) – Last frame of the play range.

anim_range()[source]

Return the animation range as {"start": int, "end": int} (frames).

set_anim_range(start, end)[source]

Set the animation range in frames.

Parameters:

start (int) – First frame.
end (int) – Last frame.

is_playing()[source]

Return True if the scene is currently playing back.

loop_playback(on)[source]

Enable or disable looping playback.

Parameters:: on (bool) – True to enable looping, False to disable.

undo_last()[source]

Step back one level in DAZ Studio’s undo stack.

Equivalent to pressing Ctrl+Z / Edit > Undo in DAZ Studio. Has no effect if the undo stack is empty.

Note: this steps the global undo stack. To group a series of changes into a single undoable operation use undo() (the context manager).

redo_last()[source]

Step forward one level in DAZ Studio’s undo stack.

Equivalent to pressing Ctrl+Y / Edit > Redo in DAZ Studio. Has no effect if there is nothing to redo.

is_simulating()[source]

Return True if a dForce simulation is currently running.

clear_dforce_simulation()[source]

Discard all cached dForce simulation data for the active engine.

run_dforce_simulation(nodes=None, *, wait=True, timeout=300.0)[source]

Run a dForce simulation using the active simulation engine.

Parameters:

nodes (list[DazNode] | None) – Optional subset of nodes to simulate via DzSimulationEngine.customSimulate(). None (default) simulates the whole scene via DzSimulationMgr.simulate(), which follows the frame range configured in the Simulation Settings pane.
wait (bool) – If True (default), block until the simulation finishes, using the async execute-and-poll endpoint since dForce runs can take minutes. If False, submit the job and return immediately.
timeout (float) – Maximum seconds to wait when wait is True.

Returns:

None when wait is True (the simulation already finished by the time this call returns). When wait is False, the request_id of the submitted async job — poll it with get_request_status() / get_request_result().

Raises:

ScriptRuntimeError – If the simulation engine reports an error.

Return type:

str | None