Tree — base classes

Hierarchy and container nodes used by all geometry/material graphs. Leaf nodes live on Tree — leaf 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)
bounding_box(self: pyvcad.pyvcad.Node) → tuple[pyvcad.pyvcad.Vec3, pyvcad.pyvcad.Vec3]

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

Example

>>> from libvcad import pyvcad as pv
>>> sphere = pv.Sphere(pv.Vec3(0,0,0), 2, 2)
>>> min, max = sphere.bounding_box() # Will return (Vec3(-2, -2, -2), Vec3(2, 2, 2))
clone(self: pyvcad.pyvcad.Node) → pyvcad.pyvcad.Node

Clones the node and returns a pointer to the new node.

Example

>>> from libvcad import pyvcad as pv
>>> sphere = pv.Sphere()
>>> cloned_sphere = sphere.clone()
distribution(self: pyvcad.pyvcad.Node, x: SupportsFloat, y: SupportsFloat, z: SupportsFloat) → dict[int, float]

Returns the material distribution at the given point. Returns a list of pairs, each containing the material ID and the probability distribution of that material.

Parameters:

  • x (double) – The x-coordinate of the point to evaluate.

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

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

Example

>>> from libvcad import pyvcad as pv
>>> sphere = pv.Sphere(pv.Vec3(0,0,0), 2, 2)
>>> distribution = sphere.distribution(0, 0, 0) # Since there is a single material, will return [2, 1.0], meaning 100% material 2
distribution_gradient(self: pyvcad.pyvcad.Node, x: SupportsFloat, y: SupportsFloat, z: SupportsFloat, delta: SupportsFloat = 1) → dict[int, pyvcad.pyvcad.Vec3]

Returns the material distribution gradient at the given point using the central difference method. Returns a list of pairs, each containing the material ID and the gradient of the probability distribution of that material.

Parameters:

  • x (double) – The x-coordinate of the point to evaluate.

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

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

  • delta (double) – The distance to use for the central difference method.

Example

>>> from libvcad import pyvcad as pv
>>> sphere = pv.Sphere(pv.Vec3(0,0,0), 2, 2)
>>> gradient = sphere.distribution_gradient(0, 0, 0, 1) # There is not a material gradient, so this returns 0
evaluate(self: pyvcad.pyvcad.Node, x: SupportsFloat, y: SupportsFloat, z: SupportsFloat) → float

Evaluates the node at the given point. Returns the distance to the surface at the given point.

Parameters:

  • x (double) – The x-coordinate of the point to evaluate.

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

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

Example

>>> from libvcad import pyvcad as pv
>>> sphere = pv.Sphere(pv.Vec3(0,0,0), 2, 2)
>>> distance = sphere.evaluate(0, 0, 0) # Signed distance from center is -2
gradient(*args, **kwargs)

Overloaded function.

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

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

Parameters:

  • x (double) – The x-coordinate of the point to evaluate.

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

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

Returns:

The gradient at the given point.

Return type:

Vec3

Example

>>> from libvcad import pyvcad as pv
>>> sphere = pv.Sphere(pv.Vec3(0,0,0), 2, 2)
>>> g = sphere.gradient(2, 0, 0) # On the surface, should be unit vector (1,0,0)

  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 gradient at the given point.

Return type:

Vec3

Example

>>> from libvcad import pyvcad as pv
>>> sphere = pv.Sphere(pv.Vec3(0,0,0), 2, 2)
>>> g = sphere.gradient(pv.Vec3(2, 0, 0)) # On the surface, should be unit vector (1,0,0)
heterogeneity(self: pyvcad.pyvcad.Node, x: SupportsFloat, y: SupportsFloat, z: SupportsFloat) → float

Returns a number on the range [0, 1] that represents the heterogeneity of the material distribution at the given point. A value of 0 means that the material distribution is homogeneous (composed completely of a single channel), while a value of 1 means that the material distribution is heterogeneous (even distribution across all channels).

