Nodes

NodeIdentifier

class dazpy.NodeIdentifier(value, kind='name')

Bases: object

Identifies a scene node by name or label.

value

The name or label string used to look up the node.

Type:

str

kind

Either "name" (uses Scene.findNode()) or "label" (uses Scene.findNodeByLabel()).

Type:

str

DazNode

class dazpy.DazNode(client, identifier)

Bases: DazElement

Proxy for a DzNode in the active DAZ Studio scene.

Provides access to transforms, hierarchy, visibility, materials, modifiers, and geometry. Instances are typically obtained from DazScene rather than constructed directly.

All properties that read from the server may return None if the node no longer exists in the scene.

Parameters:

• client (DazClient) – The DazClient for remote calls.

• identifier (NodeIdentifier) – Identifies the underlying DzNode.

property label: str | None

User-visible display label shown in the Scene panel (read/write).

property name: str | None

Internal node name used to look up the node (read-only).

property position: dict | None

World-space position as {"x": float, "y": float, "z": float} (read-only).

Use set_position() to change.

set_position(x, y, z)

Set the world-space position of this node.

Parameters:

• x (float) – X coordinate in DAZ Studio units (centimetres by default).

• y (float) – Y coordinate.

• z (float) – Z coordinate.

property rotation: dict | None

World-space rotation as {"x", "y", "z", "w"} quaternion (read-only).

Use set_rotation() to change (accepts Euler angles in degrees).

property general_scale: float | None

Uniform scale factor (read-only).

property scale: dict | None

Per-axis and uniform scale as {"x", "y", "z", "general"} (read-only).

Use set_scale() to change the per-axis values.

set_scale(x, y, z)

Set per-axis local scale.

Does not affect the general/uniform scale dial (general_scale) — DAZ Studio tracks per-axis and uniform scale as separate controls.

Parameters:

• x (float) – X-axis scale factor (1.0 = unscaled).

• y (float) – Y-axis scale factor.

• z (float) – Z-axis scale factor.

set_transform(position=None, rotation=None, scale=None)

Set any combination of local position, rotation, and scale in one call.

Every argument is optional. Omitted components are left untouched. Equivalent to calling set_local_position(), set_local_rotation(), and/or set_scale() individually, but round-trips only once.

Parameters:

• position (tuple[float, float, float] | None) – (x, y, z) local-space position, or None to leave unchanged.

• rotation (tuple[float, float, float] | None) – (x, y, z) Euler rotation in degrees, or None to leave unchanged.

• scale (tuple[float, float, float] | None) – (x, y, z) per-axis scale, or None to leave unchanged.

property visible: bool | None

General visibility flag (read/write).

Affects both viewport and render visibility unless overridden by the per-channel visibility setters.

property parent: DazNode | None

Parent node in the scene hierarchy, or None for root nodes.

property children: list[DazNode]

Direct child nodes.

delete()

Remove this node from the scene entirely.

Returns:

True if the node was found and removed, False otherwise.

Return type:

bool

reparent(new_parent, *, preserve_world_transform=True)

Move this node to a new position in the scene hierarchy.

Detaches the node from its current parent (if any) and attaches it as a child of new_parent, following the removeNodeChild / addNodeChild DazScript pattern.

Parameters:

• new_parent (DazNode) – The node to reparent under.

• preserve_world_transform (bool) – When True (default), the node keeps its current world-space position/rotation/scale, adjusting its local transform to compensate. When False, the node’s local transform values are left unchanged, which may move it in world space.

Raises:

ScriptRuntimeError – If the reparent operation fails (e.g. new_parent cannot be found, or would create a cycle).

modifiers()

Return all modifiers (morphs, constraints, etc.) on this node.

Returns:

A list of DazMorph and DazModifier instances.

Return type:

list[‘DazModifier’]

find_modifier(name)

Find a modifier by internal name.

Parameters:

name (str) – The getName() string of the modifier.

Returns:

A DazMorph or DazModifier, or None if not found.

Return type:

DazModifier | None

materials()

Return all surface materials on this node’s current shape.

find_material(name)

Find a surface material by name.

Parameters:

name (str) – The material’s getName() string.

Returns:

A DazMaterial proxy, or None if not found.

Return type:

DazMaterial | None

find_modifier_by_label(label)

