Tree — composition#

Transforms, boolean CSG, and other composition operators.

Transforms and warps#

class Identity : public Unary#
#include <identity.h>

A pass-through identity node that implements no transformations or operations of its own.

This node operates identically to the base Unary node. Its primary use case is to act as an attachment point for AttributeModifiers without affecting the global coordinate space of the attributes, which is useful when its child node contains an arbitrary transformation.

Public Functions

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

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

Identity() = default#

Default constructor.

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

Constructor with child.

Parameters:

child – The child 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.

class Rotate : public Unary#
#include <rotate.h>

Rotates a child node about the centre of the child’s bounding box by three Euler angles in degrees.

Parameters, always in this order:

  • pitch: angle about the X axis

  • yaw: angle about the Y axis

  • roll: angle about the Z axis

The vec3 constructors pack the same angles as (x, y, z) = (pitch, yaw, roll).

Order: the child is turned by roll about Z first, then by yaw about Y, then by pitch about X. All three turns are about the fixed world axes (through the pivot), so the applied rotation matrix is R = Rx(-pitch) * Ry(-yaw) * Rz(-roll), and a child point c maps to the world point R * (c - p) + p.

Sign: every angle is negated before it is applied, so a positive angle turns the child clockwise when looking from the positive end of its axis toward the origin. This is the opposite of the right-hand rule. For 90 degree turns:

Pivot: the rotation turns about the child’s bounding-box centre p, not about the origin. The pivot is fixed the first time bounding_box() runs, so bounding_box() is safe before prepare(), but you must still call prepare() before evaluate() or sample(). Use Transform to rotate about the origin.

Rotation is an isometry, so the child’s signed distance is returned unchanged and stays exact. The sample point in evaluate() and sample() is mapped back into the child by the inverse rotation about the pivot.

Distance accuracy (distance_accuracy()): an exact child stays exact. A bound child stays a bound only for turns by multiples of 90 degrees; any other turn makes it approximate, because the bounding box is the axis-aligned bounds of the turned child box and a bound only promises the per-axis distance to the child’s own box (see AffineDistance::keeps_axis_alignment()).

Public Functions

inline glm::vec3 angles() const#

Returns the authored Euler angles in degrees (pitch, yaw, roll).

Returns:

The authored Euler angles in degrees (pitch, yaw, roll).

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

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 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, except that a bound child turned off the axes is approximate. An exact child’s value is at least the Euclidean distance to its box, and the turned box lies inside this node’s box, so it stays exact. A bound child only promises the per-axis distance to its own box. Turned by anything but multiples of 90 degrees, a point just off a turned edge can be nearer to the child’s box per child axis than it is to this node’s box per world axis, and the band edge of this node’s box cuts the child’s field off below the band. Approximate also if the child was last prepared with a narrower band than this node.

Returns:

The accuracy of the subtree rooted at this node.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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::shared_ptr<Node> inverse_placement(const std::shared_ptr<Node> &child) override#

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.

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.

glm::dmat4 matrix()#

Returns the 4x4 child-to-world matrix this node applies, pivot included.

The matrix is T(p) * R * T(-p) for column vectors, so world = matrix() * (child, 1). Transform(matrix()) reproduces this node. Needs the child, like pivot().

Returns:

The 4x4 child-to-world matrix this node applies, pivot included.

glm::vec3 pivot()#

Returns the point the rotation turns around.

This is the child’s bounding-box centre, fixed the first time bounding_box() runs.

Returns:

The point the rotation turns around.

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

Rotate keeps this node’s pivot instead of re-centring on the new child.

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.

Rotate() = default#

Default constructor. Defaults to no rotation.

Rotate(double pitch, double yaw, double roll)#

Constructor.

Parameters:
  • pitch – Angle in degrees about the X axis, applied last

  • yaw – Angle in degrees about the Y axis, applied second

  • roll – Angle in degrees about the Z axis, applied first

Rotate(double pitch, double yaw, double roll, const std::shared_ptr<Node> &child)#

Constructor with child.

Parameters:
  • pitch – Angle in degrees about the X axis, applied last

  • yaw – Angle in degrees about the Y axis, applied second

  • roll – Angle in degrees about the Z axis, applied first

  • child – Child node

Rotate(glm::vec3 rotation_angles)#

Constructor.

Parameters:

rotation_angles – Euler angles in degrees packed as (pitch, yaw, roll), i.e. about (X, Y, Z)

Rotate(glm::vec3 rotation_angles, const std::shared_ptr<Node> &child)#

Constructor with child.

Parameters:
  • rotation_angles – Euler angles in degrees packed as (pitch, yaw, roll), i.e. about (X, Y, Z)

  • child – Child node

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

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

Public Static Functions

static std::shared_ptr<Rotate> from_axis_angle(const glm::vec3 &axis, double degrees, const std::shared_ptr<Node> &child = nullptr)#

Builds a rotation by an angle about an arbitrary axis through the pivot, using the right-hand rule.

A positive angle turns counter-clockwise when looking from the tip of the axis toward the origin, so from_axis_angle((0, 0, 1), 90) sends +X to +Y. The equivalent (pitch, yaw, roll) are stored, so angles() reports them.

Parameters:
  • axis – Rotation axis; it does not need to be unit length.

  • degrees – Angle in degrees.

  • child – Child node, or nullptr to set it later.

Throws:

std::runtime_error – if the axis is zero or not finite, or the angle is not finite.

Returns:

The new Rotate node.

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

void set_rotation(const glm::quat &rotation)#

Sets the rotation from a quaternion and stores the matching (pitch, yaw, roll).

void set_rotation(double pitch, double yaw, double roll)#
glm::vec3 to_child(double x, double y, double z) const#

Maps a world point into the child by the inverse rotation about the pivot.

Private Members

glm::vec3 m_angles = glm::vec3(0.0f)#

The authored Euler angles in degrees.

glm::vec3 m_around = glm::vec3(0.0f, 0.0f, 0.0f)#

Point around which the rotation is performed.

std::optional<glm::vec3> m_fixed_pivot#

Pivot to use instead of the child bounding-box centre (set by rebind_child and inverse_placement).

glm::quat m_inverse_rotation = glm::quat(1.0f, 0.0f, 0.0f, 0.0f)#

Inverse rotation quaternion.

glm::quat m_rotation = glm::quat(1.0f, 0.0f, 0.0f, 0.0f)#

Rotation quaternion.

Private Static Functions

static glm::vec3 angles_from_rotation(const glm::quat &rotation)#

Recovers (pitch, yaw, roll) in degrees such that set_rotation(pitch, yaw, roll) gives this rotation.

class Scale : public Unary#
#include <scale.h>

Scales a child node about the origin, uniformly or per axis.

This node is unary, therefore can only have one child.

The scale is applied when evaluate() is called by mapping the query point into the child’s local coordinates, (x / sx, y / sy, z / sz), and converting the returned signed distance back into world units.

Uniform scaling (one factor, or three equal factors) is exact: the child’s distance is multiplied by the factor, so a true signed distance field stays a true signed distance field.

Non-uniform scaling (different factors per axis) is allowed but warps the distance field, so use it with caution. Equal distances in the child become ellipsoids in the world, and no formula that only sees the child’s value can recover the exact world distance. This node returns the first-order estimate d / |S^-1 n|, where d is the child’s value, n its unit gradient direction (central differences in child space) and S = diag(sx, sy, sz). The estimate is exact on planar faces, exact to first order at the surface, and always lies between d * min(s) and d * max(s). It drifts from the true distance far from curved surfaces, so nodes that read distances away from the surface (Offset, Shell, distance-driven attributes, smooth blends) give approximate results. The sign, and therefore the surface itself, is always exact. Each evaluation costs about seven child evaluations instead of one.

Distance accuracy (distance_accuracy()): a uniform scale keeps the child’s accuracy and Lipschitz bound; a non-uniform scale is approximate, since its gradient direction can switch between faces and the estimate then jumps.

Public Functions

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

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 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 for a uniform scale; approximate for a non-uniform one. A uniform scale s returns s f(p / s): the band-clipped value is the child’s, clipped to T / s, stretched by s in both value and space, so its Lipschitz bound is unchanged, and the box and its per-axis distance scale by s too. That needs the child prepared with a band of at least T / s, which

prepare() gives it; if the child was last prepared with less (a child shared with another parent) this is approximate. A non-uniform scale returns the first-order estimate, whose finite-difference direction switches between faces on the child’s medial surfaces, so the value jumps there: approximate.

Returns:

The accuracy of the subtree rooted at this node.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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.

double factor() const#

Returns the authored uniform scale factor.

Throws:

std::runtime_error – if the scale is non-uniform; use factors() instead.

Returns:

The authored uniform scale factor.

inline glm::dvec3 factors() const#

Returns the per-axis scale factors (sx, sy, sz).

Returns:

The per-axis scale factors (sx, sy, sz).

virtual std::shared_ptr<Node> inverse_placement(const std::shared_ptr<Node> &child) override#

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_uniform() const#

Returns true if all three factors are equal, so the signed distance is exact.

Returns:

True if all three factors are equal, so the signed distance is exact.

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 for a uniform scale (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.

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) final#

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

Scale() = default#

Default constructor. Sets the scale to 1.0.

Scale(double scale)#

Constructor.

Sets the uniform scale.

Parameters:

scale – The positive uniform scale factor.

Throws:

std::runtime_error – if scale is not positive and finite.

Scale(double scale, const std::shared_ptr<Node> &child)#

Constructor with child.

Sets the uniform scale and child.

Parameters:
  • scale – The positive uniform scale factor.

  • child – The child node.

Throws:

std::runtime_error – if scale is not positive and finite.

Scale(double x, double y, double z)#

Constructor.

Sets a per-axis, possibly non-uniform, scale.

Unequal factors warp the signed distance field; see the class details.

Parameters:
  • x – The positive scale factor along X.

  • y – The positive scale factor along Y.

  • z – The positive scale factor along Z.

Throws:

std::runtime_error – if any factor is not positive and finite.

Scale(double x, double y, double z, const std::shared_ptr<Node> &child)#

Constructor with child.

Sets a per-axis, possibly non-uniform, scale and child.

Unequal factors warp the signed distance field; see the class details.

Parameters:
  • x – The positive scale factor along X.

  • y – The positive scale factor along Y.

  • z – The positive scale factor along Z.

  • child – The child node.

Throws:

std::runtime_error – if any factor is not positive and finite.

Protected Functions

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 child; when shrinking, its bandwidth is widened to bandwidth / min(s). The child returns no value farther than its bandwidth, in its own units, outside its bounding box. Scaled down, that would be closer than this node’s bandwidth in world units, and a union around it would then report a farther sibling’s distance instead. Scales of 1 or more keep the bandwidth as it is. Also sets the finite-difference step used by the non-uniform distance estimate.

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

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

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

double world_distance(const glm::dvec3 &child_point, double child_value)#

Converts a child value at a child-space point into world units.

Private Members

double m_child_step = 1e-4#

Finite-difference step in child units for the non-uniform distance estimate.

glm::dvec3 m_factors = glm::dvec3(1.0)#

The positive per-axis scale factors.

class Translate : public Unary#
#include <translate.h>

Translate a child in cartesian space by a given amount.

This node is unary, so it may only have one child.

This node performs the inverse translation on the coordinates passed to evaluate() and sample().

Public Functions

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

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 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: a translation moves the value, the box and the band edge together. Approximate if the child was last prepared with a narrower band than this node (a child shared with another parent), since this node would then cut it off early.

Returns:

The accuracy of the subtree rooted at this node.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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::shared_ptr<Node> inverse_placement(const std::shared_ptr<Node> &child) override#

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.

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 glm::vec3 offset() const#

Returns the authored translation offset.

Returns:

The authored translation offset.

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.

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) final#

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

Translate() = default#

Default constructor. Sets the translation to 0, 0, 0.

Translate(double x, double y, double z)#

Constructor.

Sets the translation to the given values.

Parameters:
  • x – The amount to translate in the x direction.

  • y – The amount to translate in the y direction.

  • z – The amount to translate in the z direction.

Translate(double x, double y, double z, const std::shared_ptr<Node> &child)#

Constructor.

Sets the translation to the given values and sets the child.

Parameters:
  • x – The amount to translate in the x direction.

  • y – The amount to translate in the y direction.

  • z – The amount to translate in the z direction.

  • child – The child to set.

Private 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

double m_x = 0#

The amount to translate in the x direction.

