Tree — leaves#
Leaf geometry and primitives.
-
class Function : public Leaf#
- #include <function.h>
A function geometry primitive/ leaf node.
This is analogs to an F-rep. Functions can be defined in cartesian, cylindrical, or spherical coordinates.
The function is defined by a string that is a math expression. The node uses the exprtk library and therefore can use any operations defined within its parser. The string can contain the following variables:
Cartesian coordinates: x, y, and z
Cylindrical coordinates: rho, phic, and z
Spherical coordinates: r, theta, and phis
Note
phic corresponds to phi in cylindrical and phis to phi in spherical
Note
This node can be evaluated in O(n) time, where N is the number of tokens in the expressions.
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: the field is an arbitrary user expression or callback. Nothing bounds how fast a user function changes or whether it measures distance at all (a TPMS or a scaled distance is a common input), so no Lipschitz bound can be promised.
- 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 std::string &expression() const#
Returns the math expression evaluated by this node.
- Returns:
The expression string, or an empty string when the node wraps a callback.
-
Function()#
Constructor for any empty function.
-
Function(const std::function<double(double x, double y, double z, double rho, double phic, double r, double theta, double phis)> &function, glm::vec3 min = glm::vec3(-10.0), glm::vec3 max = glm::vec3(10.0))#
Constructs a Function node using a native C++ std::function callback.
- Parameters:
function – The callback returning the scalar distance field value.
min – The minimum bounds of the geometry function.
max – The maximum bounds of the geometry function.
-
Function(const std::string &function, glm::vec3 min = glm::vec3(-10.0), glm::vec3 max = glm::vec3(10.0))#
Constructor for string-based mathematical expressions.
- Parameters:
function – The mathematical string expression to evaluate.
min – The minimum bounds of the geometry function.
max – The maximum bounds of the geometry function.
-
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 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.
Validates & compiles the function, prepares parser
- 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()
.
The summary “expression” entry is shortened to one line; a “full expression” entry holds the complete string whenever the summary had to be shortened.
- Returns:
The ordered property list. The base implementation returns an empty list.
-
inline bool uses_expression() const#
Returns true when the node evaluates a string expression rather than a callback.
- Returns:
True when the node evaluates a string expression rather than a callback.
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 prepare_expression()#
Private Members
-
std::shared_ptr<ExpressionEvaluator> m_evaluator#
-
std::function<double(double x, double y, double z, double rho, double phic, double r, double theta, double phis)> m_function#
-
double m_phic#
-
double m_phis#
-
bool m_prepared = false#
-
double m_r#
-
double m_rho#
-
std::string m_string_function#
The function to evaluate as a string.
-
double m_theta#
-
bool m_use_string_evaluator = true#
-
double m_x#
The variables for each thread.
-
double m_y#
-
double m_z#
-
class Mesh : public Leaf#
- #include <mesh.h>
A mesh geometry primitive/ leaf node.
The mesh is loaded from a file and converted into a signed distance field using OpenVDB.
Mesh files are loaded into triangles/ vertices using the Assimp library when the node is constructed. prepare() then converts the triangles into an OpenVDB narrow-band signed distance grid at a resolution derived from the voxel size, and evaluate() returns the interpolated distance to the mesh. Attributes are set on the node like any other leaf.
The value: prepare() stores distances within bandwidth + |sdf_shim| of the surface (the band value beyond it), so the shimmed value is valid out to the bandwidth on both sides. Inside the bounding box padded by the bandwidth, evaluate() returns max(F, d), where F is the grid interpolated trilinearly minus sdf_shim and d the signed Euclidean distance to the bounding box; beyond the padded box it returns no value. A positive sdf_shim grows the bounding box by the shim (the grown part stays inside it); a negative one keeps the mesh’s box. Inside the box d only lifts values that fall below minus the distance to the box, which a true distance never does, and never changes their sign; outside it, d removes interpolated material beyond the box.
Distance accuracy (distance_accuracy()): bound, with the Lipschitz bound prepare() measures on its grid (SurfaceMesh::sdf_lipschitz_bound(), at least 1): the largest trilinear gradient over every grid cell the padded box reads, including inactive voxels, tiles and the background. d is at least the bandwidth on the faces of the padded box, so the band-clipped value runs continuously into the early-out, and outside the box every value is at least the distance to it. The bound holds for the implemented surface (the grid’s own sign), whatever the mesh’s quality. approximate before prepare(), or if the measurement fails.
Note
The Mesh class is only available if the Assimp and OpenVDB libraries are available.
Note
This node can be evaluated in O(1) time.
Public Functions
-
inline bool center() const#
Returns whether the mesh was centered at the origin after loading.
- Returns:
Whether the mesh was centered at the origin after loading.
-
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 bool compensate_slicer_ras() const#
Returns whether the mesh is mirrored across Y to compensate for 3D Slicer RAS exports.
- Returns:
Whether the mesh is mirrored across Y to compensate for 3D Slicer RAS exports.
-
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 bool disable_validation() const#
Returns whether mesh validation was disabled when loading the file.
- Returns:
Whether mesh validation was disabled when loading the file.
-
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.
bound once prepared, with the measured Lipschitz bound (see the class notes).
- 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 std::string &file_path() const#
Returns the path of the mesh file, or an empty string for a mesh built from a SurfaceMesh.
- Returns:
The path of the mesh file, or an empty string for a mesh built from a SurfaceMesh.
-
openvdb::FloatGrid::Ptr getGrid()#
Returns the raw OpenVDB signed distance grid.
- Returns:
The raw OpenVDB grid
-
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 Lipschitz bound
prepare() measured on the grid, or infinity when approximate.- Returns:
L, at least 1, or infinity when nothing is promised.
-
Mesh() = default#
-
Mesh(const std::string &path, bool center, bool disable_validation, double override_voxel_size, bool compensate_slicer_ras = false)#
Constructor.
- Parameters:
path – The path to the mesh file to load.
center – If true, the mesh will be centered at the origin after loading.
disable_validation – If true, the mesh will not be validated for errors.
override_voxel_size – Explicit voxel size to use when voxelizing the mesh into an SDF, bypassing the minimum bound heuristic.
compensate_slicer_ras – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.
-
Mesh(const std::string &path, bool center = false, bool disable_validation = false, const std::optional<double> &override_voxel_size = std::nullopt, bool compensate_slicer_ras = false)#
Constructor.
- Parameters:
path – The path to the mesh file to load.
center – If true, the mesh will be centered at the origin after loading.
disable_validation – If true, the mesh will not be validated for errors. This is useful for meshes where we know its ok if the mesh is not watertight or has self-intersections.
override_voxel_size – Optional explicit voxel size to use when voxelizing the mesh into an SDF, bypassing the minimum bound heuristic.
compensate_slicer_ras – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.
-
Mesh(const std::string &path, const glm::vec3 &sample_size, bool center, bool disable_validation, double override_voxel_size, bool compensate_slicer_ras = false)#
Constructor.
- Parameters:
path – The path to the mesh file to load.
sample_size – The voxel size to use when voxelizing the mesh into an SDF.
center – If true, the mesh will be centered at the origin after loading.
disable_validation – If true, the mesh will not be validated for errors.
override_voxel_size – Explicit voxel size to use when voxelizing the mesh into an SDF. If provided, this takes precedence over sample_size.
compensate_slicer_ras – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.
-
Mesh(const std::string &path, const glm::vec3 &sample_size, bool center = false, bool disable_validation = false, const std::optional<double> &override_voxel_size = std::nullopt, bool compensate_slicer_ras = false)#
Constructor.
- Parameters:
path – The path to the mesh file to load.
sample_size – The voxel size to use when voxelizing the mesh into an SDF.
center – If true, the mesh will be centered at the origin after loading.
disable_validation – If true, the mesh will not be validated for errors.
override_voxel_size – Optional explicit voxel size to use when voxelizing the mesh into an SDF. If provided, this takes precedence over sample_size.
compensate_slicer_ras – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.
-
Mesh(const std::string &path, double override_voxel_size, bool disable_validation = false, bool center = false, bool compensate_slicer_ras = false)#
Constructor kept for source compatibility with the previous override-only overload.
- Parameters:
path – The path to the mesh file to load.
override_voxel_size – The explicit voxel size to use when voxelizing the mesh into an SDF, bypassing the minimum bound heuristic.
disable_validation – If true, the mesh will not be validated for errors.
center – If true, the mesh will be centered at the origin after loading.
compensate_slicer_ras – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.
-
Mesh(double sdf_shim, const std::string &path, bool center, bool disable_validation, double override_voxel_size, bool compensate_slicer_ras = false)#
Constructor.
- Parameters:
sdf_shim – Amount to subtract from evaluated signed distance values.
path – The path to the mesh file to load.
center – If true, the mesh will be centered at the origin after loading.
disable_validation – If true, the mesh will not be validated for errors.
override_voxel_size – Explicit voxel size to use when voxelizing the mesh into an SDF, bypassing the minimum bound heuristic.
compensate_slicer_ras – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.
-
Mesh(double sdf_shim, const std::string &path, bool center = false, bool disable_validation = false, const std::optional<double> &override_voxel_size = std::nullopt, bool compensate_slicer_ras = false)#
Constructor.
- Parameters:
sdf_shim – Amount to subtract from evaluated signed distance values.
path – The path to the mesh file to load.
center – If true, the mesh will be centered at the origin after loading.
disable_validation – If true, the mesh will not be validated for errors.
override_voxel_size – Optional explicit voxel size to use when voxelizing the mesh into an SDF, bypassing the minimum bound heuristic.
compensate_slicer_ras – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.
Constructor.
- Parameters:
mesh – The mesh to load.
center – If true, the mesh will be centered at the origin before voxelization.
override_voxel_size – Explicit voxel size to use when voxelizing the mesh into an SDF, bypassing the minimum bound heuristic.
compensate_slicer_ras – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.
Constructor.
- Parameters:
mesh – The mesh to load.
center – If true, the mesh will be centered at the origin before voxelization.
override_voxel_size – Optional explicit voxel size to use when voxelizing the mesh into an SDF, bypassing the minimum bound heuristic.
compensate_slicer_ras – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.
-
inline std::optional<double> override_voxel_size() const#
Returns the explicit voxel size that bypasses the minimum bound heuristic, if one was given.
- Returns:
The explicit voxel size that bypasses the minimum bound heuristic, if one was given.
-
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.
Builds the signed distance grid from the mesh loaded by the constructor and measures its Lipschitz bound. The grid voxel size is the override voxel size if given, else the sample size if given, else the requested voxel size clamped to at least 0.5% of the smallest bounding-box dimension.
- 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.
Returns the signed distance and, only where it is at most zero, the attributes. Outside points and points with no value get no attributes; see
Node::sample().- 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 std::optional<glm::vec3> sample_size() const#
Returns the requested voxel size for voxelizing the mesh, if one was given.
- Returns:
The requested voxel size for voxelizing the mesh, if one was given.
-
inline double sdf_shim() const#
Returns the amount subtracted from evaluated signed distance values.
- Returns:
The amount subtracted from evaluated signed distance values.
Private Types
-
typedef openvdb::FloatGrid GridType#
The type of grid used by OpenVDB.
Private Functions
-
void apply_slicer_ras_compensation(bool disable_validation)#
-
void load_from_file(bool center = false, bool disable_validation = false, bool compensate_slicer_ras = false)#
Loads the mesh from file into memory.
- Parameters:
center – If true, the mesh will be centered at the origin after loading
disable_validation – If true, the mesh will not be validated for errors
compensate_slicer_ras – If true, mirrors the mesh across Y to compensate for 3D Slicer RAS mesh exports used with DICOMLoader volumes.
-
virtual void prepare_bounding_box() override#
Sets the bounding box to the mesh’s box, grown by a positive sdf_shim.
Private Members
-
bool m_center = false#
Whether the mesh was centered at the origin after loading.
-
bool m_compensate_slicer_ras = false#
-
bool m_disable_validation = false#
Whether mesh validation was disabled when loading the file.
-
std::string m_file_path#
The path to the mesh file to load.
-
bool m_is_loaded = false#
Whether the mesh has been loaded into the signed distance field grid.
-
double m_lipschitz = DistanceBounds::unknown_lipschitz#
The Lipschitz bound prepare() measured on the grid (infinity until then).
-
std::shared_ptr<SurfaceMesh> m_mesh#
-
std::optional<double> m_override_voxel_size = std::nullopt#
The explicit voxel size to use when voxelizing the mesh, bypassing the minimum bound heuristic.
-
std::optional<glm::vec3> m_sample_size = std::nullopt#
-
double m_sdf_shim = 0.0#
-
glm::vec3 m_voxel_size#
The size of each voxel in the grid. This resolution does not need to match what you sample, and can be asymmetric.
-
inline bool center() const#
-
class TexturedMesh : public Leaf#
- #include <textured_mesh.h>
A closed textured triangle solid with an intrinsic volumetric COLOR_RGBA field.
TexturedMesh imports 3MF Materials/Properties or OBJ/MTL appearance data and converts the surface appearance during prepare() into a sparse inward color shell. Shell colors are extended from the closest surface point; deeper samples use the configured opaque core color. Geometry is prepared as an OpenVDB signed-distance grid.
The value follows Mesh: inside the bounding box padded by the bandwidth, evaluate() returns max(F, d), F the grid interpolated trilinearly and d the signed Euclidean distance to the bounding box, and no value beyond it. The grid’s exterior band reaches the prepared bandwidth (or sqrt(3) voxels, if wider).
Distance accuracy (distance_accuracy()): bound, with the Lipschitz bound prepare() measures on the grid (SurfaceMesh::sdf_lipschitz_bound(), at least 1), for the same reasons as Mesh; approximate before prepare() or if the measurement fails. Colors and other attributes are only sampled where the value is at most zero.
Note
3MF model units are converted to millimeters. OBJ coordinates are multiplied by obj_unit_scale because OBJ does not define physical units.
Note
Source alpha is deliberately ignored. COLOR_RGBA is always emitted with alpha 1.
Warning
prepare() must be called before evaluate() or sample().
Public Functions
-
virtual std::vector<std::string> attribute_list() final#
Returns a list of the attribute names in use by this node and its children.
Returns authored attributes plus intrinsic COLOR_RGBA.
- Returns:
A list of the attribute names
-
inline bool center() const#
Returns whether the resolved scene was centered at the origin.
- Returns:
Whether the resolved scene was centered at the origin.
-
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 double color_depth() const#
Returns the configured inward color depth.
- Returns:
The configured inward color depth.
-
inline glm::vec3 core_color() const#
Returns the configured opaque core RGB color.
- Returns:
The configured opaque core RGB color.
-
virtual std::vector<DiagramAttributeArtifact> diagram_attributes() const override#
Returns attribute artifacts owned by this node for Mermaid diagrams.
- Returns:
The node’s own attributes, sorted by name.
-
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 bool disable_validation() const#
Returns whether closed-manifold validation was bypassed.
- Returns:
Whether closed-manifold validation was bypassed.
-
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.
bound once prepared, with the measured Lipschitz bound (see the class notes).
- 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 std::optional<glm::vec3> fallback_color() const#
Returns the RGB color used for triangles without appearance, if one was given.
- Returns:
The RGB color used for triangles without appearance, if one was given.
-
inline const std::string &file_path() const#
Returns the path of the .3mf or .obj file.
- Returns:
The path of the .3mf or .obj file.
-
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 Lipschitz bound
prepare() measured on the grid, or infinity when approximate.- Returns:
L, at least 1, or infinity when nothing is promised.
-
inline double obj_unit_scale() const#
Returns the OBJ unit scale in millimeters per source unit.
- Returns:
The OBJ unit scale in millimeters per source unit.
-
inline std::optional<double> override_voxel_size() const#
Returns the explicit preparation voxel size in millimeters, if one was given.
- Returns:
The explicit preparation voxel size in millimeters, if one was given.
-
virtual void prepare_impl(const glm::vec3 &voxel_size, double bandwidth) final#
Prepares the SDF and sparse closest-surface color shell.
- Parameters:
voxel_size – Intended downstream sample size.
bandwidth – Requested signed-distance sampling bandwidth.
-
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.
Returns the signed distance and, only where it is at most zero, the attributes and color. Outside points and points with no value get no attributes; see
Node::sample().- Parameters:
x – The x coordinate of the point.
y – The y coordinate of the point.
z – The z coordinate of the point.
- Returns:
A TreeSample containing the signed distance (if any) and attribute samples (inside the part only).
Sets an attribute function for the node.
Rejects replacement of the intrinsic COLOR_RGBA field.
- Parameters:
name – The name of the attribute.
attribute – The attribute function to set.
- Throws:
std::runtime_error – if the attribute name is already in use by the node
-
TexturedMesh() = default#
-
TexturedMesh(const std::string &path, double color_depth = 1.0, const glm::vec3 &core_color = glm::vec3(1.0f), const std::optional<glm::vec3> &fallback_color = std::nullopt, bool center = false, double obj_unit_scale = 1.0, const std::optional<double> &override_voxel_size = std::nullopt, bool disable_validation = false)#
Loads a textured solid from a 3MF or OBJ file.
- Parameters:
path – Input .3mf or .obj path.
color_depth – Inward textured-shell depth in millimeters.
core_color – Opaque RGB color used below the shell.
fallback_color – Optional opaque RGB color used when a triangle has no appearance.
center – If true, centers the resolved scene at the origin.
obj_unit_scale – Millimeters per OBJ coordinate unit. Ignored for 3MF.
override_voxel_size – Optional explicit preparation voxel size in millimeters.
disable_validation – If true, bypasses closed-manifold validation for imperfect scans.
Private Functions
-
void initialize_samplers()#
-
void load_source(bool center)#
-
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
-
bool m_center = false#
-
double m_color_depth = 1.0#
-
std::shared_ptr<openvdb::tools::GridSampler<Vec4sGrid, openvdb::tools::BoxSampler>> m_color_sampler#
-
glm::vec3 m_core_color = glm::vec3(1.0f)#
-
bool m_disable_validation = false#
-
std::optional<glm::vec3> m_fallback_color = std::nullopt#
-
std::string m_file_path#
-
double m_lipschitz = DistanceBounds::unknown_lipschitz#
The Lipschitz bound prepare() measured on the SDF grid (infinity until then).
-
double m_obj_unit_scale = 1.0#
-
std::optional<double> m_override_voxel_size = std::nullopt#
-
glm::vec3 m_prepared_voxel_size = glm::vec3(0.0f)#
-
std::shared_ptr<openvdb::FloatGrid::Accessor> m_sdf_accessor#
-
openvdb::FloatGrid::Ptr m_sdf_grid#
-
std::shared_ptr<openvdb::tools::GridSampler<openvdb::FloatGrid, openvdb::tools::BoxSampler>> m_sdf_sampler#
-
std::shared_ptr<SourceData> m_source#
-
virtual std::vector<std::string> attribute_list() final#
-
class RectPrism : public Leaf#
- #include <rect_prism.h>
A rectangular prism leaf node/ geometric primitive.
This node is an axis-aligned rectangular prism with a center point and size. The size is the side lengths in X, Y, and Z. evaluate() returns the exact Euclidean signed distance to the box.
Note
This node can be evaluated in O(1) time.
Note
This node is a leaf node, and therefore cannot have any children.
Public Functions
-
inline glm::vec3 center() const#
Returns the center point of the RectPrism.
- Returns:
The center point of the RectPrism.
-
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.
Exact: the value is the Euclidean signed distance to the box, which is the bounding box. A negative side length describes no box, so it promises nothing (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.
-
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 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 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.
-
RectPrism()#
Default constructor. Creates a RectPrism with a center of (0, 0, 0) and size of (1, 1, 1).
Public Static Functions
-
inline glm::vec3 center() const#
-
class Sphere : public Leaf#
- #include <sphere.h>
A sphere leaf node/ geometric primitive.
This node is a sphere with a center point and radius. evaluate() returns the exact Euclidean signed distance to the sphere.
Note
This node can be evaluated in O(1) time.
Note
This node is a leaf node, and therefore cannot have any children.
Public Functions
-
inline glm::vec3 center() const#
Returns the center point of the Sphere.
- Returns:
The center point of the Sphere.
-
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.
Exact: the value is the Euclidean signed distance to the ball, which the bounding box holds. A negative radius describes no ball, so it promises nothing (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.
-
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.
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().
-
inline glm::vec3 center() const#
-
class Strut : public Leaf#
- #include <strut.h>
A leaf node that represents a strut.
A strut is the conical frustum swept between a start and an end point, with an independent radius at each end, closed by a capping mode at each end. When both radii are equal and both ends are sphere capped, the strut is a capsule.
Note
The geometry follows the 3MF Beam Lattice Extension definition of a beam: the frustum is built between the two vertices and then unioned with the requested end caps.
Public Types
-
enum class CapMode#
How a strut end is closed off.
Mirrors ST_CapMode from the 3MF Beam Lattice Extension.
Values:
-
enumerator Sphere#
The end is closed with a full sphere of the end radius.
-
enumerator HemiSphere#
The end is closed with the outward half of a sphere of the end radius.
-
enumerator Butt#
The end is closed flat, leaving a cylindrical or conical shape.
-
enumerator Sphere#
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.
How faithfully the value matches the true distance, by cap configuration.
exact: a capsule (equal radii, sphere caps), a frustum with butt caps at both ends, and a degenerate (zero-length) strut without butt caps (a ball);
bound, Lipschitz bound 1: a frustum with sphere caps at either end otherwise. The caps are joined by min, which is exact outside and underestimates the depth inside;
approximate: a hemisphere at the wider end. The hemisphere is gated by the plane through its vertex, so the value jumps inside the material across that plane (from the frustum’s near-zero depth to the sphere’s). Also a degenerate strut with a butt cap, whose ball may not fit the butt end’s box.
- Returns:
The accuracy of the subtree rooted at this node.
-
inline const glm::vec3 &end() const#
Returns the end point of the strut.
- Returns:
The end point of the strut.
-
inline CapMode end_cap() const#
Returns the capping mode applied at the end point.
- Returns:
The capping mode applied at the end point.
-
inline double end_radius() const#
Returns the radius at the end point.
- Returns:
The radius at the end point.
-
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 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()
.
A strut with equal end radii reports a single “radius” entry.
- Returns:
The ordered property list. The base implementation returns an empty list.
-
inline const glm::vec3 &start() const#
Returns the start point of the strut.
- Returns:
The start point of the strut.
-
inline CapMode start_cap() const#
Returns the capping mode applied at the start point.
- Returns:
The capping mode applied at the start point.
-
inline double start_radius() const#
Returns the radius at the start point.
- Returns:
The radius at the start point.
-
Strut(glm::vec3 start, glm::vec3 end, double radius)#
Constructor for a capsule: one radius, sphere caps at both ends.
- Parameters:
start – The start of the strut.
end – The end of the strut.
radius – The radius of the strut.
-
Strut(glm::vec3 start, glm::vec3 end, double start_radius, double end_radius, CapMode start_cap = CapMode::Sphere, CapMode end_cap = CapMode::Sphere)#
Constructor for a general beam with independent end radii and cap modes.
- Parameters:
start – The start of the strut.
end – The end of the strut.
start_radius – The radius at the start point.
end_radius – The radius at the end point.
start_cap – The capping mode applied at the start point.
end_cap – The capping mode applied at the end point.
Private Functions
-
bool is_capsule() const#
Returns true when the strut reduces to a plain capsule.
- Returns:
True when the strut reduces to a plain capsule.
-
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
-
glm::vec3 m_end#
The end of the strut.
-
double m_end_radius#
The radius at the end of the strut.
-
glm::vec3 m_start#
The start of the strut.
-
CapMode m_start_cap_effective#
The start cap reduced to the simplest mode describing the same solid.
-
double m_start_radius#
The radius at the start of the strut.
-
enum class CapMode#
-
class CAD : public Leaf#
- #include <cad.h>
A CAD geometry primitive/ leaf node.
The CAD is loaded from a file into memory for sampling.
Distance accuracy (distance_accuracy()): in exact mode (use_fast_mode = false) the value is OpenCASCADE’s distance to the B-rep, signed by its solid classifier. prepare() checks the part: when it is one closed shell (every face in it, every edge bounding two faces) and every face and edge is elementary (planes, cylinders, cones, spheres and tori bounded by lines and conics), the distance comes from closed-form extrema and the value is exact. A solid is sewn into its shell; a solid bounded by a single face (a sphere, a torus), which sewing would leave as a loose face with no inside, keeps its own shell. Otherwise exact mode is approximate: free-form (B-spline or offset) geometry uses sampled extrema that can miss the nearest point, an open shape or a loose face has no consistent sign, and unsewn or overlapping bodies are not checked.
Fast mode samples a mesh SDF grid of the tessellated part like Mesh: inside the bounding box padded by the bandwidth, evaluate() returns max(F, d), F the grid interpolated trilinearly and d the signed Euclidean distance to the bounding box, and no value beyond it. It is bound, with the Lipschitz bound prepare() measures on the grid (SurfaceMesh::sdf_lipschitz_bound(), at least 1), for the same reasons as Mesh. Attributes are only sampled where the value is at most zero, in both modes.
Note
The node supports .STEP and .igs files.
Public Functions
-
CAD() = default#
-
CAD(const std::string &path, bool use_fast_mode = true, std::optional<double> fast_sdf_voxel_size = std::nullopt)#
Constructor.
- Parameters:
path – The path to the CAD file to load
use_fast_mode – Whether preparation should construct an accelerated SDF grid.
fast_sdf_voxel_size – Optional uniform SDF cache spacing in millimetres.
-
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.
exact in exact mode for a closed part with elementary geometry, bound in fast mode, otherwise approximate. See the class notes. Decided by
prepare().- 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 std::optional<double> fast_sdf_voxel_size() const#
Returns the requested uniform fast-SDF voxel size in millimetres.
An empty value uses the smallest component of the downstream sampling voxel size.
- Returns:
The requested uniform fast-SDF voxel size in millimetres.
-
inline const std::string &file_path() const#
Returns the path of the CAD file, or an empty string for a node built from a CADPart.
-
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()
.
1 when exact, the measured bound in fast mode, 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#
Prepares the CAD node by loading it from disk and building the internal bounding volume hierarchy.
- Parameters:
voxel_size – The size of the voxels
bandwidth – The bandwidth of the tree
-
inline std::optional<double> prepared_fast_sdf_voxel_size() const#
Returns the uniform fast-SDF voxel size used by the most recent preparation.
- Returns:
The uniform fast-SDF voxel size used by the most recent preparation.
-
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.
Returns the signed distance and, only where it is at most zero, the attributes. Outside points and points with no value get no attributes; see
Node::sample().- 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 bool use_fast_mode() const#
Returns whether preparation constructs an accelerated SDF grid.
- Returns:
Whether preparation constructs an accelerated SDF grid.
Private Functions
-
double resolve_fast_sdf_voxel_size() const#
Resolves the uniform fast-SDF voxel size for the current preparation.
-
void validate_fast_sdf_cache_size(double fast_sdf_voxel_size, double interior_bandwidth, double exterior_bandwidth) const#
Rejects fast-SDF requests whose padded dense-grid estimate is unsafe.
Private Members
-
bool m_exact_distance_geometry = false#
Set by prepare(): the part is closed and every face and edge is elementary.
-
double m_fast_lipschitz = DistanceBounds::unknown_lipschitz#
Fast mode: the Lipschitz bound prepare() measured on the grid (infinity until then).
-
double m_fast_lipschitz_bandwidth = -1.0#
Fast mode: the bandwidth m_fast_lipschitz was measured for (negative until then).
-
std::optional<double> m_fast_sdf_voxel_size#
-
std::string m_file_path#
-
bool m_is_loaded = false#
-
double m_prepared_exterior_bandwidth = 0.0#
-
std::optional<double> m_prepared_fast_sdf_voxel_size#
-
double m_prepared_interior_bandwidth = 0.0#
-
bool m_use_fast_mode = true#
-
glm::vec3 m_voxel_size#
-
CAD() = default#
-
class Cylinder : public Leaf#
- #include <cylinder.h>
A cylinder leaf node/ geometric primitive.
This node is a capped cylinder with a center point, radius, and height. Its axis is parallel to the Z axis and passes through the center, and it spans center.z - height / 2 to center.z + height / 2. The evaluate() function returns the signed distance to the surface.
Note
This node can be evaluated in O(1) time.
Note
This node is a leaf node, and therefore cannot have any children.
Public Functions
-
inline glm::vec3 center() const#
Returns the center point of the Cylinder.
- Returns:
The center point of the Cylinder.
-
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
-
Cylinder()#
Default constructor. Creates a Cylinder with a center of (0,0,0), radius of 1, and height of 1.
-
Cylinder(glm::vec3 center, double radius, double height)#
Constructor.
Creates a Z-aligned Cylinder with a center, radius, and height.
-
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.
Exact: the value is the Euclidean signed distance to the capped cylinder (a 2D box distance in radius and height), which the bounding box holds. A negative radius or height describes no cylinder, so it promises nothing (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.
-
inline double height() const#
Returns the height of the Cylinder.
- Returns:
The height of the Cylinder.
-
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.
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().
-
inline glm::vec3 center() const#
-
class Cone : public Leaf#
- #include <cone.h>
A cone leaf node/ geometric primitive.
The apex is at the origin and the axis points along +Y: the cone opens downward and its flat base, of radius height * tan(angle), lies in the plane y = -height. Use Translate and Rotate to place it elsewhere.
Public Functions
-
inline double angle() const#
Returns the aperture half-angle of the cone in radians.
- Returns:
The aperture half-angle of the cone in radians.
-
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
-
Cone() = default#
Default constructor. Creates a Cone with a half-angle of 0.5 radians and a height of 1.
-
Cone(double angle, double height)#
Constructor.
Creates a Cone with an angle and height.
- Parameters:
angle – The aperture half-angle in radians.
height – The height of the cone, from the apex at the origin down to the base at y = -height.
-
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.
Exact for a proper cone: the value is the exact capped-cone distance, which the bounding box holds. Needs an aperture half-angle strictly between 0 and 90 degrees and a positive height; other values degenerate the formula or invert the box, so they promise nothing.
- 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 height() const#
Returns the height of the cone.
- Returns:
The height of the cone.
-
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.
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().
-
inline double angle() const#
-
class Torus : public Leaf#
- #include <torus.h>
A torus leaf node/ geometric primitive.
This node is a torus with a major and minor radius. See this for more information: https://wiki.povray.org/uploaded/2/29/RefImgMimxrtor.gif The major radius is the distance from the center of the torus to the center of the tube. The minor radius is the radius of the tube. The torus is centered at the origin with its ring in the XY plane, so its axis of symmetry is Z.
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.
Exact for a ring or horn torus (r2 <= r1), bound with Lipschitz bound 1 for a spindle torus. The value |(|xy| - r1, z)| - r2 is 1-Lipschitz and is the exact distance outside every torus. Inside a spindle torus (r2 > r1, r1 > 0) the tube circle crosses the axis, so the depth near the axis is underestimated: a bound. r1 = 0 is a sphere (exact). Negative radii describe no torus, so they promise nothing (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.
-
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.
-
inline double r1() const#
Returns the major radius (distance from the torus center to the tube center).
- Returns:
The major radius (distance from the torus center to the tube center).
-
inline double r2() const#
Returns the minor radius (radius of the tube).
- Returns:
The minor radius (radius of the tube).
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().
-
virtual std::shared_ptr<Node> clone() final#
-
class GraphLattice : public Leaf#
- #include <graph_lattice.h>
A leaf node representing a lattice structure constructed from a list of edges.
Struts are created for each edge and grouped into an internal bounding volume hierarchy.
Public Types
-
enum class LatticeType#
Built-in unit cells whose edges the lattice can generate.
Values:
-
enumerator BodyCenteredCubic#
Body-centered cubic (see BCC_GenerateEdges()).
-
enumerator FaceCenteredCubic#
Face-centered cubic (see FCC_GenerateEdges()).
-
enumerator Cubic#
Simple cubic (see Cubic_GenerateEdges()).
-
enumerator KelvinCell#
Kelvin cell (see KelvinCell_GenerateEdges()).
-
enumerator BodyCenteredCubic#
Public Functions
-
inline std::optional<glm::vec3> cell_size() const#
Returns the unit cell size, if the lattice was built from a unit cell type.
- Returns:
The unit cell size, if the lattice was built from a unit cell type.
-
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.
bound, sharp or blended: the value is the larger of the strut union and the exact distance to the lattice box. The union is the sorted quadratic fold of exact capsule distances, which is 1-Lipschitz, and the members it skips are far enough that they cannot move it within the bandwidth. The box term keeps every value outside the box at least the distance to it, however far a blend of several struts dips.
- Returns:
The accuracy of the subtree rooted at this node.
-
inline const std::vector<std::pair<glm::vec3, glm::vec3>> &edges() const#
Returns the strut edges, either as supplied or as generated for the unit cell.
- Returns:
The strut edges, either as supplied or as generated for the unit cell.
-
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.
-
GraphLattice(const std::vector<std::pair<glm::vec3, glm::vec3>> &edges, double radius)#
Constructor.
Builds one strut per edge.
- Parameters:
edges – The strut start and end points.
radius – The strut radius.
-
GraphLattice(LatticeType type, glm::vec3 size, double radius)#
Constructor.
Builds the struts of one built-in unit cell.
- Parameters:
type – The unit cell type.
size – The dimensions of the unit cell in X, Y, and Z.
radius – The strut radius.
-
inline std::optional<LatticeType> lattice_type() const#
Returns the unit cell type, if the lattice was built from one.
- Returns:
The unit cell type, if the lattice was built from one.
-
virtual double lipschitz_bound() const override#
See also
- Returns:
1.
-
inline double member_blend_radius() const#
Returns the smooth-blend radius between distinct struts.
- Returns:
The smooth-blend radius between distinct struts.
-
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.
-
inline double radius() const#
Returns the strut radius.
- Returns:
The strut radius.
-
void set_member_blend_radius(double radius)#
Sets the smooth-blend radius between distinct struts (0, the default, is sharp).
Struts are joined with the shared quadratic blend (SmoothBlend), which fillets the nodes. Every edge is its own member, so repeated identical edges in the list would bulge; give each edge once. Call before prepare().
- Parameters:
radius – The blend radius.
- Throws:
std::runtime_error – if radius is negative or not finite.
Public Static Functions
-
static std::vector<std::pair<glm::vec3, glm::vec3>> BCC_GenerateEdges(glm::vec3 size)#
Generates edge definitions for a Body Centered Cubic (BCC) lattice unit cell.
- Parameters:
size – The dimensions of the unit cell in X, Y, and Z.
- Returns:
A list of start and end point pairs defining the struts.
-
static std::vector<std::pair<glm::vec3, glm::vec3>> Cubic_GenerateEdges(glm::vec3 size)#
Generates edge definitions for a simple Cubic lattice unit cell.
- Parameters:
size – The dimensions of the unit cell in X, Y, and Z.
- Returns:
A list of start and end point pairs defining the struts.
-
static std::vector<std::pair<glm::vec3, glm::vec3>> FCC_GenerateEdges(glm::vec3 size)#
Generates edge definitions for a Face Centered Cubic (FCC) lattice unit cell.
- Parameters:
size – The dimensions of the unit cell in X, Y, and Z.
- Returns:
A list of start and end point pairs defining the struts.
-
static std::vector<std::pair<glm::vec3, glm::vec3>> KelvinCell_GenerateEdges(glm::vec3 size)#
Generates edge definitions for a Kelvin Cell lattice unit cell.
- Parameters:
size – The dimensions of the unit cell in X, Y, and Z.
- Returns:
A list of start and end point pairs defining the struts.
Private Functions
-
void build_lattice()#
-
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().
-
enum class LatticeType#
-
class BeamLattice : public Leaf#
- #include <beam_lattice.h>
A leaf node representing a beam-and-ball lattice defined over a shared vertex list.
BeamLattice implements the geometry model of the 3MF Beam Lattice Extension. Beams index into a shared vertex list and carry optional per-end radii and cap modes that fall back to the lattice defaults. Balls are spheres centred on vertices. Every beam and ball becomes a child of an internal accelerated union, so large lattices stay cheap to sample.
Note
Beams shorter than min_length are dropped, as the specification requires consumers to ignore them.
Warning
prepare() must be called before evaluate() or sample(). bounding_box() is safe before prepare(); the box is computed in the constructor.
Public Types
-
enum class BallMode#
Whether balls are generated at beam vertices.
Mirrors ST_BallMode from the 3MF Beam Lattice Extension.
Values:
-
enumerator None#
No balls are created.
-
enumerator Mixed#
Balls are created only at vertices with an explicit ball entry.
-
enumerator All#
Balls are created at every vertex that terminates a surviving beam.
-
enumerator None#
Public Functions
-
inline size_t active_ball_count() const#
Returns the number of balls that were generated.
- Returns:
The number of balls that were generated.
-
inline size_t active_beam_count() const#
Returns the number of beams that survived the min_length filter.
- Returns:
The number of beams that survived the min_length filter.
-
inline double ball_radius() const#
Returns the default ball radius.
- Returns:
The default ball radius.
-
inline const std::vector<Ball> &balls() const#
Returns the explicit ball entries as supplied.
- Returns:
The explicit ball entries as supplied.
-
BeamLattice(const std::vector<glm::vec3> &vertices, const std::vector<Beam> &beams, double radius, double min_length = 0.0, CapMode cap = CapMode::Sphere, BallMode ball_mode = BallMode::None, double ball_radius = 0.0, const std::vector<Ball> &balls = {})#
Constructor.
- Parameters:
vertices – The shared vertex list that beams and balls index into.
beams – The beams of the lattice.
radius – The default beam radius used when a beam does not specify one.
min_length – Beams shorter than this length are discarded.
cap – The default cap mode used when a beam end does not specify one.
ball_mode – Whether balls are generated at beam vertices.
ball_radius – The default ball radius. Required when ball_mode is not None.
balls – Explicit per-vertex ball entries.
-
inline const std::vector<Beam> &beams() const#
Returns the beams as supplied, including any dropped by min_length.
- Returns:
The beams as supplied, including any dropped by min_length.
-
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.
bound: the value is the sharp minimum of exact beam and ball distances, every member is evaluated within the bandwidth of its own box, and the box covers every member. approximate when a beam keeps a hemisphere cap on its wider end: inside that beam the value jumps across the cap’s flat face.
- 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 double lipschitz_bound() const override#
See also
- Returns:
1 for a bound lattice, infinity otherwise.
-
inline double min_length() const#
Returns the minimum beam length.
- Returns:
The minimum beam length.
-
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.
-
inline double radius() const#
Returns the default beam radius.
- Returns:
The default beam radius.
-
inline const std::vector<glm::vec3> &vertices() const#
Returns the shared vertex list.
- Returns:
The shared vertex list.
Private Functions
-
void build_lattice()#
Builds the internal accelerated union of struts and balls.
-
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
-
size_t m_active_ball_count = 0#
-
size_t m_active_beam_count = 0#
-
double m_ball_radius#
-
bool m_has_wide_hemisphere_cap = false#
True if a surviving beam has a hemisphere cap on its strictly wider end.
-
double m_min_length#
-
double m_radius#
-
std::vector<glm::vec3> m_vertices#
-
struct Ball#
- #include <beam_lattice.h>
One ball of the lattice.
-
struct Beam#
- #include <beam_lattice.h>
One beam of the lattice.
Unset radii and cap modes fall back to the lattice defaults, matching the resolution order defined by the specification.
-
enum class BallMode#
Enums
-
enum class ThreeMFClipMode#
How a beam lattice is clipped against its clipping mesh.
Mirrors ST_ClippingMode from the 3MF Beam Lattice Extension.
Values:
-
enumerator None#
The lattice is not clipped.
-
enumerator Inside#
Only lattice geometry inside the clipping mesh is retained.
-
enumerator Outside#
Only lattice geometry outside the clipping mesh is retained.
-
enumerator None#
Functions
-
ThreeMFBeamLatticeScene read_3mf_beam_lattice(const std::string &path)#
Reads the geometry of a 3MF file, including any beam lattices, without building a tree.
Every build item is resolved through its component graph, transforms are baked into the returned coordinates, and coordinates are converted to millimeters. Beam and ball property references are not read; this importer covers geometry only.
- Parameters:
path – The path to the .3mf file.
- Throws:
std::runtime_error – if the file cannot be read or contains unsupported constructs.
- Returns:
The resolved scene.
-
class ThreeMFBeamLattice : public Leaf#
- #include <three_mf_beam_lattice.h>
A leaf node that imports a 3MF Beam Lattice Extension file as an implicit tree.
Each imported object becomes a BeamLattice unioned with the object’s triangle shell. A lattice with a clipping mode is intersected with, or subtracted from, its clipping mesh, so the imported geometry matches what a conforming consumer would produce. Coordinates are converted to millimeters and build transforms are applied.
Note
This importer covers geometry only. Per-beam and per-ball property references (pid, p1, p2) are not read, so imported lattices carry no material or color attributes.
Warning
prepare() must be called before evaluate() or sample(). bounding_box() is safe before prepare(); the box is computed in the constructor.
Public Functions
-
inline bool apply_clipping() const#
Returns true if lattice clipping modes are applied against their clipping meshes.
- Returns:
True if lattice clipping modes are applied against their clipping meshes.
-
size_t ball_count() const#
Returns the total number of explicit balls across the imported objects.
- Returns:
The total number of explicit balls across the imported objects.
-
size_t beam_count() const#
Returns the total number of beams across the imported objects.
- Returns:
The total number of beams across the imported objects.
-
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.
Composes the imported pieces: each
BeamLattice and Mesh reports its own accuracy, and the sharp union, clip intersection and clip difference the importer builds keep a bound with the largest L. approximate if any piece is, if a printed piece (lattice, shell, or representation mesh) reaches outside the import box, or if a clipping mesh’s box misses the lattice box entirely.- 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 std::string &file_path() const#
Returns the source file path.
- Returns:
The source file path.
-
inline const std::vector<ThreeMFBeamLatticeObject> &imported_objects() const#
Returns the objects that were imported into the tree.
- Returns:
The objects that were imported into the tree.
-
inline bool include_triangle_mesh() const#
Returns true if each object’s triangle shell is unioned with its lattice.
- Returns:
True if each object’s triangle shell is unioned with its lattice.
-
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.
-
inline std::optional<double> mesh_voxel_size() const#
Returns the explicit voxel size for triangle and clipping meshes, if one was given.
- Returns:
The explicit voxel size for triangle and clipping meshes, if one was given.
-
inline std::optional<uint32_t> object_id() const#
Returns the selected object resource id, or no value when the whole build is imported.
- Returns:
The selected object resource id, or no value when the whole build is imported.
-
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.
-
inline const ThreeMFBeamLatticeScene &scene() const#
Returns the scene that was read from the file.
- Returns:
The scene that was read from the file.
-
ThreeMFBeamLattice(const std::string &path, const std::optional<uint32_t> &object_id = std::nullopt, bool include_triangle_mesh = true, bool apply_clipping = true, bool use_representation_mesh = false, const std::optional<double> &mesh_voxel_size = std::nullopt)#
Constructor.
- Parameters:
path – The path to the .3mf file.
object_id – Imports only this object resource id. Defaults to the whole build.
include_triangle_mesh – If true, unions each object’s triangle shell with its lattice.
apply_clipping – If true, applies the lattice clipping mode against its clipping mesh.
use_representation_mesh – If true, substitutes the representation mesh for the lattice geometry. The specification restricts representation meshes to display and preview, so this must not be used to manufacture a part.
mesh_voxel_size – Optional explicit voxel size for triangle and clipping meshes.
-
inline bool use_representation_mesh() const#
Returns true if representation meshes replace the lattice geometry.
- Returns:
True if representation meshes replace the lattice geometry.
Private Functions
-
std::shared_ptr<Node> build_object(const ThreeMFBeamLatticeObject &object) const#
Builds the implicit node for a single imported object.
-
void build_tree()#
Builds the implicit tree for the selected objects.
-
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
-
bool m_apply_clipping = true#
-
std::string m_file_path#
-
std::vector<ThreeMFBeamLatticeObject> m_imported#
-
bool m_include_triangle_mesh = true#
-
std::optional<double> m_mesh_voxel_size#
-
std::optional<uint32_t> m_object_id#
-
ThreeMFBeamLatticeScene m_scene#
-
bool m_use_representation_mesh = false#
-
inline bool apply_clipping() const#
-
struct ThreeMFBeamLatticeObject#
- #include <three_mf_beam_lattice.h>
One mesh object resolved from a 3MF build, with its beam lattice if it carries one.
All coordinates are resolved into millimeters and already carry the build item and component transforms that apply to the object.
Public Members
-
BeamLattice::BallMode ball_mode = BeamLattice::BallMode::None#
The ball mode.
-
double ball_radius = 0.0#
The default ball radius.
-
std::vector<BeamLattice::Ball> balls#
The explicit ball entries of the lattice.
-
std::vector<BeamLattice::Beam> beams#
The beams of the lattice.
-
Strut::CapMode cap = Strut::CapMode::Sphere#
The most common resolved beam-end cap mode (lib3mf does not expose the file’s default).
-
ThreeMFClipMode clip_mode = ThreeMFClipMode::None#
The clipping mode of the lattice.
-
std::vector<Indexed_Triangle> clip_triangles#
Clipping mesh triangles.
-
std::vector<glm::vec3> clip_vertices#
Clipping mesh vertices, under the same transform.
-
std::optional<uint32_t> clipping_mesh_id#
The resource id of the clipping mesh.
-
bool has_lattice = false#
True when the object carries a beam lattice.
-
double min_length = 0.0#
The minimum beam length.
-
std::string name#
The object name, when the file supplies one.
-
uint32_t object_id = 0#
The 3MF resource id of the object.
-
double radius = 0.0#
The most common resolved beam-end radius (lib3mf does not expose the file’s default).
-
std::optional<uint32_t> representation_mesh_id#
The resource id of the representation mesh.
-
std::vector<Indexed_Triangle> representation_triangles#
Representation mesh triangles.
-
std::vector<glm::vec3> representation_vertices#
Representation mesh vertices, under the same transform.
-
std::vector<Indexed_Triangle> triangles#
The triangle shell of the same object.
-
std::vector<glm::vec3> vertices#
The mesh vertex list beams index into.
-
BeamLattice::BallMode ball_mode = BeamLattice::BallMode::None#
-
struct ThreeMFBeamLatticeScene#
- #include <three_mf_beam_lattice.h>
The resolved contents of a 3MF file read through the Beam Lattice Extension.
Public Members
-
std::vector<ThreeMFBeamLatticeObject> objects#
Objects in build order.
-
double unit_scale_mm = 1.0#
Millimeters per source model unit.
-
std::vector<ThreeMFBeamLatticeObject> objects#
-
class MappedImplicitLattice : public Leaf#
- #include <mapped_implicit_lattice.h>
A metric-corrected periodic implicit unit cell evaluated through a CellMap.
At a world point the unit cell’s value is evaluated at the point’s logical coordinates and divided by the length of its gradient pulled back through the map’s Jacobian, which gives a first-order world-space distance to the cell’s zero surface. In “sheet” mode the solid is the wall of that surface, |distance| - thickness / 2; in “solid” mode it is distance - level.
Public Functions
-
virtual std::vector<std::string> attribute_list() override#
Returns a list of the attribute names in use by this node and its children.
Includes the shell attributes.
- Returns:
A list of the attribute names
-
inline const std::shared_ptr<CellMap> &cell_map() const#
Return the immutable coordinate map.
- Returns:
The coordinate map.
-
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
-
std::shared_ptr<FloatAttribute> component_side_field() const#
A field giving which side of the zero surface a point is on: 1, -1, or 0 on it.
- Returns:
The field.
-
std::shared_ptr<FloatAttribute> component_surface_distance_field() const#
A field giving the signed first-order distance to the unit cell’s zero surface.
Component fields only work inside shell attributes (set_shell_attribute()); sampled anywhere else they throw.
- Returns:
The field.
-
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.
approximate: the value is the first-order estimate raw / |metric gradient|, which can over- or under-estimate the distance, it has no value where that gradient vanishes, and outside the map domain it switches to the distance to the domain boundary.
- 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 std::shared_ptr<FloatAttribute> &level() const#
Return the solid level-offset field.
- Returns:
The solid level-offset field.
-
virtual double lipschitz_bound() const override#
See also
- Returns:
Infinity.
Constructor.
- Parameters:
cell_map – The map the unit cell is evaluated through; must validate (no folds).
unit_cell – The periodic implicit unit cell; its callback must be periodic.
mode – “sheet” for a wall around the zero surface, or “solid” for one side of it.
wall_thickness – The full sheet thickness field in world units; nullptr for 1.
level – The solid level-offset field in world units; nullptr for 0.
- Throws:
std::runtime_error – if the map or unit cell is null, the mode is unknown, the map is folded or invalid, or the unit cell is not periodic.
-
inline const std::string &mode() const#
Return the evaluation mode, “sheet” or “solid”.
- Returns:
The evaluation mode, “sheet” or “solid”.
-
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) 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).
Sets an attribute function for the node.
Sets a lattice-wide attribute. Shell attributes of the same name take precedence.
- Parameters:
name – The name of the attribute.
attribute – The attribute function to set.
- Throws:
std::runtime_error – if the attribute name is already in use by the node
std::runtime_error – if the attribute is null or a shell attribute of the same name has a different return type.
Attach an attribute to the repeated implicit shell component.
Replaces any earlier shell attribute of the same name. Shell attributes override the lattice-wide ones and can read the component fields below.
- Parameters:
name – The attribute name.
attribute – The attribute.
- Throws:
std::runtime_error – if the attribute is null or a lattice attribute of the same name has a different return type.
-
inline const std::shared_ptr<ImplicitUnitCell> &unit_cell() const#
Return the implicit unit cell.
- Returns:
The unit cell.
-
inline const std::shared_ptr<FloatAttribute> &wall_thickness() const#
Return the sheet wall-thickness field.
- Returns:
The sheet wall-thickness field.
Private Functions
-
std::optional<double> evaluate_located(const glm::vec3 &world, const CellMapLocation &location, double *surface_distance = nullptr) const#
-
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<FloatAttribute> m_level#
-
std::string m_mode#
-
std::shared_ptr<AttributeSet> m_shell_attributes#
-
std::shared_ptr<ImplicitUnitCell> m_unit_cell#
-
std::shared_ptr<FloatAttribute> m_wall_thickness#
-
virtual std::vector<std::string> attribute_list() override#
-
struct MappedGraphComponentDefinition#
- #include <mapped_graph_lattice.h>
Authoring metadata for one reusable graph-unit-cell component.
Tags are -1 when the unit cell defines none. Joints only fill id and tag.
Public Members
-
glm::vec3 direction = {0.0f}#
Unit direction from the strut’s first to second vertex in unit-cell coordinates; zero for a joint.
-
int id = -1#
The unit-cell edge index (strut) or vertex index (joint).
-
int material_tag = -1#
The strut’s material tag.
-
int orientation_tag = -1#
The strut’s orientation tag.
-
int tag = -1#
The edge tag (strut) or vertex tag (joint).
-
glm::vec3 direction = {0.0f}#
-
class MappedGraphLattice : public Leaf#
- #include <mapped_graph_lattice.h>
A compact native graph lattice tiled and curved through a CellMap.
Struts (and optional joint spheres) are combined with a plain minimum unless a member blend radius is given. Then distinct members are joined with the shared smooth blend (SmoothBlend, quadratic profile, order-independent), which fillets the nodes where struts meet. A member is one strut or one joint in lattice coordinates: the copies of a strut or joint that neighbouring cells share, and the pieces of a strut subdivided to follow a curved map, count as one member and are never blended with each other. The radius may be a field (a ScalarParameter with bounds); where it is 0 the nodes stay sharp. Fillet material takes the nearest member’s component attributes.
Public Functions
-
virtual std::vector<std::string> attribute_list() override#
Returns a list of the attribute names in use by this node and its children.
Includes the strut and joint component attributes.
- Returns:
A list of the attribute names
-
inline const std::shared_ptr<FloatAttribute> &beam_radius() const#
Return the beam-radius field.
- Returns:
The beam-radius field.
-
inline const std::shared_ptr<CellMap> &cell_map() const#
Return the immutable coordinate map.
- Returns:
The immutable coordinate map.
-
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
-
std::shared_ptr<Vec3Attribute> component_direction_field() const#
A field giving the sampled strut’s unit world direction.
- Returns:
The field.
-
std::shared_ptr<FloatAttribute> component_id_field() const#
A field giving the sampled component’s unit-cell edge or vertex index.
Component fields only work inside component attributes (set_strut_attribute(), set_joint_attribute()); sampled anywhere else they throw.
- Returns:
The field.
-
std::shared_ptr<FloatAttribute> component_material_tag_field() const#
A field giving the sampled strut’s material tag.
- Returns:
The field.
-
std::shared_ptr<FloatAttribute> component_orientation_tag_field() const#
A field giving the sampled strut’s orientation tag.
- Returns:
The field.
-
std::shared_ptr<FloatAttribute> component_parameter_field() const#
A field giving the position along the sampled strut, 0 at its first vertex and 1 at its second.
- Returns:
The field.
-
std::shared_ptr<FloatAttribute> component_surface_distance_field() const#
A field giving the lattice’s signed distance at the sample point.
- Returns:
The field.
-
std::shared_ptr<FloatAttribute> component_tag_field() const#
A field giving the sampled component’s tag (edge tag, or vertex tag for a joint).
- Returns:
The field.
-
inline double curve_tolerance() const#
Return the maximum mapped chord error.
- Returns:
The maximum mapped chord error.
-
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.
approximate: outside the located map domain the value switches to the distance to the domain boundary, so crossing an open boundary cell face jumps from the strut distance to about 0.
- 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.
-
size_t joint_count() const#
Returns the number of unit-cell joints (vertices).
- Returns:
The joint count.
-
MappedGraphComponentDefinition joint_definition(size_t vertex_id) const#
Returns the authoring metadata of one unit-cell joint.
- Parameters:
vertex_id – The unit-cell vertex index.
- Throws:
std::runtime_error – if vertex_id is out of range.
- Returns:
The joint’s id and tag.
-
virtual double lipschitz_bound() const override#
See also
- Returns:
Infinity.
Constructor.
A strut whose unit-cell edge has a material tag gets a one-material VOLUME_FRACTIONS component attribute for that tag.
- Parameters:
cell_map – The map the unit cell is tiled through; must validate (no folds).
unit_cell – The graph unit cell tiled once per active cell.
beam_radius – The strut radius field, sampled along the struts in the map’s context.
node_radius – Optional joint-sphere radius field; nullptr for no joint spheres.
curve_tolerance – The maximum chord error when a strut is subdivided to follow a curved map; must be positive.
member_blend_radius – The radius that blends distinct members; 0 for a sharp lattice.
- Throws:
std::runtime_error – if a required input is null, the map is folded or invalid, curve_tolerance is not positive, or the blend radius can be negative.
-
inline const ScalarParameter &member_blend_radius() const#
Return the radius that blends distinct struts and joints (0 for a sharp lattice).
- Returns:
The radius that blends distinct struts and joints (0 for a sharp lattice).
-
inline const std::shared_ptr<FloatAttribute> &node_radius() const#
Return the optional node-radius field, or nullptr when none was given.
- Returns:
The optional node-radius field, or nullptr when none was given.
-
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.
Tiles the unit cell through every active cell and builds the segment BVH.
- Parameters:
voxel_size – The size of a voxel we plan to sample with.
bandwidth – The bandwidth of the tree we are sampling.
- Throws:
std::runtime_error – if the lattice has no active segment or the node radius is not a positive scalar.
-
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).
-
std::optional<MappedGraphSegmentInfo> segment_info(const glm::vec3 &world) const#
Returns the provenance of the segment nearest a world point.
- Parameters:
world – The world point.
- Returns:
The nearest segment’s info, or std::nullopt before prepare() or outside the map domain.
Sets an attribute function for the node.
Sets a lattice-wide attribute. Component attributes of the same name take precedence where they are set.
- Parameters:
name – The name of the attribute.
attribute – The attribute function to set.
- Throws:
std::runtime_error – if the attribute name is already in use by the node
std::runtime_error – if the attribute is null or a component attribute of the same name has a different return type.
Attach an attribute to one reusable unit-cell joint.
As set_strut_attribute(), for the joint spheres at one unit-cell vertex.
- Parameters:
vertex_id – The unit-cell vertex index.
name – The attribute name.
attribute – The attribute.
- Throws:
std::runtime_error – if vertex_id is out of range, the attribute is null, or a lattice attribute of the same name has a different return type.
Attach an attribute to one reusable unit-cell strut.
The attribute applies to every copy of that strut and replaces any earlier component attribute of the same name. Component attributes override the lattice-wide ones and can read the component fields below.
- Parameters:
edge_id – The unit-cell edge index.
name – The attribute name.
attribute – The attribute.
- Throws:
std::runtime_error – if edge_id is out of range, the attribute is null, or a lattice attribute of the same name has a different return type.
-
size_t strut_count() const#
Returns the number of unit-cell struts (edges).
- Returns:
The strut count.
-
MappedGraphComponentDefinition strut_definition(size_t edge_id) const#
Returns the authoring metadata of one unit-cell strut.
- Parameters:
edge_id – The unit-cell edge index.
- Throws:
std::runtime_error – if edge_id is out of range.
- Returns:
The strut’s id, tags and direction.
-
inline const std::shared_ptr<GraphUnitCell> &unit_cell() const#
Return the graph unit cell used for tiling.
- Returns:
The graph unit cell used for tiling.
Private Functions
-
void append_curve(const glm::vec3 &logical_a, const glm::vec3 &logical_b, const glm::vec3 &world_a, const glm::vec3 &world_b, double radius_a, double radius_b, const MappedGraphSegmentInfo &info, double parameter_a, double parameter_b, int depth)#
-
void append_curve(const glm::vec3 &logical_a, const glm::vec3 &logical_b, const MappedGraphSegmentInfo &info, int depth)#
-
void assign_members()#
Assigns blend members: segments that are the same strut or joint share one id.
-
int build_bvh(size_t begin, size_t end)#
-
void collect_bvh(int node_index, const glm::vec3 &point, double maximum_distance, std::vector<std::pair<size_t, double>> &candidates) const#
Collects every segment within maximum_distance of a point.
-
void evaluate_bvh(int node_index, const glm::vec3 &point, double &best, size_t &best_segment) const#
-
double lattice_distance(const glm::vec3 &point, size_t &nearest_segment) const#
The lattice value at a point: the nearest member, blended with its neighbours.
-
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 sample_radius(const glm::vec3 &logical) const#
-
double segment_distance(const SegmentMetadata &segment, const glm::vec3 &point) const#
Private Members
-
std::shared_ptr<FloatAttribute> m_beam_radius#
-
double m_curve_tolerance#
-
std::vector<std::shared_ptr<AttributeSet>> m_joint_attributes#
-
BooleanBlend m_member_blend#
-
std::shared_ptr<FloatAttribute> m_node_radius#
-
std::shared_ptr<PreparedData> m_prepared#
-
std::vector<std::shared_ptr<AttributeSet>> m_strut_attributes#
-
std::shared_ptr<GraphUnitCell> m_unit_cell#
-
struct Bounds#
-
struct BVHNode#
-
struct PreparedData#
-
struct SegmentMetadata#
-
virtual std::vector<std::string> attribute_list() override#
-
struct MappedGraphSegmentInfo#
- #include <mapped_graph_lattice.h>
Unit-cell provenance retained for a prepared mapped graph segment.
Tags are -1 when the unit cell defines none.
Public Members
-
glm::ivec3 cell_index = {0}#
Logical index of the cell that emitted the segment.
-
int edge_tag = -1#
Tag of the strut’s edge (-1 for a joint).
-
int first_vertex_tag = -1#
Tag of the strut’s first vertex, or of the joint’s vertex.
-
int material_tag = -1#
Material tag of the strut’s edge (-1 for a joint).
-
int orientation_tag = -1#
Orientation tag of the strut’s edge (-1 for a joint).
-
int second_vertex_tag = -1#
Tag of the strut’s second vertex (the joint’s own tag for a joint).
-
int unit_cell_edge_id = -1#
Unit-cell edge (strut) index, or -1 for a joint.
-
int unit_cell_vertex_id = -1#
Unit-cell vertex (joint) index, or -1 for a strut.
-
glm::ivec3 cell_index = {0}#
-
struct MappedFaceComponentDefinition#
- #include <mapped_face_lattice.h>
Authoring metadata for one reusable source face or plate.
Tags are -1 when the unit cell defines none.
-
struct MappedFaceInfo#
- #include <mapped_face_lattice.h>
Unit-cell provenance retained for a prepared mapped face triangle.
Tags are -1 when the unit cell defines none.
Public Members
-
glm::ivec3 cell_index = {0}#
Logical index of the cell that emitted the face.
-
int face_tag = -1#
Tag of the source face.
-
int material_tag = -1#
Material tag of the source face.
-
int orientation_tag = -1#
Orientation tag of the source face.
-
int unit_cell_face_id = -1#
Unit-cell face (plate) index.
-
std::vector<int> vertex_tags#
Tags of the source face’s vertices, in face order.
-
glm::ivec3 cell_index = {0}#
-
class MappedFaceLattice : public Leaf#
- #include <mapped_face_lattice.h>
A compact native face lattice tiled and curved through a CellMap.
Logical triangles and quadrilateral patches are adaptively mapped into world-space triangles. The solid is the union of symmetric tubular neighborhoods around those prepared center surfaces.
Public Functions
-
virtual std::vector<std::string> attribute_list() override#
Returns a list of the attribute names in use by this node and its children.
Includes the plate component attributes.
- Returns:
A list of the attribute names
-
inline const std::shared_ptr<CellMap> &cell_map() const#
Return the immutable coordinate map.
- Returns:
The coordinate map.
-
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
-
std::shared_ptr<Vec3Attribute> component_direction_field() const#
A field giving the unit normal of the nearest prepared plate triangle.
- Returns:
The field.
-
std::shared_ptr<FloatAttribute> component_id_field() const#
A field giving the sampled plate’s unit-cell face index.
Component fields only work inside plate attributes (set_plate_attribute()); sampled anywhere else they throw.
- Returns:
The field.
-
std::shared_ptr<FloatAttribute> component_material_tag_field() const#
A field giving the sampled plate’s material tag.
- Returns:
The field.
-
std::shared_ptr<FloatAttribute> component_orientation_tag_field() const#
A field giving the sampled plate’s orientation tag.
- Returns:
The field.
-
std::shared_ptr<FloatAttribute> component_surface_distance_field() const#
A field giving the signed distance to the nearest plate at the sample point.
- Returns:
The field.
-
std::shared_ptr<FloatAttribute> component_tag_field() const#
A field giving the sampled plate’s face tag.
- Returns:
The field.
-
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.
bound when the cell extends the map domain and every element is active, so the solid is not clipped to the map: the value is then the exact minimum over the prepared triangles of the distance minus half the interpolated thickness. approximate otherwise: outside the map domain the value switches to the distance to the domain boundary, which jumps against the lattice value 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.
-
std::optional<MappedFaceInfo> face_info(const glm::vec3 &world) const#
Return parent-cell and face provenance nearest a world point.
- Parameters:
world – World-space inspection point inside the prepared lattice bounds.
- Returns:
Nearest prepared face metadata, or no value outside supported bounds.
-
virtual double lipschitz_bound() const override#
See also
- Returns:
For a bound lattice, the largest sqrt(1 + |grad t|^2 / 4) over the prepared triangles, with grad t the in-plane gradient of the interpolated thickness (1 for a constant thickness); infinity otherwise.
Construct a mapped tubular face solid.
A plate whose source face has a material tag gets a one-material VOLUME_FRACTIONS component attribute for that tag.
- Parameters:
cell_map – Finite structured logical-to-world map.
unit_cell – Static or native parametric face cell.
wall_thickness – Positive finite full-thickness field in world units.
surface_mode – Bilinear patch or legacy triangulated interpretation.
surface_tolerance – Maximum mapping and thickness interpolation error.
- Throws:
std::runtime_error – if a required input is null, the map is folded or invalid, surface_mode is not “bilinear” or “triangulated”, or surface_tolerance is not positive and finite.
-
std::vector<MappedFacePatch> midsurface_patches() const#
Return authored midsurface patches before adaptive triangulation.
World vertices and thicknesses use the same mapping and field semantics as the implicit solid. Folded plates intentionally retain their legacy boundary overhang in this diagnostic view.
- Returns:
Deterministically ordered triangle or quadrilateral patches.
-
MappedFaceVertex midsurface_vertex(const glm::vec3 &logical) const#
Map one logical face point with the node’s geometry semantics.
- Parameters:
logical – Logical CellMap coordinate on an authored patch.
- Returns:
Exact mapped midsurface position and sampled full thickness.
-
size_t plate_count() const#
Returns the number of unit-cell faces (plates).
- Returns:
The plate count.
-
MappedFaceComponentDefinition plate_definition(size_t face_id) const#
Returns the authoring metadata of one unit-cell face.
- Parameters:
face_id – The unit-cell face index.
- Throws:
std::runtime_error – if face_id is out of range.
- Returns:
The face’s id and tags.
-
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.
-
size_t prepared_triangle_count() const#
Return the number of compact world triangles after preparation.
- Returns:
The number of compact world triangles after preparation.
-
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).
Sets an attribute function for the node.
Sets a lattice-wide attribute. Plate attributes of the same name take precedence where they are set.
- Parameters:
name – The name of the attribute.
attribute – The attribute function to set.
- Throws:
std::runtime_error – if the attribute name is already in use by the node
std::runtime_error – if the attribute is null or a plate attribute of the same name has a different return type.
Attach an attribute to one reusable source face or plate.
The attribute applies to every copy of that face and replaces any earlier plate attribute of the same name. Plate attributes override the lattice-wide ones and can read the component fields below.
- Parameters:
face_id – The unit-cell face index.
name – The attribute name.
attribute – The attribute.
- Throws:
std::runtime_error – if face_id is out of range, the attribute is null, or a lattice attribute of the same name has a different return type.
-
inline const std::string &surface_mode() const#
Return how quadrilateral patches are interpreted.
- Returns:
“bilinear” or “triangulated”.
-
inline double surface_tolerance() const#
Return the maximum mapping and thickness interpolation error.
- Returns:
The surface tolerance in world units.
-
inline const std::shared_ptr<FaceUnitCell> &unit_cell() const#
Return the face unit cell used for tiling.
- Returns:
The face unit cell.
-
inline const std::shared_ptr<FloatAttribute> &wall_thickness() const#
Return the full wall-thickness field.
- Returns:
The full wall-thickness field.
Private Functions
-
void append_bilinear_quad(const std::array<glm::vec3, 4> &logical, const MappedFaceInfo &info, int depth)#
-
void append_mapped_triangle(const std::array<glm::vec3, 3> &logical, const MappedFaceInfo &info, int depth)#
-
void append_patch(const FaceUnitCellPatch &patch, const glm::ivec3 &cell_index)#
-
void append_triangle(const std::array<MappedFaceVertex, 3> &vertices, const MappedFaceInfo &info)#
-
int build_bvh(size_t begin, size_t end)#
-
bool contains_extended_logical(const glm::vec3 &logical) const#
-
void evaluate_bvh(int node_index, const glm::vec3 &point, ClosestTriangle &closest) const#
-
bool in_reference_bounds(const glm::vec3 &logical) const#
-
glm::ivec3 logical_cell_index(const glm::vec3 &logical) const#
-
glm::vec3 normalize_logical(const glm::vec3 &logical) const#
-
bool patch_may_be_active(const std::vector<glm::vec3> &logical) const#
-
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 sample_thickness(const glm::vec3 &logical, const glm::vec3 &world) const#
-
double triangle_distance(const TriangleMetadata &triangle, const glm::vec3 &point, glm::vec3 *barycentric = nullptr) const#
-
std::array<std::array<glm::vec3, 3>, 2> triangulate_quad(const std::array<glm::vec3, 4> &logical) const#
-
bool uses_extended_domain() const#
-
bool uses_unclipped_extended_solid() const#
Private Members
-
std::vector<std::shared_ptr<AttributeSet>> m_plate_attributes#
-
std::shared_ptr<PreparedData> m_prepared#
-
std::string m_surface_mode#
-
double m_surface_tolerance#
-
bool m_unclipped_extended_solid = false#
-
std::shared_ptr<FaceUnitCell> m_unit_cell#
-
std::shared_ptr<FloatAttribute> m_wall_thickness#
-
struct Bounds#
-
struct BVHNode#
-
struct ClosestTriangle#
-
struct PreparedData#
Public Members
-
double lipschitz = 1.0#
Largest slope of a triangle’s thickened distance (see lipschitz_bound()).
-
std::vector<size_t> triangle_indices#
-
std::vector<TriangleMetadata> triangle_metadata#
-
double lipschitz = 1.0#
-
virtual std::vector<std::string> attribute_list() override#
-
struct MappedFacePatch#
- #include <mapped_face_lattice.h>
One authored midsurface patch mapped into world coordinates.
Patches preserve their original triangle or quadrilateral topology. Logical vertices permit downstream consumers to apply their own deterministic subdivision without reconstructing the unit cell.
Public Members
-
MappedFaceInfo info#
Provenance of the source face.
-
std::vector<glm::vec3> logical_vertices#
Patch corners in logical coordinates (3 or 4).
-
std::vector<double> thicknesses#
Full wall thickness at each corner.
-
std::vector<glm::vec3> world_vertices#
Patch corners mapped to world coordinates.
-
MappedFaceInfo info#
-
struct MappedFaceVertex#
- #include <mapped_face_lattice.h>
One exact sample of a mapped face midsurface and thickness field.
-
class MappedRim : public Leaf#
- #include <mapped_rim.h>
A solid band along the cropped edges of a CellMap, built as a signed distance field from the map’s edge wall.
MappedRim closes off the open lateral edges that trimming leaves on a mapped lattice. The rim is the set of points inside the active map domain that lie within the width field of the map’s edge wall: the smooth trim wall swept from the surface’s cropped boundary through the map height for boundary-trimmed maps, and the exposed lateral element faces otherwise. The band therefore spans the full map height, follows the cropped edge exactly, and extends the sampled width inward, so unioning it with any lattice mapped through the same CellMap seals the lattice’s open edge cells.
The width attribute is sampled through the shared CellMap context, so it can vary with logical position exactly like the other mapped lattice fields.
Public Functions
-
inline const std::shared_ptr<CellMap> &cell_map() const#
Returns the map whose edge wall the rim follows.
- Returns:
The cell map.
-
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.
approximate: outside the located map domain the value switches to the distance to the domain boundary, so crossing the map’s base or offset surface far from the edge wall jumps from the rim distance to about 0; the width field has no slope bound either.
- 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 double lipschitz_bound() const override#
See also
- Returns:
Infinity.
Constructs a rim over a cell map’s edge wall.
- Parameters:
cell_map – The validated map whose cropped edges the rim follows.
width – The inward rim width in world units, sampled per query point; nullptr for 1.
- Throws:
std::runtime_error – if the map is null, folded or invalid, or has no finite edge wall (every lateral direction is periodic and untrimmed).
-
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<FloatAttribute> &width() const#
Returns the rim width field.
- Returns:
The width field (a constant 1 if none was given).
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().
-
inline const std::shared_ptr<CellMap> &cell_map() const#
-
class CellMapDomain : public Leaf#
- #include <cell_map_domain.h>
The active volume of a CellMap as a solid implicit node.
The node’s field is CellMap::domain_signed_distance(): negative inside the active, trimmed map domain, zero on its boundary, and positive outside. Trimmed margins, boundary-trimmed edges, and holes of a surface map are all outside. The boundary is the map’s exposed element faces plus its smooth trim wall, so the distance is exact to that triangulated boundary (about one quarter of an element face in resolution).
Uses: clip any node to a liner volume with an Intersection, use the volume as a host for a stochastic lattice, or subtract it as a keep-out. The node has no internal state to prepare beyond the bounding box, which is the map’s world bounding box.
Public Functions
-
inline const std::shared_ptr<CellMap> &cell_map() const#
Returns the immutable map whose domain this node represents.
- Returns:
The immutable map whose domain this node represents.
Constructs the solid domain of a validated cell map.
- Parameters:
cell_map – The map whose active domain becomes the solid.
- Throws:
std::runtime_error – if the map is null or has no active elements.
-
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.
approximate: the sign comes from locating the point in the trilinear map, the magnitude from the triangulated boundary (and the polyline trim wall), so where the two boundaries differ the value flips sign without passing through 0.
- 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.
Returns std::nullopt outside the prepared bounding box, otherwise the signed distance to the active map domain in world units (mm).
- 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#
See also
- Returns:
Infinity.
-
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.
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().
-
inline const std::shared_ptr<CellMap> &cell_map() const#
-
class StochasticGraphLattice : public Node#
- #include <stochastic_graph_lattice.h>
Compact Delaunay or Voronoi graph lattice confined by an implicit host.
World-space seed points are tessellated with CGAL during prepare(). Prepared graph edges use tapered capsule SDFs and an internal BVH. The host is an owned geometry child and is always the authoritative confinement SDF: like every node, the lattice has no value beyond the host’s box padded by the bandwidth, even with seeds outside the host. sample() has the value of evaluate() and evaluates and returns attributes only where that value is <= 0.
Warning
prepare() must be called before evaluate(), sample(), or product inspection.
Public Functions
-
inline bool allow_outside_seeds() const#
Return whether seeds outside the host are accepted.
- Returns:
Whether seeds outside the host are accepted.
-
inline const std::shared_ptr<FloatAttribute> &beam_radius() const#
Return the beam-radius field.
- Returns:
The beam-radius field.
-
const std::vector<StochasticBoundaryCapProduct> &boundary_caps() const#
Return explicit graph cap records for closed confinement.
- Returns:
Explicit graph cap records for closed confinement.
-
inline StochasticBoundaryMode boundary_mode() const#
Return the boundary topology mode.
- Returns:
The boundary topology mode.
-
inline double boundary_tolerance() const#
Return the boundary root and inspection tolerance.
- Returns:
The boundary root and inspection tolerance.
-
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
-
const std::vector<StochasticEdgeProduct> &confined_edges() const#
Return centerline fragments confined to the host after preparation.
- Returns:
Centerline fragments confined to the host after preparation.
-
const std::vector<DelaunayCellProduct> &delaunay_cells() const#
Return Delaunay tetrahedra shared by all graph extraction modes.
- Returns:
Delaunay tetrahedra shared by all graph extraction modes.
-
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”.
-
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.
bound when the host is exact or bound: the value is the larger of the host value and the exact minimum (or sorted smooth blend) over the prepared beam pieces, and the box is the host’s. approximate when the host is.
- 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 StochasticGraphExtraction extraction() const#
Return the graph extraction mode.
- Returns:
The graph extraction mode.
-
inline double field_tolerance() const#
Return the maximum radius interpolation error.
- Returns:
The maximum radius interpolation error.
-
inline const std::shared_ptr<Node> &host() const#
Return the implicit host that confines the lattice.
- Returns:
The implicit host that confines the lattice.
-
virtual double lipschitz_bound() const override#
See also
- Returns:
For a bound lattice, the larger of the host’s bound and the steepest beam piece, sqrt(1 + (radius change / length)^2) (1 for a constant radius); infinity otherwise.
-
inline double member_blend_radius() const#
Return the smooth-union radius between distinct graph members.
- Returns:
The smooth-union radius between distinct graph members.
-
inline const std::shared_ptr<FloatAttribute> &node_radius() const#
Return the optional graph-node radius field, or nullptr when none was given.
- Returns:
The optional graph-node radius field, or nullptr when none was given.
-
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.
-
inline bool prune_loose_fragments() const#
Return whether loose host-clipped strut pieces are dropped.
- Returns:
Whether loose host-clipped strut pieces are dropped.
-
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 std::vector<glm::vec3> &seed_points() const#
Return the world-space seed points.
- Returns:
The world-space seed points.
Construct a stochastic graph lattice.
- Parameters:
host – Implicit host node prepared recursively by this node.
seed_points – Unique world-space seed points, inside the host unless allow_outside_seeds is set.
extraction – Graph extraction applied to the shared Delaunay tessellation.
beam_radius – Positive finite beam-radius field in world units.
node_radius – Optional positive finite graph-node radius field.
boundary_mode – Open topology or explicit closed-boundary inspection semantics.
field_tolerance – Maximum radius interpolation error.
boundary_tolerance – Boundary root and inspection tolerance.
member_blend_radius – Smooth-union radius between distinct graph members.
prune_loose_fragments – Drop strut pieces that the host cuts off at both ends (chords through a corner or a concave part of the host, which would print as loose pieces), edges that never enter the host, and joints centred outside it.
allow_outside_seeds – Accept seeds outside the host (but inside a finite working box). A layer of such seeds bounds the Voronoi cells at the host surface; the host still confines all geometry.
-
const std::vector<StochasticEdgeProduct> &tessellation_edges() const#
Return raw tessellation edges after preparation.
- Returns:
Raw tessellation edges after preparation.
-
const std::vector<VoronoiCellProduct> &voronoi_cells() const#
Return bounded working-domain Voronoi cells.
- Returns:
Bounded working-domain Voronoi cells.
Private Functions
-
void append_segment(const StochasticEdgeProduct &edge, const glm::vec3 &first, const glm::vec3 &second, double first_radius, double second_radius, int depth)#
-
int build_bvh(size_t begin, size_t end)#
-
void collect_blend_candidates(int node_index, const glm::vec3 &point, double maximum_distance, double search_distance, std::vector<std::pair<size_t, double>> &candidates) const#
-
std::vector<StochasticEdgeProduct> confine_edges(const std::vector<StochasticEdgeProduct> &edges) const#
-
void evaluate_bvh(int node_index, const glm::vec3 &point, double &best, size_t &best_segment) const#
-
std::vector<StochasticEdgeProduct> extract_edges(const StochasticTessellation &tessellation) const#
-
double lattice_distance(const glm::vec3 &point, double &hard_distance, size_t &best_segment) const#
-
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 validate_points() const#
Private Members
-
bool m_allow_outside_seeds = false#
-
std::shared_ptr<FloatAttribute> m_beam_radius#
-
StochasticBoundaryMode m_boundary_mode#
-
double m_boundary_tolerance#
-
StochasticGraphExtraction m_extraction#
-
double m_field_tolerance#
-
double m_member_blend_radius#
-
std::shared_ptr<FloatAttribute> m_node_radius#
-
std::shared_ptr<PreparedData> m_prepared#
-
bool m_prune_loose_fragments = false#
-
std::vector<glm::vec3> m_seed_points#
-
struct Bounds#
-
struct BVHNode#
-
struct PreparedData#
Public Members
-
std::vector<StochasticBoundaryCapProduct> boundary_caps#
-
std::vector<StochasticEdgeProduct> confined_edges#
-
double lipschitz = 1.0#
Largest slope of a beam piece’s distance (see lipschitz_bound()).
-
std::vector<size_t> segment_indices#
-
StochasticTessellation tessellation#
-
std::vector<StochasticEdgeProduct> tessellation_edges#
-
bool voronoi_cells_ready = false#
-
std::mutex voronoi_mutex#
-
std::vector<StochasticBoundaryCapProduct> boundary_caps#
-
struct Segment#
-
inline bool allow_outside_seeds() const#
-
class StochasticFaceLattice : public Node#
- #include <stochastic_face_lattice.h>
Compact Delaunay or Voronoi plate lattice confined by an implicit host.
World-space tessellation faces are triangulated and thickened as symmetric tubular neighborhoods during prepare(). Evaluation uses an internal triangle BVH. sample() has the value of evaluate() and evaluates and returns attributes only where that value is <= 0.
Warning
prepare() must be called before evaluate(), sample(), or product inspection.
Public Functions
-
const std::vector<StochasticBoundaryContactProduct> &boundary_contact_patches() const#
Return approximate host-surface contact patches for closed confinement.
- Returns:
Approximate host-surface contact patches for closed confinement.
-
inline StochasticBoundaryMode boundary_mode() const#
Return the boundary topology mode.
- Returns:
The boundary topology mode.
-
const std::vector<StochasticBoundarySeamProduct> &boundary_seams() const#
Return approximate seam segments around closed contact patches.
- Returns:
Approximate seam segments around closed contact patches.
-
inline double boundary_tolerance() const#
Return the boundary-product and working-domain tolerance.
- Returns:
The boundary-product and working-domain tolerance.
-
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
-
const std::vector<DelaunayCellProduct> &delaunay_cells() const#
Return Delaunay tetrahedra shared by both face extraction modes.
- Returns:
Delaunay tetrahedra shared by both face extraction modes.
-
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”.
-
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.
bound when the host is exact or bound: the value is the larger of the host value and the exact minimum (or sorted smooth blend) over the prepared plate triangles, and the box is the host’s. approximate when the host is.
- 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 StochasticFaceExtraction extraction() const#
Return the face extraction mode.
- Returns:
The face extraction mode.
-
inline const std::shared_ptr<Node> &host() const#
Return the implicit host that confines the lattice.
- Returns:
The implicit host that confines the lattice.
-
virtual double lipschitz_bound() const override#
See also
- Returns:
For a bound lattice, the larger of the host’s bound and the steepest plate triangle, sqrt(1 + |grad t|^2 / 4) with grad t the in-plane gradient of the interpolated thickness (1 for a constant thickness); infinity otherwise.
-
inline double member_blend_radius() const#
Return the smooth-union radius between distinct plate members.
- Returns:
The smooth-union radius between distinct plate members.
-
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.
-
size_t prepared_triangle_count() const#
Return the number of compact prepared SDF triangles.
- Returns:
The number of compact prepared SDF triangles.
-
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 std::vector<glm::vec3> &seed_points() const#
Return the world-space seed points.
- Returns:
The world-space seed points.
Construct a stochastic face lattice.
- Parameters:
host – Implicit host node prepared recursively by this node.
seed_points – Unique world-space points inside the host.
extraction – Delaunay facets or Voronoi cell faces.
wall_thickness – Positive finite full-thickness field in world units.
boundary_mode – Open topology or explicit closed-boundary inspection semantics.
surface_tolerance – Maximum thickness interpolation error.
boundary_tolerance – Boundary-product and working-domain tolerance.
member_blend_radius – Smooth-union radius between distinct plate members.
-
inline double surface_tolerance() const#
Return the maximum thickness interpolation error.
- Returns:
The maximum thickness interpolation error.
-
const std::vector<StochasticFaceProduct> &tessellation_faces() const#
Return raw tessellation faces after preparation.
- Returns:
Raw tessellation faces after preparation.
-
const std::vector<VoronoiCellProduct> &voronoi_cells() const#
Return bounded working-domain Voronoi cells.
- Returns:
Bounded working-domain Voronoi cells.
-
inline const std::shared_ptr<FloatAttribute> &wall_thickness() const#
Return the full wall-thickness field.
- Returns:
The full wall-thickness field.
Private Functions
-
void append_triangle(const std::array<glm::vec3, 3> &vertices, const std::array<double, 3> &thicknesses, size_t source_face_id, int depth)#
-
int build_bvh(size_t begin, size_t end)#
-
void collect_blend_candidates(int node_index, const glm::vec3 &point, double maximum_distance, double search_distance, std::vector<std::pair<size_t, double>> &candidates) const#
-
void evaluate_bvh(int node_index, const glm::vec3 &point, double &best, size_t &best_triangle) const#
-
double lattice_distance(const glm::vec3 &point, double &hard_distance, size_t &best_triangle) const#
-
void prepare_boundary_contacts(double resolution)#
-
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 sample_thickness(const glm::vec3 &point) const#
-
double triangle_distance(const Triangle &triangle, const glm::vec3 &point, glm::vec3 *barycentric = nullptr) const#
-
void validate_points() const#
Private Members
-
StochasticBoundaryMode m_boundary_mode#
-
double m_boundary_tolerance#
-
StochasticFaceExtraction m_extraction#
-
double m_member_blend_radius#
-
std::shared_ptr<PreparedData> m_prepared#
-
std::vector<glm::vec3> m_seed_points#
-
double m_surface_tolerance#
-
std::shared_ptr<FloatAttribute> m_wall_thickness#
-
struct Bounds#
-
struct BVHNode#
-
struct PreparedData#
Public Members
-
std::vector<StochasticBoundaryContactProduct> boundary_contact_patches#
-
std::vector<StochasticBoundarySeamProduct> boundary_seams#
-
double lipschitz = 1.0#
Largest slope of a triangle’s thickened distance (see lipschitz_bound()).
-
StochasticTessellation tessellation#
-
std::vector<StochasticFaceProduct> tessellation_faces#
-
std::vector<size_t> triangle_indices#
-
std::vector<StochasticBoundaryContactProduct> boundary_contact_patches#
-
struct Triangle#
-
const std::vector<StochasticBoundaryContactProduct> &boundary_contact_patches() const#
-
class Text : public Leaf#
- #include <text.h>
A text leaf node which generates a 3D text object by extruding the text along the Z-axis.
Generates a 3D text object from a given string by creating a planar CAD outline in the XY plane, anchored at the origin, and extruding it along Z, centered so it spans -depth / 2 to depth / 2.
Note
The default font is Consolas. The CAD part is built in the constructor; prepare() builds the voxelized distance grid that evaluate() reads.
Public Types
-
enum class FontAspect#
Font style options.
Values:
-
enumerator Regular#
Regular weight, upright.
-
enumerator Bold#
Bold weight.
-
enumerator Italic#
Italic.
-
enumerator BoldItalic#
Bold weight and italic.
-
enumerator Regular#
-
enum class HorizontalAlignment#
Horizontal text alignment options.
Values:
-
enum class VerticalAlignment#
Vertical text alignment options.
Values:
-
enumerator Bottom#
The anchor lies on the last line of the text.
-
enumerator Center#
The anchor lies on the center of the text.
-
enumerator Top#
The anchor lies on the line preceding the first line of the text.
-
enumerator TopFirstLine#
The anchor lies on the first line of the text.
-
enumerator Bottom#
Public Functions
-
inline FontAspect aspect() const#
Returns the font aspect of the text.
- Returns:
The font aspect of the text.
-
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 double depth() const#
Returns the extrusion depth of the text.
- Returns:
The extrusion depth of the text.
-
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.
Approximate: the value is sampled from a grid, not computed from the glyphs.
prepare() tessellates the extruded outline (0.1 deflection) and voxelizes it into an OpenVDB narrow-band level set, which evaluate() interpolates trilinearly. The grid is uniform at the smallest voxel size, its distances and signs come from the voxelizer, and trilinear interpolation is only sqrt(3)-Lipschitz even for exact samples. In practice the value also falls below the per-axis distance to the box and jumps at the edge of the narrow band, so no Lipschitz bound holds.- 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 const std::string &font() const#
Returns the name of the font used for the text.
- Returns:
The name of the font used for the text.
-
inline HorizontalAlignment h_align() const#
Returns the horizontal alignment of the text.
- Returns:
The horizontal alignment of the text.
-
inline double height() const#
Returns the height of the text.
- Returns:
The height of the text.
-
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 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()
.
The summary “text” entry is shortened to one line; a “full text” entry holds the complete string whenever the summary had to be shortened.
- Returns:
The ordered property list. The base implementation returns an empty list.
-
Text() = default#
Default constructor. Creates an empty Text node with no CAD part; used by clone().
-
Text(std::string text, double height, double depth, FontAspect aspect = FontAspect::Regular, std::string font = "Consolas", HorizontalAlignment h_align = HorizontalAlignment::Center, VerticalAlignment v_align = VerticalAlignment::Center)#
Constructor.
Creates a Text node with a given text, height, depth, font, and alignment.
- Parameters:
text – The text content used for generating the 3D object.
height – The height of the text.
depth – The extrusion depth of the text.
aspect – The font style (default is Regular).
font – The name of the font (default is Consolas).
h_align – The horizontal alignment of the text about the origin (default is Center).
v_align – The vertical alignment of the text about the origin (default is Center).
-
inline const std::string &text() const#
Returns the text content used for generating the 3D object.
- Returns:
The text content used for generating the 3D object.
-
inline VerticalAlignment v_align() const#
Returns the vertical alignment of the text.
- Returns:
The vertical alignment of the text.
Private Functions
-
void make_text_cad_part(const std::string &text, double height, double depth)#
Builds the CAD part for the text node.
- Parameters:
text – The text string.
height – The height of the text.
depth – The extrusion depth.
-
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
-
FontAspect m_aspect = FontAspect::Regular#
-
double m_depth = 0.0#
-
std::string m_font = "Consolas"#
-
HorizontalAlignment m_h_align = HorizontalAlignment::Left#
-
double m_height = 0.0#
-
std::string m_string#
-
VerticalAlignment m_v_align = VerticalAlignment::Bottom#
-
enum class FontAspect#
-
class SignedDistanceField : public Leaf#
- #include <signed_distance_field.h>
A leaf node whose signed distance is read from an OpenVDB grid.
The grid can be a FloatGrid of signed distances, a BoolGrid occupancy grid converted to a level set, a FloatVDBVolume, or a grid loaded from a .vdb file. evaluate() interpolates the grid.
Distance accuracy (distance_accuracy()): approximate. The grid is sampled as given: a FloatGrid’s values need not be distances at all, and the narrow band and background are fixed when the grid is built, independent of the prepared bandwidth. With a bandwidth wider than the stored band the value saturates at the background and then jumps to the bandwidth where evaluate() stops returning values, so no Lipschitz bound can be promised.
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 int closing_steps() const#
Returns the number of morphological closing steps used to convert an occupancy grid.
Holds the default value when the field was not converted from an occupancy grid.
- Returns:
The number of morphological closing steps used to convert an occupancy grid.
-
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 int dilation_voxels() const#
Returns the number of dilation voxels used to convert an occupancy grid.
Holds the default value when the field was not converted from an occupancy grid.
- Returns:
The number of dilation voxels used to convert an occupancy grid.
-
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: the grid’s values and band are not checked (see the class notes).
- 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 const std::string &file_path() const#
Returns the path of the VDB file the field was loaded from, or an empty string for an in-memory grid.
- Returns:
The path of the VDB file the field was loaded from, or an empty string for an in-memory grid.
-
inline bool from_occupancy_grid() const#
Returns whether the field was converted from a BoolGrid occupancy grid.
- Returns:
Whether the field was converted from a BoolGrid occupancy grid.
-
inline const std::string &grid_name() const#
Returns the name of the grid loaded from the VDB file, or an empty string for an in-memory grid.
- Returns:
The name of the grid loaded from the VDB file, or an empty string for an in-memory grid.
-
inline int half_width_voxels() const#
Returns the narrow-band half width, in voxels, used to convert an occupancy grid.
Holds the default value when the field was not converted from an occupancy grid.
- Returns:
The narrow-band half width, in voxels, used to convert an occupancy grid.
-
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()
.
Infinity, since no bound is promised.
- 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.
-
void save_openvdb_occupancy_grid(const std::string &file_path) const#
Save the signed distance field as a single OpenVDB BoolGrid occupancy grid.
The exported grid is named “occupancy”. Active SDF voxels with values less than or equal to zero are written as occupied voxels. Inactive SDF background voxels remain unoccupied.
- Parameters:
file_path – The path where the VDB file will be saved.
-
void save_openvdb_sdf_grid(const std::string &file_path) const#
Save the underlying signed distance field as a single OpenVDB FloatGrid.
The exported grid is named “surface”, marked as a level set, and written as the only grid in the file.
- Parameters:
file_path – The path where the VDB file will be saved.
-
SignedDistanceField()#
Create an empty SignedDistanceField.
This constructor initializes an empty SignedDistanceField.
-
SignedDistanceField(const openvdb::BoolGrid::Ptr &occupancy_grid, int half_width_voxels = 3, int closing_steps = 0, int dilation_voxels = 0, int smoothing_steps = 3)#
Create a SignedDistanceField from an occupancy grid.
This constructor computes the signed distance field from a given occupancy grid. The occupancy grid is expected to be a BoolGrid where occupied voxels are set to true. The topology options are passed to OpenVDB’s topologyToLevelSet() call. The default values preserve OpenVCAD’s existing conversion behavior.
- Parameters:
occupancy_grid – The occupancy grid from which to compute the signed distance field
half_width_voxels – Half the width of the generated narrow-band level set, in voxel units.
closing_steps – Number of morphological closing steps used to fill gaps in the active voxel region.
dilation_voxels – Number of voxels to expand the active voxel region before conversion.
smoothing_steps – Number of smoothing iterations applied after level-set generation.
-
SignedDistanceField(const openvdb::FloatGrid::Ptr &grid)#
Create an SignedDistanceField from an OpenVDB FloatGrid.
This constructor initializes the SignedDistanceField with an existing OpenVDB FloatGrid. The FloatGrid is expected to represent a signed distance field where positive values indicate distances to the surface and negative values indicate distances inside the surface. Zero values indicate the surface itself.
- Parameters:
grid – The OpenVDB FloatGrid to use as the signed distance field
- Throws:
std::runtime_error – if the grid is null.
Create a SignedDistanceField from a float volume holding signed distances.
Copies the volume’s grid, so the caller’s volume is left unchanged.
- Parameters:
sdf_volume – The volume whose values are signed distances (negative inside).
- Throws:
std::runtime_error – if the volume is null.
-
SignedDistanceField(const std::string &vdb_file_path, const std::string &grid_name = "occupancy", int half_width_voxels = 3, int closing_steps = 0, int dilation_voxels = 0, int smoothing_steps = 3)#
Create a SignedDistanceField from a VDB file.
This constructor loads a signed distance field from a specified VDB file path. The VDB file is expected to contain either a BooleanGrid representing an occupancy grid or a FloatGrid representing the signed distance field. We auto-detect the grid type based the type of grid stored in the file. If the grid is a BooleanGrid, it will be converted to a signed distance field. If it’s already a FloatGrid, it will be used directly as the signed distance field. The topology options are used only when the loaded grid is a BooleanGrid. They are ignored for FloatGrid inputs. The default topology option values preserve OpenVCAD’s existing conversion behavior. The grid name can be specified, and it defaults to “occupancy”.
- Parameters:
vdb_file_path – The file path to the VDB file containing the grid
grid_name – The name of the grid to load from the VDB file, default is “occupancy”
half_width_voxels – Half the width of the generated narrow-band level set, in voxel units.
closing_steps – Number of morphological closing steps used to fill gaps in the active voxel region.
dilation_voxels – Number of voxels to expand the active voxel region before conversion.
smoothing_steps – Number of smoothing iterations applied after level-set generation.
-
inline int smoothing_steps() const#
Returns the number of smoothing steps used to convert an occupancy grid.
Holds the default value when the field was not converted from an occupancy grid.
- Returns:
The number of smoothing steps used to convert an occupancy grid.
Private Types
-
typedef openvdb::FloatGrid GridType#
Private Functions
-
void init_from_bool_grid(const openvdb::BoolGrid::Ptr &occupancy_grid, int half_width_voxels, int closing_steps, int dilation_voxels, int smoothing_steps)#
Initialize the grid from a BoolGrid (occupancy grid).
Converts the BoolGrid to a level set SDF and stores in m_grid.
- Parameters:
occupancy_grid – The BoolGrid representing occupied voxels
half_width_voxels – Half the width of the generated narrow-band level set, in voxel units.
closing_steps – Number of morphological closing steps used to fill gaps in the active voxel region.
dilation_voxels – Number of voxels to expand the active voxel region before conversion.
smoothing_steps – Number of smoothing iterations applied after level-set generation.
-
void init_from_float_grid(const openvdb::FloatGrid::Ptr &grid)#
Initialize the grid from a FloatGrid.
Sets m_grid from the provided FloatGrid, marks it as a level set, and names it “surface”.
- Parameters:
grid – The FloatGrid to use as the signed distance field
-
void load_from_vdb_file(const std::string &vdb_file_path, const std::string &grid_name, int half_width_voxels, int closing_steps, int dilation_voxels, int smoothing_steps)#
Load a grid from a VDB file and initialize appropriately.
Opens the VDB file, finds the named grid, determines if it’s a FloatGrid or BoolGrid, and calls the appropriate init function.
- Parameters:
vdb_file_path – Path to the VDB file
grid_name – Name of the grid to load from the file
half_width_voxels – Half the width of the generated narrow-band level set, in voxel units.
closing_steps – Number of morphological closing steps used to fill gaps in the active voxel region.
dilation_voxels – Number of voxels to expand the active voxel region before conversion.
smoothing_steps – Number of smoothing iterations applied after level-set generation.
Private Members
-
int m_closing_steps = 0#
-
int m_dilation_voxels = 0#
-
std::string m_file_path#
The VDB file the field was loaded from, empty for an in-memory grid.
-
bool m_from_occupancy_grid = false#
Whether the field was converted from a BoolGrid occupancy grid.
-
openvdb::FloatGrid::Ptr m_grid#
-
std::string m_grid_name#
The name of the grid loaded from m_file_path.
-
int m_half_width_voxels = 3#
Topology options passed to topologyToLevelSet() when converting an occupancy grid.
-
int m_smoothing_steps = 3#
-
virtual std::shared_ptr<Node> clone() override#
-
class SurfaceReliefVolume : public Leaf#
- #include <surface_relief_volume.h>
Compact live implicit volume between an embedded selected surface and a raised height map.
For surface q(u,v), outward normal n(u,v), height h(u,v), and embed depth e, this represents q + t*n for -e <= t <= h inside the selected patch. Its zero surface is correct, but the field is not generally an exact Euclidean signed distance when surface curvature or height varies.
Distance accuracy (distance_accuracy()): approximate. The top term t - h(u, v) is as steep as the height field, which an image or a function can make arbitrarily steep, and the closest-point projection behind (u, v), its normal and boundary distance can jump (across mesh edges or the medial axis of a curved patch), so no Lipschitz bound holds.
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.
Always approximate: the field is as steep as the height field (see the class notes).
- Returns:
The accuracy of the subtree rooted at this node.
-
inline double edge_falloff_mm() const#
Returns the width of the edge falloff ramp.
- Returns:
The falloff width in mm (0 for none).
-
inline double embed_mm() const#
Returns the embed depth below the surface.
- Returns:
The embed depth in mm.
-
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 std::shared_ptr<HeightField> &height_field() const#
Returns the relief height field.
- Returns:
The height field.
-
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()
.
Infinity, since no bound is promised.
- 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.
Builds the closest-point projector for the surface.
- Parameters:
voxel_size – The size of a voxel we plan to sample with.
bandwidth – The bandwidth of the tree we are sampling.
- Throws:
std::runtime_error – if the voxel size or bandwidth is invalid, the surface’s outward orientation was not validated, or its UV bounds are invalid.
-
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<ParametricSurface> &surface() const#
Returns the selected surface patch.
- Returns:
The surface.
Constructor.
- Parameters:
surface – The selected surface patch; its outward orientation must be validated against the source solid (checked by prepare()).
height_field – The relief height h(u, v) over the patch’s normalized UV square.
embed_mm – How far the volume extends below the surface, in mm; must be positive.
edge_falloff_mm – Width of a smooth ramp that brings the height to zero at the patch boundary, in mm; 0 (the default) for no ramp.
- Throws:
std::runtime_error – if the surface or height field is null, embed_mm is not positive and finite, or edge_falloff_mm is negative or not finite.
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_edge_falloff_mm#
-
double m_embed_mm#
-
std::shared_ptr<HeightField> m_height_field#
-
std::shared_ptr<PreparedSurfaceProjector> m_projector#
-
std::shared_ptr<ParametricSurface> m_surface#
-
glm::vec2 m_uv_extent = {1.0f}#
-
glm::vec2 m_uv_minimum = {0.0f}#
-
glm::vec3 m_voxel_size = {1.0f}#
-
virtual std::shared_ptr<Node> clone() final#
-
class PolygonExtrude : public Extrude#
- #include <polygon_extrude.h>
An extruded polygon leaf node / geometric primitive.
This node takes a planar polygon defined by a series of 3D points and extrudes it along its computed normal (right-hand rule) by a given height. The polygon must be planar; the constructor validates this and throws if the points are not coplanar. The extrusion can be symmetric (half the height on each side of the polygon plane) or one-directional (full height in the normal direction). A negative height extrudes in the opposite direction of the normal.
PolygonExtrude is the polygon case of Extrude: the vertices become a Profile in the polygon’s own plane, and the plane is placed with a rigid frame. The distance is exact, and the Extrude coordinate fields are available.
Note
This node is a leaf node, and therefore cannot have any children.
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”.
-
PolygonExtrude()#
Default constructor. Creates a unit square in the XY plane, extruded 1 unit in +Z.
-
PolygonExtrude(const std::vector<glm::vec3> &vertices, double height, bool symmetric = false)#
Constructor.
Creates an extruded polygon from a list of coplanar 3D vertices.
- Parameters:
vertices – The vertices of the planar polygon (minimum 3, must be coplanar).
height – The extrusion distance along the polygon normal.
symmetric – If true, extrudes height/2 on each side of the polygon plane.
- Throws:
std::runtime_error – if fewer than 3 vertices, points are collinear, or not coplanar.
-
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::vector<glm::vec3> &vertices() const#
Returns the vertices of the planar polygon.
- Returns:
The vertices of the planar polygon.
Private Functions
Private Members
-
std::vector<glm::vec3> m_vertices#
The original 3D vertices of the polygon.
Private Static Functions
-
struct Placement#
The polygon as a profile in its own plane, and the frame placing that plane.
-
virtual std::shared_ptr<Node> clone() override#
-
class PolygonRevolve : public Revolve#
- #include <polygon_revolve.h>
A revolved polygon leaf node / geometric primitive.
This node takes a planar CAD-style half-profile polygon and revolves it around an arbitrary axis line. The axis is defined by two points, and positive partial sweeps follow the right-hand rule of axis_end - axis_start. The profile plane must contain the axis, and all profile vertices must remain on one side of the axis though they may touch it. Partial sweeps are capped at the start and end angles.
PolygonRevolve is the polygon case of Revolve: the vertices become a Profile in (distance from the axis, position along the axis) coordinates, and the axis is placed with a rigid frame. The distance is exact for full and partial sweeps, and the Revolve coordinate fields are available.
Note
Axis-aligned bounding boxes are available before prepare(), but prepare() must still be called before evaluate(), sample(), or other prepared-tree queries.
Note
This node is a leaf node, and therefore cannot have any children.
Public Functions
-
inline glm::vec3 axis_end() const#
Returns the second point on the revolve axis, which defines the positive direction.
- Returns:
The second point on the revolve axis, which defines the positive direction.
-
inline glm::vec3 axis_start() const#
Returns the first point on the revolve axis.
- Returns:
The first point on the revolve axis.
-
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”.
-
PolygonRevolve()#
Default constructor. Creates a unit-radius cylinder centered on the origin.
-
PolygonRevolve(const std::vector<glm::vec3> &vertices, const glm::vec3 &axis_start, const glm::vec3 &axis_end, double sweep_degrees = 360.0)#
Constructor.
Creates a revolved polygon from a planar half-profile.
- Parameters:
vertices – The vertices of the planar half-profile polygon.
axis_start – A point on the revolve axis.
axis_end – A second point on the revolve axis defining positive direction.
sweep_degrees – Positive sweep angle in degrees, in the range (0, 360].
- Throws:
std::runtime_error – if the polygon, axis, sweep, or profile placement is invalid.
-
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 double sweep_degrees() const#
Returns the sweep angle in degrees.
- Returns:
The sweep angle in degrees.
-
inline const std::vector<glm::vec3> &vertices() const#
Returns the vertices of the planar half-profile polygon.
- Returns:
The vertices of the planar half-profile polygon.
Private Functions
Private Members
-
glm::vec3 m_axis_end#
A second point on the revolve axis defining positive direction.
-
glm::vec3 m_axis_start#
A point on the revolve axis.
-
std::vector<glm::vec3> m_vertices#
The original 3D vertices of the profile polygon.
Private Static Functions
-
struct Placement#
The half-profile as a profile in (radial, axial) coordinates, and the axis frame.
-
inline glm::vec3 axis_end() const#
-
class Tube : public Leaf#
- #include <tube.h>
A tube (pipe) of constant or varying radius along any curve.
The tube is every point within r of the curve, where r is measured at the curve point closest to the query: the signed distance is |p - c(t*)| - r(c(t*)). The radius is a ScalarParameter sampled at c(t*), so it can vary in space (any FloatAttribute) or along the curve: a law on the curve parameter or arc length is a field built from curve_field() / coordinate_field(), for example the normalized length mapped to a radius range.
Ends of open curves: CapMode::Sphere and CapMode::HemiSphere both close the end with a rounded (half-ball) cap; CapMode::Butt cuts it flat, perpendicular to the end tangent. Closed curves have no ends. Strut remains the cheaper choice for a straight tube.
Attributes (new geometry): the node’s own attributes, plus coordinate fields from coordinate_field(): “parameter”, “length”, “normalized_length”, “angle” and “distance”.
Distance accuracy (distance_accuracy()): exact for a straight (LineSegment) tube of constant radius; bound for a curved tube of constant radius; approximate for a field radius (which needs known bounds to size the bounding box) and for butt caps on a curved open curve. With a constant radius the value |p - c(t*)| - r is 1-Lipschitz and exact outside (to the curve’s closest-point accuracy); inside a curved tube it is exact only while the tube is proper (see below), else it underestimates the depth.
The tube stays a proper tube while the radius is smaller than the curve’s radius of curvature; beyond that the surface folds over itself.
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
-
std::shared_ptr<FloatAttribute> coordinate_field(const std::string &name) const#
Returns a field for one of the tube’s coordinates.
- Parameters:
name – “parameter”, “length”, “normalized_length”, “angle” or “distance”.
- Throws:
std::runtime_error – if the name is not one of the tube’s coordinates.
- Returns:
A CoordinateFieldAttribute over a private copy of the tube geometry.
-
inline const std::shared_ptr<const Curve> &curve() const#
Returns the centre curve.
- Returns:
The centre curve.
-
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.
Exact for a straight constant-radius tube, bound for a curved one, approximate for a field radius or for butt caps on a curved open curve. A curved tube is exact outside but underestimates the depth once the radius passes the curve’s radius of curvature. With a butt cap,
evaluate() takes the flat-end formula when the closest curve point is that end and the plane-clipped tube formula otherwise; on a curved open curve the two disagree where the closest point jumps between the end and the body (a point beyond the end plane equally far from both), so the value jumps there. A straight curve (a LineSegment) or a closed curve has no such jump.- 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 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()
.
1, or infinity when
distance_accuracy() is 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.
-
inline const ScalarParameter &radius() const#
Returns the radius parameter.
- Returns:
The radius parameter.
Constructor.
- Parameters:
curve – The centre curve; must have positive length.
radius – The radius: a constant, or a field with known bounds.
start_cap – How the start of an open curve is closed.
end_cap – How the end of an open curve is closed.
- Throws:
std::runtime_error – if the curve is null or has zero length, the radius is not positive, or a field radius has no bounds.
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
-
std::shared_ptr<TubeGeometry> m_geometry#
-
virtual std::shared_ptr<Node> clone() override#
-
class TubeGeometry : public CoordinateSource#
- #include <tube.h>
The evaluation state of a Tube, shared with its coordinate fields.
Holds the (immutable) curve and frames, the radius parameter and the caps. Coordinates: “parameter”, “length”, “normalized_length” (of the closest curve point), “angle” (degrees in [0, 360) around the curve, measured from the rotation-minimizing frame’s normal toward its binormal) and “distance” (from the curve).
Public Functions
-
std::shared_ptr<TubeGeometry> clone() const#
Returns a copy with its own radius field, for another thread.
- Returns:
A copy with its own radius field, for another thread.
-
virtual std::shared_ptr<CoordinateSource> clone_source() const override#
Returns a copy for another thread.
- Returns:
The copy.
-
virtual double coordinate(size_t index, const glm::dvec3 &point) const override#
Evaluates coordinate
indexat a point.- Parameters:
index – The coordinate index into coordinate_names().
point – The point, in the source’s coordinate system.
- Returns:
The coordinate value.
-
virtual const std::vector<std::string> &coordinate_names() const override#
Returns the names of the coordinates, in index order.
- Returns:
The coordinate names.
-
inline const std::shared_ptr<const Curve> &curve() const#
Returns the centre curve.
- Returns:
The centre curve.
-
double distance(const glm::dvec3 &point) const#
Signed distance to the tube at a point.
- Parameters:
point – The query point.
- Returns:
The signed distance (negative inside).
-
inline const ScalarParameter &radius() const#
Returns the radius parameter.
- Returns:
The radius parameter.
Constructor.
Validates the inputs and builds the curve frames.
- Parameters:
curve – The centre curve; must have positive length.
radius – The radius: a positive constant, or a field with known bounds.
start_cap – How the start of an open curve is closed.
end_cap – How the end of an open curve is closed.
- Throws:
std::runtime_error – if the curve is null or has zero length, the radius is not positive, or a field radius has no bounds.
-
std::shared_ptr<TubeGeometry> clone() const#
-
class Extrude : public Leaf#
- #include <extrude.h>
A profile extruded from a sketch plane along its normal, with optional draft (taper), twist and a wall offset law.
The profile lies in the plane (by default the XY plane) and is extruded along the plane’s normal from 0 to height (from height up to 0 when height is negative), or from -|height|/2 to |height|/2 when symmetric; below, “z” is the distance along the normal. Draft tapers the walls: the section at height s above the base is the profile offset inward by s * tan(draft) (a negative draft widens it); when symmetric, s is measured from the profile plane both ways. Twist turns the section counter-clockwise about the normal, growing linearly from 0 at the base to twist at the top.
The offset law shapes the walls along the height: points (f, w) say that the section at fraction f of the way from the base to the top is the profile offset outward by w (inward for negative w), joined smoothly between the points (a monotone cubic, PiecewiseCurve) and held at the end values beyond them. It adds to the draft, so a bulge, a waist or a flared foot is a few points.
Attributes (new geometry): the node’s own attributes, plus coordinate fields from coordinate_field(): “u”, “v”, “height”, “normalized_height” and “profile_distance”.
Distance accuracy (distance_accuracy()): exact without draft, twist or offset law (the profile distance is exact). With any of them the wall term is divided by a bound on its slope, sqrt(1 + (omega * rho + |tan(draft)| + lambda)^2), where omega is the twist rate, rho the larger of the point’s and the profile’s distance from the axis and lambda the law’s largest slope, and it is combined with the end caps by max. Beside the walls that value falls below the per-axis distance to the bounding box, so the box promise fails and the value jumps to the band where is_in_bbox() cuts it off: approximate.
Subclassed by PolygonExtrude
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
-
std::shared_ptr<FloatAttribute> coordinate_field(const std::string &name) const#
Returns a field for one of the extrusion’s coordinates.
- Parameters:
name – “u”, “v”, “height”, “normalized_height” or “profile_distance”.
- Throws:
std::runtime_error – if the name is not one of the extrusion’s coordinates.
- Returns:
A CoordinateFieldAttribute over a copy of the extrusion geometry.
-
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.
Exact without draft, twist or offset law; approximate with any of them. Without draft or twist the value is the exact prism distance (profile distance and slab joined exactly), and the box holds the prism. With draft or twist the divided wall term is below the per-axis distance to the box beside the walls (a 45 degree draft gives cos(45) of it at the base), which breaks the box promise and makes the band-clipped value jump at the bandwidth-padded box face.
PolygonExtrude has neither, so it is exact.- Returns:
The accuracy of the subtree rooted at this node.
-
inline double draft_degrees() const#
Returns the draft angle in degrees.
- Returns:
The draft angle in degrees.
-
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.
Constructor.
- Parameters:
profile – The profile in the XY plane; must not be empty.
height – The extrusion height; non-zero, negative extrudes along -Z.
symmetric – True to extrude |height|/2 to each side of the profile plane.
draft_degrees – Wall taper in degrees, in (-90, 90); positive narrows toward the top.
twist_degrees – Total twist from base to top in degrees, counter-clockwise about the normal.
plane – The sketch plane the profile lies in; the extrusion runs along its normal.
offset_law – Points (fraction of the height from the base, outward wall offset); empty for none, otherwise at least two with distinct fractions.
- Throws:
std::runtime_error – on invalid input, including a draft or offset law that shrinks the section to nothing within the extrusion.
-
inline const LocalFrame &frame() const#
Returns the frame placing the profile plane in the world (local Z is the normal).
- Returns:
The frame.
-
inline double height() const#
Returns the extrusion height.
- Returns:
The extrusion height.
-
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.
-
inline const std::shared_ptr<const PiecewiseCurve> &offset_law() const#
Returns the wall offset law, or null without one.
- Returns:
The law.
-
inline const std::shared_ptr<const Profile> &profile() const#
Returns the profile.
- Returns:
The profile.
-
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 bool symmetric() const#
Returns whether the extrusion is symmetric about the profile plane.
- Returns:
Whether the extrusion is symmetric about the profile plane.
-
inline double twist_degrees() const#
Returns the twist angle in degrees.
- Returns:
The twist angle in degrees.
Protected Functions
Constructor placing the profile plane with a rigid frame (used by PolygonExtrude).
- Parameters:
profile – The profile in the local XY plane; must not be empty.
height – The extrusion height along the local Z axis; non-zero.
symmetric – True to extrude |height|/2 to each side of the profile plane.
frame – The rigid frame placing the local coordinates in the world.
-
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().
Protected Attributes
-
std::shared_ptr<ExtrudeGeometry> m_geometry#
The evaluation state, shared with coordinate fields.
-
virtual std::shared_ptr<Node> clone() override#
-
class ExtrudeGeometry : public CoordinateSource#
- #include <extrude.h>
The evaluation state of an Extrude, shared with its coordinate fields.
Coordinates: “u” and “v” (the section coordinates, with the twist undone), “height” (from the base), “normalized_height” (0 at the base, 1 at the top) and “profile_distance” (the signed distance to the section’s outline at that height, draft and offset law included).
Public Functions
-
std::pair<glm::dvec3, glm::dvec3> bounding_box() const#
The world-space bounding box.
- Returns:
The minimum and maximum corners.
-
virtual std::shared_ptr<CoordinateSource> clone_source() const override#
Returns a copy for another thread.
- Returns:
The copy.
-
virtual double coordinate(size_t index, const glm::dvec3 &point) const override#
Evaluates coordinate
indexat a point.- Parameters:
index – The coordinate index into coordinate_names().
point – The point, in the source’s coordinate system.
- Returns:
The coordinate value.
-
virtual const std::vector<std::string> &coordinate_names() const override#
Returns the names of the coordinates, in index order.
- Returns:
The coordinate names.
-
double distance(const glm::dvec3 &point) const#
Signed distance at a world point.
- Parameters:
point – The world point.
- Returns:
The signed distance (negative inside).
-
inline double draft_degrees() const#
Returns the draft angle in degrees.
- Returns:
The draft angle in degrees.
Constructor.
Validates the inputs; see Extrude::Extrude() for their meaning.
- Parameters:
profile – The profile in the local XY plane; must not be empty.
height – The extrusion height; finite and non-zero.
symmetric – True to extrude |height|/2 to each side of the profile plane.
draft_degrees – Wall taper in degrees, in (-90, 90).
twist_degrees – Total twist from base to top in degrees.
frame – The rigid frame placing the local coordinates in the world.
offset_law – Points (fraction of the height, outward offset) of the wall offset law; empty for none.
- Throws:
std::runtime_error – on invalid input.
-
inline const LocalFrame &frame() const#
Returns the frame placing the local coordinates in the world.
- Returns:
The frame.
-
inline double height() const#
Returns the authored extrusion height.
- Returns:
The extrusion height (negative extrudes along -Z).
-
inline const std::shared_ptr<const PiecewiseCurve> &offset_law() const#
Returns the wall offset law, or null without one.
- Returns:
The law: outward offset against the fraction of the height.
-
inline const std::shared_ptr<const Profile> &profile() const#
Returns the profile.
- Returns:
The profile.
-
inline bool symmetric() const#
Returns whether the extrusion is symmetric about the profile plane.
- Returns:
True if symmetric.
-
inline double twist_degrees() const#
Returns the twist angle in degrees.
- Returns:
The twist angle in degrees.
Private Functions
-
void check_section_survives() const#
Throws when the draft and offset law shrink the section to nothing within the extrusion.
-
double inset(double z) const#
How far the section at local height z is offset inward (draft minus offset law).
-
void section(const glm::dvec3 &local, glm::dvec2 &uv, double &s, double &profile_distance) const#
Local coordinates of a point: the section point (u, v), the height s from the base, and the in-plane signed distance (draft and offset law included, before any scaling).
Private Members
-
double m_bottom = 0.0#
Local z of the base.
-
double m_draft_degrees#
-
LocalFrame m_frame#
-
double m_height#
-
double m_law_slope = 0.0#
Largest |d offset / d z| of the law.
-
std::shared_ptr<const PiecewiseCurve> m_offset_law#
-
double m_radius = 0.0#
Largest distance of the profile from the local z axis.
-
bool m_symmetric#
-
double m_tan_draft = 0.0#
-
double m_top = 0.0#
Local z of the top.
-
double m_twist_degrees#
-
double m_twist_rate = 0.0#
Radians per unit height.
-
std::pair<glm::dvec3, glm::dvec3> bounding_box() const#
-
class Revolve : public Leaf#
- #include <revolve.h>
A profile revolved about an axis in its sketch plane, fully or through a partial angle.
The profile lies in a sketch plane and turns about the plane’s y axis (through its origin). The profile’s u coordinate (its x) is the distance from the axis and must not be negative; its v coordinate (its y) is the position along the axis. The default plane is SketchPlane::xz(): the axis is world +Z, x is the radius and y becomes z. The sweep starts in the sketch plane (on its +x side) and turns counter-clockwise about the axis through angle_degrees. Profile edges that lie on the axis are interior to the solid, not surfaces. A partial sweep is closed by flat caps.
Attributes (new geometry): the node’s own attributes, plus coordinate fields from coordinate_field(): “u”, “v”, “angle”, “normalized_angle” and “profile_distance”.
Distance accuracy (distance_accuracy()): exact for full and partial sweeps. Inside the swept wedge the distance is the meridian-plane profile distance (and, inside the solid, the distance to the end caps); outside it, the distance to the nearer cap face, which is where the closest point lies because distance along each orbit grows with angle.
Subclassed by PolygonRevolve
Public Functions
-
inline double angle_degrees() const#
Returns the sweep angle in degrees.
- Returns:
The sweep angle in degrees.
-
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 revolve’s coordinates.
- Parameters:
name – “u”, “v”, “angle”, “normalized_angle” or “profile_distance”.
- Throws:
std::runtime_error – if the name is not one of the revolve’s coordinates.
- Returns:
A CoordinateFieldAttribute over a copy of the revolve geometry.
-
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.
Exact, for full and partial sweeps (and so for
PolygonRevolve). The closest point of a solid of revolution lies in the query’s own meridian half-plane, so the meridian profile distance is exact outside; inside, edges on the axis are dropped since they are interior. A partial sweep adds the exact distance to its two cap faces (inside the solid, and outside the wedge where the closest point is on the angularly nearer cap). The box holds every profile point swept through the extreme angles of each world axis.- 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 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.
-
inline const std::shared_ptr<const Profile> &profile() const#
Returns the profile.
- Returns:
The profile.
-
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.
Constructor.
- Parameters:
profile – The profile, in x >= 0 of its sketch plane; must not be empty.
angle_degrees – The sweep angle in degrees, in (0, 360].
plane – The sketch plane; the axis is its y axis through its origin.
- Throws:
std::runtime_error – on invalid input.
Protected 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().
Constructor placing the axis with a rigid frame (used by PolygonRevolve).
- Parameters:
profile – The profile, in x >= 0 of the local XY plane; must not be empty.
angle_degrees – The sweep angle in degrees, in (0, 360].
frame – The rigid frame placing the local coordinates in the world; the local Z axis is the revolve axis.
Protected Attributes
-
std::shared_ptr<RevolveGeometry> m_geometry#
The evaluation state, shared with coordinate fields.
-
inline double angle_degrees() const#
-
class RevolveGeometry : public CoordinateSource#
- #include <revolve.h>
The evaluation state of a Revolve, shared with its coordinate fields.
Coordinates: “u” (distance from the axis), “v” (position along the axis), “angle” (degrees from the start of the sweep), “normalized_angle” (0 to 1 over the sweep) and “profile_distance” (the signed distance in the point’s meridian plane).
Public Functions
-
inline double angle_degrees() const#
Returns the sweep angle in degrees.
- Returns:
The sweep angle in degrees.
-
std::pair<glm::dvec3, glm::dvec3> bounding_box() const#
The world-space bounding box.
- Returns:
The minimum and maximum corners.
-
virtual std::shared_ptr<CoordinateSource> clone_source() const override#
Returns a copy for another thread.
- Returns:
The copy.
-
virtual double coordinate(size_t index, const glm::dvec3 &point) const override#
Evaluates coordinate
indexat a point.- Parameters:
index – The coordinate index into coordinate_names().
point – The point, in the source’s coordinate system.
- Returns:
The coordinate value.
-
virtual const std::vector<std::string> &coordinate_names() const override#
Returns the names of the coordinates, in index order.
- Returns:
The coordinate names.
-
double distance(const glm::dvec3 &point) const#
Signed distance at a world point.
- Parameters:
point – The world point.
- Returns:
The signed distance (negative inside).
-
inline bool is_full() const#
Returns true for a full 360 degree sweep (no end caps).
- Returns:
True if the sweep is a full turn.
-
inline const std::shared_ptr<const Profile> &profile() const#
Returns the profile.
- Returns:
The profile.
Constructor.
Validates the inputs; see Revolve::Revolve() for their meaning.
- Parameters:
profile – The profile, in x >= 0 of the local XY plane; must not be empty.
angle_degrees – The sweep angle in degrees, in (0, 360].
frame – The rigid frame placing the local coordinates in the world.
- Throws:
std::runtime_error – on invalid input.
Private Functions
-
double cap_distance(const glm::dvec3 &local, double angle) const#
Distance from a local point to the end cap face at angle
angle(radians).
-
double meridian_distance(double radius, double height) const#
Signed distance in a meridian plane; boundary pieces on the axis do not count for points inside (they are inside the solid).
-
inline double angle_degrees() const#
-
class Sweep : public Leaf#
- #include <sweep.h>
A profile swept along a path curve.
The profile’s (u, v) plane is carried along the path in its rotation-minimizing frames: u along the frame normal and v along the binormal, so the profile does not twist on its own. For a planar path the binormal is the plane normal unless
upsays otherwise. The section can be scaled and twisted along the way: scale and twist (in degrees, counter-clockwise about the path tangent) are ScalarParameters sampled at the closest path point, so a law along the path is a field built from the path’s own fields, such as path.length_field(normalized=True). Open paths end in flat caps perpendicular to the end tangents; closed paths close on themselves (the frames are made to meet at the seam).Attributes (new geometry): the node’s own attributes, plus coordinate fields from coordinate_field(): “parameter”, “length”, “normalized_length”, “u”, “v” and “profile_distance”.
Distance accuracy (distance_accuracy()): exact for a straight path (a LineSegment) with a constant scale and a constant twist (an extrusion of a rigidly turned profile); otherwise approximate. The section of each point is the one at its closest path point, so the profile must stay inside the path’s radius of curvature, as for any swept solid.
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
-
std::shared_ptr<FloatAttribute> coordinate_field(const std::string &name) const#
Returns a field for one of the sweep’s coordinates.
- Parameters:
name – “parameter”, “length”, “normalized_length”, “u”, “v” or “profile_distance”.
- Throws:
std::runtime_error – if the name is not one of the sweep’s coordinates.
- Returns:
A CoordinateFieldAttribute over a private copy of the sweep geometry.
-
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.
Exact for a straight path with constant scale and twist; otherwise approximate. Along a
LineSegment the frame is constant, so a constant scale and twist place one rigidly turned, scaled profile at every closest point: the value is the exact prism distance, and the box (the path box grown by the scaled profile radius) holds it. Elsewhere the section at the closest path point can change abruptly (where the closest point jumps, or with scale and twist laws), so nothing is promised.- 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 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.
-
inline const std::shared_ptr<const Profile> &profile() const#
Returns the profile.
- Returns:
The profile.
-
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 ScalarParameter &scale() const#
Returns the scale parameter.
- Returns:
The scale parameter.
Constructor.
- Parameters:
profile – The cross-section, in its own (u, v) plane; must not be empty.
path – The path curve; must have positive length.
scale – Section scale; a positive constant, or a field with positive bounds.
twist – Section angle in degrees at each path point (a law along the path, not a total as in Extrude); a constant or a field (no bounds needed).
up – Optional direction for the initial binormal (the profile’s v axis).
- Throws:
std::runtime_error – on invalid input, including a section that reaches past the centre of curvature on the inside of a bend of the path.
-
inline const ScalarParameter &twist() const#
Returns the twist parameter, in degrees.
- Returns:
The twist parameter, in degrees.
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
-
std::shared_ptr<SweepGeometry> m_geometry#
-
virtual std::shared_ptr<Node> clone() override#
-
class SweepGeometry : public CoordinateSource#
- #include <sweep.h>
The evaluation state of a Sweep, shared with its coordinate fields.
Coordinates: “parameter”, “length”, “normalized_length” (of the closest path point), “u” and “v” (profile coordinates, with the scale and twist undone) and “profile_distance” (the signed distance to the scaled, twisted section outline).
Public Functions
-
std::pair<glm::dvec3, glm::dvec3> bounding_box() const#
The bounding box.
- Returns:
The minimum and maximum corners.
-
std::shared_ptr<SweepGeometry> clone() const#
Returns a copy with its own scale and twist fields, for another thread.
- Returns:
A copy with its own scale and twist fields, for another thread.
-
virtual std::shared_ptr<CoordinateSource> clone_source() const override#
Returns a copy for another thread.
- Returns:
The copy.
-
virtual double coordinate(size_t index, const glm::dvec3 &point) const override#
Evaluates coordinate
indexat a point.- Parameters:
index – The coordinate index into coordinate_names().
point – The point, in the source’s coordinate system.
- Returns:
The coordinate value.
-
virtual const std::vector<std::string> &coordinate_names() const override#
Returns the names of the coordinates, in index order.
- Returns:
The coordinate names.
-
double distance(const glm::dvec3 &point) const#
Signed distance at a point.
- Parameters:
point – The query point.
- Returns:
The signed distance (negative inside).
-
inline const std::shared_ptr<const Profile> &profile() const#
Returns the profile.
- Returns:
The profile.
-
inline const ScalarParameter &scale() const#
Returns the scale parameter.
- Returns:
The scale parameter.
Constructor.
Validates the inputs and builds the path frames; see Sweep::Sweep().
- Parameters:
profile – The cross-section, in its own (u, v) plane; must not be empty.
path – The path curve; must have positive length.
scale – Section scale; a positive constant, or a field with positive bounds.
twist – Section angle in degrees at each path point; a constant or a field.
up – Optional direction for the initial binormal (the profile’s v axis).
- Throws:
std::runtime_error – on invalid input.
-
inline const ScalarParameter &twist() const#
Returns the twist parameter, in degrees.
- Returns:
The twist parameter.
Private Functions
-
void check_bends() const#
Throws when the section certainly reaches past the centre of curvature on the inside of a bend of the path, where it would fold over itself.
- Throws:
std::runtime_error – naming the bend and how far the section reaches into it.
-
SweepGeometry() = default#
Private Members
-
std::shared_ptr<const CurveFrames> m_frames#
-
ScalarParameter m_scale#
-
ScalarParameter m_twist#
-
struct Section#
The section through a point: the closest path point, its frame, and the point in profile coordinates.
-
std::pair<glm::dvec3, glm::dvec3> bounding_box() const#
-
struct LocalFrame#
- #include <local_frame.h>
A rigid placement: an origin and three orthonormal axes.
Extrude and Revolve work in their own local coordinates (the profile in the local XY plane); PolygonExtrude and PolygonRevolve place those coordinates in the world with a frame. The default is the world frame. Being rigid, it keeps distances exact.
Public Functions
-
inline glm::dvec3 to_local(const glm::dvec3 &p) const#
World point to local coordinates.
- Parameters:
p – The world point.
- Returns:
The point in local coordinates.
-
inline glm::dvec3 to_world(const glm::dvec3 &q) const#
Local coordinates to a world point.
- Parameters:
q – The local coordinates.
- Returns:
The world point.
Public Members
-
glm::dvec3 origin = glm::dvec3(0.0)#
World position of the local origin.
-
glm::dvec3 x = glm::dvec3(1.0, 0.0, 0.0)#
World direction of the local X axis (unit length).
-
glm::dvec3 y = glm::dvec3(0.0, 1.0, 0.0)#
World direction of the local Y axis (unit length).
-
glm::dvec3 z = glm::dvec3(0.0, 0.0, 1.0)#
World direction of the local Z axis (unit length).
-
inline glm::dvec3 to_local(const glm::dvec3 &p) const#