Parameters:

  • x (double) – The x-coordinate of the point to evaluate.

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

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

Example

>>> from libvcad import pyvcad as pv
>>> sphere = pv.Sphere(pv.Vec3(0,0,0), 2, 2)
>>> heterogeneity = sphere.heterogeneity(0, 0, 0) # Will return 0 because there is only a single material
material_list(self: pyvcad.pyvcad.Node) → list[int]

Returns a list of all the materials used by the node and its children.

Example

>>> from libvcad import pyvcad as pv
>>> sphere = pv.Sphere(pv.Vec3(0,0,0), 2, 2)
>>> materials = sphere.material_list() # Will return [2] as the only material
prepare(self: pyvcad.pyvcad.Node, voxel_size: pyvcad.pyvcad.Vec3, interior_bandwidth: SupportsFloat, exterior_bandwidth: SupportsFloat) → 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.

  • interior_bandwidth (double) – The interior bandwidth.

  • exterior_bandwidth (double) – The exterior bandwidth.

Example

>>> from libvcad import pyvcad as pv
>>> sphere = pv.Sphere(pv.Vec3(0,0,0), 2, 2)
>>> sphere.prepare(pv.vec3(1, 1, 1), 0.1, 0.1)
sample_points_color(self: pyvcad.pyvcad.Node, points: collections.abc.Sequence[pyvcad.pyvcad.Vec3], material_defs: MaterialDefs, voxel_size: pyvcad.pyvcad.Vec3, progress: collections.abc.Callable[[SupportsInt], None] = None) → list[pyvcad.pyvcad.Vec3]

Samples the colors at the given points and returns a list of colors.

Parameters:

  • points (list of Vec3) – The points to sample.

  • material_defs (MaterialDefs) – Material definitions used for color mapping.

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

Returns:

The colors at the given points.

Return type:

list of Vec3

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

Example

>>> from libvcad import pyvcad as pv
>>> sphere = pv.Sphere(pv.Vec3(0,0,0), 2, 2)
>>> snapped_point = sphere.snap(pv.Vec3(0,0,0))
toRGBAArray(self: pyvcad.pyvcad.Node, voxel_size: pyvcad.pyvcad.Vec3, material_defs: MaterialDefs, blend: bool = True, progress: object = None) → tuple

Generates a 3D RGBA array representing the voxelized node.

Parameters:

  • voxel_size (vec3) – The size of the voxels.

  • material_defs (MaterialDefs) – The material definitions used for color mapping.

  • progress (callable, optional) – A callback function for progress tracking. It should accept a single integer argument representing the percentage of completion (0-100).

Returns:

A tuple containing (nx, ny, nz, numpy_array) where nx, ny, nz are the dimensions of the array and numpy_array is a NumPy array of shape (nx * ny * nz * 4) with dtype uint8 representing the RGBA values.

Return type:

tuple

toSignedDistanceArray(self: pyvcad.pyvcad.Node, voxel_size: pyvcad.pyvcad.Vec3, progress: object = None) → tuple

Generates a 3D array representing the signed distance field of the voxelized node.

Parameters:

  • voxel_size (vec3) – The size of the voxels.

  • progress (callable, optional) – A callback function for progress tracking. It should accept a single integer argument representing the percentage of completion (0-100).

Returns:

A tuple containing (nx, ny, nz, numpy_array) where nx, ny, nz are the dimensions of the array and numpy_array is a NumPy array of shape (nx * ny * nz) with dtype float32 representing the signed distance values.

Return type:

tuple

type(self: pyvcad.pyvcad.Node) → str

Returns the type of the node as a string.

Example

>>> from libvcad import pyvcad as pv
>>> sphere = pv.Sphere()
>>> node_type = sphere.type() # Should return 'leaf'
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)
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_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

Tries to add a child to the node. If the node is full, it returns false.

Parameters:

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

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

Returns the child at the given index.

Parameters:

index (uint8_t) – The index of the child to return.

Returns:

The child at the given index.

Return type:

Node

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.