double m_y = 0#

The amount to translate in the y direction.

double m_z = 0#

The amount to translate in the z direction.

class Transform : public Unary#
#include <transform.h>

Places a child with a full 4x4 affine matrix in one step.

This node is unary, so it may only have one child.

Convention: points are column vectors and the matrix maps child coordinates to world coordinates, world = M * (x, y, z, 1). The matrix acts about the origin (unlike Rotate, which turns about the child’s bounding-box centre). Compose the usual way, M = T * R * S, to scale first, then rotate, then translate. The translation is the last column, M[3] in GLM’s column-major storage. The bottom row must be (0, 0, 0, 1) and the upper-left 3x3 block A must be invertible; reflections (det A < 0) are allowed. shear() and shear_matrix() build a shear.

Distance: if A is a rotation or reflection times a uniform scale s (A^T A = s^2 I), the child’s distance is multiplied by s and stays exact. Otherwise A stretches space unevenly and the signed distance field is warped, so use it with caution. The node then returns the first-order estimate d / |A^-T n|, with d the child’s value and n its unit gradient direction in child space, exactly like a non-uniform Scale. It is exact on planar faces, exact to first order at the surface, and always lies between d times the smallest and the largest singular value of A, but it drifts from the true distance far from curved surfaces. The sign, and so the surface itself, is always exact. That path costs about seven child evaluations per evaluation.

Distance accuracy (distance_accuracy()): a similarity keeps an exact child exact, and keeps a bound child a bound only when it maps the axes onto the axes (turns by multiples of 90 degrees, axis reflections). Any other matrix is approximate.

Public Functions

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

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 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 through a similarity; approximate otherwise. A similarity A = s Q returns s f(A^-1 (p - t)), which keeps the child’s Lipschitz bound when the child is prepared with a band of at least T / s (

prepare() does this). An exact child stays exact: its value is at least the Euclidean distance to its box, whose image lies inside this node’s box. A bound child only promises the per-axis distance to its own box, which survives only if Q maps the axes onto the axes; otherwise the axis-aligned bounds of the mapped box break that promise, so it is approximate. A matrix that is not a similarity returns the first-order estimate, which jumps where the child’s gradient direction switches between faces: approximate. Approximate also if the child was last prepared with a narrower band than T / s.

Returns:

The accuracy of the subtree rooted at this node.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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.

inline const glm::dmat4 &inverse_matrix() const#

Returns the world-to-child matrix.

Returns:

The world-to-child matrix.

virtual std::shared_ptr<Node> inverse_placement(const std::shared_ptr<Node> &child) override#

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.

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 const glm::dmat4 &matrix() const#

Returns the authored child-to-world matrix.

Returns:

The authored child-to-world matrix.

inline bool preserves_distance() const#

Returns true if the linear part is a rotation or reflection times a uniform scale, so the signed distance is exact.

Returns:

True if the linear part is a similarity.

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.

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) final#

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

Transform() = default#

Default constructor. Sets the identity matrix.

explicit Transform(const glm::dmat4 &matrix)#

Constructor.

Sets the child-to-world matrix.

Parameters:

matrix – The 4x4 affine matrix in GLM’s column-major storage.

Throws:

std::runtime_error – if the matrix is not finite, not affine, or singular.

Transform(const glm::dmat4 &matrix, const std::shared_ptr<Node> &child)#

Constructor with child.

Sets the child-to-world matrix and child.

Parameters:
  • matrix – The 4x4 affine matrix in GLM’s column-major storage.

  • child – The child node.

Throws:

std::runtime_error – if the matrix is not finite, not affine, or singular.

Public Static Functions

static std::shared_ptr<Transform> shear(const glm::dvec3 &direction, const glm::dvec3 &normal, double factor, const std::shared_ptr<Node> &child, const glm::dvec3 &origin = glm::dvec3(0.0))#

Builds a Transform that shears its child; see shear_matrix().

Parameters:
  • direction – The direction points slide in.

  • normal – The normal of the fixed plane, perpendicular to direction.

  • factor – How far a point slides per unit of height above the plane.

  • child – The child node.

  • origin – A point on the fixed plane.

Returns:

The Transform node.

static glm::dmat4 shear_matrix(const glm::dvec3 &direction, const glm::dvec3 &normal, double factor, const glm::dvec3 &origin = glm::dvec3(0.0))#

Builds the matrix of a shear: points slide along a direction in proportion to their height above a plane.

p’ = p + factor * ((p - origin) . n) * d, with d and n the unit direction and normal. Points on the plane through origin with normal n stay put; a point at height h above it moves factor * h along d. factor is the tangent of the shear angle (the tilt of lines that were parallel to n). A shear keeps volume and is not a similarity, so a Transform built from it returns the first-order distance estimate (see the class details).

Parameters:
  • direction – The direction points slide in; normalized internally.

  • normal – The normal of the fixed plane; normalized internally. Must be perpendicular to direction.

  • factor – How far a point slides per unit of height above the plane.

  • origin – A point on the fixed plane.

Throws:

std::runtime_error – if a vector is zero or not finite, direction and normal are not perpendicular, or factor is not finite.

Returns:

The child-to-world matrix.

Protected Functions

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 child; when shrinking, its bandwidth is widened by the smallest stretch of the matrix. Also sets the finite-difference step used by the warped distance estimate.

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

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

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

void set_matrix(const glm::dmat4 &matrix)#
glm::dvec3 to_child(double x, double y, double z) const#

Maps a world point into child coordinates.

double world_distance(const glm::dvec3 &child_point, double child_value)#

Converts a child value at a child-space point into world units.

Private Members

double m_child_step = 1e-4#

Finite-difference step in child units for the warped distance estimate.

glm::dmat4 m_inverse = glm::dmat4(1.0)#

World-to-child matrix.

glm::dmat3 m_inverse_transpose = glm::dmat3(1.0)#

Inverse transpose of the linear part, used by the warped distance estimate.

double m_largest_stretch = 1.0#

Upper bound on the largest singular value of the linear part.

glm::dmat4 m_matrix = glm::dmat4(1.0)#

Child-to-world matrix.

bool m_similarity = true#

True if the linear part is a rotation or reflection times a uniform scale.

double m_similarity_scale = 1.0#

The uniform scale of a similarity; unused otherwise.

double m_smallest_stretch = 1.0#

Lower bound on the smallest singular value of the linear part.

namespace AffineDistance#

Converts a child’s signed distance into world units through a linear map that may stretch space unevenly (a non-uniform Scale, a general Transform, or a map Jacobian).

With A the linear map from child to world coordinates, the child field f evaluated at the mapped point is no longer a world distance: equal child distances become ellipsoids in the world. No formula that only sees f can recover the exact world distance, because that depends on where the child’s closest surface point lies. The first-order estimate f / |A^-T n|, with n the child’s unit gradient direction, is used instead. It is exact for planar surfaces, exact to first order at the zero level set of any surface, and always lies between f times the smallest and the largest stretch of A. Far from a curved surface it under- or over-estimates. The sign, and therefore the surface itself, is always exact.

Functions

glm::dvec3 child_direction(Node &child, const glm::dvec3 &point, double value, double step)#

Unit direction of the child’s field gradient at a child-space point.

Central differences first. On a medial surface of the child (equidistant from two faces) they cancel, so this falls back to one-sided differences, which stay well defined.

Parameters:
  • child – The prepared child node.

  • point – The child-space point.

  • value – The child’s value at point.

  • step – The finite-difference step in child units.

Returns:

The unit direction, or zero if the child is flat there.

double first_order_distance(Node &child, const glm::dvec3 &point, double value, const glm::dmat3 &inverse_transpose, double smallest_stretch, double step)#

First-order world distance of a child value through a linear map.

Parameters:
  • child – The prepared child node.

  • point – The child-space point where the child was evaluated.

  • value – The child’s value at point, treated as a distance in child units.

  • inverse_transpose – The inverse transpose A^-T of the child-to-world linear map.

  • smallest_stretch – A lower bound on the smallest singular value of A, used where the child’s gradient direction is undefined.

  • step – The finite-difference step in child units.

Returns:

value / |A^-T n|, or value * smallest_stretch where n is undefined.

bool keeps_axis_alignment(const glm::dmat3 &matrix, double tolerance = 1e-6)#

True if a linear map sends the coordinate axes onto the coordinate axes with one common stretch.

That is a positive multiple of a signed permutation matrix: a turn by multiples of 90 degrees, a reflection across a coordinate or diagonal plane, a uniform scale, or a product of these. Such a map sends an axis-aligned box onto an axis-aligned box and scales the per-axis (Chebyshev) distance to it by the stretch, so a child value that is at least the per-axis distance to the child’s box stays at least the per-axis distance to the mapped box. A general rotation does not keep that: the axis-aligned bounds of a turned box are larger, but a point off a turned edge can be farther from those bounds per axis than it is from the turned box in the child’s own axes.

Parameters:
  • matrix – The linear map.

  • tolerance – Allowed deviation of each entry, relative to the stretch (absorbs rounding from single-precision rotations).

Returns:

True if the map is axis-aligned in this sense.

double largest_stretch_bound(const glm::dmat3 &matrix)#

Upper bound on the largest singular value of a 3x3 matrix: ||M||_F.

Parameters:

matrix – The matrix.

Returns:

The Frobenius norm of the matrix.

double smallest_stretch_bound(const glm::dmat3 &matrix)#

Lower bound on the smallest singular value of a 3x3 matrix: 1 / ||M^-1||_F.

Parameters:

matrix – The matrix.

Returns:

The bound, or 0 for a singular matrix.

class Mirror : public Unary#
#include <mirror.h>

Unary node that reflects child geometry across a plane.

A world sample point \(p\) is reflected across the configured plane before evaluating the child. The original child geometry is not retained; use Union(child, Mirror(..., child)) if both the source and reflected copy are desired.

Distance accuracy (distance_accuracy()): a reflection is an isometry, so an exact child stays exact. A bound child stays a bound across a coordinate plane (or a diagonal plane that swaps two axes) and is approximate across any other plane.

Note

As for every node, call prepare() on the root before evaluate() or sample(); bounding_box() is safe before it.

Public Functions

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

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 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, except that a bound child reflected off the axes is approximate. An exact child’s value is at least the Euclidean distance to its box, and the reflected box lies inside this node’s box, so it stays exact. A bound child only promises the per-axis distance to its own box; that survives only a reflection that maps the axes onto the axes (see

AffineDistance::keeps_axis_alignment()). Approximate also if the child was last prepared with a narrower band than this node.

Returns:

The accuracy of the subtree rooted at this node.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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::shared_ptr<Node> inverse_placement(const std::shared_ptr<Node> &child) override#

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.

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.

Mirror() = default#

Default constructor. Reflects across the x=0 plane.

Mirror(const glm::vec3 &p0, const glm::vec3 &p1, const glm::vec3 &p2)#

Constructor.

Reflects across a plane defined by three non-collinear points.

Parameters:
  • p0 – The first point on the mirror plane.

  • p1 – The second point on the mirror plane.

  • p2 – The third point on the mirror plane.

Mirror(const glm::vec3 &p0, const glm::vec3 &p1, const glm::vec3 &p2, const std::shared_ptr<Node> &child)#

Constructor.

Reflects a child across a plane defined by three non-collinear points.

Parameters:
  • p0 – The first point on the mirror plane.

  • p1 – The second point on the mirror plane.

  • p2 – The third point on the mirror plane.

  • child – The child node.

Mirror(const glm::vec3 &point, const glm::vec3 &normal)#

Constructor.

Reflects across a plane defined by one point and a normal.

Parameters:
  • point – A point on the mirror plane.

  • normal – The mirror plane normal. The vector is normalized internally.

Mirror(const glm::vec3 &point, const glm::vec3 &normal, const std::shared_ptr<Node> &child)#

Constructor.

Reflects a child across a plane defined by one point and a normal.

Parameters:
  • point – A point on the mirror plane.

  • normal – The mirror plane normal. The vector is normalized internally.

  • child – The child node.

explicit Mirror(const std::string &axis)#

Constructor.

Reflects across a coordinate plane through the origin.

Parameters:

axis – The axis name.

Mirror(const std::string &axis, const std::shared_ptr<Node> &child)#

Constructor.

Reflects a child across a coordinate plane through the origin.

Parameters:
  • axis – The axis name.

  • child – The child node.

Mirror(const std::string &axis, double offset)#

Constructor.

