Tree — base classes#

These types form the structural vocabulary of the OpenVCAD graph. Every design is a Node tree: the engine evaluates signed distance and attributes by walking from the root to the leaves and aggregating results upward.

Leaf marks terminals that hold geometry or field data directly (see Tree — leaf nodes). Most other nodes are composition operators; they wrap one or more child subtrees and are modeled as Unary, Binary, or NAry according to how many children they take (see Tree — composition nodes).

class pyvcad.Node#

Base class for all nodes in the tree. NOTE: the VCAD tree is NOT thread-safe. You must use a separate tree for each thread (see Node.clone()).

__init__(*args, **kwargs)#
attribute_list(self: pyvcad.pyvcad.Node) → list[str]#

Returns a list of the attributes in use by this node and its children.

bounding_box(self: pyvcad.pyvcad.Node) → tuple[pyvcad.pyvcad.Vec3, pyvcad.pyvcad.Vec3]#

Returns the bounding box of the node as a tuple of min and max points.

child_labels(self: pyvcad.pyvcad.Node) → list[str]#

Returns the role label of each child in the same order as child_nodes(), e.g. ‘keep’ and ‘subtract’ for a Difference.

Children without a role get an empty string.

child_nodes(self: pyvcad.pyvcad.Node) → list[pyvcad.pyvcad.Node]#

Returns the direct children of this node in authored order. Leaves return an empty list.

Safe to call before prepare().

Example

>>> import pyvcad as pv
>>> union = pv.Union(pv.Sphere(pv.Vec3(0, 0, 0), 5), pv.RectPrism(pv.Vec3(0, 0, 0), pv.Vec3(4, 4, 4)))
>>> [child.type_name() for child in union.child_nodes()]
clone(self: pyvcad.pyvcad.Node) → pyvcad.pyvcad.Node#

Clones the node and its subtree.

Returns:

The new node.

Return type:

Node

display_label(self: pyvcad.pyvcad.Node) → str#

Returns a short human-readable label built from the type and summary properties, e.g. ‘Sphere radius=5’.

distance_accuracy(self: pyvcad.pyvcad.Node) → pyvcad.pyvcad.DistanceAccuracy#

How faithfully this node’s value, including its whole subtree, matches the true signed distance.

exact: a true signed distance. bound: within the bandwidth, the value never exceeds lipschitz_bound() times the true distance, so a positive value v proves no material lies within v / lipschitz_bound(). approximate: no guarantee away from the surface. Only valid after prepare().

Returns:

The accuracy of the subtree rooted at this node.

Return type:

DistanceAccuracy

evaluate(self: pyvcad.pyvcad.Node, x: SupportsFloat | SupportsIndex, y: SupportsFloat | SupportsIndex, z: SupportsFloat | SupportsIndex) → float | None#

Evaluates the node at the given point. Returns the distance to the surface at the given point. May return None if point is out of bounds.

Parameters:
  • x (float) – The x-coordinate of the point to evaluate.

  • y (float) – The y-coordinate of the point to evaluate.

  • z (float) – The z-coordinate of the point to evaluate.

Returns:

The signed distance, or None outside the node’s domain.

Return type:

float | None

Raises:

RuntimeError – If prepare() has not been called.

family(self: pyvcad.pyvcad.Node) → str#

Returns the node family: ‘geometry’, ‘composition’, ‘transform’, ‘modifier’, ‘attribute_process’, or ‘mapping’.

get_attribute(self: pyvcad.pyvcad.Node, name: str) → Attribute#

Returns the attribute function for the given attribute name.

Parameters:

name (str) – The name of the attribute to get.

Returns:

The attribute set directly on this node under that name.

Return type:

Attribute

get_gradient_epsilon(self: pyvcad.pyvcad.Node) → float#

Gets the currently configured gradient epsilon.

gradient(*args, **kwargs)#

Overloaded function.

  1. gradient(self: pyvcad.pyvcad.Node, x: typing.SupportsFloat | typing.SupportsIndex, y: typing.SupportsFloat | typing.SupportsIndex, z: typing.SupportsFloat | typing.SupportsIndex) -> pyvcad.pyvcad.Vec3

Returns the gradient of the signed distance field at the given point.

