Tree — attribute nodes#

Unary attribute operators (modifier, convolution, blur) on the attribute tree.

class AttributeModifier : public Unary#
#include <attribute_modifier.h>

A unary node that modifies or converts attributes produced by its child tree.

Public Functions

AttributeModifier(const std::shared_ptr<AttributeConverterBase> &converter, std::shared_ptr<Node> child)#

Constructor.

Parameters:
  • converter – The converter logic that modifies samples coming from the child node.

  • child – The child node to modify the attributes of.

virtual std::shared_ptr<Node> clone() override#

Clones the node and returns a new instance of the node.

Note

This may be called before or after prepare() is called, however it is always more efficient to call it after. This is because the prepare() function must be called on all clones of the node separately. If you call prepare() first and then clone the node, the clone() operation will copy from memory instead of re-reading from disk.

Returns:

A new instance of the node

inline std::shared_ptr<AttributeConverterBase> converter() const#

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

Returns:

The converter applied to the child’s attribute samples.

virtual std::vector<Node::DiagramAttributeArtifact> diagram_attributes() const override#

Returns attribute artifacts owned by this node for Mermaid diagrams.

Returns:

The node’s own attributes, sorted by name.

inline virtual Node::DiagramFamily diagram_family() const override#

Returns the semantic style family used for this node in Mermaid diagrams.

Concrete OpenVCAD nodes should override this. The base fallback exists for mocks and other internal helper nodes that do not need custom diagram metadata.

Returns:

The diagram family. The base implementation returns DiagramFamily::composition.

inline virtual std::string diagram_label() const override#

Returns the display label used for this node in Mermaid diagrams.

Concrete OpenVCAD nodes should override this. The base fallback exists for mocks and other internal helper nodes that do not need custom diagram metadata.

Returns:

The node’s type name, e.g. “Sphere”. The base implementation returns “Node”.

virtual DistanceAccuracy distance_accuracy() const override#

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

Composes the node’s own operation with its children’s accuracy, so the root’s answer describes the whole tree. exact and bound promise that the value clamped to the bandwidth is lipschitz_bound()-Lipschitz and that values outside the bounding box are at least the per-axis distance to it (see DistanceAccuracy). Only valid after prepare(); some nodes decide from what prepare()

measured. The default is approximate, so a node without an override can only disable optimizations that rely on the guarantee.

The child’s accuracy: only attributes change, the value, box and band are the child’s. Approximate if the child was last prepared with a narrower band than this node (a child shared with another parent), since its value would then stop short of this node’s band.

Returns:

The accuracy of the subtree rooted at this node.

virtual std::shared_ptr<Attribute> get_attribute(const std::string &name) override#

Returns the attribute function for the given attribute name.

This node modifies existing child attributes; it throws std::runtime_error if you attempt to retrieve attributes from it directly.

Parameters:

name – The name of the attribute to get.

Returns:

The attribute function for the given attribute name.

virtual double lipschitz_bound() const override#

The Lipschitz bound L that goes with distance_accuracy().

A point whose value v (clamped to the bandwidth) is positive has no inside point within v / L of it. 1 for exact; infinity for approximate. Only valid after prepare()

.

The child’s Lipschitz bound (infinity when approximate).

Returns:

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

virtual std::vector<NodeProperty> properties() const override#

Returns the authored parameters of this node as display-ready name/value pairs.

Safe to call before prepare(). Properties flagged as summary are the few that identify the node at a glance and are used by display_label().

Returns:

The ordered property list. The base implementation returns an empty list.

virtual std::shared_ptr<Node> rebind_child(const std::shared_ptr<Node> &child, bool keep_attributes) override#

Builds a shallow copy of this node that wraps a different child.

Used by SubtreeView to re-apply the effect of an ancestor to part of its subtree. The copy keeps this node’s parameters and any state that depended on its original child (e.g. the Rotate

pivot). Only placement and attribute-process nodes support it.

The rebound node processes only the new child, so its effect is recomputed for that subtree.