Reflects across an offset coordinate plane.

Parameters:
  • axis – The axis name.

  • offset – The coordinate value of the mirror plane on the selected axis.

Mirror(const std::string &axis, double offset, const std::shared_ptr<Node> &child)#

Constructor.

Reflects a child across an offset coordinate plane.

Parameters:
  • axis – The axis name.

  • offset – The coordinate value of the mirror plane on the selected axis.

  • child – The child node.

inline glm::vec3 plane_normal() const#

Returns the unit normal of the mirror plane.

Returns:

The unit normal of the mirror plane.

inline glm::vec3 plane_point() const#

Returns the authored point on the mirror plane.

Returns:

The authored point on the mirror plane.

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.

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) final#

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

Private Functions

glm::dvec3 map_to_child_space(double x, double y, double z) const#

Maps world coordinates into child space by reflecting across the mirror plane.

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

void set_axis_plane(const std::string &axis, double offset)#

Sets the mirror plane from a coordinate axis and offset.

void set_plane(const glm::vec3 &point, const glm::vec3 &normal)#

Sets and validates the mirror plane from a point and normal.

void set_plane_from_points(const glm::vec3 &p0, const glm::vec3 &p1, const glm::vec3 &p2)#

Sets and validates the mirror plane from three points.

Private Members

glm::vec3 m_plane_normal = glm::vec3(1.0f, 0.0f, 0.0f)#

Unit normal of the mirror plane.

glm::vec3 m_plane_point = glm::vec3(0.0f)#

A point on the mirror plane.

Private Static Functions

static bool is_finite_vec3(const glm::vec3 &value)#

Returns whether a vector’s components are finite.

class MappedNode : public Unary#
#include <mapped_node.h>

Wraps any child node through a CellMap, so geometry designed in a flat box follows a curved, conformal map.

A world point inside the active map domain is inverted to logical map coordinates (u, v, w), scaled to child coordinates c = (u * s_u, v * s_v, w * s_w), and the child is evaluated at c. With Space::physical the scale s is the map’s average size of one logical unit in millimetres along each axis, so the child is authored in approximate millimetres: the child box [0, nu * s_u] x [0, nv * s_v] x [0, nw * s_w] covers the whole map (see child_bounds()). With Space::logical the scale is 1 and the child is authored directly in logical cell units. An explicit per-axis scale may also be given.

Distance: the child’s value is converted to world units with the local map Jacobian. With M = J * diag(1 / s) the derivative of world position with respect to child coordinates, the returned value is the first-order estimate d / |M^-T n|, where d is the child’s value, treated as a distance in child units, and n its unit gradient direction (central differences, or one-sided differences on a medial surface where central differences cancel). The estimate therefore always lies between d times the smallest and the largest stretch of M. It is accurate near the zero level set (the surface that is meshed), so it is safe within a narrow band of a few voxels, but it is an approximation, not a true distance: far from the surface the curvature of the map makes it under- or over-estimate. Where the child has no value (beyond its prepared bounding box) a conservative lower bound from the child’s box distance and a lower bound on the smallest singular value of M is returned instead. distance_accuracy() is approximate.

Domain: the mapped child exists only inside the active map domain. Outside it, or in trimmed regions and holes, the node returns the positive distance to the domain, and inside it the field is clipped with the domain distance, exactly as mapped lattices are. set_clip_to_domain(false) skips that clipping inside the domain, so a wrapped box keeps its own depth there: use it when the node marks a zone of the map (a region for zones, overlap bands or blends) rather than a solid that should end at the domain. Periodic map directions wrap, so a child crossing the seam is cut there.

prepare() prepares the child with the voxel size and bandwidth converted to child coordinates.

Public Types

enum class Space#

Child coordinate convention.

Values:

enumerator physical#

Logical coordinates scaled by the map’s average millimetres per unit.

enumerator logical#

Raw logical coordinates in cell units.

Public Functions

inline const std::shared_ptr<CellMap> &cell_map() const#

Returns the immutable map the child follows.

Returns:

The immutable map the child follows.

std::pair<glm::vec3, glm::vec3> child_bounds() const#

Returns the child-space box that covers the whole logical map domain.

Returns:

(0, 0, 0) and the map’s cell counts multiplied by scale().

inline bool clip_to_domain() const#

Whether the field is clipped with the domain distance inside the domain.

Returns:

True if clipping is on (the default).

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

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

How faithfully the value of the whole subtree matches the true distance: always approximate. The value is the first-order estimate, which can exceed the true distance away from the surface. Its transitions are not continuous either: beyond the child’s prepared box the fallback scales by 1 / |M^-1|_F, which is at most the smallest stretch of M and only 1 / sqrt(3) of it where M stretches evenly, so the clipped field drops there; and just outside the active domain the domain distance (near 0) replaces whatever the mapped child gave just inside.

Returns:

The accuracy of the subtree rooted at this node.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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.

MappedNode(const std::shared_ptr<CellMap> &cell_map, const std::shared_ptr<Node> &child, const glm::vec3 &scale)#

Wraps a child through a map with an explicit child scale.

Parameters:
  • cell_map – The validated map to follow.

  • child – The node evaluated in child coordinates.

  • scale – Positive child units per logical unit along U, V, and W.

MappedNode(const std::shared_ptr<CellMap> &cell_map, const std::shared_ptr<Node> &child, Space space = Space::physical)#

Wraps a child through a map using a named child coordinate space.

Parameters:
  • cell_map – The validated map to follow.

  • child – The node evaluated in child coordinates.

  • space – The child coordinate convention.

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 TreeSample sample_impl(double x, double y, double z) final#

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

inline const glm::vec3 &scale() const#

Returns the child units per logical unit along U, V, and W.

Returns:

The child units per logical unit along U, V, and W.

inline void set_clip_to_domain(bool clip)#

Clip (true, the default) or keep the child’s own depth inside the domain.

Parameters:

clip – True to clip with the domain distance.

inline Space space() const#

Returns the child coordinate convention.

Returns:

The child coordinate convention.

std::optional<glm::vec3> to_child(const glm::vec3 &world) const#

Maps a world point into child coordinates.

Parameters:

world – World-space point.

Returns:

Child coordinates, or std::nullopt outside the active map domain.

Public Static Functions

static glm::vec3 physical_scale(const CellMap &cell_map)#

Returns the average millimetres per logical unit of a map along U, V, and W.

Averages the Jacobian column lengths at the centres of all active cells.

Parameters:

cell_map – The map to measure.

Returns:

The average millimetres per logical unit along U, V, and W.

Private Functions

std::optional<double> mapped_value(const glm::vec3 &world, glm::vec3 &child_point, bool &located)#

Evaluates the mapped field and reports the child point it used.

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<CellMap> m_cell_map#
double m_child_bandwidth = 0.0#
double m_child_step = 1e-4#
bool m_clip_to_domain = true#
glm::vec3 m_physical_scale = {1.0f}#
glm::vec3 m_scale = {1.0f}#
Space m_space = Space::physical#
class Warp : public Unary#
#include <warp.h>

Deforms space: the child is sampled at g(p), where a WarpMap g pulls each world point back to the child point it came from.

Attributes (pull-back): the child’s attributes are sampled at g(p), so material follows the deformation. The map’s natural coordinates are available as fields through coordinate_field(): “child_x”, “child_y”, “child_z” for every map, plus the map’s own (for example the twist angle).

Distance: the child’s value f at g(p) is converted to world units with the map’s Jacobian J = dg/dp. With A = J^-1 the local child-to-world map, the value is the first-order estimate f / |J^T n| from AffineDistance (n is the child’s unit gradient direction), as MappedNode and a non-uniform Scale use. The surface is exact; the value is accurate near it and an approximation far from it. Built-in maps have analytic Jacobians; a field map takes central differences, which costs six more map evaluations per point. With a Lipschitz bound L on g (|g(p) - g(q)| <= L |p - q|), the value is f / L instead, never larger than the true distance inside the box for an exact child. Beyond the child’s prepared box the conservative fallback of MappedNode is used: the child’s box distance plus bandwidth, times a lower bound on the stretch of A, or divided by L with a bound. distance_accuracy() is approximate either way, because f / L can fall below the distance to the box just outside it (see there).

Bounding box: a warp moves material, so the box comes from explicit bounds or from the map’s world_bounds() of the child’s box. A map that cannot bound its image (a field map) needs explicit bounds.

prepare() estimates the largest stretch of g over the box (from L, or by sampling the Jacobian) and prepares the child with the bandwidth widened by it. It then lets the map check itself against the prepared child (WarpMap::prepare()).

Public Types

typedef WarpMap::Box Box#

An axis-aligned box as (minimum, maximum).

Public Functions

inline const std::optional<Box> &bounds() const#

Returns the explicit bounds, or std::nullopt when the box comes from the map.

Returns:

The explicit bounds, or std::nullopt when the box comes from the map.

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

std::shared_ptr<FloatAttribute> coordinate_field(const std::string &name) const#

Returns a field for one of the map’s coordinates, defined everywhere in space.

Parameters:

name – “child_x”, “child_y”, “child_z”, or one of the map’s own coordinates.

Throws:

std::runtime_error – listing the valid names when the name is unknown.

Returns:

A CoordinateFieldAttribute over a copy of the map.

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.

How faithfully the value of the whole subtree matches the true distance: always approximate. Without a Lipschitz bound on g the value is the first-order estimate, which can exceed the true distance away from the surface. With a bound L the value f / L is Lipschitz inside the box grown by the bandwidth (the child is prepared with the bandwidth times max(1, L), and the fallback beyond the child’s box clips to the bandwidth like the child’s own “no value”), but nothing keeps it at least the per-axis distance to the box just outside the box: maps that keep lengths across a face the child reaches (the height of a twist or taper, the depth of a bend or wrap) give the distance divided by L there. Where that is still below the bandwidth at the edge of the box grown by the bandwidth, the clipped field jumps to the bandwidth (no value), which no Lipschitz bound covers. See deforming_space_architecture.md.

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.

inline size_t failed_inversions() const#

Number of points whose pull-back failed to converge (displacements only), summed over every clone that shares this node’s map.

Returns:

The number of failed pull-backs.

inline const std::optional<double> &lipschitz() const#

Returns the Lipschitz bound on g, if one was given.

Returns:

The Lipschitz bound on g, if one was given.

inline const std::shared_ptr<WarpMap> &map() const#

Returns the map.

Returns:

The map.

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

Warp(const std::shared_ptr<Vec3Attribute> &map, const std::shared_ptr<Node> &child, const Box &bounds, const std::optional<double> &lipschitz = std::nullopt)#

Constructor from a vector field: g(p) is the field’s value at p (sampled with d = 0).

Parameters:
  • map – The vector field.

  • child – The child node.

  • bounds – The world box of the warped child.

  • lipschitz – Optional Lipschitz bound L on g; when given, the value is f / L instead of the first-order estimate. distance_accuracy() is still approximate (see the class notes).

Throws:

std::runtime_error – on invalid input.

Warp(const std::shared_ptr<WarpMap> &map, const std::shared_ptr<Node> &child, const std::optional<Box> &bounds = std::nullopt, const std::optional<double> &lipschitz = std::nullopt)#

Constructor from any map.

Parameters:
  • map – The map g from world points to child points.

  • child – The child node.

  • bounds – The world box of the warped child; std::nullopt to use the map’s own bounds.

  • lipschitz – Optional Lipschitz bound L on g; when given, the value is f / L instead of the first-order estimate. distance_accuracy() is still approximate (see the class notes).

Throws:

std::runtime_error – if map or child is null, the bounds are invalid, lipschitz is not positive and finite, or no bounds are given and the map has none.

Public Static Functions

static std::shared_ptr<Warp> bend(double radius, const std::shared_ptr<Node> &child, const glm::dvec3 &origin = glm::dvec3(0.0), const glm::dvec3 &direction = glm::dvec3(1.0, 0.0, 0.0), const glm::dvec3 &axis = glm::dvec3(0.0, 1.0, 0.0))#

Bends the child around an axis (BendMap).

The line through origin along direction is bent into a circle of radius |radius| about an axis parallel to axis: toward direction x axis for a positive radius, away for a negative one. Arc length along that line is kept (it is the neutral surface), and the child stays put at the origin. Valid while, on the side it curls toward, the child stays closer to the line than |radius| (farther would pass the bend centre and fold), and within half a turn each way (|length along direction| < pi |radius|). Coordinates: “angle” (degrees, zero at the origin) and “radius” (distance from the bend’s centre line). The box is the exact annular sector holding the child.

