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(), bounding_box(), is_in_bbox(), gradient(), or snap(). Behavior is undefined otherwise.

Subclassed by Binary, Leaf, N_ary, Unary

Public Types

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 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::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(), bounding_box(), 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

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

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

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::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

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

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 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::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

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

See also

Node::attribute_list()

virtual std::shared_ptr<Node> child(uint8_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.

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 uint8_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()

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::vector<std::shared_ptr<Node>> m_children: The children of the node.