Parameters:
  • child – The new child.

  • keep_attributes – If true, the copy shares this node’s own attributes.

Returns:

The rebound node, or nullptr if this node cannot be rebound.

virtual TreeSample sample_impl(double x, double y, double z) override#

Node-specific sampling, called by sample() once the node is prepared.

The base implementation evaluates the node and, only where the distance is at most zero, samples this node’s own attributes.

Samples the child node and applies the converter to its attribute samples. The converter only runs inside the part: where the child’s value is above zero or missing, no attributes are returned.

Parameters:
  • x – The x coordinate of the point.

  • y – The y coordinate of the point.

  • z – The z coordinate of the point.

Returns:

A TreeSample containing the signed distance (if any) and attribute samples (inside the part only).

virtual void set_attribute(const std::string &name, const std::shared_ptr<Attribute> &attribute) override#

Sets an attribute function for the node.

This node modifies existing child attributes; it throws std::runtime_error if you attempt to set standard attributes directly on it.

Parameters:
  • name – The name of the attribute.

  • attribute – The attribute function to set.

Throws:

std::runtime_error – if the attribute name is already in use by the node

Protected Functions

virtual std::vector<std::string> node_attribute_list() override#

Returns a list of the attributes in use by this node itself (not including children).

Returns the list of output attributes generated by the inner converter.

Returns:

The attribute names.

Private Members

std::shared_ptr<AttributeConverterBase> m_converter#
class Convolve : public Unary#
#include <convolve.h>

A unary node that convolves the attributes of its child node using a defined kernel.

Convolve intercepts sample() calls and blends/convolves the child’s attributes over a local region using an arbitrary kernel. The signed distance field (geometry) is passed through unmodified.

Under the hood, prepare() precomputes a dense typed voxel grid of the child’s targeted attributes using the shared AttributeVoxelGrid utility. At sample time each kernel tap becomes a cheap flat-memory trilinear grid lookup instead of a full child->sample() traversal, which makes the node orders of magnitude faster than a naive implementation.

Convolve is the generic, flexible sibling of the specialized Blend node; both share the same precomputation utility but have independent sample-time logic. Use Blend as a shorthand for the common box-blend case (where a separable-blur fast path lives entirely in prepare() and sample() becomes a single trilinear lookup). Use Convolve for arbitrary kernel weights or non-blur operations (sharpen, derivative, etc.).

The internal grid defaults to the voxel_size passed to prepare(). Users can supply a sparser override_voxel_size in the constructor to reduce memory cost for large scenes; trilinear interpolation at sample time still produces smooth output.

Public Functions

virtual std::shared_ptr<Node> clone() override#

Clones the node and returns a new instance of the node.

Clones share the immutable precomputed grid via shared_ptr so threaded samplers pay the prepare cost only once per tree.

Note

This may be called before or after prepare() is called, however it is always more efficient to call it after. This is because the prepare() function must be called on all clones of the node separately. If you call prepare() first and then clone the node, the clone() operation will copy from memory instead of re-reading from disk.

Returns:

A new instance of the node

Convolve(const std::shared_ptr<Node> &child, const std::vector<std::string> &attributes, const std::shared_ptr<ConvolveKernel> &kernel, const glm::vec3 &physical_radius, const std::optional<glm::vec3> &override_voxel_size = std::nullopt)#

Constructs a Convolve node.

Parameters:
  • child – The child node containing the attributes to convolve.

  • attributes – The names of the attributes to target. If empty, all attributes observed on the child at prepare time are targeted.

  • kernel – The convolution kernel (weights and extents).

  • physical_radius – The physical world-space radius (in mm) that the kernel spans along X, Y, and Z.

  • override_voxel_size – Optional sparser voxel size used for the internal precomputed grid. When unset, the voxel_size passed to prepare() is used.

inline virtual Node::DiagramFamily diagram_family() const override#

Returns the semantic style family used for this node in Mermaid diagrams.

