Tree — core#
Core node types: base class, leaves container, unary, binary, and n-ary nodes, plus tools for inspecting a tree (subtree views and Mermaid tree diagrams).
-
class Node#
- #include <node.h>
Base class for all nodes in the tree.
Every concrete node must implement these pure virtual methods:
evaluate_impl(double x, double y, double z): the signed distance at a point (called by evaluate()).
prepare_bounding_box(): computes the authored bounding box (called lazily by bounding_box()).
clone(): returns a deep copy of the node.
Commonly overridden methods:
prepare_impl(): per-sampling setup that needs the voxel size and bandwidth (e.g. Mesh builds its signed distance grid here; the mesh file itself is read in the constructor).
sample_impl(): returns the signed distance together with the attribute samples.
distance_accuracy() and lipschitz_bound(): the distance guarantee of the subtree.
diagram_label(), diagram_family(), properties(), child_nodes(): metadata for diagrams and UIs.
Warning
You must call prepare() on the root node (and thus the whole tree) before calling evaluate(), sample(), is_in_bbox(), gradient(), or snap(). Behavior is undefined otherwise. Methods that only read the authored tree, such as bounding_box(), properties(), child_nodes(), to_diagram() and clone(), are safe before prepare().
Subclassed by Binary, Leaf, N_ary, StochasticFaceLattice, StochasticGraphLattice, Unary
Public Types
-
enum class DiagramFamily#
The semantic style family of a node in Mermaid tree diagrams.
Values:
-
enumerator transform#
Placement nodes that reposition a child (Translate, Rotate, Scale, Transform, Mirror).
-
enumerator modifier#
Nodes that reshape or repeat a child’s geometry (Offset, Shell, Tile, PolarArray).
-
enumerator attribute_process#
Nodes that only change attributes (Blend, Convolve, AttributeModifier).
-
enumerator mapping#
Nodes that map a child through a cell map or deformation (MappedNode, Warp).
-
enumerator transform#
-
typedef std::pair<std::optional<double>, std::optional<AttributeSamples>> TreeSample#
A sample of a tree.
The first element is the distance to the surface, and the second element is the attribute samples.
Either element is empty where it is not defined: the distance outside the node’s domain, and the attribute samples outside the part.
Public Functions
-
virtual std::vector<std::string> attribute_list()#
Returns a list of the attribute names in use by this node and its children.
- Returns:
A list of the attribute names
-
std::pair<glm::vec3, glm::vec3> bounding_box()#
Returns the bounding box of the node.
The box is computed by prepare_bounding_box() on the first call and cached. It is not padded by the bandwidth; is_in_bbox() adds that padding.
Note
This is safe before prepare() and can be used to rapidly determine if a point is within the bounding box of the node before performing more expensive queries.
- Returns:
A pair of vectors representing the minimum and maximum corners of the bounding box.
-
std::vector<std::string> child_labels() const#
Returns the role label of each child, in the same order as child_nodes().
Children without a role (e.g. the members of a Union) get an empty string.
- Returns:
One label per child, such as “keep” and “subtract” for a Difference.
-
virtual std::vector<std::shared_ptr<Node>> child_nodes() const#
Returns the direct children of this node in authored order.
Safe to call before prepare(). Leaves return an empty list. The order matches child_labels() and diagram_child_links().
- Returns:
The child nodes.
-
virtual std::shared_ptr<Node> clone() = 0#
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
-
virtual std::vector<DiagramAttributeArtifact> diagram_attributes() const#
Returns attribute artifacts owned by this node for Mermaid diagrams.
- Returns:
The node’s own attributes, sorted by name.
-
virtual std::vector<DiagramChildLink> diagram_child_links() const#
Returns the authored child topology for Mermaid diagrams.
- Returns:
One link per child, in authored order. The base implementation returns an empty list.
-
virtual DiagramFamily diagram_family() const#
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.
-
virtual std::string diagram_label() const#
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”.
-
std::string display_label() const#
Returns a short human-readable label, e.g.
“Sphere radius=5”.
Built from diagram_label() and the summary entries of properties().
- Returns:
The label.
-
virtual DistanceAccuracy distance_accuracy() const#
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.
- Returns:
The accuracy of the subtree rooted at this node.
-
std::optional<double> evaluate(double x, double y, double z)#
Evaluates the node at the given point.
- Parameters:
x – The x coordinate of the point to evaluate.
y – The y coordinate of the point to evaluate.
z – The z coordinate of the point to evaluate.
- Returns:
An optional. The distance to the surface at the given point if it is defined, or an empty optional if it is not (outside the domain).
-
virtual std::shared_ptr<Attribute> get_attribute(const std::string &name)#
Returns the attribute function for the given attribute name.
- Parameters:
name – The name of the attribute to get.
- Returns:
The attribute function for the given attribute name.
-
inline virtual glm::vec3 gradient(const glm::vec3 &p)#
Computes the gradient of the signed distance field using central differences.
- Parameters:
p – The point to evaluate.
- Returns:
The gradient vector at the given point.
-
virtual glm::vec3 gradient(double x, double y, double z)#
Computes the gradient of the signed distance field using central differences.
- Parameters:
x – The x coordinate of the point.
y – The y coordinate of the point.
z – The z coordinate of the point.
- Returns:
The gradient vector at the given point.
-
inline double gradientEpsilon() const#
Gets the epsilon used for central difference gradient calculations.
- Returns:
The current gradient epsilon.
Builds the inverse of this placement node around a child.
Wrapping a node in rebind_child() and then inverse_placement() maps space back onto itself.
- Parameters:
child – The child of the inverse node.
- Returns:
The inverse node, or nullptr if this node is not a placement node.
-
bool is_in_bbox(double x, double y, double z)#
Checks if a given point is within the prepared bounding box of the node.
- Parameters:
x – The x coordinate of the point.
y – The y coordinate of the point.
z – The z coordinate of the point.
- Returns:
True if the point is within the bounding box (expanded by sample bandwidth), false otherwise.
-
inline bool is_placement() const#
Returns true if this node only repositions its child (Translate, Rotate, Scale, Transform, Mirror).
- Returns:
True if diagram_family() is DiagramFamily::transform.
-
virtual double lipschitz_bound() const#
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().
- Returns:
L, at least 1, or infinity when nothing is promised.
-
std::unordered_map<std::string, std::shared_ptr<Attribute>> nodal_attributes()#
Returns a map of the actual attributes in use by this node itself (not including children).
- Returns:
A map from attribute name to attribute.
-
Node()#
Constructor.
-
std::vector<std::string> own_attribute_list()#
Returns the attributes set directly on this node, excluding those of its children.
- Returns:
The attribute names.
-
void prepare(const glm::vec3 &voxel_size, double bandwidth)#
Performs any single-run operations that need to be done before the tree is evaluated.
Must be called once on the root node before calling evaluate(), sample(), is_in_bbox(), gradient(), or snap(). It records the bandwidth, marks the node as prepared and calls prepare_impl(), which composite nodes forward to their children. This is useful for nodes that need the voxel size and bandwidth before evaluation (e.g. Mesh builds its signed distance grid here).
Note
prepare() does not change the bounding box. The bandwidth padding is applied by is_in_bbox().
- 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#
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.
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.
- 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.
-
inline void require_prepared() const#
Throws an exception if prepare() has not been called.
- Throws:
std::runtime_error – if the node has not been prepared.
-
TreeSample sample(double x, double y, double z)#
Samples the node at the given point.
- 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.
-
inline double sample_bandwidth() const#
The bandwidth the node was last prepared with.
evaluate() returns no value farther than this outside the bounding box, so a point with no value is at least this far from the node’s surface.
- Returns:
The bandwidth (1.0 before the first prepare()).
Sets an attribute function for the node.
- 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
-
inline void setGradientEpsilon(double eps)#
Sets the epsilon used for central difference gradient calculations.
- Parameters:
eps – The gradient epsilon.
Makes another node read this node’s own attributes (the same set, not a copy).
- Parameters:
node – The node that should share the attribute set.
-
virtual glm::vec3 snap(glm::vec3 point)#
Snaps a given point to the nearest point on the surface.
- Parameters:
point – The point to snap
- Returns:
The snapped point on the surface
-
std::string to_diagram() const#
Builds a Mermaid diagram string for the authored OpenVCAD tree rooted at this node.
This is a thin convenience wrapper around TreeDiagram and is safe to call before prepare().
- Returns:
A self-contained Mermaid flowchart string.
-
double volume()#
Estimates the volume of the node by sampling its signed distance field.
The sample size is computed from the bounding box as the longest bounding-box dimension divided by 128. This method calls prepare() before sampling, which updates the prepared state of the tree.
- Returns:
The estimated volume in cubic model units, e.g. mm^3 when the model is authored in millimeters.
-
double volume(const glm::vec3 &voxel_size)#
Estimates the volume of the node with a per-axis voxel size.
Samples cell centers over the authored bounding box and counts cells where evaluate() returns a signed distance less than or equal to zero. This method calls prepare() before sampling, which updates the prepared state of the tree.
- Parameters:
voxel_size – The positive finite voxel size to use in each dimension.
- Throws:
std::runtime_error – if any voxel_size component is not positive and finite.
- Returns:
The estimated volume in cubic model units, e.g. mm^3 when the model is authored in millimeters.
-
double volume(double sample_size)#
Estimates the volume of the node with a uniform sample size.
This method calls prepare() before sampling, which updates the prepared state of the tree.
- Parameters:
sample_size – The positive finite sample size to use in all dimensions.
- Throws:
std::runtime_error – if sample_size is not positive and finite.
- Returns:
The estimated volume in cubic model units, e.g. mm^3 when the model is authored in millimeters.
-
virtual ~Node() = default#
Virtual Destructor.
Protected Functions
Copies this node’s attributes (deep-cloned), bounding box and prepared state into a clone.
- Parameters:
node – The clone to fill.
-
virtual std::optional<double> evaluate_impl(double x, double y, double z) = 0#
Node-specific signed distance, called by evaluate() once the node is prepared.
- Parameters:
x – The x coordinate of the point to evaluate.
y – The y coordinate of the point to evaluate.
z – The z coordinate of the point to evaluate.
- Returns:
The signed distance (negative inside), or an empty optional where the node has no value.
-
virtual std::vector<std::string> node_attribute_list()#
Returns a list of the attributes in use by this node itself (not including children).
- Returns:
The attribute names.
-
virtual void prepare_bounding_box() = 0#
Computes the authored bounding box into m_min and m_max.
Called once, lazily, by bounding_box(). Must not depend on prepare().
-
inline virtual void prepare_impl(const glm::vec3 &voxel_size, double bandwidth)#
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 TreeSample sample_impl(double x, double y, double z)#
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.
- 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).
Protected Attributes
-
std::shared_ptr<AttributeSet> m_attributes#
The attributes set directly on this node.
-
bool m_bounding_box_prepared = false#
True once prepare_bounding_box() has filled m_min and m_max.
-
double m_gradient_epsilon = 1e-4#
The base step for the finite-difference gradient.
-
glm::vec3 m_max#
The maximum corner of the bounding box, valid once m_bounding_box_prepared is set.
-
glm::vec3 m_min#
The minimum corner of the bounding box, valid once m_bounding_box_prepared is set.
Protected Static Functions
-
static std::string format_property(const glm::vec3 &value)#
Formats a vector for properties() as “(x, y, z)”.
- Parameters:
value – The vector to format.
- Returns:
The formatted text.
-
static std::string format_property(const std::vector<std::string> &names)#
Formats a list of names for properties() as “a, b, c”.
- Parameters:
names – The names to join.
- Returns:
The formatted text.
-
static std::string format_property(double value)#
Formats a number for properties() with up to six significant digits.
- Parameters:
value – The number to format.
- Returns:
The formatted text (“nan”, “inf” and “-inf” for non-finite values).
-
static std::string format_property_file_name(const std::string &path)#
Formats a file path for properties() as its file name (the part after the last separator).
- Parameters:
path – The file path.
- Returns:
The file name.
-
static std::string format_property_flag(bool value)#
Formats a flag for properties() as “yes” or “no”.
- Parameters:
value – The flag.
- Returns:
“yes” or “no”.
-
static std::string format_property_preview(const std::string &text)#
Formats long text for a summary property: one line, cut to 48 characters with “…”.
The cut never splits a UTF-8 multi-byte character.
- Parameters:
text – The text to shorten.
- Returns:
The one-line preview.
The largest lipschitz_bound() among the given nodes (1 if the list is empty).
- Parameters:
nodes – The nodes to compare.
- Returns:
Infinity if any node is approximate or missing.
Builds the diagram entry for one attribute.
- Parameters:
name – The attribute name.
attribute – The attribute, which may be null.
- Returns:
The diagram artifact, with the volume type name filled in for volume-backed attributes.
True if every node was last prepared with at least the given bandwidth.
A node shared by two parents keeps the bandwidth of its last prepare(). A parent whose accuracy argument needs its children at a wider band than that must report approximate, or a child that falls silent too early would break its promise.
- Parameters:
nodes – The children.
bandwidth – The bandwidth the parent asked them to be prepared with.
- Returns:
False if any node is null or was prepared with a narrower band.
The weakest distance_accuracy() among the given nodes (exact if the list is empty).
- Parameters:
nodes – The nodes to compare. A null node counts as approximate.
- Returns:
The weakest accuracy.
-
struct DiagramAttributeArtifact#
- #include <node.h>
An attribute drawn next to its node in a Mermaid tree diagram.
Public Members
-
std::string name#
The attribute name.
-
Attribute::ReturnType return_type = Attribute::ReturnType::none#
The attribute’s return type, or none if the attribute is null.
-
std::string volume_type_name#
The backing volume type name for volume-backed attributes, empty otherwise.
-
std::string name#
-
struct DiagramChildLink#
- #include <node.h>
One child edge of a node in a Mermaid tree diagram.
-
struct NodeProperty#
- #include <node.h>
One read-only authored parameter of a node, formatted for display.
Public Members
-
std::string name#
The parameter name, e.g. “radius”.
-
bool summary = false#
True if the property identifies the node at a glance and is used by display_label().
-
std::string value#
The formatted value, e.g. “5”.
-
std::string name#
Enums
-
enum class DistanceAccuracy#
How faithfully a node’s value matches the true signed distance to its surface.
The surface (the zero level set) and the sign are always meant to be right; this describes the magnitude away from the surface. Every node reports it for its whole subtree from Node::distance_accuracy(), together with Node::lipschitz_bound().
The guarantee behind exact and bound, for a node prepared with bandwidth T: let G(x) be the returned value clamped to [-T, T], with T where evaluate() returns no value. Then G is L-Lipschitz everywhere (L = lipschitz_bound()), and outside the bounding box every returned value is at least the per-axis distance to the box. So a point with G > 0 has no inside point within G / L of it. Values beyond the bandwidth carry no promise. See tree/core_tree_architecture.md.
Values:
-
enumerator exact#
A true signed distance (lipschitz_bound() is 1).
-
enumerator bound#
Never larger in magnitude than lipschitz_bound() times the true distance, within the bandwidth.
-
enumerator approximate#
Close to the surface, but may over- or under-estimate farther away.
-
enumerator exact#
-
namespace DistanceBounds#
Helpers for composing DistanceAccuracy and Lipschitz bounds across a tree.
Functions
-
inline double largest(double a, double b)#
Returns the larger of two Lipschitz bounds.
- Parameters:
a – The first bound.
b – The second bound.
- Returns:
The larger bound, or infinity if either is NaN.
-
inline bool usable(DistanceAccuracy accuracy, double lipschitz)#
Returns true if a value with this accuracy and bound can prove a region empty.
- Parameters:
accuracy – The accuracy.
lipschitz – The Lipschitz bound that goes with it.
- Returns:
True if the accuracy is not approximate and the bound is finite and positive.
-
inline DistanceAccuracy weakest(DistanceAccuracy a, DistanceAccuracy b)#
Returns the weaker of two accuracies (exact > bound > approximate).
- Parameters:
a – The first accuracy.
b – The second accuracy.
- Returns:
The weaker of the two.
Variables
-
constexpr double unknown_lipschitz = std::numeric_limits<double>::infinity()#
The Lipschitz bound of a node that promises nothing.
-
inline double largest(double a, double b)#
-
class Leaf : public Node#
- #include <leaf.h>
A leaf node that cannot have any children.
Subclassed by BeamLattice, CAD, CellMapDomain, Cone, Cylinder, Extrude, Function, GraphLattice, Loft, MappedFaceLattice, MappedGraphLattice, MappedImplicitLattice, MappedRim, Mesh, RectPrism, Revolve, SignedDistanceField, Sphere, Strut, SurfaceReliefVolume, Sweep, Text, TexturedMesh, ThreeMFBeamLattice, Torus, Tube
Public Functions
-
virtual std::vector<Node::DiagramChildLink> diagram_child_links() const override#
Returns the authored child topology for Mermaid diagrams.
- Returns:
One link per child, in authored order. The base implementation returns an empty list.
-
Leaf() = default#
Default constructor.
-
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<Node::DiagramChildLink> diagram_child_links() const override#
-
class Unary : public Node#
- #include <unary.h>
A node with a single child.
Subclassed by AttributeModifier, Blend, Convolve, Identity, MappedNode, Mirror, Offset, PolarArray, Rotate, Scale, Shell, SubtreeView, Tile, Transform, Translate, Warp
Public Functions
-
virtual std::vector<std::string> attribute_list() override#
Returns a list of the attribute names in use by this node and its children.
- Returns:
A list of the attribute names
-
std::shared_ptr<Node> child() const#
Returns the one and only child of this node.
- Returns:
The one and only child of this node.
-
virtual std::vector<std::shared_ptr<Node>> child_nodes() const override#
Returns the direct children of this node in authored order.
Safe to call before prepare(). Leaves return an empty list. The order matches child_labels() and diagram_child_links().
- Returns:
The child nodes.
-
virtual std::vector<Node::DiagramChildLink> diagram_child_links() const override#
Returns the authored child topology for Mermaid diagrams.
- Returns:
One link per child, in authored order. The base implementation returns an empty list.
-
virtual std::optional<double> evaluate_impl(double x, double y, double z) override#
Node-specific signed distance, called by evaluate() once the node is prepared.
- Parameters:
x – The x coordinate of the point to evaluate.
y – The y coordinate of the point to evaluate.
z – The z coordinate of the point to evaluate.
- Returns:
The signed distance (negative inside), or an empty optional where the node has no value.
-
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 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.
- 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).
Sets the one and only child of this node.
- Parameters:
child – The one and only child of this node.
-
Unary() = default#
Default constructor.
Constructor to fill the single child.
- Parameters:
child – The one and only child of this node.
Protected Functions
Clones the child of this node.
- Parameters:
clone – The clone of this node.
-
virtual void prepare_bounding_box() override#
Uses the child’s bounding box.
-
virtual std::vector<std::string> attribute_list() override#
-
class Binary : public Node#
- #include <binary.h>
A binary node with exactly two children.
The children are stored in m_left_child and m_right_child
Subclassed by Difference, Mix
Public Functions
-
const std::unordered_map<std::string, std::shared_ptr<AttributeConflictResolver>> &attribute_conflict_resolvers() const#
Retrieves the map of attribute conflict resolvers.
- Returns:
The resolvers, keyed by attribute name.
-
virtual std::vector<std::string> attribute_list() override#
Returns a combined list of attributes from this node, its left child, and its right child.
- Returns:
A vector of unique attribute names.
-
Binary() = default#
Default constructor.
Constructor to fill the both children.
- Parameters:
left – The left child
right – The right child
-
virtual std::vector<std::shared_ptr<Node>> child_nodes() const override#
Returns the direct children of this node in authored order.
Safe to call before prepare(). Leaves return an empty list. The order matches child_labels() and diagram_child_links().
- Returns:
The child nodes.
-
virtual std::vector<Node::DiagramChildLink> diagram_child_links() const override#
Returns the authored child topology for Mermaid diagrams.
- Returns:
One link per child, in authored order. The base implementation returns an empty list.
-
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.
Adds or updates an attribute conflict resolver for the given attribute name.
- Parameters:
name – The string name of the attribute.
resolver – The shared pointer to the resolver.
Sets the left child.
- Parameters:
left – The left child
Sets the right child.
- Parameters:
right – The right child
Protected Functions
Clones the children of the node.
- Parameters:
node – The node to clone the children from
-
const std::unordered_map<std::string, std::shared_ptr<AttributeConflictResolver>> &attribute_conflict_resolvers() const#
-
class N_ary : public Node#
- #include <n_ary.h>
A node with an arbitrary number of children.
Subclassed by BBoxIntersection, BBoxUnion, Intersection, Sum, Union
Public Functions
Appends a child to the node.
The base implementation always appends the child and returns true. BBoxUnion and BBoxIntersection reject a null child and return false.
- Parameters:
child – The child to add to the node
- Returns:
True if the child was added, false otherwise
-
const std::unordered_map<std::string, std::shared_ptr<AttributeConflictResolver>> &attribute_conflict_resolvers() const#
Retrieves the map of attribute conflict resolvers.
- Returns:
The resolvers, keyed by attribute name.
-
virtual std::vector<std::string> attribute_list() override#
Returns a list of the attribute names in use by this node and its children.
- Returns:
A list of the attribute names
-
virtual std::shared_ptr<Node> child(size_t index) const#
Returns the child at the given index.
- Parameters:
index – The index of the child to return.
- Returns:
The child at the given index.
-
virtual std::vector<std::shared_ptr<Node>> child_nodes() const override#
Returns the direct children of this node in authored order.
Safe to call before prepare(). Leaves return an empty list. The order matches child_labels() and diagram_child_links().
- Returns:
The child nodes.
-
virtual std::vector<std::shared_ptr<Node>> &children()#
Returns the children of the node.
- Returns:
The children of the node.
-
virtual std::vector<Node::DiagramChildLink> diagram_child_links() const override#
Returns the authored child topology for Mermaid diagrams.
- Returns:
One link per child, in authored order. The base implementation returns an empty list.
-
N_ary() = default#
Default constructor.
Constructor to fill the children.
- Parameters:
children – The children of the node.
-
virtual size_t numChildren() const#
Returns the number of children of the node.
- Returns:
The number of children of the node.
-
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.
Adds or updates an attribute conflict resolver for the given attribute name.
- Parameters:
name – The string name of the attribute.
resolver – The shared pointer to the resolver.
Protected Functions
Clones the children of the node.
- Parameters:
node – The node to clone the children from
Protected Attributes
-
std::unordered_map<std::string, std::shared_ptr<AttributeConflictResolver>> m_attribute_conflict_resolvers#
The map of attribute conflict resolvers.
-
class SubtreeView : public Unary#
- #include <subtree_view.h>
A read-only view of one node of a design, with optional ancestor context re-applied.
A design is a tree of nodes. SubtreeView lets tools such as the renderer show part of that tree on its own. With no context the view is exactly the target node’s own result, in the target’s own coordinate frame, so every operation above it is undone.
Two independent options re-apply parts of the path from the root to the target:
apply_placement: re-applies every placement ancestor (Translate, Rotate, Scale, Transform, Mirror), so the target sits where it lands in the full design.
apply_attributes: re-applies attributes set on ancestors and attribute-process ancestors (AttributeModifier, Blend, Convolve), evaluated where the part sits in the full design. If placement is off, the result is then mapped back onto the target’s own frame.
Booleans and shape modifiers above the target (Union, Difference, Offset, Shell, Tile, …) are never applied: they are the steps a SubtreeView exists to take apart.
The view shares the design’s nodes rather than copying them, and preparing it prepares the target subtree in place. Do not prepare a view and its design concurrently.
Public Functions
-
inline bool applies_attributes() const#
Returns true if ancestor attributes are re-applied.
- Returns:
True if ancestor attributes are re-applied.
-
inline bool applies_placement() const#
Returns true if ancestor placement is re-applied.
- Returns:
True if ancestor placement is re-applied.
-
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 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 accuracy of the evaluated chain (the target with any re-applied ancestors). The view returns the chain’s value inside its own box grown by the band. When that box holds the chain’s box (measured by
prepare()), the view is exactly the chain’s field and keeps its accuracy: this is always so with placement or with no context. With attributes but no placement the box is the target’s, which can be smaller than the chain’s (mapping out and back through a Rotate grows the axis-aligned box, and float rounding can move a translated one). The chain’s own promise then says nothing about values between the two boxes, so the view reports approximate, even though the chain’s geometry is the target’s. Approximate also if the chain was last prepared with a narrower band.- Returns:
The accuracy of the subtree rooted at this node.
-
virtual std::optional<double> evaluate_impl(double x, double y, double z) override#
Node-specific signed distance, called by evaluate() once the node is prepared.
- Parameters:
x – The x coordinate of the point to evaluate.
y – The y coordinate of the point to evaluate.
z – The z coordinate of the point to evaluate.
- Returns:
The signed distance (negative inside), or an empty optional where the node has no value.
-
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 chain’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.
Wraps an already built context chain.
Prefer build(), which creates the chain from a root-to-target path.
- Parameters:
chain – The node to evaluate (the target, possibly wrapped by re-applied ancestors).
target – The node being viewed.
apply_placement – Whether ancestor placement was re-applied.
apply_attributes – Whether ancestor attributes were re-applied.
Public Static Functions
Builds a view of the last node of a root-to-target path.
- Parameters:
path – The nodes from the root (first) to the target (last). Each node must be a direct child of the one before it.
apply_placement – Re-apply placement ancestors.
apply_attributes – Re-apply ancestor attributes and attribute-process ancestors.
- Throws:
std::runtime_error – if the path is empty or broken.
- Returns:
The view.
Resolves a path of child indices from a root node.
- Parameters:
root – The root node.
child_indices – Index into child_nodes() at each level, starting below the root.
- Throws:
std::runtime_error – if an index is out of range.
- Returns:
The nodes from the root to the resolved node, inclusive.
Protected Functions
-
virtual void prepare_bounding_box() override#
Uses the target’s own bounds whenever the view is in the target’s frame.
Mapping attributes out and back through Rotate nodes grows the chain’s axis-aligned box, but the geometry is still exactly the target’s.
-
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.
Prepares the chain and records whether the view’s box holds the chain’s box.
- Parameters:
voxel_size – The size of a voxel we plan to sample with.
bandwidth – The bandwidth of the tree we are sampling.
-
class TreeDiagram#
- #include <tree_diagram.h>
Builds Mermaid diagrams for authored OpenVCAD trees and DAGs.
TreeDiagram owns Mermaid-specific traversal, styling boilerplate, and file export. It is safe to construct and use before prepare() is called on the tree.
Public Functions
-
void save_mermaid(const std::string &path) const#
Saves the Mermaid source to disk.
- Parameters:
path – The path to the
.mmdfile to write.
-
std::string to_mermaid() const#
Returns the final Mermaid diagram text.
- Returns:
A self-contained Mermaid flowchart string.
-
explicit TreeDiagram(const Node *root)#
Construct a diagram builder from a non-owning root pointer.
- Parameters:
root – The root node of the authored OpenVCAD tree.
Construct a diagram builder from a shared root node.
- Parameters:
root – The root node of the authored OpenVCAD tree.
Public Static Functions
-
static std::string master_legend()#
Returns a hardcoded master legend covering the full OpenVCAD tree-diagram language.
This legend is separate from any particular design tree and is intended as a companion reference asset for documentation or tooling.
- Returns:
A self-contained Mermaid flowchart string for the master legend.
-
static void save_master_legend(const std::string &path)#
Saves the hardcoded master legend Mermaid source to disk.
- Parameters:
path – The path to the
.mmdfile to write.
-
void save_mermaid(const std::string &path) const#