Tree — attribute nodes#

Attribute nodes are Unary scene nodes: each wraps a child subtree and changes how continuous attributes are produced or post-processed for that geometry. They are not the same thing as attaching an Attribute with Node.set_attribute()—that API defines field values on a node (see Attributes). Attribute nodes instead implement attribute-side operators in the tree: converters, lookup tables, or spatial filters that sit between evaluation and the rest of the pipeline.

AttributeModifier applies an attribute converter (for example, mapping one named field into another, such as HU to RGBA via a lookup table). Convolve and Blend spatially filter attribute samples without altering the signed-distance geometry of the child.

Unary attribute nodes#

class pyvcad.AttributeModifier#

An attribute modifier node that applies a converter to its child’s attributes.

Note: Setting or getting attributes directly on this node via set_attribute or get_attribute is not supported and will raise an error.

__init__(self: pyvcad.pyvcad.AttributeModifier, converter: AttributeConverterBase, child: pyvcad.pyvcad.Node) → None#

Constructor. Creates an AttributeModifier with a converter and a child node.

Parameters:
converter(self: pyvcad.pyvcad.AttributeModifier) → AttributeConverterBase#

Returns the converter applied to the child’s attribute samples.

class pyvcad.Convolve#

A Unary node that applies a convolution kernel to the continuous attributes of its child node.

Convolve is useful for blending, blurring, or sharpening scalar fields, colors, or material distributions without affecting the raw signed distance field geometry. It is the generic, flexible sibling of the Blend node; both share the same precomputed child-attribute voxel grid, but Convolve performs a per-sample weighted sum over arbitrary kernel weights while Blend specializes in a fast separable-blur fast path that moves all per-sample cost into prepare(). Use Blend for the common box-blend case; use Convolve when you need custom kernel weights or a non-blur operation.

During prepare() the child’s targeted attributes are parallel-sampled onto a dense voxel grid. At sample() time each kernel tap becomes a cheap flat-memory trilinear grid lookup instead of a full child-tree traversal, which makes the node orders of magnitude faster than a naive implementation. Tap (i, j, k) sits at (i * physical_radius.x / rx, …) from the query point, and the result is the weighted sum divided by the weights of the taps that landed inside the part.

__init__(self: pyvcad.pyvcad.Convolve, child: pyvcad.pyvcad.Node, attributes: collections.abc.Sequence[str], kernel: pyvcad.pyvcad.ConvolveKernel, physical_radius: collections.abc.Sequence[SupportsFloat | SupportsIndex], override_voxel_size: collections.abc.Sequence[SupportsFloat | SupportsIndex] | None = None) → None#

Constructor. Creates a Convolve over a child.

Parameters:
  • child (Node) – The node to process.

  • attributes (list[str]) – Names of the attributes to target. Pass an empty list to target all.

  • kernel (ConvolveKernel) – The kernel to apply.

  • physical_radius (list[float]) – [rx, ry, rz] physical bounds (in mm) that the kernel spans. Missing components are 0.

  • override_voxel_size (list[float], optional) – Optional [x, y, z] voxel size (mm) for the internal precomputed grid. Sparser than the tree sampler’s voxel_size saves memory; trilinear interpolation preserves smoothness at sample time. Defaults to the tree sampler’s voxel_size.

Raises:

RuntimeError – If child or kernel is None, or a physical_radius component is negative.

Example

>>> import pyvcad as pv
>>> my_shape = pv.Sphere(pv.Vec3(0, 0, 0), 10)
>>> my_shape.set_attribute('temperature', pv.FloatAttribute('20 + x'))
>>> kernel = pv.BoxKernel(2)
>>> blur_node = pv.Convolve(my_shape, ['temperature'], kernel, [5.0, 5.0, 5.0])
>>> # Coarser precomputed grid to save memory on a very large scene:
>>> blur_node = pv.Convolve(my_shape, ['temperature'], kernel, [5.0, 5.0, 5.0], override_voxel_size=[1.0, 1.0, 1.0])
kernel(self: pyvcad.pyvcad.Convolve) → pyvcad.pyvcad.ConvolveKernel#

Returns the convolution kernel.

override_voxel_size(self: pyvcad.pyvcad.Convolve) → pyvcad.pyvcad.Vec3 | None#

Returns the voxel size override, or None.

physical_radius(self: pyvcad.pyvcad.Convolve) → pyvcad.pyvcad.Vec3#

Returns the kernel radius in model units along each axis.

target_attributes(self: pyvcad.pyvcad.Convolve) → list[str]#

Returns the names of the attributes this node convolves.

class pyvcad.Blend#

A Unary node that locally blends the targeted attributes of its child within a user-defined physical radius.

Blend precomputes the child’s attributes onto a voxel grid during prepare() and applies a fast masked separable box blur in place. Each sample() call then performs a single child sample plus one trilinear lookup. Convolve samples the child onto the same kind of grid but sums one trilinear lookup per kernel tap at sample time, so Blend is faster for plain attribute smoothing and Convolve is the choice for custom kernel weights.

Blend is a mathematical no-op wherever the targeted attributes are already locally constant, so it is safe to apply across an entire assembly and only see change near attribute boundaries.