Parameters:
  • radius – The bend radius; non-zero, its sign picks the bend side.

  • child – The child node.

  • origin – A point on the line that is bent; it stays put.

  • direction – The direction of the line that is bent.

  • axis – The direction of the bend axis; made perpendicular to direction.

Throws:

std::runtime_error – if the child is null, the radius is zero or not finite, or the directions are zero or parallel.

Returns:

The Warp node.

static std::shared_ptr<Warp> displace(const std::shared_ptr<Vec3Attribute> &displacement, const std::shared_ptr<Node> &child, const std::optional<Box> &bounds = std::nullopt)#

Moves the child’s material by a displacement field (DisplacementMap).

Material at X moves to X + u(X). u is sampled at the undeformed point X, in the child’s coordinates, and is a vector in those coordinates (the Warp’s own: world, when the Warp is the root). The pull-back solves X + u(X) = p by fixed-point iteration, then Newton steps; prepare() throws if u folds material onto itself, and points that fail to converge are counted (failed_inversions()). Coordinate: “displacement” (|u|).

Parameters:
  • displacement – The displacement field u, sampled with d = 0.

  • child – The child node.

  • bounds – The world box of the moved child; std::nullopt to estimate it by sampling u.

Throws:

std::runtime_error – if displacement or child is null.

Returns:

The Warp node.

static std::shared_ptr<Warp> displace(const std::string &attribute_name, const std::shared_ptr<Node> &child, const std::optional<Box> &bounds = std::nullopt)#

Moves the child’s material by a displacement attribute the child already carries.

The attribute must be a Vec3Attribute set on the child node itself. It is sampled directly at the undeformed point, also outside the material, where the child’s tree samples carry no attributes. See displace() for the rest.

Parameters:
  • attribute_name – The name of the child’s displacement attribute.

  • child – The child node.

  • bounds – The world box of the moved child; std::nullopt to estimate it by sampling u.

Throws:

std::runtime_error – if the child has no Vec3Attribute of that name.

Returns:

The Warp node.

static std::shared_ptr<Warp> taper(const ScalarParameter &rate, const std::shared_ptr<Node> &child, const glm::dvec3 &axis = glm::dvec3(0.0, 0.0, 1.0), const glm::dvec3 &origin = glm::dvec3(0.0))#

Tapers the child along an axis (TaperMap).

The section perpendicular to the axis at height h is scaled about the axis by s(h) = 1 + integral of the rate from 0 to h, so a constant rate is a linear taper and s = 1 at the origin. A field rate is read along the axis. Coordinates: “scale” and “height”.

Parameters:
  • rate – The relative scale change per unit length; a constant or a field.

  • child – The child node.

  • axis – The taper axis direction.

  • origin – A point on the axis where the scale is 1.

Throws:

std::runtime_error – if the child is null, the axis is zero, or s reaches zero over the child.

Returns:

The Warp node.

static std::shared_ptr<Warp> twist(const ScalarParameter &rate, const std::shared_ptr<Node> &child, const glm::dvec3 &axis = glm::dvec3(0.0, 0.0, 1.0), const glm::dvec3 &origin = glm::dvec3(0.0))#

Twists the child about an axis (TwistMap).

The section at height h = (p - origin) . axis turns counter-clockwise about the axis by the integral of the rate from 0 to h, so a constant rate is a uniform twist. A field rate is read along the axis and integrated over the child’s axial extent. Coordinates: “angle” (degrees) and “height”. The box is the cylinder about the axis holding the child.

Parameters:
  • rate – The twist rate in degrees per unit length; a constant or a field.

  • child – The child node.

  • axis – The twist axis direction.

  • origin – A point on the axis where the twist angle is zero.

Throws:

std::runtime_error – if the child is null or the axis is zero.

Returns:

The Warp node.

static std::shared_ptr<Warp> wrap_cylinder(double radius, const std::shared_ptr<Node> &child, const glm::dvec3 &center = glm::dvec3(0.0), const glm::dvec3 &axis = glm::dvec3(0.0, 0.0, 1.0), const glm::dvec3 &reference_direction = glm::dvec3(1.0, 0.0, 0.0))#

Wraps a flat design around a cylinder (a BendMap in a flat-design frame).

The child is authored flat: x is arc length around the cylinder, from 0 at the seam (reference_direction) counter-clockwise about axis up to 2 pi radius; y is height along the axis from center; z is height above the cylinder surface (outward). Lengths on the surface are kept. Coordinates: “angle” (degrees from the seam) and “radius” (distance from the axis).

Parameters:
  • radius – The cylinder radius, positive.

  • child – The flat child node.

  • center – A point on the cylinder axis, where y = 0.

  • axis – The cylinder axis direction.

  • reference_direction – The direction of the seam; made perpendicular to axis.

Throws:

std::runtime_error – if the child is null, the radius is not positive, or the directions are zero or parallel.

Returns:

The Warp node.

static std::shared_ptr<Warp> wrap_sphere(double radius, const std::shared_ptr<Node> &child, const glm::dvec3 &center = glm::dvec3(0.0), const glm::dvec3 &north_axis = glm::dvec3(0.0, 0.0, 1.0), const glm::dvec3 &reference_direction = glm::dvec3(1.0, 0.0, 0.0))#

Wraps a flat design onto a sphere (SphereWrapMap).

The child is authored flat: x is arc length along the equator (longitude times radius, from 0 at reference_direction), y is arc length along a meridian (latitude times radius, from the equator), z is height above the sphere surface. Parallels shrink toward the poles, so keep the design away from them. Coordinates: “longitude”, “latitude” (degrees) and “radius”.

Parameters:
  • radius – The sphere radius, positive.

  • child – The flat child node.

  • center – The sphere centre.

  • north_axis – The north direction.

  • reference_direction – The direction of longitude 0; projected onto the equator.

Throws:

std::runtime_error – on invalid input.

Returns:

The Warp node.

Protected Functions

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.

Private Functions

virtual void prepare_bounding_box() override#

Uses the child’s bounding box.

Warp() = default#

Empty node for clone().

double world_distance(const glm::dvec3 &world, const glm::dvec3 &child_point, const std::optional<double> &child_value)#

World value at a world point from the child’s value at its pull-back.

Private Members

std::optional<Box> m_bounds#
double m_child_bandwidth = 0.0#

Bandwidth the child was prepared with, in child units.

double m_child_step = 1e-4#

Finite-difference step for the child’s gradient direction, in child units.

std::optional<double> m_lipschitz#
std::shared_ptr<WarpMap> m_map#
double m_map_step = 1e-3#

Finite-difference step for a map without a closed-form Jacobian, in world units.

class Offset : public Unary#
#include <offset.h>

Moves its child’s surface outward (positive distance) or inward (negative distance).

The value is f - t, where f is the child’s signed distance and t the offset distance. The distance may be a constant or a field (a ScalarParameter), so the offset can vary through space. A field is sampled with the child’s signed distance as d.

Distance accuracy (distance_accuracy(), for the whole subtree): a constant offset of an exact or bound child is a bound with the child’s Lipschitz bound (an offset of an exact distance is exact only on one side of the new surface), outward or inward and for any finite child bound; offset 0 keeps the child’s accuracy. A field offset is an approximation. Its value is divided by 1 + L when the field has a Lipschitz hint L, which keeps the surface and the slope, but the scaled value falls below the distance to the box and short of the bandwidth where the child goes silent.

Attributes: inside the child (removal, or the child’s own material) the child’s attributes apply, with this node’s attributes taking precedence. Material that the offset grows outside the child follows the growth policy: undefined (the default, no attributes), extend (the child’s attributes at its closest surface point) or own (this node’s only). This node’s own attributes (and grown ones) are only evaluated, and attributes only returned, where the offset’s value is 0 or less.

Bounding box: moves out by the largest distance when it is positive. Otherwise it is the child’s box: an inward offset of a child whose value has slope bound L only moves the surface in by |t| / L, so shrinking the box by |t| would cut material. A field distance must have known bounds (ScalarParameter::bounds()).

Public Functions

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

inline const ScalarParameter &distance() const#

Returns the offset distance, a constant or a field.

Returns:

The offset distance, a constant or a field.

virtual DistanceAccuracy distance_accuracy() const override#

How faithfully this offset and its subtree match the true distance (see the class description).

The child is prepared at the bandwidth plus |t|, so the child’s clamped value decides f - t wherever that lies within the bandwidth.

Returns:

The child’s accuracy for offset 0, at best bound otherwise, approximate for a field.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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.

inline GrowthPolicy growth() const#

Returns the growth policy for grown material.

Returns:

The growth policy for grown material.

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

distance_accuracy() is approximate.

Returns:

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

Offset() = default#

Default constructor with zero offset.

Offset(const ScalarParameter &distance, const std::shared_ptr<Node> &child, GrowthPolicy growth = GrowthPolicy::undefined)#

Constructor with a constant or field offset, child and growth policy.

Parameters:
  • distance – The offset distance; positive grows the child. A field must have known bounds.

  • child – The child node.

  • growth – The attributes of grown material.

Throws:

std::runtime_error – if a field distance has no bounds.

explicit Offset(double offset)#

Constructor with a constant offset.

Parameters:

offset – The offset distance; positive grows the child.

Offset(double offset, const std::shared_ptr<Node> &child)#

Constructor with a constant offset and child.

Parameters:
  • offset – The offset distance; positive grows the child.

  • child – The child node.

inline double offset() const#

Returns the constant offset distance (positive grows the child).

Throws:

std::runtime_error – if the distance is a field; use distance() instead.

Returns:

The constant offset distance (positive grows the child).

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

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

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

Private Functions

double offset_value(double x, double y, double z, double child_distance) const#

This node’s value from the child’s value at a point.

Private Members

ScalarParameter m_distance#
double m_distance_scale = 1.0#

1 / (1 + L) for a field with a Lipschitz hint, else 1.

GrowthPolicy m_growth = GrowthPolicy::undefined#
class Shell : public Unary#
#include <shell.h>

A wall of a given thickness that follows its child’s surface.

With f the child’s signed distance and t the thickness, the wall lies

  • inward (the default): inside the child, -t <= f <= 0, value max(f, -f - t);

  • outward: outside the child, 0 <= f <= t, value max(f - t, -f);

  • centered: across the surface, |f| <= t / 2, value |f| - t / 2. The thickness may be a constant or a field (a ScalarParameter), sampled with the child’s signed distance as d. Where a field thickness is zero or negative there is no wall.

Distance accuracy (distance_accuracy(), for the whole subtree): a shell with a constant thickness over an exact or bound child, in any direction, is a bound with the child’s Lipschitz bound. The child is prepared t beyond the bandwidth (t / 2 for centered), which covers every child value the clamped wall depends on: down to -(bandwidth + t) for the inner face of an inward wall, up to bandwidth + t for the outer face of an outward one. A field thickness is an approximation: with a Lipschitz hint L the value is divided by 1 + L (1 + L / 2 when centered), which keeps the slope but falls below the distance to the box.

Attributes: the wall inside the child carries the child’s attributes (removal), with this node’s attributes taking precedence. Wall outside the child (outward and centered shells) is grown material and follows the growth policy. This node’s own attributes (and grown ones) are only evaluated, and attributes only returned, where the wall’s value is 0 or less.

Bounding box: an inward shell keeps the child’s box. Outward and centered shells grow it by the largest t (or t / 2), so a field thickness for them needs known bounds.

The legacy constructors take a negative thickness for an inward shell; they also accept a positive one, which means the same inward shell.

Subclassed by Thicken

Public Types

enum class Direction#

Which side of the child’s surface the wall lies on.

Values:

enumerator inward#

Inside the child.

enumerator outward#

Outside the child.

enumerator centered#

Half inside, half outside.

Public Functions

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

inline Direction direction() const#

Returns which side of the surface the wall lies on.

Returns:

Which side of the surface the wall lies on.

virtual DistanceAccuracy distance_accuracy() const override#

How faithfully this shell and its subtree match the true distance (see the class description).

Returns:

At best bound for a constant thickness; approximate for a field.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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.

inline GrowthPolicy growth() const#

Returns the growth policy for wall outside the child.

Returns:

The growth policy for wall outside the child.

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

distance_accuracy() is approximate.

Returns:

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

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

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

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 Node::TreeSample sample_impl(double x, double y, double z) final#

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

Shell() = default#

