Tree — core#

Core node types: base class, leaves container, unary, binary, and n-ary nodes.

class Node#
#include <node.h>

Base class for all nodes in the tree.

All nodes must implement the following methods:

  • evaluate(double x, double y, double z) - returns the distance to the surface at the given point

  • material(double x, double y, double z) - returns the material at the given point

  • material_list() - returns a list of all the materials used by the node and its children

  • bounding_box() - returns the bounding box of the node

  • type() - returns the named type of the node Optional methods:

  • prepare() - must be called before the tree is evaluated. This is useful for nodes that need to load data before evaluation (e.g. the mesh node loads the mesh data from disk).

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. The only query that is guaranteed safe before prepare() is bounding_box().

Subclassed by Binary, Leaf, N_ary, Unary

Public Types

enum class DiagramFamily#

Values:

enumerator geometry#
enumerator composition#
enumerator transform#
enumerator modifier#
enumerator attribute_process#
enumerator mapping#
typedef std::pair<std::optional<double>, std::optional<AttributeSamples>> TreeSample#

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.

Note

This is guaranteed to be 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.

Note

This can be used to rapidly determine if a point is within the bounding box of the node if you check that the point is within the bounding box of the node before evaluating the node.

Returns:

A pair of vectors representing the minimum and maximum corners of the bounding box.

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.

virtual std::vector<DiagramChildLink> diagram_child_links() const#

Returns the authored child topology for Mermaid diagrams.

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.

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.

virtual std::optional<double> evaluate(double x, double y, double z) = 0#

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.

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.

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).

Node()#

Constructor.

virtual 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(). This is useful for nodes that need to know the voxel size and bandwidth before evaluation (e.g. Mesh loads from disk; Rotate sets rotation center).

Note

The default implementation expands the bounding box by the bandwidth in all directions.

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(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.

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

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.

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.

virtual ~Node() = default#

Virtual Destructor.

Protected Functions

virtual void clone_attributes(const std::shared_ptr<Node> &node)#
virtual std::vector<std::string> node_attribute_list()#

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

virtual void prepare_bounding_box() = 0#

Protected Attributes

std::shared_ptr<AttributeSet> m_attributes#
bool m_bounding_box_prepared = false#
double m_gradient_epsilon = 1e-4#
glm::vec3 m_max#
glm::vec3 m_min#
double m_sample_bandwidth = 1.0#

Protected Static Functions

static DiagramAttributeArtifact make_diagram_attribute(const std::string &name, const std::shared_ptr<Attribute> &attribute)#
struct DiagramAttributeArtifact#
#include <node.h>

Public Members

std::string name#
Attribute::ReturnType return_type = Attribute::ReturnType::none#
std::string volume_type_name#
struct DiagramChildLink#
#include <node.h>

Public Members

const Node *child = nullptr#
std::string edge_label#
class Leaf : public Node#
#include <leaf.h>

A leaf node that cannot have any children.

Subclassed by CAD, Cone, Cylinder, Function, GraphLattice, Map, Mesh, PolygonExtrude, RectPrism, SignedDistanceField, Sphere, Strut, Text, Torus

Public Functions

virtual std::vector<Node::DiagramChildLink> diagram_child_links() const override#

See also

Node::diagram_child_links()

Leaf() = default#

Default constructor.

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

See also

Node::prepare()

class Unary : public Node#
#include <unary.h>

A node with a single child.

Subclassed by AttributeModifier, Convolve, Identity, Offset, Rotate, Scale, Shell, Tile, Translate

Public Functions

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

See also

Node::attribute_list()

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<Node::DiagramChildLink> diagram_child_links() const override#

See also

Node::diagram_child_links()

virtual std::optional<double> evaluate(double x, double y, double z) override#

See also

Node::evaluate()

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

See also

Node::prepare()

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

See also

Node::sample()

void setChild(std::shared_ptr<Node> child)#

Sets the one and only child of this node.

Parameters:

child – The one and only child of this node.

Unary() = default#

Default constructor.

explicit Unary(const std::shared_ptr<Node> &child)#

\breif Constructor to fill the single child.

Parameters:

child – The one and only child of this node.

Protected Functions

void clone_child(const std::shared_ptr<Unary> &clone) const#

Clones the child of this node.

Parameters:

clone – The clone of this node.

virtual void prepare_bounding_box() override#

Protected Attributes

std::shared_ptr<Node> m_child#

The one and only child of this node.

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 ConformalMap, Difference

Public Functions

const std::unordered_map<std::string, std::shared_ptr<AttributeConflictResolver>> &attribute_conflict_resolvers() const#

Retrieves the map of attribute conflict resolvers.

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.

Binary(const std::shared_ptr<Node> &left, const std::shared_ptr<Node> &right)#

\breif Constructor to fill the both children.

Parameters:

  • left – The left child

  • right – The right child

virtual std::vector<Node::DiagramChildLink> diagram_child_links() const override#

See also

Node::diagram_child_links()

std::shared_ptr<Node> leftChild() const#

Returns the left child.

Returns:

The left child

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

See also

Node::prepare()

std::shared_ptr<Node> rightChild() const#

Returns the right child.

Returns:

The right child

void set_attribute_conflict_resolver(const std::string &name, const std::shared_ptr<AttributeConflictResolver> &resolver)#

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.

void setLeftChild(std::shared_ptr<Node> left)#

Sets the left child.

Parameters:

left – The left child

void setRightChild(std::shared_ptr<Node> right)#

Sets the right child.

Parameters:

right – The right child

Protected Functions

virtual void clone_children(const std::shared_ptr<Binary> &node)#

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.

std::shared_ptr<Node> m_left_child#

The left child.

std::shared_ptr<Node> m_right_child#

The right child.

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

virtual bool addChild(std::shared_ptr<Node> child)#

Trys to add a child to the node, if the node is full then it returns 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.

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

See also

Node::attribute_list()

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>> &children()#

Returns the children of the node.

Returns:

The children of the node.

virtual std::vector<Node::DiagramChildLink> diagram_child_links() const override#

See also

Node::diagram_child_links()

N_ary() = default#

Default constructor.

explicit N_ary(const std::vector<std::shared_ptr<Node>> &children)#

\breif 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(const glm::vec3 &voxel_size, double bandwidth) override#

See also

Node::prepare()

void set_attribute_conflict_resolver(const std::string &name, const std::shared_ptr<AttributeConflictResolver> &resolver)#

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

virtual void clone_children(const std::shared_ptr<N_ary> &node)#

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.

std::vector<std::shared_ptr<Node>> m_children#

The children of the node.