Concrete OpenVCAD nodes should override this. The base fallback exists for mocks and other internal helper nodes that do not need custom diagram metadata.

Returns:

The diagram family. The base implementation returns DiagramFamily::composition.

inline virtual std::string diagram_label() const override#

Returns the display label used for this node in Mermaid diagrams.

Concrete OpenVCAD nodes should override this. The base fallback exists for mocks and other internal helper nodes that do not need custom diagram metadata.

Returns:

The node’s type name, e.g. “Sphere”. The base implementation returns “Node”.

virtual DistanceAccuracy distance_accuracy() const override#

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

Composes the node’s own operation with its children’s accuracy, so the root’s answer describes the whole tree. exact and bound promise that the value clamped to the bandwidth is lipschitz_bound()-Lipschitz and that values outside the bounding box are at least the per-axis distance to it (see DistanceAccuracy). Only valid after prepare(); some nodes decide from what prepare()

measured. The default is approximate, so a node without an override can only disable optimizations that rely on the guarantee.

The child’s accuracy: only attributes are convolved, the value and box are the child’s.

prepare() widens the child’s band by the kernel radius, which only makes it reach farther than this node’s band; clipping a wider band to this one keeps the child’s Lipschitz bound. Approximate if the child was last prepared with a narrower band than this node (a child shared with another parent).

Returns:

The accuracy of the subtree rooted at this node.

inline std::shared_ptr<ConvolveKernel> kernel() const#

Returns the convolution kernel.

Returns:

The convolution kernel.

virtual double lipschitz_bound() const override#

The Lipschitz bound L that goes with distance_accuracy().

A point whose value v (clamped to the bandwidth) is positive has no inside point within v / L of it. 1 for exact; infinity for approximate. Only valid after prepare()

.

The child’s Lipschitz bound (infinity when approximate).

Returns:

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

inline std::optional<glm::vec3> override_voxel_size() const#

Returns the voxel size override, if one was given.

Returns:

The voxel size override, if one was given.

inline glm::vec3 physical_radius() const#

Returns the kernel radius in model units along each axis.

Returns:

The kernel radius in model units along each axis.

virtual void prepare_impl(const glm::vec3 &voxel_size, double bandwidth) override#

Node-specific part of prepare(), called after the bandwidth has been recorded.

Composite nodes prepare their children here. The base implementation does nothing.

Parameters:
  • voxel_size – The size of a voxel we plan to sample with.

  • bandwidth – The bandwidth of the tree we are sampling.

virtual std::vector<NodeProperty> properties() const override#

Returns the authored parameters of this node as display-ready name/value pairs.

Safe to call before prepare(). Properties flagged as summary are the few that identify the node at a glance and are used by display_label().

Returns:

The ordered property list. The base implementation returns an empty list.

virtual std::shared_ptr<Node> rebind_child(const std::shared_ptr<Node> &child, bool keep_attributes) override#

Builds a shallow copy of this node that wraps a different child.

Used by SubtreeView to re-apply the effect of an ancestor to part of its subtree. The copy keeps this node’s parameters and any state that depended on its original child (e.g. the Rotate

pivot). Only placement and attribute-process nodes support it.

The rebound node processes only the new child, so its effect is recomputed for that subtree.

Parameters:
  • child – The new child.

  • keep_attributes – If true, the copy shares this node’s own attributes.

Returns:

The rebound node, or nullptr if this node cannot be rebound.

virtual TreeSample sample_impl(double x, double y, double z) override#

Node-specific sampling, called by sample() once the node is prepared.

The base implementation evaluates the node and, only where the distance is at most zero, samples this node’s own attributes.

Computes the convolved attributes at the requested coordinate. Returns no attributes where the child’s value is above zero or missing (outside the part).

Parameters:
  • x – The x coordinate of the point.

  • y – The y coordinate of the point.

  • z – The z coordinate of the point.

Returns:

A TreeSample containing the signed distance (if any) and attribute samples (inside the part only).

inline const std::vector<std::string> &target_attributes() const#