Parameters:
  • x (float) – The x-coordinate of the point to evaluate.

  • y (float) – The y-coordinate of the point to evaluate.

  • z (float) – The z-coordinate of the point to evaluate.

Returns:

The central-difference gradient.

Return type:

Vec3

  1. gradient(self: pyvcad.pyvcad.Node, p: pyvcad.pyvcad.Vec3) -> pyvcad.pyvcad.Vec3

Returns the gradient of the signed distance field at the given point.

Parameters:

p (Vec3) – The point to evaluate.

Returns:

The central-difference gradient.

Return type:

Vec3

is_placement(self: pyvcad.pyvcad.Node) → bool#

Returns True if this node only repositions its child (Translate, Rotate, Scale, Transform, Mirror).

lipschitz_bound(self: pyvcad.pyvcad.Node) → float#

The Lipschitz bound L that goes with distance_accuracy(): 1 for exact, infinity for approximate. Only valid after prepare().

Returns:

L (at least 1), or infinity when nothing is promised.

Return type:

float

node_id(self: pyvcad.pyvcad.Node) → int#

Returns an integer that identifies the underlying node for as long as it is alive.

Two Python wrappers refer to the same node exactly when their node_id() values are equal, which is how tools detect a node shared by several parents.

own_attribute_list(self: pyvcad.pyvcad.Node) → list[str]#

Returns the attributes set directly on this node, excluding those of its children.

prepare(self: pyvcad.pyvcad.Node, voxel_size: pyvcad.pyvcad.Vec3, bandwidth: SupportsFloat | SupportsIndex) → None#

Performs any single-run operations that need to be done before the tree is evaluated.

Parameters:
  • voxel_size (Vec3) – The size of the voxels.

  • bandwidth (float) – The bandwidth of the tree we are sampling.

properties(self: pyvcad.pyvcad.Node) → list[pyvcad.pyvcad.NodeProperty]#

Returns the node’s authored parameters as a list of NodeProperty (name, value, summary).

Safe to call before prepare().

Example

>>> import pyvcad as pv
>>> [(p.name, p.value) for p in pv.Sphere(pv.Vec3(0, 0, 0), 5).properties()]
sample(self: pyvcad.pyvcad.Node, x: SupportsFloat | SupportsIndex, y: SupportsFloat | SupportsIndex, z: SupportsFloat | SupportsIndex) → tuple[float | None, AttributeSamples | None]#

Samples the signed distance and the attributes at the given point.

Parameters:
  • x (float) – The x-coordinate of the point to sample.

  • y (float) – The y-coordinate of the point to sample.

  • z (float) – The z-coordinate of the point to sample.

Returns:

The signed distance (None outside the node’s domain) and the attribute samples. The attribute samples are None where the distance is positive or missing (outside the part).

Return type:

tuple[float | None, AttributeSamples | None]

Raises:

RuntimeError – If prepare() has not been called.

set_attribute(self: pyvcad.pyvcad.Node, name: str, attribute: Attribute, coordinates: str = 'node') → None#

Sets an attribute function for the node.

Parameters:
  • name (str) – The name of the attribute.

  • attribute (Attribute) – The attribute function to set.

  • coordinates (str) – The position passed to the attribute: ‘node’ (default, the node’s own Cartesian coordinates), ‘map’, ‘logical’, ‘cell_index’, or ‘cell’. The last four need a CellMap sample context, so they only work under a mapped node or lattice.

Raises:

RuntimeError – If the node already has an attribute with this name, or if coordinates is not one of the values above.

set_gradient_epsilon(self: pyvcad.pyvcad.Node, eps: SupportsFloat | SupportsIndex) → None#

Sets the epsilon to use for central difference gradient calculation.

Parameters:

eps (float) – The gradient epsilon. Values at or below zero reset it to 1e-4.

snap(self: pyvcad.pyvcad.Node, point: pyvcad.pyvcad.Vec3) → pyvcad.pyvcad.Vec3#

Snaps a given point to the nearest point on the surface.

Parameters:

point (Vec3) – The point to snap.

Returns:

The snapped point on the surface.

Return type:

Vec3

to_diagram(self: pyvcad.pyvcad.Node) → str#

Build a Mermaid diagram string for the authored tree rooted at this node.

Safe to call before prepare().

Returns:

A self-contained Mermaid flowchart string.

Return type:

str