Default constructor with no child.

Shell(const ScalarParameter &thickness, const std::shared_ptr<Node> &child, Direction direction = Direction::inward, GrowthPolicy growth = GrowthPolicy::undefined)#

Constructor with a constant or field thickness, child, direction and growth policy.

Parameters:
  • thickness – The positive wall thickness.

  • child – The child node.

  • direction – Which side of the surface the wall lies on.

  • growth – The attributes of wall grown outside the child.

Throws:

std::invalid_argument – if a constant thickness is not positive, if a field’s known bounds are negative, or if an outward or centered field has no known bounds.

explicit Shell(double thickness)#

Constructor with an inward shell thickness (negative, or positive for the same shell).

Parameters:

thickness – The wall thickness; its absolute value is used.

Throws:

std::invalid_argument – if thickness is zero or not finite.

Shell(double thickness, const std::shared_ptr<Node> &child)#

Constructor with an inward shell thickness and child.

Parameters:
  • thickness – The wall thickness; its absolute value is used.

  • child – The child node.

Throws:

std::invalid_argument – if thickness is zero or not finite.

double thickness() const#

Returns the authored constant thickness (negative when built with the legacy negative value).

Throws:

std::runtime_error – if the thickness is a field; use thickness_parameter() instead.

Returns:

The authored constant thickness (negative when built with the legacy negative value).

inline const ScalarParameter &thickness_parameter() const#

Returns the positive thickness, a constant or a field.

Returns:

The positive thickness, a constant or a field.

Protected Functions

void copy_parameters_to(Shell &target) const#

Copies the shell parameters (not the child or attributes) into another shell.

Parameters:

target – The shell to copy into.

Private Functions

double child_band_extent() const#

How far beyond the bandwidth the wall reads its child: the largest t (t / 2 when centered).

double outside_extent() const#

How far the wall can reach outside the child.

double shell_value(double x, double y, double z, double child_distance) const#

This node’s value from the child’s value at a point.

Private Members

Direction m_direction = Direction::inward#
double m_distance_scale = 1.0#

1 / (1 + slope of the thickness term) for a field with a Lipschitz hint, else 1.

GrowthPolicy m_growth = GrowthPolicy::undefined#
bool m_legacy_negative = false#
ScalarParameter m_thickness#
class Thicken : public Shell#
#include <shell.h>

Turns a surface or thin body into a solid of thickness t: the value is |f| - t / 2.

A centered Shell under its own name. Use it on a child whose value is an unsigned distance to a surface (an open sheet), or on a thin body to make it thicker. The thickness may be a field with known bounds. Attributes, accuracy and bounding box follow Shell with Direction::centered: the part inside the child keeps the child’s attributes, the rest is grown material and follows the growth policy.

Distance accuracy: a constant thickness over an exact or bound child is a bound with the child’s Lipschitz bound; a field thickness is an approximation (see Shell).

Public Functions

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

inline 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 a centered

Shell.

Returns:

The accuracy of the subtree rooted at this node.

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

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.

Thicken() = default#
Thicken(const ScalarParameter &thickness, const std::shared_ptr<Node> &child, GrowthPolicy growth = GrowthPolicy::undefined)#

Constructor with a constant or field thickness, child and growth policy.

Parameters:
  • thickness – The positive total thickness. A field needs known bounds.

  • child – The child node.

  • growth – The attributes of material outside the child.

Enums

enum class GrowthPolicy#

What attributes a growth operator gives material its child never had.

Growth operators (positive offsets, outward shells, thickening) create material outside their child. Inside the child they always report the child’s attributes; this policy only decides the grown region.

Values:

enumerator undefined#

No attributes in grown material (the historical Offset behaviour).

enumerator extend#

The child’s attributes at its closest surface point, so material carries straight outward.

enumerator own#

Only the operator’s own attributes.

Functions

std::string growth_policy_name(GrowthPolicy policy)#

Lower-case name of a growth policy (“undefined”, “extend” or “own”), for properties and messages.

namespace GrowthAttributes#

The one sampling path every growth operator uses for its grown material.

Functions

std::optional<AttributeSamples> closest_child_samples(Node &child, double x, double y, double z, double child_distance)#

The child’s attribute samples at its closest surface point to (x, y, z).

Parameters:
  • child – The prepared child node.

  • x – The x-coordinate.

  • y – The y-coordinate.

  • z – The z-coordinate.

  • child_distance – The child’s signed distance at the point.

Returns:

The samples, or std::nullopt if no material point was found (flat or empty child).

std::optional<AttributeSamples> sample(GrowthPolicy policy, Node &child, const std::shared_ptr<AttributeSet> &own_attributes, double x, double y, double z, double distance, double child_distance)#

Attribute samples for a point in material the operator grew.

The operator’s own attributes always take precedence over the child’s, matching the interior merge. With GrowthPolicy::extend the child is sampled at its closest surface point, found by stepping p - d * n with n the child’s unit gradient. The step is repeated (at most four times) until the child reports material there, so the result does not depend on the child’s distance being exact.

Parameters:
  • policy – The operator’s growth policy.

  • child – The prepared child node.

  • own_attributes – The operator’s own attributes (may be null).

  • x – The x-coordinate.

  • y – The y-coordinate.

  • z – The z-coordinate.

  • distance – The operator’s signed distance at the point, passed to its own attributes.

  • child_distance – The child’s signed distance at the point (positive in grown material).

Returns:

The samples, or std::nullopt for GrowthPolicy::undefined and where distance is positive (no material, so no attributes are evaluated).

Sums, mixes and arrays#

class Sum : public N_ary#
#include <sum.h>

A sum node.

The sum is taken as the sum of all child SDFs.

Distance accuracy (distance_accuracy()): always an approximation. A sum of distances is not a distance (its slope can reach the sum of the children’s), and a child without a value simply drops out of the sum.

Public Functions

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

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

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

Always approximate (see the class description).

Returns:

The accuracy of the subtree rooted at this node.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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.

inline double iso_value() const#

Returns the iso value added to the summed child distances.

Returns:

The iso value added to the summed child distances.

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

.

Always infinity: nothing is promised.

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 TreeSample sample_impl(double x, double y, double z) final#

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

Sum() = default#

Default constructor.

Sum(double iso_value)#

Constructor.

Parameters:

iso_value – The iso value of the sum.

Sum(double iso_value, const std::vector<std::shared_ptr<Node>> &children)#

Constructor.

Parameters:
  • iso_value – The iso value of the sum.

  • children – The children of the sum.

Private 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

double m_iso_value = 0.0#
class Mix : public Binary#
#include <mix.h>

Interpolates two child fields with a spatial weight in [0, 1].

A zero weight returns the left child and a one weight returns the right child. The weight may be an explicit mapped scalar field or a native smooth ramp derived from a prepared region node’s signed distance.

Distance accuracy (distance_accuracy()): always an approximation. The slope of a varying weight multiplies the (unbounded) difference between the children’s values, and where one child has no value the other is returned unmixed, so even a constant weight jumps at the edge of a child’s band.

Public Types

using AttributePolicy = AttributeMixPolicy#

How a conflicting attribute is combined (weighted interpolation or dominant side).

Public Functions

const std::unordered_map<std::string, AttributePolicy> &attribute_policies() const#

Return the per-attribute policy overrides.

Returns:

The policies, keyed by attribute name.

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::shared_ptr<Node> clone() final#

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

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

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

Always approximate (see the class description).

Returns:

The accuracy of the subtree rooted at this node.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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.

inline double half_width() const#

Returns the half-width of the region transition band (0 for a field-driven mix).

Returns:

The half-width of the region transition band (0 for a field-driven mix).

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

.

Always infinity: nothing is promised.

Returns:

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

Mix(const std::shared_ptr<Node> &left, const std::shared_ptr<Node> &right, const std::shared_ptr<FloatAttribute> &weight)#

Construct a field-driven mix.

The weight is sampled directly in this node’s current coordinates. Use an explicit CellMap adapter when logical, phase, or cell-index values are needed.

Parameters:
  • left – Child returned when the sampled weight is zero.

  • right – Child returned when the sampled weight is one.

  • weight – Spatial weight field.

Mix(const std::shared_ptr<Node> &left, const std::shared_ptr<Node> &right, const std::shared_ptr<Node> &region, double half_width)#

Construct a smooth region-driven mix.

The region surface is the weight-0.5 midline. Points at least one half-width inside select the left child, while points at least one half-width outside select the right child.

Parameters:
  • left – Child selected inside the region.

  • right – Child selected outside the region.

  • region – Region node whose signed distance drives the weight.

  • half_width – Positive half-width of the smooth transition band.

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.

inline const std::shared_ptr<Node> &region() const#

Returns the region node, or nullptr for a field-driven mix.

Returns:

The region node, or nullptr for a field-driven mix.

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

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

void set_attribute_policy(const std::string &name, AttributePolicy policy)#

Set the combination policy for one conflicting attribute.

Parameters:
  • name – Attribute name.

  • policy – Weighted interpolation or dominant-side selection.

inline const std::shared_ptr<FloatAttribute> &weight() const#

Returns the weight field, or nullptr for a region-driven mix.

Returns:

The weight field, or nullptr for a region-driven mix.

Private Functions

TreeSample combine_node_attributes(double x, double y, double z, const TreeSample &child_sample)#
virtual void prepare_bounding_box() final#

Computes the authored bounding box into m_min and m_max.

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

double sample_weight(const glm::vec3 &world)#

Private Members

std::unordered_map<std::string, AttributePolicy> m_attribute_policies#
double m_half_width = 0.0#
std::shared_ptr<Node> m_region#
std::shared_ptr<FloatAttribute> m_weight#
class Tile : public Unary#
#include <tile.h>

A tile is a unary operator that repeats a geometry as a pattern in a grid.

Cell k along an axis spans [k c, (k + 1) c), with the child’s origin placed at the cell centre (k + 1/2) c. By default the grid is infinite. An optional per-axis count makes it a finite array of cells 0 … n − 1 along that axis (a count of 0 or less keeps the axis infinite); points beyond the ends see the nearest end copy.

Pull-back node: the child is sampled at the point’s position within its copy, so attributes follow the material. instance_index_field() exposes the copy index as a field, so material can vary per copy.

Neighbours: prepare() measures how far the child’s box overhangs its cell and also evaluates that many neighbouring copies, taking the nearest. A child that fits its cell costs one evaluation.

Distance accuracy (distance_accuracy()): the value is the nearest copy within that window. It keeps the child’s accuracy only when every copy left out of the window is farther than the band from any point, which prepare() checks from the child’s box: per axis, the window must reach the overhang plus the band (a child that fits its cell must clear every cell face by the band). Otherwise a nearer copy just across a cell face can be missed, even for a child whose box is centred in its cell, and the value is approximate. Copies whose boxes overlap or touch merge, so the nearest copy’s value is then only a bound inside them.

Public Functions

inline glm::vec3 cell_size() const#

Returns the cell dimensions of the grid.

Components are negative while the size is unset; prepare() then derives it from the child.

Returns:

The cell dimensions of the grid.

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

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 glm::ivec3 count() const#

Returns the number of copies along each axis (0 or less means infinite).

Returns:

The number of copies along each axis (0 or less means infinite).

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 accuracy of the tiled subtree, from the child’s and the window measured by

prepare(). With the band T, the value clipped to T is the minimum of every copy’s clipped value when the window covers every copy that can come within T of a point (a copy left out has its box farther than T, so its value is at least T by the child’s box promise). The minimum of L-Lipschitz fields is L-Lipschitz, and outside a finite array’s box every copy’s value is at least the per-axis distance to its own box, which lies inside the array’s. So:
  • approximate if the child is approximate, the window misses copies within the band, or the child was last prepared with a narrower band than this node;

  • the child’s accuracy and bound when no two copies’ boxes meet (disjoint copies: the nearest copy is the true distance to their union, inside and out);

  • otherwise a bound with the child’s Lipschitz bound (merged copies).

Returns:

The accuracy of the subtree rooted at this node.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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.

inline bool has_cell_size() const#

Returns true if the cell dimensions are set (authored or derived by prepare()).

Returns:

True if the cell dimensions are set (authored or derived by prepare()).

std::shared_ptr<FloatAttribute> instance_index_field(int axis = -1) const#

The copy index of the cell containing a point, as a field.

Attach it (or a field derived from it) to this node to vary material per copy. Uses the cell size as it is when called, so call it after the size is set.

Parameters:

axis – 0, 1 or 2 for that axis’ cell index; -1 for the linear index i + nx (j + ny k) of a finite array.

Throws:

std::runtime_error – if the cell size is unset, or axis is -1 and an axis is infinite.

Returns:

A FloatAttribute giving the copy index at each point.

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 void prepare_impl(const glm::vec3 &voxel_size, double bandwidth) final#

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 Node::TreeSample sample_impl(double x, double y, double z) final#

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

Tile() = default#

Default Constructor.

Note

The cell dimensions will be calculated from the child node when prepare is called

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

Constructor.

Note

The cell dimensions will be calculated from the child node

Parameters:

child – The child node

Tile(double cell_x, double cell_y, double cell_z)#

Constructor.

Note

The child node’s size will be ignored and the supplied cell dimensions will be used instead

Parameters:
  • cell_x – The x dimension of a cell the grid

  • cell_y – The y dimension of a cell the grid

  • cell_z – The z dimension of a cell the grid

Tile(double cell_x, double cell_y, double cell_z, const glm::ivec3 &count, const std::shared_ptr<Node> &child)#

Constructor for a finite array.

Parameters:
  • cell_x – The x dimension of a cell the grid

  • cell_y – The y dimension of a cell the grid

  • cell_z – The z dimension of a cell the grid

  • count – The number of copies along each axis; 0 or less keeps that axis infinite.

  • child – The child node

Tile(double cell_x, double cell_y, double cell_z, const std::shared_ptr<Node> &child)#

Constructor.

Parameters:
  • cell_x – The x dimension of a cell the grid

  • cell_y – The y dimension of a cell the grid

  • cell_z – The z dimension of a cell the grid

  • child – The child node

Private Functions

glm::ivec3 cell_of(const glm::dvec3 &point) const#

The cell containing a point, clamped to a finite array.

glm::dvec3 effective_cell_size() const#

Derives the cell size from the child when it is unset.

glm::dvec3 local_point(const glm::dvec3 &point, const glm::ivec3 &cell) const#

The child-space point inside copy (i, j, k) for a world point.

std::optional<double> nearest_copy(const glm::dvec3 &point, glm::ivec3 &cell)#

Finds the nearest copy among the point’s cell and its needed neighbours.

Returns:

The child’s value there, or std::nullopt; cell receives the copy.

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

double m_cell_x = -1#

The x dimension of a cell the grid.

double m_cell_y = -1#

The y dimension of a cell the grid.

double m_cell_z = -1#

The z dimension of a cell the grid.

bool m_copies_disjoint = false#

True when no two copies’ boxes meet (set in prepare()).

glm::ivec3 m_count = {0}#

Copies along each axis; 0 or less is infinite.

glm::ivec3 m_neighbors = {0}#

Neighbouring copies to check on each side, from the child’s overhang (set in prepare()).

bool m_window_covers_band = false#

True when the window holds every copy that can come within the band of a point (set in prepare()).

class PolarArray : public Unary#
#include <polar_array.h>

Repeats its child N times around an axis.

Copy 0 is the child as authored. Without an angle range the copies are spaced 360 / N degrees apart around the axis (through center); with a range (start, end) in degrees they are spaced evenly from start to end inclusive, copy 0 rotated to start.

Evaluation is a pull-back: the point’s angle about the axis picks the nearest copy, the point is rotated back by that copy’s angle and the child is sampled there, so attributes follow the material. instance_index_field() exposes the copy index as a field, so material can vary per copy.

Neighbours: prepare() measures the child’s angular half-width w about the axis, and a point evaluates every copy whose angle lies within the window’s reach, ceil(w / step) plus a half steps (at least one neighbour on each side), of its own angle, taking the nearest. The reach is measured either way round the circle, so with an angle range the copies at the two ends also see each other across the empty part of the circle. Every copy whose material can hold the point is therefore evaluated. A child whose box reaches around the axis makes every copy a neighbour.

Attributes: sample() evaluates and returns attributes only where the value is <= 0.

Distance accuracy (distance_accuracy()): over a full circle the window always holds the nearest copy of an exact child, so it stays exact while copies stay apart and becomes a bound where they meet. A bound child, or an angle range, needs every copy left out of the window to be farther than the band, and a bound child also needs every copy turned by a multiple of 90 degrees about a coordinate axis; otherwise the value is approximate.

Bounding box: the child’s box swept around the axis (a bounding cylinder).

Public Functions

inline std::optional<std::pair<double, double>> angle_range() const#

Returns the angle range in degrees, or std::nullopt for the full circle.

Returns:

The angle range in degrees, or std::nullopt for the full circle.

inline glm::dvec3 axis() const#

Returns the unit axis direction.

Returns:

The unit axis direction.

inline glm::dvec3 center() const#

Returns the point the axis passes through.

Returns:

The point the axis passes through.

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

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

double copy_angle(int copy) const#

The angle of copy k about the axis, in radians.

Parameters:

copy – The copy index k.

Returns:

The start angle plus k angular steps, in radians.

inline int count() const#

Returns the number of copies.

Returns:

The number of copies.

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 accuracy of the arrayed subtree, from the child’s and the window measured by

prepare(). The value is the nearest copy within the window. With the band T it keeps the child’s Lipschitz bound when the window holds, at every point, the copy with the smallest value clipped to T: the minimum of L-Lipschitz fields is L-Lipschitz.
  • Exact child, full circle: always. A copy’s material lies within the child’s angular half-width w of its own angle and the window reaches w plus half a step, so for the nearest material point of a copy left out, the window holds a copy that brings the same point at least as close (same circle about the axis, smaller angle).

  • Any child: when every copy left out of the window lies, angle-wise, farther from the point than the child’s box grown by T reaches about the axis; such a copy’s value is at least T by the child’s box promise. A copy left out lies at least the window’s reach from the point’s angle, either way round the circle (the window wraps across the empty part of an angle range), so prepare() checks that the grown box reaches less far round the axis than the window. An angle range needs it. The array’s box holds every turned copy’s box. An exact child’s value is at least the Euclidean distance to its box, so it keeps the box promise; a bound child only promises the per-axis distance, which survives only turns that map the axes onto the axes. So:

  • approximate if the child is approximate, the window can miss a copy, a bound child is turned off the axes, or the child was last prepared with a narrower band;

  • the child’s accuracy when the copies’ angular sectors are apart (the nearest copy is the true distance to their union, inside and out);

  • otherwise a bound with the child’s Lipschitz bound (merged copies).

Returns:

The accuracy of the subtree rooted at this node.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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.

std::shared_ptr<FloatAttribute> instance_index_field() const#

The copy index nearest a point, as a field.

Attach it to this node to vary material per copy.

Uses the child’s angular position as measured by prepare(); before prepare() copy 0 is assumed to sit at angle 0.

Returns:

A FloatAttribute giving the nearest copy index at each point.

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.

PolarArray(int count, const std::shared_ptr<Node> &child, const glm::dvec3 &axis = glm::dvec3(0.0, 0.0, 1.0), const glm::dvec3 &center = glm::dvec3(0.0), const std::optional<std::pair<double, double>> &angle_range = std::nullopt)#

Constructor.

Parameters:
  • count – The number of copies, at least 1.

  • child – The child node; copy 0.

  • axis – The rotation axis direction (normalized internally).

  • center – A point on the axis.

  • angle_range – Optional (start, end) angles in degrees; copies are spaced evenly from start to end inclusive. Without it the copies fill the full circle.

Throws:

std::runtime_error – if count < 1, the axis is zero, or the range is empty or wider than 360.

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

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 Node::TreeSample sample_impl(double x, double y, double z) final#

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

Private Functions

glm::dvec3 local_point(const glm::dvec3 &point, int copy) const#

The point rotated back by copy k’s angle, in the child’s frame.

std::optional<double> nearest_copy(const glm::dvec3 &point, int &copy)#

Finds the nearest copy among the copies in the point’s window.

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

std::vector<int> window(const glm::dvec3 &point, int &base) const#

The copies evaluated at a point, sorted.

The point’s own copy and its neighbours on each side, which hold every copy whose angle lies within window_reach() of the point’s angle; with an angle range, also every copy within the reach measured the other way round the circle, across the empty part, so the two ends of the range see each other. Every copy when the window holds them all.

Parameters:
  • point – The query point.

  • base – Set to the point’s own (nearest) copy.

Returns:

The copy indices, sorted.

bool window_holds_every_copy() const#

True when every point’s window holds every copy.

double window_reach() const#

How far round the axis the window reaches from a point’s angle: (neighbours + 1/2) steps.

Private Members

std::optional<std::pair<double, double>> m_angle_range#
glm::dvec3 m_axis#
glm::dvec3 m_center#
bool m_copies_axis_aligned = false#

True when every copy’s turn maps the coordinate axes onto the axes (set in prepare()).

bool m_copies_disjoint = false#

True when the copies’ angular sectors do not meet (set in prepare()).

int m_count#
Frame m_frame#
int m_neighbors = 1#

Neighbouring copies to check on each side (set in prepare()).

bool m_window_covers_band = false#

True when every copy left out of the window is farther than the band (set in prepare()).

bool m_wraps_axis = false#

True when the child’s box reaches around the axis.

struct Frame#

The angular frame of the array, shared with the index field.

Public Functions

int copy_at(double relative) const#

The copy whose angular position is nearest a relative angle.

int nearest(const glm::dvec3 &point) const#

The copy whose angular position is nearest the point’s angle.

double relative_angle(const glm::dvec3 &point) const#

The point’s angle about the axis measured from copy 0, in radians.

In [0, 2 pi) over a full circle; with an angle range, within half a turn of the middle of the range, so the cut sits in the middle of the empty part of the circle.

Public Members

glm::dvec3 center#
int count = 1#
bool full_circle = true#
double reference = 0.0#

The child’s own angle about the axis, radians.

double start = 0.0#

Angle of copy 0, radians.

double step = 0.0#

Angle between copies, radians.

glm::dvec3 u#
glm::dvec3 v#
glm::dvec3 w#

Boolean CSG#

class Difference : public Binary#
#include <difference.h>

A difference binary node.

The difference is taken as the left child minus the right child.

Supports an optional blend (BooleanBlend) where the cut meets the left child: a radius, which may be a field, and a profile (quadratic by default, as with the original k constructors; circular, chamfer or cubic). A radius of 0 is sharp. The value is -smooth_min(-left, right). A smooth difference only removes material, so attributes come from the left child and the bounding box is the left child’s.

Distance accuracy (distance_accuracy(), for the whole subtree): never better than the weakest child. Both children are prepared at the bandwidth plus the blend’s support(), so the blend never reads a value the children do not promise. A sharp difference, and one blended with a constant quadratic or cubic radius, is a bound with the larger of the children’s Lipschitz bounds. Circular and chamfer profiles and field radii are approximations.

Public Functions

inline const BooleanBlend &blend() const#

Returns the blend: radius and profile.

Returns:

The blend: radius and profile.

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

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

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

Difference() = default#

Default constructor.

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

Constructor for a sharp difference.

Parameters:
  • left – The child to keep.

  • right – The child to subtract.

Difference(const std::shared_ptr<Node> &left, const std::shared_ptr<Node> &right, const ScalarParameter &blend_radius, BlendProfile profile = BlendProfile::quadratic)#

Constructor with children and a blend.

Parameters:
  • left – The left child node.

  • right – The right child node, subtracted from the left.

  • blend_radius – The blend radius, a constant or a field with known bounds; 0 is sharp.

  • profile – The fillet profile.

explicit Difference(double k)#

Constructor for smooth difference.

Parameters:

k – The smoothing radius. When k > 0, produces a quadratic smooth subtraction.

Difference(double k, const std::shared_ptr<Node> &left, const std::shared_ptr<Node> &right)#

Constructor for smooth difference with children.

Parameters:
  • k – The smoothing radius.

  • left – The left child node.

  • right – The right child node.

virtual DistanceAccuracy distance_accuracy() const override#

How faithfully this difference and its subtree match the true distance.

See the class description. The value is the (smooth) maximum of left and -right, clamped to the bandwidth T; with S the blend’s support() the children are prepared at T + S. A silent left child gives no value (left at least T + S, so the result is at least T). A silent right child returns the left child’s value unblended, which is what the blend gives for -right at or below -(T + S): blending with a value at least S beyond changes nothing while left is above -T, and keeps the clamped result at -T otherwise. Children’s values beyond T + S (for example where the cut goes silent deep inside the left child) are clamped away the same way, so the clamped value is a Lipschitz function of the children’s clamped values with their larger bound. The result is at least left, so outside the box it is at least the per-axis distance.