Returns the names of the attributes this node convolves.

Returns:

The names of the attributes this node convolves.

Protected Functions

virtual void prepare_bounding_box() override#

Computes the authored bounding box into m_min and m_max.

Called once, lazily, by bounding_box(). Must not depend on prepare().

Private Members

std::shared_ptr<AttributeVoxelGrid> m_grid#
std::shared_ptr<ConvolveKernel> m_kernel#
std::optional<glm::vec3> m_override_voxel_size#
glm::vec3 m_physical_radius#
std::vector<std::string> m_target_attributes#
std::set<std::string> m_target_attributes_set#
class BoxKernel : public ConvolveKernel#
#include <convolve_kernel.h>

A simple box average kernel where all weights are equal to 1.0 (normalization happens later in the node).

Public Functions

inline explicit BoxKernel(int r)#

Constructor.

Parameters:

r – Radius of the box kernel

inline BoxKernel(int rx, int ry, int rz)#

Constructor.

Parameters:
  • rx – X radius

  • ry – Y radius

  • rz – Z radius

inline virtual int get_radius_x() const override#

Gets the X radius (number of voxels positive and negative from center).

Returns:

The X radius in voxels.

inline virtual int get_radius_y() const override#

Gets the Y radius (number of voxels positive and negative from center).

Returns:

The Y radius in voxels.

inline virtual int get_radius_z() const override#

Gets the Z radius (number of voxels positive and negative from center).

Returns:

The Z radius in voxels.

inline virtual double get_weight(int i, int j, int k) const override#

Return the weight at the integer coordinate offset (i, j, k) relative to the center of the kernel (0, 0, 0).

Parameters:
  • i – The X offset in voxels.

  • j – The Y offset in voxels.

  • k – The Z offset in voxels.

Returns:

The weight; 0 outside the kernel’s radii. Weights need not be normalized.

Private Members

int m_rx#
int m_ry#
int m_rz#
class ConvolveKernel#
#include <convolve_kernel.h>

Base interface for a convolution kernel used by the Convolve node.

Subclassed by BoxKernel, CustomKernel

Public Functions

virtual int get_radius_x() const = 0#

Gets the X radius (number of voxels positive and negative from center).

Returns:

The X radius in voxels.

virtual int get_radius_y() const = 0#

Gets the Y radius (number of voxels positive and negative from center).

Returns:

The Y radius in voxels.

virtual int get_radius_z() const = 0#

Gets the Z radius (number of voxels positive and negative from center).

Returns:

The Z radius in voxels.

virtual double get_weight(int i, int j, int k) const = 0#

Return the weight at the integer coordinate offset (i, j, k) relative to the center of the kernel (0, 0, 0).

Parameters:
  • i – The X offset in voxels.

  • j – The Y offset in voxels.

  • k – The Z offset in voxels.

Returns:

The weight; 0 outside the kernel’s radii. Weights need not be normalized.

virtual ~ConvolveKernel() = default#

Virtual destructor.

class CustomKernel : public ConvolveKernel#
#include <convolve_kernel.h>

A custom dense volume kernel initialized usually from Python (numpy array).

Public Functions

inline CustomKernel(const std::vector<double> &weights, int rx, int ry, int rz)#

Constructor.

The weights are indexed X fastest: index = (i + rx) + (j + ry) * (2 rx + 1)

  • (k + rz) * (2 rx + 1) * (2 ry + 1).

Throws:

std::runtime_error – if the number of weights is not (2 rx + 1)(2 ry + 1)(2 rz + 1).

Parameters:
  • weights – 1D vector representing the flattened 3D array.

  • rx – The half-size (radius) in X (total size = 2*rx + 1)

  • ry – The half-size (radius) in Y

  • rz – The half-size (radius) in Z

inline virtual int get_radius_x() const override#

Gets the X radius (number of voxels positive and negative from center).

Returns:

The X radius in voxels.

inline virtual int get_radius_y() const override#