__init__(self: pyvcad.pyvcad.Blend, child: pyvcad.pyvcad.Node, attributes: collections.abc.Sequence[str], physical_radius: collections.abc.Sequence[SupportsFloat | SupportsIndex], num_passes: SupportsInt | SupportsIndex = 1, override_voxel_size: collections.abc.Sequence[SupportsFloat | SupportsIndex] | None = None) → None#

Constructor. Creates a Blend over a child.

Parameters:
  • child (Node) – The child node whose attributes will be blended.

  • attributes (list[str]) – Names of the attributes to blend. Pass an empty list to target all.

  • physical_radius (list[float]) – [rx, ry, rz] blend radius in mm along each axis. Defines the transition width across attribute boundaries. Missing components are 0.

  • num_passes (int, optional) – Number of successive box-blur passes. 1 = box (linear ramp), 2 = tent, 3+ approximates Gaussian. Values below 1 are raised to 1. Defaults to 1.

  • override_voxel_size (list[float], optional) – Optional [x, y, z] voxel size (mm) for the internal blend grid. Sparser than the tree sampler’s voxel_size saves memory; trilinear interpolation preserves smoothness at sample time. Defaults to the tree sampler’s voxel_size.

Raises:

RuntimeError – If child is None or a physical_radius component is negative.

Example

>>> import pyvcad as pv
>>> my_shape = pv.Sphere(pv.Vec3(0, 0, 0), 10)
>>> my_shape.set_attribute(pv.DefaultAttributes.MODULUS, pv.FloatAttribute('1000 + 100*x'))
>>> blended = pv.Blend(my_shape, [pv.DefaultAttributes.MODULUS], [3.0, 3.0, 3.0])
>>> # Softer ramp + coarser grid to save memory on a very large scene:
>>> blended = pv.Blend(my_shape, [pv.DefaultAttributes.MODULUS], [3.0, 3.0, 3.0], num_passes=3, override_voxel_size=[1.0, 1.0, 1.0])
num_passes(self: pyvcad.pyvcad.Blend) → int#

Returns the number of blur passes.

override_voxel_size(self: pyvcad.pyvcad.Blend) → pyvcad.pyvcad.Vec3 | None#

Returns the voxel size override, or None.

physical_radius(self: pyvcad.pyvcad.Blend) → pyvcad.pyvcad.Vec3#

Returns the blend radius in model units along each axis.

target_attributes(self: pyvcad.pyvcad.Blend) → list[str]#

Returns the names of the attributes this node blends.

Convolution kernels#

Kernels describe the spatial stencil Convolve uses (uniform box averaging or explicit per-voxel weights).

class pyvcad.ConvolveKernel#

Base class for the convolution kernels used by Convolve. A kernel holds one weight per integer tap offset (i, j, k) with abs(i) <= rx, abs(j) <= ry and abs(k) <= rz. Convolve normalizes by the sum of the weights that land inside the part, so the weights need not sum to 1. Use BoxKernel or CustomKernel.

__init__(*args, **kwargs)#
get_radius_x(self: pyvcad.pyvcad.ConvolveKernel) → int#

Gets the X radius of the kernel.

get_radius_y(self: pyvcad.pyvcad.ConvolveKernel) → int#

Gets the Y radius of the kernel.

get_radius_z(self: pyvcad.pyvcad.ConvolveKernel) → int#

Gets the Z radius of the kernel.

class pyvcad.BoxKernel#

A Box Kernel acts as a simple uniform average over a local radius volume: every tap has weight 1.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.BoxKernel, radius: typing.SupportsInt | typing.SupportsIndex) -> None

Constructor. Creates a box kernel with the same radius on all three axes.

Parameters:

radius (int) – Uniform radius in taps. A radius of 1 samples a 3x3x3 grid.

Example

>>> import pyvcad as pv
>>> kernel = pv.BoxKernel(1)
  1. __init__(self: pyvcad.pyvcad.BoxKernel, rx: typing.SupportsInt | typing.SupportsIndex, ry: typing.SupportsInt | typing.SupportsIndex, rz: typing.SupportsInt | typing.SupportsIndex) -> None

Constructor. Creates a box kernel with a separate radius on each axis.

Parameters:
  • rx (int) – The X radius in taps.

  • ry (int) – The Y radius in taps.

  • rz (int) – The Z radius in taps.

Example

>>> import pyvcad as pv
>>> kernel = pv.BoxKernel(2, 2, 0)
class pyvcad.CustomKernel#

A Custom Convolution Kernel created from an array of explicit weights.

__init__(self: pyvcad.pyvcad.CustomKernel, weights: collections.abc.Sequence[SupportsFloat | SupportsIndex], rx: SupportsInt | SupportsIndex, ry: SupportsInt | SupportsIndex, rz: SupportsInt | SupportsIndex) → None#

Constructor. Creates a kernel from a flattened array of weights.

Parameters:
  • weights (list[float]) – The flattened 3D kernel weights, X fastest, then Y, then Z. The list must have (2*rx+1)*(2*ry+1)*(2*rz+1) entries.

  • rx (int) – The X radius in taps.

  • ry (int) – The Y radius in taps.

  • rz (int) – The Z radius in taps.

Raises:

RuntimeError – If the number of weights does not match the radii.

Example

>>> import pyvcad as pv
>>> target_size = 27 # 3x3x3
>>> kernel = pv.CustomKernel([1.0]*target_size, 1, 1, 1)