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

Subclassed by Binary, Leaf, N_ary, Unary

Public Types

typedef openvdb::Vec3dGrid ColorGridType

typedef openvdb::FloatGrid GridType

typedef std::function<void(int)> ProgressCallback

Public Functions

glm::vec4 BlendDistribution(const std::unordered_map<uint8_t, float> &distribution, const std::shared_ptr<MaterialDefs> &material_defs)

virtual std::pair<glm::vec3, glm::vec3> bounding_box() = 0

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::unordered_map<uint8_t, float> distribution(double x, double y, double z) = 0

Returns the material distribution 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:

A list of pairs each containing the material ID and the probability distribution of that material.

std::unordered_map<uint8_t, glm::vec3> distribution_gradient(double x, double y, double z, double delta = 1)

Returns the material distribution gradient at the given point using the central difference method.

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.
delta – The distance to use for the central difference method.

Returns:

A list of pairs each containing the material ID and the gradient of the probability distribution of that material.

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

The distance to the surface at the given point.

void exportRawVoxels(vec3 min, vec3 max, vec3 voxel_size, std::string path)

Samples the node across R^3 by calling the evaluate() function and saves the result as a raw voxel array.

Parameters:

min – The minimum point of the bounding box to sample.
max – The maximum point of the bounding box to sample.
voxel_size – The size of the voxels to sample.
path – The path to save the voxel array to.

inline virtual glm::vec3 gradient(const glm::vec3 &p)

virtual glm::vec3 gradient(double x, double y, double z)

inline double gradientEpsilon() const

float heterogeneity(double x, double y, double z)

Returns a number on the range [0, 1] that represents the heterogeneity of the material distribution at the given point.

A value of 0 means that the material distribution is homogeneous (composed completely of a single channel), while a value of 1 means that the material distribution is heterogeneous (even distribution across all channels).

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:

A value on the range [0, 1] that represents the heterogeneity of the material distribution.

virtual std::vector<uint8_t> material_list() = 0

Returns a list of all the materials used by the node and its children.

Returns:: A list of all the material IDs used by the node and its children.

Node(): Constructor.

virtual void prepare(const glm::vec3 &voxel_size, double interior_bandwidth, double exterior_bandwidth) = 0: Performs any single-run operations that needs to be done before the tree is evaluated.

std::vector<glm::vec3> sample_points_color(std::vector<glm::vec3> points, std::shared_ptr<MaterialDefs> material_defs, const glm::vec3 &voxel_size, ProgressCallback progress = nullptr)

void saveVDBGrids(vec3 min, vec3 max, vec3 voxel_size, std::string path)

Calls toVDBLevelSet() and toVDBMaterialGrid() and saves the grids to a single file.

Parameters:

min – The minimum point of the bounding box to sample.
max – The maximum point of the bounding box to sample.
voxel_size – The size of the voxels to sample.
path – The path to save the grid to.

void saveVDBLevelSet(vec3 min, vec3 max, vec3 voxel_size, std::string path)

Calls toVDBLevelSet() and saves the grid to file.

Parameters:

min – The minimum point of the bounding box to sample.
max – The maximum point of the bounding box to sample.
voxel_size – The size of the voxels to sample.
path – The path to save the grid to.

void saveVDBMaterialGrid(vec3 min, vec3 max, vec3 voxel_size, std::string path)

Calls toVDBMaterialGrid() and saves the grid to file.

Parameters:

min – The minimum point of the bounding box to sample.
max – The maximum point of the bounding box to sample.
voxel_size – The size of the voxels to sample.
path – The path to save the grid to.

inline void setGradientEpsilon(double eps)

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::tuple<size_t, size_t, size_t, std::vector<uint8_t>> toRGBAArray(const glm::vec3 &voxel_size, std::shared_ptr<MaterialDefs> material_defs, bool blend = true, ProgressCallback progress = nullptr)

std::tuple<size_t, size_t, size_t, std::vector<float>> toSignedDistanceArray(const glm::vec3 &voxel_size, ProgressCallback progress = nullptr)

std::pair<ColorGridType::Ptr, GridType::Ptr> toVDBColorGrid(vec3 min, vec3 max, vec3 voxel_size, std::shared_ptr<MaterialDefs> material_defs, bool use_blending = true)

Samples the tree and returns the result as OpenVDB Color and Alpha grids.

The color grid contains the material colors (RGB) and the alpha grid contains opacity values.

Parameters:

min – The minimum point of the bounding box to sample.
max – The maximum point of the bounding box to sample.
voxel_size – The size of the voxels to sample.
material_defs – The material definitions to use for the color grid.

Returns:

A pair containing the color grid and the alpha grid.

GridType::Ptr toVDBLevelSet(vec3 min, vec3 max, vec3 voxel_size)

Samples the node across R^3 by calling the evaluate() function and returns the result as a VDB grid.

Parameters:

min – The minimum point of the bounding box to sample.
max – The maximum point of the bounding box to sample.
voxel_size – The size of the voxels to sample.

Returns:

The VDB grid containing the sampled values as a level set.

GridType::Ptr toVDBMaterialGrid(vec3 min, vec3 max, vec3 voxel_size)

Samples the node across R^3 by calling the material() function and returns the result as a VDB grid.

Parameters:

min – The minimum point of the bounding box to sample.
max – The maximum point of the bounding box to sample.
voxel_size – The size of the voxels to sample.

Returns:

The VDB grid containing the sampled values as a material grid.

virtual const std::string type() = 0

Returns the named type of the node.

This is either n_ary, binary, unary, or leaf.

Returns:: The named type of the node.

Protected Attributes

double m_gradient_epsilon = 1e-4

Private Functions

glm::vec4 sample_color(const std::shared_ptr<Node> &root, const glm::vec3 &p, const std::shared_ptr<MaterialDefs> &material_defs, const glm::vec3 &voxel_size)

namespace glm

class Leaf : public Node 

#include <leaf.h>

A leaf node that cannot have any children.

Subclassed by CAD, Cylinder, Function, GraphLattice, Map, Mesh, PointMap, PolygonExtrude, RectPrism, SignedDistanceField, Sphere, Strut, Text, Voxels

Public Functions

Leaf() = default: Default constructor.

virtual void prepare(const glm::vec3 &voxel_size, double interior_bandwidth, double exterior_bandwidth)

See also

Node::prepare()

Note

The leaf node does not need to prepare any child nodes, so this function is empty unless overridden.

virtual const std::string type() override

See also

Node::type()

class Unary : public Node 

#include <unary.h>

A node with a single child.

Subclassed by Blend, Convolution, FGrade, Offset, Rotate, Scale, Shell, Tile, Translate

Public Functions

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 void prepare(const glm::vec3 &voxel_size, double interior_bandwidth, double exterior_bandwidth) override

See also

Node::prepare()

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.

virtual const std::string type() override

See also

Node::type()

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

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 interior_bandwidth, double exterior_bandwidth)

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

virtual const std::string type() override

See also

Node::type()

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

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.

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.

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 interior_bandwidth, double exterior_bandwidth) override

See also

Node::prepare()

virtual const std::string type() override

See also

Node::type()

Protected Attributes

std::vector<std::shared_ptr<Node>> m_children: The children of the node.