Gets the Y radius (number of voxels positive and negative from center).

Returns:

The Y radius in voxels.

inline virtual int get_radius_z() const override#

Gets the Z radius (number of voxels positive and negative from center).

Returns:

The Z radius in voxels.

inline virtual double get_weight(int i, int j, int k) const override#

Return the weight at the integer coordinate offset (i, j, k) relative to the center of the kernel (0, 0, 0).

Parameters:
  • i – The X offset in voxels.

  • j – The Y offset in voxels.

  • k – The Z offset in voxels.

Returns:

The weight; 0 outside the kernel’s radii. Weights need not be normalized.

Private Members

int m_rx#
int m_ry#
int m_rz#
std::vector<double> m_weights#
class Blend : public Unary#
#include <blend.h>

A fast, specialized unary node for locally blending varying attributes of its child.

Unlike the more general Convolve node (which at sample time performs a weighted sum over all kernel taps using cheap trilinear grid lookups), Blend precomputes the child’s targeted attributes onto a dense voxel grid during prepare(), applies a masked separable box blur along X, Y, Z (optionally repeated to approximate a smoother Gaussian-like ramp), and then serves sample() by doing a single trilinear lookup into the pre-blurred grid combined with a single child sample() call. This turns per-sample work into O(1) and amortizes the blur work across all downstream sample() calls.

Blend and Convolve are siblings that share the underlying AttributeVoxelGrid utility for parallel-filling typed per-attribute buffers. Blend keeps the separable-blur fast path; Convolve keeps its generic per-sample weighted-sum over arbitrary kernels.

The node is intentionally a no-op in regions where the targeted attributes are locally constant (linear blurs preserve constants), so users can safely apply it over an entire assembly and only see change near boundaries where attributes differ.

The internal grid defaults to the voxel_size passed to prepare(). Users can supply a sparser override_voxel_size in the constructor to reduce memory cost for large scenes; trilinear interpolation at sample time still produces smooth output.

Public Functions

Blend(const std::shared_ptr<Node> &child, const std::vector<std::string> &attributes, const glm::vec3 &physical_radius, int num_passes = 1, const std::optional<glm::vec3> &override_voxel_size = std::nullopt)#

Constructs a Blend node.

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

  • attributes – Names of the attributes to blend. If empty, all attributes observed on the child at prepare time are blended.

  • physical_radius – Blend radius in world units (mm) along X, Y, and Z. Controls the transition width across attribute boundaries.

  • num_passes – Number of successive box-blur passes. 1 yields a linear ramp (box), 2 a tent-like ramp, 3+ approximates a Gaussian. Must be >= 1.

  • override_voxel_size – Optional sparser voxel size used for the internal grid. When unset, the voxel_size passed to prepare() is used.

virtual std::shared_ptr<Node> clone() override#

Clones the node and returns a new instance of the node.

Clones share the same immutable precomputed grid via shared_ptr, so threaded samplers (TreeSampler) pay the prepare cost only once per tree.

Note

This may be called before or after prepare() is called, however it is always more efficient to call it after. This is because the prepare() function must be called on all clones of the node separately. If you call prepare() first and then clone the node, the clone() operation will copy from memory instead of re-reading from disk.

Returns:

A new instance of the node

inline virtual Node::DiagramFamily diagram_family() const override#

Returns the semantic style family used for this node in Mermaid diagrams.

Concrete OpenVCAD nodes should override this. The base fallback exists for mocks and other internal helper nodes that do not need custom diagram metadata.

Returns:

The diagram family. The base implementation returns DiagramFamily::composition.

inline virtual std::string diagram_label() const override#

Returns the display label used for this node in Mermaid diagrams.

Concrete OpenVCAD nodes should override this. The base fallback exists for mocks and other internal helper nodes that do not need custom diagram metadata.

Returns:

The node’s type name, e.g. “Sphere”. The base implementation returns “Node”.

virtual DistanceAccuracy distance_accuracy() const override#

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