Returns:

The weakest of the children’s accuracy and the difference’s own.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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 larger of the children’s Lipschitz bounds; infinity when

distance_accuracy() is approximate.

Returns:

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

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 both children at the bandwidth plus the blend’s support().

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 TreeSample sample_impl(double x, double y, double z) final#

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

inline double smooth_k() const#

Returns the constant smoothing radius (0 for a sharp difference).

Throws:

std::runtime_error – if the blend radius is a field; use blend() instead.

Returns:

The constant smoothing radius (0 for a sharp difference).

Public Static Functions

static std::shared_ptr<Difference> clearance(const std::shared_ptr<Node> &left, const std::shared_ptr<Node> &right, const ScalarParameter &gap, const ScalarParameter &blend_radius = ScalarParameter(0.0), BlendProfile profile = BlendProfile::quadratic)#

Subtracts right from left, leaving a gap around right: Difference(left, Offset(gap, right)).

Use it to cut a hole or slot that a part (right) fits into with a clearance. The gap may be a field (with known bounds), so the clearance can vary around the part. Attributes come from the left child (removal). Distance accuracy is that of the Difference over an Offset: a bound for a constant gap and a sharp cut, when the children are exact or bounds.

Parameters:
  • left – The body to cut.

  • right – The part that the cut must clear.

  • gap – The clearance between the cut and right; never negative.

  • blend_radius – The blend radius of the cut’s edges; 0 is sharp.

  • profile – The fillet profile.

Throws:

std::runtime_error – if the gap is negative or a field gap has no bounds.

Returns:

The Difference node.

Private Functions

std::optional<double> difference_value(std::optional<double> lhs, std::optional<double> rhs, double x, double y, double z) const#

The difference value from the children’s values at a point.

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

BooleanBlend m_blend#

The blend where the cut meets the left child. Sharp by default.

class Intersection : public N_ary#
#include <intersection.h>

Intersection of two or more nodes, optionally blended where they meet.

The blend (BooleanBlend) is a smooth maximum: a radius, which may be a field, and a profile (quadratic by default, as with the original k constructors; circular, chamfer or cubic). A radius of 0 is sharp. The result does not depend on the order of the children. A smooth intersection only removes material, so every point inside the result is inside every child, attributes are combined as before, and the bounding box is the overlap of the children’s boxes.

Distance accuracy (distance_accuracy(), for the whole subtree): never better than the weakest child. The children are prepared at the bandwidth plus the blend’s support(), because a smooth maximum near the surface reads values up to support() beyond the bandwidth. A sharp intersection, and one blended with a constant quadratic or cubic radius (any number of children), is a bound with the children’s largest Lipschitz bound. Circular and chamfer profiles and field radii are approximations. Children whose boxes do not overlap give an empty box at the origin, so that case is an approximation too. A single child keeps its own accuracy.

Public Functions

inline const BooleanBlend &blend() const#

Returns the blend: radius and profile.

Returns:

The blend: radius and profile.

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

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 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 intersection and its subtree match the true distance.

See the class description. With T the bandwidth and S the blend’s support(), the children are prepared at T + S, and G_i (child i’s value clamped to [-(T + S), T + S], T + S where it is silent) is L_i-Lipschitz. The intersection returns no value where any child is silent, and clamping the (smooth) maximum of the raw values to [-T, T] gives the same as clamping the maximum of the G_i: a value at or above T + S keeps the result at or above T, and one at or below -(T + S) cannot move the clamped result (as a smooth minimum: blending a value with one at least S above it changes nothing, and once the sorted fold is above T, folding in a value at least S above T keeps it above T). The quadratic and cubic blends with a constant radius change by at most the largest change of their inputs, so the result keeps the children’s largest Lipschitz bound. The (smooth) maximum is at least every child’s value, so outside the intersected box it is at least the per-axis distance to that box, which also makes the box early-out continuous.

Returns:

The weakest of the children’s accuracy and the intersection’s own.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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.

Intersection()#

Default constructor.

Intersection(const std::shared_ptr<Node> &lhs, const std::shared_ptr<Node> &rhs)#

Constructor with children.

Parameters:
  • lhs – Left child node

  • rhs – Right child node

Intersection(const std::vector<std::shared_ptr<Node>> &children, const ScalarParameter &blend_radius, BlendProfile profile = BlendProfile::quadratic)#

Constructor with children and a blend.

Parameters:
  • children – The children nodes.

  • blend_radius – The blend radius, a constant or a field with known bounds; 0 is sharp.

  • profile – The fillet profile.

explicit Intersection(double k)#

Constructor for smooth intersection.

Parameters:

k – The smoothing radius. When k > 0, produces a quadratic blend.

Intersection(double k, const std::vector<std::shared_ptr<Node>> &children)#

Constructor for smooth intersection with children.

Parameters:
  • k – The smoothing radius.

  • children – The children nodes.

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 children’s largest Lipschitz bound; infinity when

distance_accuracy() is approximate.

Returns:

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

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 children at the bandwidth plus the blend’s support().

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 TreeSample sample_impl(double x, double y, double z) final#

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

inline double smooth_k() const#

Returns the constant smoothing radius (0 for a sharp intersection).

Throws:

std::runtime_error – if the blend radius is a field; use blend() instead.

Returns:

The constant smoothing radius (0 for a sharp intersection).

Private Functions

virtual void prepare_bounding_box() final#

Computes the authored bounding box into m_min and m_max.

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

Private Members

BooleanBlend m_blend#

The blend between children. Sharp by default.

class BBoxIntersection : public N_ary#
#include <bbox_intersection.h>

An accelerated n-ary boolean intersection node utilizing an internal Axis-Aligned Bounding Box (AABB) tree.

This node drastically improves performance when sampling intersections of many spatially distinct children by only evaluating children whose bounding boxes overlap the sample point.

    The value is that of a sharp Intersection: the maximum of the children's values, and no
    value where any child has none or is left out of the AABB query (more than the bandwidth
    outside its box). This node's own attributes are only evaluated, and attributes only
    returned, where the value is 0 or less.

    Bounding box: the intersection of the children's finite boxes (children with an infinite
    corner do not bound it); a point at the origin if those boxes have no common point.

    Distance accuracy (distance_accuracy(), for the whole subtree): as a sharp Intersection,
    a bound with the children's largest Lipschitz bound, never better than the weakest child.
    Children whose finite boxes do not overlap make it an approximation. A single child keeps
    its own accuracy.

Public Functions

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

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

BBoxIntersection()#

Default constructor. Creates an intersection with no children.

BBoxIntersection(std::vector<std::shared_ptr<Node>> children)#

Constructor.

Adds each non-null child with addChild().

Parameters:

children – The children to intersect.

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 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 intersection and its subtree match the true distance (see the class description).

A child outside the AABB query is more than the bandwidth outside its box, so its value would be above the bandwidth; returning no value there, as for a silent child, keeps the clamped value the maximum of the children’s clamped values.

Returns:

The weakest of the children’s accuracy and bound.

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 children’s largest Lipschitz bound; infinity when

distance_accuracy() is approximate.

Returns:

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

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

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

Private Members

std::shared_ptr<AABBVCADTree> m_aabb_tree#
double m_bandwidth = 1.0#
std::unordered_map<VCADNodeBBoxPrimitive::Id, size_t> m_node_added_order#
class Union : public N_ary#
#include <union.h>

Union of any number of nodes, optionally blended where they meet.

The blend (BooleanBlend) has a radius, which may be a field, and a profile: quadratic (the default, and the behaviour of the original k constructors), circular, chamfer or cubic. A radius of 0 is a sharp union; a field radius blends only where it is positive. The result does not depend on the order of the children: the per-point values are sorted before they are folded.

Attributes: inside one or more children their attributes are combined as before (this node’s first, then the children’s, through the conflict resolvers). A blend also creates fillet material outside every child; there the two nearest children are sampled at their closest surface points and mixed by the blend weight (AttributeCombination::mix_attributes), so a fillet between two materials grades from one to the other. Attributes are only evaluated and returned where the union’s value is 0 or less.

Bounding box: the children’s boxes, padded by the blend’s max_dip() for one or two children. The sorted fold of three or more values can dip deeper than one blend, so with three or more each face is padded by how far the fold of the children’s gaps to it reaches, at most the support() (SmoothBlend::union_bounding_box()): one dip where a single child sticks out, more where several children end at the same face.

Distance accuracy (distance_accuracy(), for the whole subtree): never better than the weakest child. A sharp union is a bound (the minimum of exact distances is exact outside but only a bound inside overlapping children), as is a quadratic or cubic blend with a constant radius, for any number of children. A field radius scales the value, and circular and chamfer blends can be steeper than 1, so those are approximations. A single child keeps its own accuracy.

Subclassed by MappedStructureCollection

Public Functions

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

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

inline const BooleanBlend &blend() const#

Returns the blend: radius and profile.

Returns:

The blend: radius and profile.

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 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 union and its subtree match the true distance.

The rules (see the class description) follow from how the children are prepared: at the bandwidth T plus the blend’s support() S, so a child that has gone silent (no value) stands for a value of at least T + S. Folding a value at least S above the running result changes nothing, and a running result above T stays above T after folding in a value of at least T + S, so the clamped blend equals the blend of the children’s clamped values. Outside the box the smallest value is at least the per-axis distance to the children’s boxes and the fold ends at most the box padding below it, so values there are at least the per-axis distance to the union’s box, which also makes the box early-out continuous.

Returns:

The weakest of the children’s accuracy and the union’s own.

virtual std::optional<double> evaluate_impl(double x, double y, double z) final#

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 children’s largest Lipschitz bound (the blend’s slope is at most 1).

Returns:

Infinity when distance_accuracy() is approximate.

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 TreeSample sample_impl(double x, double y, double z) final#

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

inline double smooth_k() const#

Returns the constant smoothing radius (0 for a sharp union).

Throws:

std::runtime_error – if the blend radius is a field; use blend() instead.

Returns:

The constant smoothing radius (0 for a sharp union).

Union()#

Default constructor.

Union(const std::shared_ptr<Node> &lhs, const std::shared_ptr<Node> &rhs)#

Constructor with children.

Parameters:
  • lhs – Left child node

  • rhs – Right child node

Union(const std::vector<std::shared_ptr<Node>> &children, const ScalarParameter &blend_radius, BlendProfile profile = BlendProfile::quadratic)#

Constructor with children and a blend.

Parameters:
  • children – The children nodes.

  • blend_radius – The blend radius, a constant or a field with known bounds; 0 is sharp.

  • profile – The fillet profile.

explicit Union(double k)#

Constructor for smooth union.

Parameters:

k – The smoothing radius. When k > 0, produces a quadratic blend between children.

Union(double k, const std::vector<std::shared_ptr<Node>> &children)#

Constructor for smooth union with children.

Parameters:
  • k – The smoothing radius.

  • children – The children nodes.

Private Functions

virtual void prepare_bounding_box() final#

Computes the authored bounding box into m_min and m_max.

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

Private Members

BooleanBlend m_blend#

The blend between children. Sharp by default.

class BBoxUnion : public N_ary#
#include <bbox_union.h>

An accelerated n-ary boolean union node utilizing an internal Axis-Aligned Bounding Box (AABB) tree.

This node drastically improves performance when sampling unions of many spatially distinct children by only evaluating children whose bounding boxes overlap the sample point.

    Bounding box: the children's boxes, padded as a quadratic Union with radius k: by k for one
    or two smooth children, and for three or more by how far the fold of the children's gaps to
    each face reaches, at most the support 4k (SmoothBlend::union_bounding_box()).

    Attributes: only evaluated and returned where the union's value is 0 or less: this node's
    own, then those of the children that contain the point.

    Distance accuracy (distance_accuracy(), for the whole subtree): as Union with a constant
    quadratic blend. Sharp or smooth, with any number of children: a bound, never better than
    the weakest child. A single child keeps its own accuracy.

Public Functions

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

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

BBoxUnion()#

Default constructor. Creates a sharp union with no children.

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

Constructor for a sharp accelerated union.

Adds each non-null child with addChild().

Parameters:

children – The children to unite.

explicit BBoxUnion(double k)#

Constructor for a smooth accelerated union.

Parameters:

k – Smoothing radius. Values at or below zero produce a sharp union.