type_name(self: pyvcad.pyvcad.Node) → str#

Returns the node type name, e.g. ‘Sphere’ or ‘Translate’.

volume(*args, **kwargs)#

Overloaded function.

  1. volume(self: pyvcad.pyvcad.Node) -> float

Estimates the node volume by sampling the signed distance field over its bounding box.

The sample size is automatically computed from the bounding box as the longest dimension divided by 128. Returns cubic model units, e.g. mm^3 when the model is authored in millimeters. This counts inside voxels; pv.mass_properties() weights voxels cut by the surface, is far more accurate, and also gives surface area, mass and inertia.

  1. volume(self: pyvcad.pyvcad.Node, sample_size: typing.SupportsFloat | typing.SupportsIndex) -> float

Estimates the node volume by sampling the signed distance field over its bounding box.

Parameters:

sample_size (float) – Positive finite sample size to use in all dimensions.

Returns cubic model units, e.g. mm^3 when the model is authored in millimeters.

  1. volume(self: pyvcad.pyvcad.Node, voxel_size: pyvcad.pyvcad.Vec3) -> float

Estimates the node volume by sampling the signed distance field over its bounding box.

Parameters:

voxel_size (Vec3) – Positive finite per-axis voxel size.

Returns cubic model units, e.g. mm^3 when the model is authored in millimeters.

class pyvcad.Leaf#

A leaf node that cannot have any children.

__init__(*args, **kwargs)#
class pyvcad.Unary#

A node with a single child.

__init__(*args, **kwargs)#
child(self: pyvcad.pyvcad.Unary) → pyvcad.pyvcad.Node#

Returns the one and only child of this node.

set_child(self: pyvcad.pyvcad.Unary, child: pyvcad.pyvcad.Node) → None#

Sets the one and only child of this node.

Parameters:

child (Node) – The child node to be set.

class pyvcad.Binary#

A binary node with exactly two children. The children can be added via a constructor or via set_left() and set_right() methods. Children can be queried with left() and right().

__init__(*args, **kwargs)#
attribute_conflict_resolvers(self: pyvcad.pyvcad.Binary) → dict[str, AttributeConflictResolver]#

Returns the attribute conflict resolvers.

Returns:

The resolvers keyed by attribute name.

Return type:

dict[str, AttributeConflictResolver]

left(self: pyvcad.pyvcad.Binary) → pyvcad.pyvcad.Node#

Returns the left child of this node.

right(self: pyvcad.pyvcad.Binary) → pyvcad.pyvcad.Node#

Returns the right child of this node.

set_attribute_conflict_resolver(self: pyvcad.pyvcad.Binary, name: str, resolver: AttributeConflictResolver) → None#

Sets the attribute conflict resolver for the given attribute name, replacing any earlier one.

Parameters:
  • name (str) – The attribute name.

  • resolver (AttributeConflictResolver) – The resolver used where the children disagree on that attribute.

set_left(self: pyvcad.pyvcad.Binary, left: pyvcad.pyvcad.Node) → None#

Sets the left child of this node.

Parameters:

left (Node) – The left child to set for this node.

set_right(self: pyvcad.pyvcad.Binary, right: pyvcad.pyvcad.Node) → None#

Sets the right child of this node.

Parameters:

right (Node) – The right child to set for this node.

class pyvcad.NAry#

A node with an arbitrary number of children.

__init__(*args, **kwargs)#
add_child(self: pyvcad.pyvcad.NAry, child: pyvcad.pyvcad.Node) → bool#

Adds a child to the node.

Parameters:

child (Node) – The child to add to the node.

Returns:

True if the child was added. BBoxUnion and BBoxIntersection return False for None.

Return type:

bool

attribute_conflict_resolvers(self: pyvcad.pyvcad.NAry) → dict[str, AttributeConflictResolver]#

Returns the attribute conflict resolvers.

Returns:

The resolvers keyed by attribute name.

Return type:

dict[str, AttributeConflictResolver]

child(self: pyvcad.pyvcad.NAry, index: SupportsInt | SupportsIndex) → pyvcad.pyvcad.Node#

Returns the child at the given index.

Parameters:

index (int) – The zero-based index of the child to return.

Returns:

The child at the given index.

Return type:

Node

Raises:

IndexError – If index is out of range.