Composes the node’s own operation with its children’s accuracy, so the root’s answer describes the whole tree. exact and bound promise that the value clamped to the bandwidth is lipschitz_bound()-Lipschitz and that values outside the bounding box are at least the per-axis distance to it (see DistanceAccuracy). Only valid after prepare(); some nodes decide from what prepare()

measured. The default is approximate, so a node without an override can only disable optimizations that rely on the guarantee.

The child’s accuracy: only attributes are blended, the value and box are the child’s.

prepare() widens the child’s band by the blend radius, which only makes it reach farther than this node’s band; clipping a wider band to this one keeps the child’s Lipschitz bound. Approximate if the child was last prepared with a narrower band than this node (a child shared with another parent).

Returns:

The accuracy of the subtree rooted at this node.

virtual double lipschitz_bound() const override#

The Lipschitz bound L that goes with distance_accuracy().

A point whose value v (clamped to the bandwidth) is positive has no inside point within v / L of it. 1 for exact; infinity for approximate. Only valid after prepare()

.

The child’s Lipschitz bound (infinity when approximate).

Returns:

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

inline int num_passes() const#

Returns the number of blur passes.

Returns:

The number of blur passes.

inline std::optional<glm::vec3> override_voxel_size() const#

Returns the voxel size override, if one was given.

Returns:

The voxel size override, if one was given.

inline glm::vec3 physical_radius() const#

Returns the blend radius in model units along each axis.

Returns:

The blend radius in model units along each axis.

virtual void prepare_impl(const glm::vec3 &voxel_size, double bandwidth) override#

Node-specific part of prepare(), called after the bandwidth has been recorded.

Composite nodes prepare their children here. The base implementation does nothing.

Parameters:
  • voxel_size – The size of a voxel we plan to sample with.

  • bandwidth – The bandwidth of the tree we are sampling.

virtual std::vector<NodeProperty> properties() const override#

Returns the authored parameters of this node as display-ready name/value pairs.

Safe to call before prepare(). Properties flagged as summary are the few that identify the node at a glance and are used by display_label().

Returns:

The ordered property list. The base implementation returns an empty list.

virtual std::shared_ptr<Node> rebind_child(const std::shared_ptr<Node> &child, bool keep_attributes) override#

Builds a shallow copy of this node that wraps a different child.

Used by SubtreeView to re-apply the effect of an ancestor to part of its subtree. The copy keeps this node’s parameters and any state that depended on its original child (e.g. the Rotate

pivot). Only placement and attribute-process nodes support it.

The rebound node processes only the new child, so its effect is recomputed for that subtree.

Parameters:
  • child – The new child.

  • keep_attributes – If true, the copy shares this node’s own attributes.

Returns:

The rebound node, or nullptr if this node cannot be rebound.

virtual TreeSample sample_impl(double x, double y, double z) override#

Node-specific sampling, called by sample() once the node is prepared.

The base implementation evaluates the node and, only where the distance is at most zero, samples this node’s own attributes.

Performs one child->

sample() for the SDF and non-targeted attributes, then replaces each targeted attribute with a trilinearly interpolated value read from the precomputed blurred grid. Returns no attributes where the child’s value is above zero or missing (outside the part).

Parameters:
  • x – The x coordinate of the point.

  • y – The y coordinate of the point.

  • z – The z coordinate of the point.

Returns:

A TreeSample containing the signed distance (if any) and attribute samples (inside the part only).

inline const std::vector<std::string> &target_attributes() const#

Returns the names of the attributes this node blends.

Returns:

The names of the attributes this node blends.

Protected Functions

virtual void prepare_bounding_box() override#

Computes the authored bounding box into m_min and m_max.

Called once, lazily, by bounding_box(). Must not depend on prepare().

Private Members

std::shared_ptr<AttributeVoxelGrid> m_grid#
int m_num_passes#
std::optional<glm::vec3> m_override_voxel_size#
glm::vec3 m_physical_radius#
std::vector<std::string> m_target_attributes#