BBoxUnion(double k, const std::vector<std::shared_ptr<Node>> &children)#

Constructor for a smooth accelerated union with children.

Parameters:
  • k – Smoothing radius.

  • children – Child nodes to union.

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

How faithfully this union and its subtree match the true distance (see the class description). Children outside the AABB query are at least the child bandwidth (bandwidth + 4k) beyond their boxes, so leaving them out is the same as their going silent.

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 children’s largest Lipschitz bound; infinity when

distance_accuracy() is approximate.

Returns:

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

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

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

inline double smooth_k() const#

Returns the smoothing radius (0 for a sharp union).

Returns:

The smoothing radius (0 for a sharp union).

Private Members

std::shared_ptr<AABBVCADTree> m_aabb_tree#
double m_bandwidth = 1.0#
std::unordered_map<VCADNodeBBoxPrimitive::Id, size_t> m_node_added_order#
double m_smooth_k = 0.0#
class MappedStructureCollection : public Union#
#include <mapped_structure_collection.h>

A sharp union that preserves per-child CellMap attachment semantics.

Each child is paired with one CellMap. A mapped attribute is cloned, bound to that map, and attached to the corresponding child so normal Node samples remain the only compiler-facing representation.

Public Functions

const std::vector<std::shared_ptr<CellMap>> &cell_maps() const#

Return the immutable maps in child order.

Returns:

CellMaps paired with the collection children.

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

inline 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 collection is always a sharp union: a bound, never better than its weakest child.

Returns:

The accuracy of the subtree rooted at this node.

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

Returns:

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

MappedStructureCollection(const std::vector<std::shared_ptr<CellMap>> &cell_maps, const std::vector<std::shared_ptr<Node>> &children)#

Construct a mapped collection from aligned maps and child nodes.

Parameters:
  • cell_maps – CellMaps associated one-to-one with the children.

  • children – Mapped structure nodes combined with a sharp union.

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.

void set_mapped_attribute(const std::string &name, const std::shared_ptr<Attribute> &attribute, AttributeCoordinateSpace coordinates)#

Attach an attribute independently in each child’s mapped coordinates.

Parameters:
  • name – Attribute name.

  • attribute – Attribute definition cloned for each child.

  • coordinates – Coordinate inputs supplied to the attribute.

Private Members

std::vector<std::shared_ptr<CellMap>> m_cell_maps#

Enums

enum class BlendProfile#

The cross-section of the fillet a smooth Boolean puts where two surfaces meet.

With r the blend radius, each profile dips below min(a, b) by at most max_dip() and only where |a - b| (or both values) are within support() of each other. Elsewhere the result is the sharp min.

Values:

enumerator quadratic#

The original smooth union: a polynomial fillet, dip r, support 4r.

The default.

enumerator circular#

A circular-arc fillet of radius r between perpendicular surfaces, dip (sqrt(2) - 1) r, support r.

enumerator chamfer#

A flat 45-degree bevel, dip r / sqrt(2), support r.

enumerator cubic#

A curvature-continuous (C2) polynomial fillet, dip r, support 6r.

Functions

std::string blend_profile_name(BlendProfile profile)#

Lower-case name of a blend profile (“quadratic”, “circular”, “chamfer” or “cubic”).

Parameters:

profile – The profile.

Returns:

The name.

class BooleanBlend#
#include <smooth_blend.h>

The blend a Boolean node applies: a radius (constant or field) and a profile.

Union, Intersection and Difference each hold one. A radius of 0 (or less) gives a sharp Boolean; a field radius may be 0 in some regions and positive in others, so the edge is only blended where the user wants it. A field radius needs known bounds so the node can pad its bounding box and its children’s bandwidth.

Distance accuracy: a sharp Boolean, or a quadratic or cubic blend with a constant radius, is a bound (the blend never has a slope above 1). Circular and chamfer blends can have a slope up to sqrt(2) where the surfaces meet at shallow angles, so they are approximations. A field radius with a Lipschitz hint L is divided by 1 + L and stays a bound for the quadratic and cubic profiles; without the hint it is an approximation.

Public Functions

BooleanBlend() = default#

A sharp Boolean.

BooleanBlend(const ScalarParameter &radius, BlendProfile profile = BlendProfile::quadratic)#

A blend with a radius and profile.

Parameters:
  • radius – The blend radius; a field needs known bounds.

  • profile – The fillet profile.

Throws:

std::runtime_error – if a field radius has no bounds.

BooleanBlend clone() const#

Returns a copy whose field radius is deep-cloned, for use in Node::clone().

Returns:

A copy whose field radius is deep-cloned, for use in Node::clone().

DistanceAccuracy distance_accuracy() const#

How faithfully the blended value matches the true distance, for exact children.

The operation alone, for children whose values are true distances everywhere. The nodes’ Node::distance_accuracy() overrides compose it with their children’s accuracy, bandwidth and bounding box (see Union::distance_accuracy()).

Returns:

bound when sharp, or for a quadratic or cubic blend with a constant radius or a field radius with a Lipschitz hint; approximate otherwise.

inline bool is_sharp() const#

Returns true when the radius is a constant 0 or less, so every point is sharp.

Returns:

True when the radius is a constant 0 or less, so every point is sharp.

bool keeps_distance_bound() const#

True when a Boolean node can keep its children’s distance bound through this blend.

Sharp, or a constant radius with the quadratic or cubic profile. Then the blend of any number of values changes by at most the largest change of its inputs (each step of the sorted fold has non-negative partial derivatives that sum to 1), blending a value with one at least max_support() above it is the sharp minimum, and the sorted fold never ends more than max_support() below the smallest value (two values: at most max_dip() below). A field radius scales the value, and the circular and chamfer profiles have slopes up to sqrt(2), so those do not qualify.

Returns:

True if sharp, or a constant radius with the quadratic or cubic profile.

inline double max_dip() const#

How far beyond the sharp result the blend can reach: the bounding box padding.

Returns:

SmoothBlend::max_dip() at max_radius().

double max_radius() const#

The largest radius anywhere (0 for a sharp Boolean).

Returns:

The upper bound of the radius, clamped to at least 0.

inline double max_support() const#

How far apart two values may be and still blend: the extra child bandwidth.

Returns:

SmoothBlend::support() at max_radius().

double mix_weight(double a, double b, double x, double y, double z) const#

The second value’s share of the blend of a and b at a point, for mixing attributes.

Parameters:
  • a – The first value.

  • b – The second value.

  • x – The x coordinate of the point.

  • y – The y coordinate of the point.

  • z – The z coordinate of the point.

Returns:

The weight of b, in [0, 1].

inline BlendProfile profile() const#

The fillet profile.

Returns:

The profile.

double radius(double x, double y, double z, double d = 0.0) const#

The radius at a point (never negative).

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

  • y – The y coordinate of the point.

  • z – The z coordinate of the point.

  • d – The signed distance passed to a field radius.

Returns:

The radius, clamped to at least 0.

inline const ScalarParameter &radius_parameter() const#

The radius, a constant or a field.

Returns:

The radius parameter.

double smooth_max(std::vector<double> &values, double x, double y, double z) const#

Smooth maximum at a point: -smooth_min(-values).

Parameters:
  • values – The children’s values; negated in place. Must not be empty.

  • x – The x coordinate of the point.

  • y – The y coordinate of the point.

  • z – The z coordinate of the point.

Returns:

The blended value (the plain maximum when sharp).

double smooth_min(std::vector<double> &values, double x, double y, double z) const#

Order-independent smooth minimum at a point, with the field-radius correction.

The radius is sampled at the point with the sharp minimum as d, and a field radius with a Lipschitz hint L scales the result by 1 / (1 + L).

Parameters:
  • values – The children’s values; reordered in place. Must not be empty.

  • x – The x coordinate of the point.

  • y – The y coordinate of the point.

  • z – The z coordinate of the point.

Returns:

The blended value (the plain minimum when sharp).

inline std::pair<glm::vec3, glm::vec3> union_bounding_box(const std::vector<std::pair<glm::vec3, glm::vec3>> &child_boxes) const#

A smooth union’s bounding box around its children’s boxes, at max_radius().

Parameters:

child_boxes – The children’s bounding boxes.

Returns:

The padded box, as min and max corners.

Private Members

BlendProfile m_profile = BlendProfile::quadratic#
ScalarParameter m_radius#
double m_scale = 1.0#

1 / (1 + L) for a field radius with a Lipschitz hint, else 1.

namespace SmoothBlend#

The one blend used by Union, Intersection, Difference and the lattices.

A smooth max is -smooth_min(-a, -b) and a smooth difference is -smooth_min(-a, b). Radius 0 (or less) is the sharp min. Every profile changes the value by at most 1 per unit change of the radius, so a field radius with slope bound L adds at most L to the result’s slope.

Functions

double max_dip(double radius, BlendProfile profile = BlendProfile::quadratic)#

The largest amount the blend lowers min(a, b); bounding boxes grow by this much.

Parameters:
  • radius – The blend radius.

  • profile – The fillet profile.

Returns:

The largest dip (0 for a radius of 0 or less).

double mix_weight(double a, double b, double radius, BlendProfile profile = BlendProfile::quadratic)#

The share of the second value in the blend of a and b, for mixing attributes.

Parameters:
  • a – The first value.

  • b – The second value.

  • radius – The blend radius; 0 gives a hard switch to the smaller value.

  • profile – The fillet profile.

Returns:

0.5 where a == b, falling to 0 where b is a support() or more above a (and rising to 1 where b is that far below a).

double smooth_min(double a, double b, double radius, BlendProfile profile = BlendProfile::quadratic)#

Smooth minimum of two values.

Parameters:
  • a – The first value.

  • b – The second value.

  • radius – The blend radius; 0 gives min(a, b).

  • profile – The fillet profile.

Returns:

The blended value, never above min(a, b).

double smooth_min(std::vector<double> &values, double radius, BlendProfile profile = BlendProfile::quadratic)#

Order-independent smooth minimum of any number of values.

The values are sorted ascending and folded from the smallest, so the result depends only on the set of values, not on their order.

Parameters:
  • values – The values; reordered in place.

  • radius – The blend radius; 0 gives the plain minimum.

  • profile – The fillet profile.

Returns:

The blended value, or +infinity for no values.

double support(double radius, BlendProfile profile = BlendProfile::quadratic)#

How far apart two values may be and still blend.

Parameters:
  • radius – The blend radius.

  • profile – The fillet profile.

Returns:

The support width (0 for a radius of 0 or less).

std::pair<glm::vec3, glm::vec3> union_bounding_box(const std::vector<std::pair<glm::vec3, glm::vec3>> &child_boxes, double radius, BlendProfile profile = BlendProfile::quadratic)#

A smooth union’s bounding box: its children’s combined box, each face padded by how far the blend can reach past it.

Outside its box a child’s value is at least the per-axis distance to that box, so at t past a face of the combined box each child’s value is at least t + g, g being how far the child’s box stops short of that face. The sorted fold never falls when a value rises, and the quadratic and cubic folds shift with their values, so the union’s value there is at least t + fold(gaps): the face is padded by -fold(gaps), clamped to [max_dip(), support()]. That reaches the support only where many children end at the same face, and stays one dip where a single child sticks out. The circular and chamfer folds do not shift with their values, so their faces get union_padding(count). The fold only deepens with the radius, so a field radius uses its largest.

Parameters:
  • child_boxes – The children’s bounding boxes.

  • radius – The blend radius; 0 gives the combined box.

  • profile – The fillet profile.

Returns:

The padded box, as min and max corners.

double union_padding(double radius, size_t count, BlendProfile profile = BlendProfile::quadratic)#

How far the smooth minimum of count values can reach beyond the sharp one, whatever the values.

max_dip() for one or two values. The sorted fold of three or more can dip deeper than one blend (three equal values: 1.5625 r for the quadratic profile), so it gets support(). That holds for every profile: material (a result of 0 or less) needs the smallest value below support(). For the quadratic and cubic profiles the fold also never ends support() or more below the smallest value: if the running result is e <= k below it (k the support), the next value is at least e above the result, so the step lowers the result by at most h(e) and the gap becomes at most e + h(e) <= k (h(e) = (k - e)^2 / (4k) for the quadratic profile, ((k - e) / k)^3 k / 6 for the cubic).

Parameters:
  • radius – The blend radius.

  • count – The number of values (children).

  • profile – The fillet profile.

Returns:

support() for three or more values, otherwise max_dip().