Find a modifier by its user-visible label (the name shown in the DAZ UI).

DAZ Studio morphs have both an internal name (e.g. "PHMSmileFull") and a display label (e.g. "Smile Full Face"). find_modifier() matches the internal name; this method matches the label instead.

Parameters:

label (str) – The getLabel() string shown in the Parameters pane.

Returns:

A DazMorph or DazModifier, or None if no modifier with that label exists.

Return type:

DazModifier | None

find_property(name)

Find a node-level property by its internal name.

This searches properties directly on the node (via DzNode::findProperty), which covers pose controls, FACS dials, and other parameter channels that are not geometry modifiers and therefore invisible to find_modifier().

Parameters:

name (str) – The getName() / ID string of the property (e.g. "facs_ctrl_SmileFullFace").

Returns:

A DazProperty proxy, or None if not found.

Return type:

DazProperty | None

find_property_by_label(label)

Find a node-level property by its user-visible label.

Equivalent to find_property() but matches on getLabel() instead of getName(). Use this when you know the label shown in the DAZ Studio Parameters pane (e.g. "Smile Full Face") but not the internal ID.

Parameters:

label (str) – The getLabel() string shown in the Parameters pane.

Returns:

A DazProperty proxy, or None if not found.

Return type:

DazProperty | None

morphs()

Return only the morph modifiers on this node (convenience filter).

dforce_modifiers()

Return only the dForce simulation modifiers on this node (convenience filter).

set_rotation(x, y, z)

Set the world-space rotation using Euler angles in degrees.

Parameters:

• x (float) – Rotation around the X axis in degrees.

• y (float) – Rotation around the Y axis in degrees.

• z (float) – Rotation around the Z axis in degrees.

set_position_at_frame(frame, x, y, z)

Write a real keyframe for world-space position at timeline frame.

Unlike set_position(), this writes an actual animation curve key (via DzNode.setWSPos(tm, pos)) rather than the “current” value — the position at frames between keys is DAZ Studio’s own interpolation, not something the caller has to bake per-frame.

frame is converted to DAZ Studio time ticks via the scene’s current Scene.getTimeStep() (ticks per frame), not a hardcoded constant — that value depends on the scene’s frame rate.

Parameters:

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

• x (float) – X coordinate in DAZ Studio units (centimetres by default).

• y (float) – Y coordinate.

• z (float) – Z coordinate.

set_rotation_at_frame(frame, x, y, z)

Write a real keyframe for world-space Euler rotation at timeline frame.

Companion to set_position_at_frame() — see its docstring for the tick-conversion note. Writes to the same per-axis rotation controls as set_rotation(), but as a keyed value at frame rather than the “current” value.

Parameters:

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

• x (float) – Rotation around the X axis in degrees.

• y (float) – Rotation around the Y axis in degrees.

• z (float) – Rotation around the Z axis in degrees.

clear_position_keys()

Remove all keyframes from this node’s X/Y/Z position controls.

Newly-created nodes can already carry a default key (e.g. a preset camera position at its creation time); call this before writing a fresh animated curve with set_position_at_frame(), otherwise the leftover default key distorts interpolation/extrapolation around the new keys.

clear_rotation_keys()

Remove all keyframes from this node’s X/Y/Z rotation controls.

See clear_position_keys() — same rationale, for orientation.

property local_position: dict | None

Local-space position as {"x", "y", "z"} (read-only).

set_local_position(x, y, z)

Set the local-space position of this node.

Parameters:

• x (float) – X coordinate relative to the parent.

• y (float) – Y coordinate.

• z (float) – Z coordinate.

property local_euler: tuple[float, float, float] | None

Local-space rotation as an (x, y, z) tuple of Euler angles in degrees.

Reads the rotation controls written by set_local_rotation(), so the two are exact inverses.

Returns:

(x, y, z) in degrees, or None if the node cannot be found.

property local_rotation: dict | None

Local-space rotation as {"x", "y", "z", "w"} quaternion (read-only).

set_local_rotation(x, y, z)

Set the local-space rotation using Euler angles in degrees.

Parameters:

• x (float) – Rotation around the local X axis in degrees.

• y (float) – Rotation around the local Y axis in degrees.

• z (float) – Rotation around the local Z axis in degrees.

is_selected()

Return True if this node is currently selected.

