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

create_camera(name=None)[source]

Create a new basic camera node and add it to the scene.

Parameters:: name (str | None) – Optional internal name for the new camera. When omitted, DAZ Studio assigns its default name (e.g. "Camera", de-duplicated as "Camera 2" etc.).
Returns:: A DazCamera proxy for the newly created camera.
Return type:: DazCamera

create_light(light_type, name=None)[source]

Create a new light node and add it to the scene.

Parameters:

light_type (str) – One of "spot", "point", or "distant".
name (str | None) – Optional internal name for the new light. When omitted, DAZ Studio assigns its default name.

Returns:

A DazLight proxy for the newly created light.

Raises:

ValueError – If light_type is not a recognised light type.

Return type:

DazLight

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, *, retry_attempts=3, retry_delay=0.15)[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().
retry_attempts (int) – Number of Scene.getSkeletonList() lookups to try before concluding the skeleton is really absent. Scene.getSkeletonList() has been observed to transiently omit a skeleton that is present under load from a burst of other main-thread script calls (see daz-script-server-xtkd) – a momentary miss is retried rather than immediately raised. Set to 1 to disable retrying.
retry_delay (float) – Base seconds to sleep between retries (each attempt after the first waits retry_delay * attempt_number).

Returns:

A DazSkeleton proxy.

Raises:

NodeNotFoundError – If no skeleton with that name exists after retry_attempts lookups.

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]

node_hierarchy(root=None, max_depth=None)[source]

Return the descendant tree rooted at a single node, in one HTTP call.

Unlike node_tree() (every root-level node in the scene), this starts at one named node – typically a figure – and includes a type (DazScript class name) on every entry and an optional recursion-depth limit, which matters for deep skeletons (Genesis figures have 100+ bones).

Parameters:

root (str | None) – Display label or internal name of the root node. Searched by label first, then internal name.
max_depth (int | None) – Maximum recursion depth. None or 0 means unlimited.

Returns:

{"node": label, "hierarchy": {...}, "total_descendants": int} where hierarchy is {"label", "name", "type", "children": [...]} (children omitted for leaf nodes).

Raises:

NodeNotFoundError – If root cannot be found.

Return type:

dict

overview()[source]

Return a lightweight, top-level snapshot of the scene in one HTTP call.

Root-level figures, all cameras, all lights, the open scene file, and the primary selection – enough to orient an agent without enumerating every node (use nodes() or node_tree() for that).

Returns:: {"scene_file", "selected_node", "figures", "cameras", "lights", "total_nodes"}. figures/cameras/lights are lists of {"name", "label", "type"} (type omitted for cameras). Follower figures (eyelashes, tear surfaces, etc. parented under another figure rather than the scene root) are excluded from figures.
Return type:: 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

export_fbx(path, *, selected_only=False, include_figures=True, include_props=False, include_lights=False, include_cameras=False, include_animations=False, embed_textures=True, options=None)[source]

Export the scene to an FBX file via DAZ Studio’s built-in FBX exporter.

This is a plain synchronous call, unlike export_usd_submit() – FBX export is a native DAZ Studio exporter (DzFbxExporter) rather than a custom C++ pipeline, so there’s no async job to poll.

Parameters:

path (str) – Absolute destination path on the DAZ Studio host (should end in .fbx).
selected_only (bool) – Export only the selected node(s).
include_figures (bool) – Include figures (default True).
include_props (bool) – Include prop nodes.
include_lights (bool) – Include scene lights.
include_cameras (bool) – Include cameras.
include_animations (bool) – Include the current animation take.
embed_textures (bool) – Embed texture maps into the FBX file (default True).
options (dict | None) – Additional raw DzFileIOSettings overrides (e.g. {"Format": "FBX 2014 -- Binary"}), applied on top of the exporter’s own defaults and the named args above. See DzFbxExporter.getDefaultOptions() for the full set of keys.

export_obj(path, *, selected_only=False, ignore_invisible=True, include_normals=False, collect_maps=False, options=None)[source]

Export the scene to an OBJ file via DAZ Studio’s built-in OBJ exporter.

This is a plain synchronous call – see export_fbx() for why this doesn’t follow the USD export module’s async job pattern.

Parameters:

path (str) – Absolute destination path on the DAZ Studio host (should end in .obj).
selected_only (bool) – Export only the selected node(s).
ignore_invisible (bool) – Skip nodes hidden in the viewport (default True, matches the exporter’s own default).
include_normals (bool) – Write vertex normals (WriteVN).
collect_maps (bool) – Copy referenced texture maps next to the .obj/.mtl instead of referencing their original paths.
options (dict | None) – Additional raw DzFileIOSettings overrides, applied on top of the exporter’s own defaults and the named args above. See DzObjExporter.getDefaultOptions() for the full set of keys.

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