children(self: pyvcad.pyvcad.NAry) → list[pyvcad.pyvcad.Node]#

Returns the list of children for this node.

num_children(self: pyvcad.pyvcad.NAry) → int#

Returns the number of children this node has.

set_attribute_conflict_resolver(self: pyvcad.pyvcad.NAry, name: str, resolver: AttributeConflictResolver) → None#

Sets the attribute conflict resolver for the given attribute name, replacing any earlier one.

Parameters:
  • name (str) – The attribute name.

  • resolver (AttributeConflictResolver) – The resolver used where children disagree on that attribute.

class pyvcad.NodeProperty#

One read-only authored parameter of a node, formatted for display.

property name#

The parameter name.

property summary#

True if the parameter is part of the node’s short display label.

property value#

The parameter value formatted as text.

Inspecting a tree#

SubtreeView isolates one node of a design so it can be sampled or rendered on its own, optionally with its placement and inherited attributes re-applied. TreeDiagram turns a tree into a Mermaid flowchart.

class pyvcad.SubtreeView#

A read-only view of one node of a design, with optional ancestor context re-applied.

With no context the view is exactly the target node’s own result in its own coordinate frame, so every operation above it is undone. apply_placement re-applies Translate/Rotate/Scale/Transform/Mirror ancestors; apply_attributes re-applies ancestor attributes and AttributeModifier/Blend/Convolve ancestors. Booleans and shape modifiers above the target are never applied. The view shares the design’s nodes, so do not prepare a view and its design at the same time from different threads.

applies_attributes(self: pyvcad.pyvcad.SubtreeView) → bool#

Returns True if ancestor attributes are re-applied.

applies_placement(self: pyvcad.pyvcad.SubtreeView) → bool#

Returns True if ancestor placement is re-applied.

static build(path: collections.abc.Sequence[pyvcad.pyvcad.Node], apply_placement: bool = False, apply_attributes: bool = False) → pyvcad.pyvcad.SubtreeView#

Builds a view of the last node of a root-to-target path.

Parameters:
  • path (list[Node]) – The nodes from the root (first) to the target (last). Each must be a child of the previous one.

  • apply_placement (bool) – Re-apply placement ancestors so the target sits where it lands in the full design.

  • apply_attributes (bool) – Re-apply ancestor attributes and attribute-process ancestors.

Example

>>> import pyvcad as pv
>>> sphere = pv.Sphere(pv.Vec3(0, 0, 0), 5)
>>> root = pv.Translate(10, 0, 0, sphere)
>>> view = pv.SubtreeView.build([root, sphere], apply_placement=True, apply_attributes=False)
static resolve_path(root: pyvcad.pyvcad.Node, child_indices: collections.abc.Sequence[SupportsInt | SupportsIndex]) → list[pyvcad.pyvcad.Node]#

Resolves a path of child indices from a root node.

Parameters:
  • root (Node) – The root node.

  • child_indices (list[int]) – Index into child_nodes() at each level, starting below the root.

Returns:

The nodes from the root to the resolved node, inclusive.

Return type:

list[Node]

Example

>>> path = pv.SubtreeView.resolve_path(root, [0])
target(self: pyvcad.pyvcad.SubtreeView) → pyvcad.pyvcad.Node#

Returns the node being viewed.

class pyvcad.TreeDiagram#

Builds Mermaid diagrams for authored OpenVCAD trees and DAGs.

__init__(self: pyvcad.pyvcad.TreeDiagram, root: pyvcad.pyvcad.Node) → None#

Construct a TreeDiagram from a root node.

Parameters:

root (Node) – The root node of the authored OpenVCAD tree.

static master_legend() → str#

Return the hardcoded master legend Mermaid source for the full OpenVCAD tree-diagram language.

static save_master_legend(path: str) → None#

Save the hardcoded master legend Mermaid source to a file on disk.

Parameters:

path (str) – Destination path for the Mermaid .mmd source file.

save_mermaid(self: pyvcad.pyvcad.TreeDiagram, path: str) → None#

Save the Mermaid source to a file on disk.

Parameters:

path (str) – Destination path for the Mermaid .mmd source file.

to_mermaid(self: pyvcad.pyvcad.TreeDiagram) → str#

Return the final Mermaid diagram as a self-contained flowchart string.