select(on=True)

Select or deselect this node.

Parameters:

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

is_in_scene()

Return True if this node is still part of the active scene.

is_root()

Return True if this node has no parent (top-level node).

is_visible_in_render()

Return True if this node is visible in render output.

set_visible_in_render(on)

Set render visibility.

Parameters:

on (bool) – True to show in render, False to hide.

is_visible_in_viewport()

Return True if this node is visible in the 3D viewport.

set_visible_in_viewport(on)

Set viewport visibility.

Parameters:

on (bool) – True to show, False to hide.

bounding_box()

Return the world-space axis-aligned bounding box.

Returns:

A dict {"min": {"x", "y", "z"}, "max": {"x", "y", "z"}} or None if the node has no geometry.

Return type:

dict | None

fit_to(figure)

Fit this clothing/hair/prop node to a base figure.

For figure-based conforming clothing and hair (nodes exposing setFollowTarget/followSkeleton), this sets the follow relationship so the item deforms with the figure’s pose. For plain props/accessories, it falls back to parenting the item under the figure, preserving its current world-space transform.

Parameters:

figure (DazNode) – The target base figure node. Must already be loaded into the scene.

Returns:

"setFollowTarget", "followSkeleton", or "addNodeChild" (parenting fallback).

Return type:

The DazScript API used

Raises:

NodeNotFoundError – If this node or figure cannot be found.

unfit()

Remove this node’s fitting relationship with its figure.

Clears any follow-target relationship (conforming clothing/hair) and detaches this node from its parent skeleton (props), leaving it as a free-standing scene node at its current world position.

Returns:

• "previous_figure" — internal name of the figure this node was fitted to, or None if it had no fitting relationship.

• "actions" — list of operations performed (e.g. ["cleared follow target", "detached from parent"]), or [] if nothing was fitted.

Return type:

A dict with keys

fitted_items()

Return all clothing, hair, and prop nodes fitted to this figure.

A node counts as fitted if it either follows this node (figure-based conforming clothing/hair) or is directly parented to it (props and accessories).

Returns:

A list of DazNode proxies for each fitted item.

Return type:

list[DazNode]

property geometry_vertex_count: int | None

Total vertex count of this node’s current geometry, or None.

DazElement

class dazpy.DazElement(client, locator)

Bases: object

Generic proxy for any DzElement subclass. Base class for all typed proxies.

You normally do not instantiate DazElement directly. Use the typed subclasses (DazNode, DazMaterial, etc.) returned by DazScene and related helpers instead.

Parameters:

• client (DazClient) – The DazClient used for all remote calls.

• locator (str) – A JavaScript expression that evaluates to the underlying DzElement instance inside DAZ Studio.

get_property(label)

Return the current value of a property looked up by its display label.

Parameters:

label (str) – The getLabel() string of the DzProperty.

Returns:

The property value, or None if the property does not exist.

Return type:

object

set_property(label, value)

Set a property value by display label.

Parameters:

• label (str) – The getLabel() string of the DzProperty.

• value (object) – The new value. Must be JSON-serialisable.

set_properties(values)

Set multiple property values by display label in one call.

Parameters:

values (dict[str, object]) – {label: value}. Each value must be JSON-serialisable.

Returns:

{label: True} for labels that resolved to a real property and were written, {label: False} for labels that did not resolve.

Return type:

dict[str, bool]

list_properties()

Return metadata for every property on this element.

Returns:

A list of dicts, each with keys "label", "name", and "type" (the DazScript class name of the property).

Return type:

list[dict]

numeric_properties()

Return every numeric property on this element as {label: value}.

Unlike list_properties(), this fetches labels and current values for all numeric (float/int/bool) properties in a single HTTP round-trip — use it instead of calling get_property() in a loop over list_properties() results.

Returns:

A dict mapping each numeric property’s display label to its current value.

Return type:

dict[str, object]

property class_name: str | None

The DazScript class name of this element (e.g. "DzFigure", "DzSpotLight").

snapshot(fields)

Read and cache a set of property values in a single call.

Parameters:

fields (list[str]) – Property labels to read.

Returns:

A dict mapping each label to its current value. Missing owner or missing property both resolve to None for the affected label(s).

Return type:

dict

refresh()

Clear the local property cache so the next read fetches live data.