Attributes#
Core attribute types, samples, default name/type constants, and converters.
Core types#
Enums
-
enum class AttributeComponentKind#
Optional mapped-component provenance supplied while sampling an attribute.
Values:
-
enumerator none#
No component provenance (plain spatial sample).
-
enumerator implicit_shell#
The shell surface of a MappedImplicitLattice.
-
enumerator graph_strut#
A strut (unit-cell edge) of a mapped graph lattice.
-
enumerator graph_joint#
A joint (unit-cell vertex) of a mapped graph lattice.
-
enumerator face#
A plate (unit-cell face) of a mapped face lattice.
-
enumerator none#
-
class Attribute#
- #include <attribute.h>
The base interface for all continuous material and property attributes.
This class defines the common interface for sampling an attribute map, including material volume fractions and values like density or elastic modulus.
Subclassed by CoordinateReframedAttribute, FloatAttribute, Vec3Attribute, Vec4Attribute, VolumeFractionsAttribute
Public Types
-
enum ReturnType#
The data type returned by the attribute evaluation.
Values:
-
enumerator none#
No value (for example, a missing attribute).
-
enumerator dbl#
A scalar double.
-
enumerator vec3#
A glm::vec3.
-
enumerator vec4#
A glm::vec4.
-
enumerator vfm_ptr#
-
enumerator none#
-
typedef boost::variant<double, glm::vec3, glm::vec4, VolumeFractionMapPtr> Value#
A boost::variant that can hold any of the supported return types.
-
typedef std::unordered_map<uint8_t, double> VolumeFractionMap#
A map associating material IDs (uint8_t) to their volume fractions (double).
-
typedef std::shared_ptr<VolumeFractionMap> VolumeFractionMapPtr#
A shared pointer to a VolumeFractionMap.
Public Functions
-
virtual std::shared_ptr<Attribute> clone() = 0#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
virtual ReturnType return_type() = 0#
Retrieves the return type of the attribute.
- Returns:
The ReturnType enum value indicating the actual type stored in the Value variant.
-
inline virtual Value sample(const AttributeSampleContext &context)#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) = 0#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual ~Attribute() = default#
Virtual destructor.
-
enum ReturnType#
-
struct AttributeSampleContext#
- #include <attribute.h>
Optional CellMap location information shared by one attribute sample.
position is always expressed in the current consuming node’s coordinates. This context does not retain a root-world coordinate system; it only avoids repeating CellMap inversion while sampling lattice-specific coordinate adapters. Mapped lattice leaves may also supply compact source-component provenance.
Public Members
-
const CellMap *cell_map = nullptr#
The CellMap that produced the logical coordinates, or nullptr when there is none.
-
glm::vec3 component_direction = {0.0f}#
Unit strut direction or plate normal of the component; zero when undefined.
-
int component_id = -1#
Unit-cell edge, vertex or face id of the component, or -1 when unknown.
-
AttributeComponentKind component_kind = AttributeComponentKind::none#
Kind of mapped component the sample is attributed to (none for plain samples).
-
int component_material_tag = -1#
Material tag of the component, or -1 when unset.
-
int component_orientation_tag = -1#
Orientation tag of the component, or -1 when unset.
-
double component_parameter = 0.0#
Parameter along a graph strut in [0, 1] (graph lattices only).
-
double component_side = 0.0#
Side of an implicit shell: +1 outside the surface, -1 inside, 0 on it.
-
double component_surface_distance = 0.0#
Signed distance to the component’s own surface.
-
int component_tag = -1#
User tag of the component (edge, first-vertex or face tag), or -1 when unset.
-
glm::vec3 logical = {0.0f}#
Logical (cell-space) coordinates of the sample. Valid only when cell_map is set.
-
glm::ivec3 logical_cell_index = {0}#
Integer index of the logical cell that contains the sample.
-
glm::vec3 position = {0.0f}#
Sample position in the consuming node’s coordinates.
-
double signed_distance = 0.0#
Signed distance of the consuming node at position.
-
const CellMap *cell_map = nullptr#
-
class AttributeSet#
- #include <attribute_set.h>
A container for multiple Attributes assigned to a Node.
This class acts as a key-value store mapping attribute names to their evaluating Attribute objects. It handles the sampling of all contained attributes at a specific point.
Public Functions
-
std::unordered_map<std::string, std::shared_ptr<Attribute>> as_map() const#
Returns the underlying map of attribute objects.
- Returns:
A copy of the map tracking string names to Attribute instances.
-
std::vector<std::string> attribute_names() const#
Retrieves a list of all attribute names present in the set.
- Returns:
A vector of active attribute names.
-
AttributeSet() = default#
Constructs an empty set.
-
std::shared_ptr<AttributeSet> clone() const#
Deep copies the set and all of its contained attributes.
- Returns:
A shared pointer to the new AttributeSet.
-
std::shared_ptr<Attribute> get_attribute(const std::string &name) const#
Retrieves a specific attribute object by its name.
- Parameters:
name – The name of the attribute to locate.
- Returns:
A shared pointer to the Attribute object. Returns nullptr if the attribute is not found.
-
bool has_attribute(const std::string &name) const#
Checks if the set contains an attribute with the given name.
- Parameters:
name – The name of the attribute.
- Returns:
True if the set contains the attribute, false otherwise.
-
AttributeSamples sample(const AttributeSampleContext &context) const#
Evaluates all attributes in the set with optional CellMap/component provenance.
Each attribute is sampled with Attribute::sample(const AttributeSampleContext&). Empty volume-fraction maps are left out of the result so they cannot shadow non-empty maps from other nodes when samples are merged.
- Parameters:
context – The sample location and provenance.
- Returns:
An AttributeSamples container holding the evaluated values.
-
AttributeSamples sample(double x, double y, double z, double d) const#
Evaluates all attributes in the set at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point.
- Returns:
An AttributeSamples container holding the evaluated values.
Sets a new attribute in the set.
- Parameters:
name – The name of the attribute.
attribute – A shared pointer to the Attribute mapping to the name.
- Throws:
std::runtime_error – if an attribute with the same name already exists.
Sets or replaces an attribute in this set.
Intended for a more-specific component attachment replacing a generated default.
- Parameters:
name – The name of the attribute.
attribute – The new attribute. A replacement must have the same return type as the attribute it replaces.
- Throws:
std::runtime_error – If attribute is null, or if it would change the return type of an existing attribute with the same name.
-
std::unordered_map<std::string, std::shared_ptr<Attribute>> as_map() const#
-
class AttributeSamples#
- #include <attribute_samples.h>
A container for the results of evaluating an AttributeSet at a specific point.
This class acts as a key-value store mapping attribute names to their evaluated Attribute::Value variants.
Public Functions
-
std::unordered_map<std::string, Attribute::Value> as_map() const#
Returns the underlying unordered map of all attribute samples.
- Returns:
A copy of the internal map.
-
AttributeSamples() = default#
Constructs an empty container.
-
bool empty() const#
Checks if the container is empty.
- Returns:
True if there are zero samples, false otherwise.
-
Attribute::Value get_sample(const std::string &name) const#
Retrieves a sample by attribute name.
- Parameters:
name – The string name of the attribute.
- Throws:
std::runtime_error – if the sample does not exist.
- Returns:
The stored Attribute::Value variant.
-
bool has_sample(const std::string &name) const#
Checks if a sample for a given attribute name exists.
- Parameters:
name – The string name of the attribute.
- Returns:
True if the sample exists, false otherwise.
-
size_t num_samples() const#
Returns the number of stored attribute samples.
- Returns:
The size of the sample map.
-
AttributeSamples &operator+=(const AttributeSamples &rhs)#
Operator for += to add two AttributeSamples together.
Copies samples from rhs into this container, preferring existing values on collision.
- Parameters:
rhs – The right-hand side AttributeSamples to merge.
- Returns:
A reference to this container.
-
void set_sample(const std::string &name, const Attribute::Value &value)#
Sets a newly evaluated sample value for an attribute, replacing any existing value.
- Parameters:
name – The string name of the attribute.
value – The Attribute::Value variant to store.
-
std::unordered_map<std::string, Attribute::Value> as_map() const#
-
namespace DefaultAttributes#
Contains standard string names and matching ReturnType enumerations for common attributes used across the API.
Functions
-
inline Attribute::ReturnType get_return_type_by_name(const std::string &name)#
Looks up the expected return type for a built-in attribute name.
- Parameters:
name – The name of the attribute.
- Returns:
The ReturnType enum associated with that standard attribute name, or none if unrecognized.
Variables
-
const std::string BOTTOM_SOLID_LAYERS = "bottom_solid_layers"#
Slicer number of solid layers over a bottom surface (stored as a float, rounded when exported).
-
constexpr Attribute::ReturnType BOTTOM_SOLID_LAYERS_TYPE = Attribute::ReturnType::dbl#
ReturnType of BOTTOM_SOLID_LAYERS.
-
const std::string BOTTOM_SOLID_MIN_THICKNESS = "bottom_solid_min_thickness"#
Slicer least thickness of the solid layers over a bottom surface in mm.
-
constexpr Attribute::ReturnType BOTTOM_SOLID_MIN_THICKNESS_TYPE = Attribute::ReturnType::dbl#
ReturnType of BOTTOM_SOLID_MIN_THICKNESS.
-
const std::string BRIDGE_SPEED = "bridge_speed"#
Slicer bridge speed in mm/s.
-
constexpr Attribute::ReturnType BRIDGE_SPEED_TYPE = Attribute::ReturnType::dbl#
ReturnType of BRIDGE_SPEED.
-
const std::string COLOR_RGB = "color_rgb"#
RGB color, a vec3 with components in [0, 1].
-
constexpr Attribute::ReturnType COLOR_RGB_TYPE = Attribute::ReturnType::vec3#
ReturnType of COLOR_RGB.
-
const std::string COLOR_RGBA = "color_rgba"#
RGBA color, a vec4 with components in [0, 1].
-
constexpr Attribute::ReturnType COLOR_RGBA_TYPE = Attribute::ReturnType::vec4#
ReturnType of COLOR_RGBA.
-
const std::string DENSITY = "density"#
Density, a scalar.
-
constexpr Attribute::ReturnType DENSITY_TYPE = Attribute::ReturnType::dbl#
ReturnType of DENSITY.
-
const std::string ELONGATION = "elongation"#
Elongation at break, a scalar.
-
constexpr Attribute::ReturnType ELONGATION_TYPE = Attribute::ReturnType::dbl#
ReturnType of ELONGATION.
-
const std::string EXTERNAL_PERIMETER_EXTRUSION_WIDTH = "external_perimeter_extrusion_width"#
Slicer external perimeter extrusion width in mm.
-
constexpr Attribute::ReturnType EXTERNAL_PERIMETER_EXTRUSION_WIDTH_TYPE = Attribute::ReturnType::dbl#
ReturnType of EXTERNAL_PERIMETER_EXTRUSION_WIDTH.
-
const std::string EXTERNAL_PERIMETER_SPEED = "external_perimeter_speed"#
Slicer external perimeter speed in mm/s.
-
constexpr Attribute::ReturnType EXTERNAL_PERIMETER_SPEED_TYPE = Attribute::ReturnType::dbl#
ReturnType of EXTERNAL_PERIMETER_SPEED.
-
const std::string EXTRUSION_WIDTH = "extrusion_width"#
Slicer default extrusion width in mm.
-
constexpr Attribute::ReturnType EXTRUSION_WIDTH_TYPE = Attribute::ReturnType::dbl#
ReturnType of EXTRUSION_WIDTH.
-
const std::string FAN_SPEED = "fan_speed"#
Slicer part-cooling fan speed in percent of full fan (0 to 100).
-
constexpr Attribute::ReturnType FAN_SPEED_TYPE = Attribute::ReturnType::dbl#
ReturnType of FAN_SPEED.
-
const std::string FLOW_RATE = "flow_rate"#
Slicer extrusion flow rate in percent (written to G-code as M221).
-
constexpr Attribute::ReturnType FLOW_RATE_TYPE = Attribute::ReturnType::dbl#
ReturnType of FLOW_RATE.
-
const std::string FUZZY_SKIN_POINT_DISTANCE = "fuzzy_skin_point_distance"#
Slicer fuzzy-skin point distance in mm.
-
constexpr Attribute::ReturnType FUZZY_SKIN_POINT_DISTANCE_TYPE = Attribute::ReturnType::dbl#
ReturnType of FUZZY_SKIN_POINT_DISTANCE.
-
const std::string FUZZY_SKIN_THICKNESS = "fuzzy_skin_thickness"#
Slicer fuzzy-skin thickness in mm.
-
constexpr Attribute::ReturnType FUZZY_SKIN_THICKNESS_TYPE = Attribute::ReturnType::dbl#
ReturnType of FUZZY_SKIN_THICKNESS.
-
const std::string GAP_FILL_SPEED = "gap_fill_speed"#
Slicer gap fill speed in mm/s.
-
constexpr Attribute::ReturnType GAP_FILL_SPEED_TYPE = Attribute::ReturnType::dbl#
ReturnType of GAP_FILL_SPEED.
-
const std::string HU = "hu"#
Hounsfield units from CT/DICOM data, a scalar.
-
constexpr Attribute::ReturnType HU_TYPE = Attribute::ReturnType::dbl#
ReturnType of HU.
-
const std::string INFILL_DENSITY = "infill_density"#
Slicer infill density in percent.
-
constexpr Attribute::ReturnType INFILL_DENSITY_TYPE = Attribute::ReturnType::dbl#
ReturnType of INFILL_DENSITY.
-
const std::string INFILL_EXTRUSION_WIDTH = "infill_extrusion_width"#
Slicer infill extrusion width in mm.
-
constexpr Attribute::ReturnType INFILL_EXTRUSION_WIDTH_TYPE = Attribute::ReturnType::dbl#
ReturnType of INFILL_EXTRUSION_WIDTH.
-
const std::string INFILL_SPEED = "infill_speed"#
Slicer infill speed in mm/s.
-
constexpr Attribute::ReturnType INFILL_SPEED_TYPE = Attribute::ReturnType::dbl#
ReturnType of INFILL_SPEED.
-
const std::string INTENSITY = "intensity"#
Image or signal intensity, a scalar.
-
constexpr Attribute::ReturnType INTENSITY_TYPE = Attribute::ReturnType::dbl#
ReturnType of INTENSITY.
-
const std::string IRONING_FLOWRATE = "ironing_flowrate"#
Slicer ironing flow rate in percent.
-
constexpr Attribute::ReturnType IRONING_FLOWRATE_TYPE = Attribute::ReturnType::dbl#
ReturnType of IRONING_FLOWRATE.
-
const std::string IRONING_SPEED = "ironing_speed"#
Slicer ironing speed in mm/s.
-
constexpr Attribute::ReturnType IRONING_SPEED_TYPE = Attribute::ReturnType::dbl#
ReturnType of IRONING_SPEED.
-
const std::string LAYER_HEIGHT = "layer_height"#
Slicer layer height in mm.
-
constexpr Attribute::ReturnType LAYER_HEIGHT_TYPE = Attribute::ReturnType::dbl#
ReturnType of LAYER_HEIGHT.
-
const std::string MODULUS = "modulus"#
Elastic (Young’s) modulus, a scalar.
-
constexpr Attribute::ReturnType MODULUS_TYPE = Attribute::ReturnType::dbl#
ReturnType of MODULUS.
-
const std::string NONE = "none"#
Placeholder name meaning “no attribute”.
-
constexpr Attribute::ReturnType NONE_TYPE = Attribute::ReturnType::none#
ReturnType of NONE.
-
const std::string PERIMETER_EXTRUSION_WIDTH = "perimeter_extrusion_width"#
Slicer perimeter extrusion width in mm.
-
constexpr Attribute::ReturnType PERIMETER_EXTRUSION_WIDTH_TYPE = Attribute::ReturnType::dbl#
ReturnType of PERIMETER_EXTRUSION_WIDTH.
-
const std::string PERIMETER_SPEED = "perimeter_speed"#
Slicer perimeter speed in mm/s.
-
constexpr Attribute::ReturnType PERIMETER_SPEED_TYPE = Attribute::ReturnType::dbl#
ReturnType of PERIMETER_SPEED.
-
const std::string PERIMETERS = "perimeters"#
Slicer perimeter count (stored as a float, rounded when exported).
-
constexpr Attribute::ReturnType PERIMETERS_TYPE = Attribute::ReturnType::dbl#
ReturnType of PERIMETERS.
-
const std::string POISSONS_RATIO = "poissons_ratio"#
Poisson’s ratio, a scalar.
-
constexpr Attribute::ReturnType POISSONS_RATIO_TYPE = Attribute::ReturnType::dbl#
ReturnType of POISSONS_RATIO.
-
const std::string SHORE_HARDNESS = "shore_hardness"#
Shore hardness, a scalar.
-
constexpr Attribute::ReturnType SHORE_HARDNESS_TYPE = Attribute::ReturnType::dbl#
ReturnType of SHORE_HARDNESS.
-
const std::string SMALL_PERIMETER_SPEED = "small_perimeter_speed"#
Slicer small perimeter speed in mm/s.
-
constexpr Attribute::ReturnType SMALL_PERIMETER_SPEED_TYPE = Attribute::ReturnType::dbl#
ReturnType of SMALL_PERIMETER_SPEED.
-
const std::string SOLID_INFILL_EXTRUSION_WIDTH = "solid_infill_extrusion_width"#
Slicer solid infill extrusion width in mm.
-
constexpr Attribute::ReturnType SOLID_INFILL_EXTRUSION_WIDTH_TYPE = Attribute::ReturnType::dbl#
ReturnType of SOLID_INFILL_EXTRUSION_WIDTH.
-
const std::string SOLID_INFILL_SPEED = "solid_infill_speed"#
Slicer solid infill speed in mm/s.
-
constexpr Attribute::ReturnType SOLID_INFILL_SPEED_TYPE = Attribute::ReturnType::dbl#
ReturnType of SOLID_INFILL_SPEED.
-
const std::string SUPPORT_MATERIAL_EXTRUSION_WIDTH = "support_material_extrusion_width"#
Slicer support material extrusion width in mm.
-
constexpr Attribute::ReturnType SUPPORT_MATERIAL_EXTRUSION_WIDTH_TYPE = Attribute::ReturnType::dbl#
ReturnType of SUPPORT_MATERIAL_EXTRUSION_WIDTH.
-
const std::string TEMPERATURE = "temperature"#
Temperature, a scalar (slicer compilers use it as the nozzle temperature in degrees C).
-
constexpr Attribute::ReturnType TEMPERATURE_TYPE = Attribute::ReturnType::dbl#
ReturnType of TEMPERATURE.
-
const std::string TOP_INFILL_EXTRUSION_WIDTH = "top_infill_extrusion_width"#
Slicer top infill extrusion width in mm.
-
constexpr Attribute::ReturnType TOP_INFILL_EXTRUSION_WIDTH_TYPE = Attribute::ReturnType::dbl#
ReturnType of TOP_INFILL_EXTRUSION_WIDTH.
-
const std::string TOP_SOLID_INFILL_SPEED = "top_solid_infill_speed"#
Slicer top solid infill speed in mm/s.
-
constexpr Attribute::ReturnType TOP_SOLID_INFILL_SPEED_TYPE = Attribute::ReturnType::dbl#
ReturnType of TOP_SOLID_INFILL_SPEED.
-
const std::string TOP_SOLID_LAYERS = "top_solid_layers"#
Slicer number of solid layers under a top surface (stored as a float, rounded when exported).
-
constexpr Attribute::ReturnType TOP_SOLID_LAYERS_TYPE = Attribute::ReturnType::dbl#
ReturnType of TOP_SOLID_LAYERS.
-
const std::string TOP_SOLID_MIN_THICKNESS = "top_solid_min_thickness"#
Slicer least thickness of the solid layers under a top surface in mm.
-
constexpr Attribute::ReturnType TOP_SOLID_MIN_THICKNESS_TYPE = Attribute::ReturnType::dbl#
ReturnType of TOP_SOLID_MIN_THICKNESS.
-
const std::string TOUGHNESS = "toughness"#
Material toughness, a scalar.
-
constexpr Attribute::ReturnType TOUGHNESS_TYPE = Attribute::ReturnType::dbl#
ReturnType of TOUGHNESS.
-
constexpr Attribute::ReturnType TOUGHNSS_TYPE = TOUGHNESS_TYPE#
- Deprecated:
Misspelled alias of TOUGHNESS_TYPE, kept so existing code still compiles.
-
const std::string VOLUME_FRACTIONS = "volume_fractions"#
Per-material volume fractions, a material id to fraction map.
-
constexpr Attribute::ReturnType VOLUME_FRACTIONS_TYPE = Attribute::ReturnType::vfm_ptr#
ReturnType of VOLUME_FRACTIONS.
-
inline Attribute::ReturnType get_return_type_by_name(const std::string &name)#
-
class FloatAttribute : public Attribute#
- #include <float_attribute.h>
A scalar attribute defined by an expression, native function, constant or float volume.
The source is set once, by a constructor or by one of the setters. The setters are one-shot: set_expression(), set_function() and set_value() throw std::runtime_error if any source (expression, function, constant or volume) is already set. A default-constructed attribute has no source until a setter is called. Subclasses such as DerivedFloatAttribute and NoiseFloatAttribute override sample() and the bound queries.
Subclassed by CellMapGuardedAttribute, ComponentScalarAttribute, CoordinateFieldAttribute, CurvatureAttribute, DerivedFloatAttribute, DistanceFieldAttribute, NoiseFloatAttribute, ScatteredFloatAttribute
Public Types
-
typedef std::function<double(double x, double y, double z, double d)> FloatFunction#
A function for spatial grading.
The function takes the spatial coordinates (x, y, z) and the signed distance to the surface and returns a floating point value for some attribute.
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
inline std::optional<double> constant_value() const#
Returns the value when the attribute is a constant (built from a double or set_value()).
- Returns:
The constant, or std::nullopt for expressions, functions and volumes.
-
FloatAttribute() = default#
Default constructor. The attribute has no source until a setter is called.
-
FloatAttribute(const FloatFunction &function)#
Constructor that takes a native function.
Note
The function MUST be thread-safe as it may be called from multiple threads simultaneously
- Parameters:
function – A native function that represents the attribute
Constructor that takes a VDB volume to sample the attribute from.
- Parameters:
volume – A shared pointer to a FloatVDBVolume to sample the attribute from
-
FloatAttribute(const std::string &expression)#
Constructor that takes a math expression string.
Note
The math expression can use the following variables for spatial grading: x, y, z, rho, phic, r, theta, phis, d (signed distance) For more documentation on the math expression syntax, see the Exprtk documentation: ArashPartow/exprtk
- Parameters:
expression – A math expression that represents the attribute
-
FloatAttribute(double value)#
Constructor that takes a constant value (no spatial grading).
- Parameters:
value – The constant value for the attribute
-
bool is_volume_backed() const#
Returns true when this attribute samples from a VDB volume.
- Returns:
True for a volume-backed attribute.
-
virtual std::optional<double> lipschitz_bound() const#
Returns a known upper bound L on the field’s slope, |f(p) - f(q)| <= L |p - q|, or std::nullopt.
Known by construction, never estimated by sampling. A constant has L = 0. ScalarParameter adopts it, so operators can keep a distance bound (see ScalarParameter::lipschitz()).
- Returns:
The slope bound L, or std::nullopt when it is unknown.
-
virtual ReturnType return_type() override#
Retrieves the return type of the attribute.
- Returns:
The ReturnType enum value indicating the actual type stored in the Value variant.
-
inline virtual Value sample(const AttributeSampleContext &context)#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
-
void set_expression(const std::string &expression)#
Sets the math expression for the attribute.
- Parameters:
expression – The math expression that represents the attribute
- Throws:
std::runtime_error – If a source is already set, or if the expression fails to compile.
-
void set_function(const FloatFunction &function)#
Sets the native function for the attribute.
Note
The function MUST be thread-safe as it may be called from multiple threads simultaneously
- Parameters:
function – A native function that represents the attribute
- Throws:
std::runtime_error – If a source is already set.
-
void set_value(double value)#
Sets the constant value for the attribute (no spatial grading).
- Parameters:
value – The constant value for the attribute
- Throws:
std::runtime_error – If a source is already set.
Sets the attribute to be sampled from a VDB volume.
The signed distance is ignored; the volume is sampled at (x, y, z).
- Parameters:
volume – A shared pointer to a FloatVDBVolume to sample the attribute from
- Throws:
std::runtime_error – If an expression, function, value or volume is already set.
-
virtual std::optional<std::pair<double, double>> value_bounds() const#
Returns the range of values this field is known to stay in, or std::nullopt.
Known by construction, never estimated by sampling. A constant knows its value; fields that know their range (noise, clamp(), ease(), transfer(), …) override this. ScalarParameter adopts it, so such a field can size an operator’s bounding box.
- Returns:
The (minimum, maximum) pair, or std::nullopt when the range is unknown.
-
std::string volume_type_name() const#
Returns the Mermaid display type for the backing volume, if any.
- Returns:
“FloatVDBVolume” for a volume-backed attribute, otherwise an empty string.
-
typedef std::function<double(double x, double y, double z, double d)> FloatFunction#
-
class Vec3Attribute : public Attribute#
- #include <vec3_attribute.h>
An attribute that stores a function for spatial grading that returns a vec3.
This class can be used to create any spatially varying 3-component attribute. When used for representing color, the vec3 values should be in the range [0, 1].
Subclassed by CellMapCoordinateAttribute, CellMapJacobianAttribute, CellMapWorldDirectionAttribute, ComponentDirectionAttribute, DerivedVec3Attribute, NoiseVec3Attribute, NormalFieldAttribute, ScatteredVec3Attribute
Public Types
-
typedef std::function<double(double x, double y, double z, double d)> ComponentFunction#
A function for spatial grading of a single component.
-
typedef std::function<glm::vec3(double x, double y, double z, double d)> Vec3Function#
A function for spatial grading that returns a vec3 value.
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
bool is_volume_backed() const#
Returns true when this attribute samples from a VDB volume.
- Returns:
True for a volume-backed attribute.
-
virtual ReturnType return_type() override#
Retrieves the return type of the attribute.
- Returns:
The ReturnType enum value indicating the actual type stored in the Value variant.
-
inline virtual Value sample(const AttributeSampleContext &context)#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
-
void set_expression(const std::string &x_expression, const std::string &y_expression, const std::string &z_expression)#
Sets the math expressions for the attribute.
- Parameters:
x_expression – Expression for the x component.
y_expression – Expression for the y component.
z_expression – Expression for the z component.
-
void set_function(const ComponentFunction &x_function, const ComponentFunction &y_function, const ComponentFunction &z_function)#
Sets the native component functions for the attribute.
-
void set_function(const Vec3Function &function)#
Sets the native vec3 function for the attribute.
- Parameters:
function – Function that returns a vec3.
-
void set_value(double x, double y, double z)#
Sets constant values for the attribute.
Sets the attribute to be sampled from a VDB volume.
- Parameters:
volume – A shared pointer to a Vec3sVDBVolume to sample from.
-
Vec3Attribute() = default#
Default constructor.
-
Vec3Attribute(const ComponentFunction &x_function, const ComponentFunction &y_function, const ComponentFunction &z_function)#
Constructor that takes native component functions.
Constructor that samples from a Vec3S VDB volume.
- Parameters:
volume – Volume to sample.
-
Vec3Attribute(const std::string &x_expression, const std::string &y_expression, const std::string &z_expression)#
Constructor that takes math expression strings for each component.
- Parameters:
x_expression – Expression for the x component.
y_expression – Expression for the y component.
z_expression – Expression for the z component.
-
Vec3Attribute(const Vec3Function &function)#
Constructor that takes a native vec3 function.
- Parameters:
function – A function that returns a vec3.
-
Vec3Attribute(double x, double y, double z)#
Constructor that takes constant values for each component.
-
std::string volume_type_name() const#
Returns the Mermaid display type for the backing volume, if any.
- Returns:
“Vec3sVDBVolume” for a volume-backed attribute, otherwise an empty string.
Private Functions
-
ComponentFunction compile_expression(const std::string &expression)#
Compiles a math expression string into a native function.
- Parameters:
expression – The math expression string.
- Returns:
A native function that evaluates the expression.
Private Members
-
uint8_t m_mode = 0#
-
double m_phic#
-
double m_phis#
-
double m_r#
-
double m_rho#
-
double m_signed_distance#
-
double m_theta#
-
Vec3Function m_vec3_function#
-
std::shared_ptr<Vec3sVDBVolume> m_volume#
-
double m_x#
-
std::string m_x_expression#
-
ComponentFunction m_x_function#
-
double m_y#
-
std::string m_y_expression#
-
ComponentFunction m_y_function#
-
double m_z#
-
std::string m_z_expression#
-
ComponentFunction m_z_function#
-
typedef std::function<double(double x, double y, double z, double d)> ComponentFunction#
-
class ScalarParameter#
- #include <scalar_parameter.h>
A geometry parameter that is either a constant or a spatially varying scalar field.
Operators whose parameters may vary in space (offset distance, shell thickness, blend radius, tube radius, twist rate) store one of these instead of a double. A constant takes a fast path with no virtual call. A field is any FloatAttribute, sampled with value(x, y, z, d). A FloatAttribute built from a double is detected and treated as a constant.
Optional hints describe a field where they are known:
bounds(): the smallest and largest value the field takes, used to size bounding boxes. Constants always know their bounds.
lipschitz(): an upper bound L on the field’s slope, |t(p) - t(q)| <= L |p - q|. An operator that subtracts the field from a distance (f - t) can divide by 1 + L to keep a safe distance bound. Constants have L = 0. A field that knows its range or slope by construction (FloatAttribute::value_bounds() and lipschitz_bound(), for example noise, clamp() or ease()) supplies them itself; the caller’s with_bounds() and with_lipschitz() override them. Nothing is estimated by sampling.
The value is copyable and cheap to copy; copies share the field. Nodes call clone() in their own clone() so each evaluation thread gets its own field, the same way they clone FloatAttribute members today.
Public Functions
-
std::shared_ptr<FloatAttribute> as_attribute() const#
Returns the parameter as a FloatAttribute, wrapping a constant when needed.
- Returns:
The field, or a constant FloatAttribute.
-
std::optional<std::pair<double, double>> bounds() const#
Returns the known bounds (minimum, maximum), or std::nullopt when unknown.
- Returns:
The bounds, or std::nullopt.
-
ScalarParameter clone() const#
Returns a copy whose field is deep-cloned, for use in Node::clone().
- Returns:
The copy.
-
double constant() const#
Returns the constant value.
- Throws:
std::runtime_error – if the parameter is a field.
- Returns:
The constant.
-
std::string description() const#
Short display text for Node::properties(): the constant, “volume” or “field”.
- Returns:
The display text.
-
inline std::shared_ptr<FloatAttribute> field() const#
Returns the field, or nullptr for a parameter built from a double.
- Returns:
The field, or nullptr.
-
inline bool is_constant() const#
Returns true when the parameter is a constant.
- Returns:
True for a constant, false for a field.
-
std::optional<double> lipschitz() const#
Returns the known Lipschitz bound (0 for constants), or std::nullopt when unknown.
- Returns:
The Lipschitz bound, or std::nullopt.
-
std::optional<double> max_magnitude() const#
Returns the largest |value| when the bounds are known.
- Returns:
The largest magnitude, or std::nullopt when the bounds are unknown.
-
ScalarParameter() = default#
Constructs the constant zero.
Constructs a field parameter.
- Parameters:
field – The scalar field. A FloatAttribute holding a constant becomes a constant parameter. The field’s own value_bounds() and lipschitz_bound() become the hints.
- Throws:
std::runtime_error – if field is null.
Constructs a field parameter with known bounds.
- Parameters:
field – The scalar field.
minimum – The smallest value the field takes.
maximum – The largest value the field takes.
- Throws:
std::runtime_error – if field is null or the bounds are not finite and ordered.
-
ScalarParameter(double value)#
Constructs a constant parameter.
- Parameters:
value – The constant value.
-
double value(const AttributeSampleContext &context) const#
Evaluates the parameter with mapped-lattice sample context.
- Parameters:
context – The sample context; context.position is the point.
- Returns:
The value at the point.
-
inline double value(double x, double y, double z, double d = 0.0) const#
Evaluates the parameter at a point.
- Parameters:
x – The x-coordinate.
y – The y-coordinate.
z – The z-coordinate.
d – The signed distance passed to the field (fields may ignore it).
- Throws:
std::runtime_error – if the field does not return a scalar.
- Returns:
The value at the point.
-
ScalarParameter with_bounds(double minimum, double maximum) const#
Returns a copy with known bounds.
- Parameters:
minimum – The smallest value the parameter takes.
maximum – The largest value the parameter takes.
- Throws:
std::runtime_error – if the bounds are not finite and ordered, or the parameter is a constant outside them.
- Returns:
The copy.
-
ScalarParameter with_lipschitz(double lipschitz) const#
Returns a copy with a known Lipschitz bound.
- Parameters:
lipschitz – The slope bound, non-negative and finite.
- Throws:
std::runtime_error – if lipschitz is negative or not finite.
- Returns:
The copy.
Public Static Functions
-
static std::string format_number(double value)#
Formats a number in the compact form used by node properties (six significant digits).
- Parameters:
value – The number.
- Returns:
The formatted text.
Private Functions
-
double sample_field(double x, double y, double z, double d) const#
-
class Vec4Attribute : public Attribute#
- #include <vec4_attribute.h>
An attribute that stores a function for spatial grading that returns a vec4.
Note
This class can be used to create an attribute for any vec4 value that can be spatially graded.
Note
When used for representing color, the vec4 values should be in the range [0, 1].
Public Types
-
typedef std::function<double(double x, double y, double z, double d)> ComponentFunction#
A function for spatial grading of a single component.
The function takes the spatial coordinates (x, y, z) and the signed distance to the surface and returns a floating point value.
-
typedef std::function<glm::vec4(double x, double y, double z, double d)> Vec4Function#
A function for spatial grading.
The function takes the spatial coordinates (x, y, z) and the signed distance to the surface and returns a glm::vec4 value.
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
bool is_volume_backed() const#
Returns true when this attribute samples from a VDB volume.
- Returns:
True for a volume-backed attribute.
-
virtual ReturnType return_type() override#
Retrieves the return type of the attribute.
- Returns:
The ReturnType enum value indicating the actual type stored in the Value variant.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
-
void set_expression(const std::string &r_expression, const std::string &g_expression, const std::string &b_expression, const std::string &a_expression)#
Sets the math expressions for the attribute.
- Parameters:
r_expression – The math expression for the x (red) component
g_expression – The math expression for the y (green) component
b_expression – The math expression for the z (blue) component
a_expression – The math expression for the w (alpha) component
-
void set_function(const ComponentFunction &r_function, const ComponentFunction &g_function, const ComponentFunction &b_function, const ComponentFunction &a_function)#
Sets the native functions for the attribute.
- Parameters:
r_function – A native function for the x (red) component
g_function – A native function for the y (green) component
b_function – A native function for the z (blue) component
a_function – A native function for the w (alpha) component
-
void set_function(const Vec4Function &function)#
Sets the native function for the attribute.
- Parameters:
function – A native function that returns a vec4
-
void set_value(double r, double g, double b, double a)#
Sets the constant values for the attribute (no spatial grading).
- Parameters:
r – The constant value for the x (red) component
g – The constant value for the y (green) component
b – The constant value for the z (blue) component
a – The constant value for the w (alpha) component
Sets the attribute to be sampled from a VDB volume.
- Parameters:
volume – A shared pointer to a Vec4sVDBVolume to sample from.
-
Vec4Attribute() = default#
Default constructor.
-
Vec4Attribute(const ComponentFunction &r_function, const ComponentFunction &g_function, const ComponentFunction &b_function, const ComponentFunction &a_function)#
Constructor that takes native functions for each component.
- Parameters:
r_function – A native function for the x (red) component
g_function – A native function for the y (green) component
b_function – A native function for the z (blue) component
a_function – A native function for the w (alpha) component
Constructor that samples from a Vec4s VDB volume.
- Parameters:
volume – Volume to sample.
-
Vec4Attribute(const std::string &r_expression, const std::string &g_expression, const std::string &b_expression, const std::string &a_expression)#
Constructor that takes math expression strings for each component.
- Parameters:
r_expression – The math expression for the x (red) component
g_expression – The math expression for the y (green) component
b_expression – The math expression for the z (blue) component
a_expression – The math expression for the w (alpha) component
-
Vec4Attribute(const Vec4Function &function)#
Constructor that takes a native function for the vec4.
- Parameters:
function – A native function that returns a vec4
-
Vec4Attribute(double r, double g, double b, double a)#
Constructor that takes constant values for each component (no spatial grading).
- Parameters:
r – The constant value for the x (red) component
g – The constant value for the y (green) component
b – The constant value for the z (blue) component
a – The constant value for the w (alpha) component
-
std::string volume_type_name() const#
Returns the Mermaid display type for the backing volume, if any.
- Returns:
“Vec4sVDBVolume” for a volume-backed attribute, otherwise an empty string.
Private Functions
-
ComponentFunction compile_expression(const std::string &expression)#
Compiles a math expression string into a native function.
Note
This function uses the Exprtk library to compile the math expression string into a native function
Note
These native functions do not update the spatial grading variables (x, y, z, etc.), instead a parent function does do once
- Parameters:
expression – The math expression string
- Returns:
A native function that represents the math expression
Private Members
-
std::string m_a_expression#
-
ComponentFunction m_a_function#
-
std::string m_b_expression#
-
ComponentFunction m_b_function#
-
std::string m_g_expression#
-
ComponentFunction m_g_function#
-
uint8_t m_mode = 0#
-
double m_phic#
-
double m_phis#
-
Vec4Function m_quad_color_function#
The actual function we will use for the attribute sampling.
This function returns a vec4 color based on the spatial coordinates (x, y, z) and the signed distance to the surface
-
double m_r#
-
std::string m_r_expression#
-
ComponentFunction m_r_function#
-
double m_rho#
-
double m_signed_distance#
-
double m_theta#
-
std::shared_ptr<Vec4sVDBVolume> m_volume#
-
double m_x#
-
double m_y#
-
double m_z#
-
typedef std::function<double(double x, double y, double z, double d)> ComponentFunction#
-
class VolumeFractionsAttribute : public Attribute#
- #include <volume_fractions_attribute.h>
An attribute that stores a set of volume fraction (functions) for different materials.
The attribute contains a spatially graded function for each material. The attribute can be sampled at a point to get the volume fractions for each material. The attribute can be used to create a material distribution for a point in space. Sampled fractions are returned exactly as the functions evaluate; they are not clamped or normalized to sum to 1. Each material may be added only once.
Note
Functions in this class can be defined as math expressions or as native (lambda) functions.
Note
If using the math expression strings, you can use the following variables in the expression to spatially grade: x, y, z, rho, phic, r, theta, phis, d (signed distance) For more documentation on the math expression syntax, see the Exprtk documentation: ArashPartow/exprtk
Public Types
-
typedef std::function<double(double x, double y, double z, double d)> VolumeFunction#
A function for spatial grading.
The function takes the spatial coordinates (x, y, z) and the signed distance to the surface and returns the volume fraction for the material.
Public Functions
Adds a scalar field as the volume fraction of a material.
Any FloatAttribute works: noise, a distance field, a ramp shaped with ease() or transfer(), a scattered-point field. clone() deep-clones the field, so every thread samples its own copy.
- Parameters:
attribute – The field giving the material’s fraction.
material – The material that the field represents.
- Throws:
std::invalid_argument – if the field is null or the material is already in use.
-
void add_expression(const std::pair<std::string, uint8_t> &expression_material_pair)#
Adds an expression (string math expression)/material pair to the attribute.
- Parameters:
expression_material_pair – A pair where the first element is the math expression and the second element is the material
-
void add_expression(const std::string &expression, uint8_t material)#
Adds an expression (string math expression) to the attribute.
- Parameters:
expression – The math expression that represents the volume fraction for the material
material – The material that the expression represents
- Throws:
std::invalid_argument – If the material is already in use.
std::runtime_error – If the expression fails to compile.
-
void add_function(const std::pair<VolumeFunction, uint8_t> &function_material_pair)#
Adds a function (native/ lambda)/material pair to the attribute.
- Parameters:
function_material_pair – A pair where the first element is the function and the second element is the material
-
void add_function(const VolumeFunction &function, uint8_t material)#
Adds a function (native/ lambda) to the attribute for a material.
- Parameters:
function – The function that represents the volume fraction for the material
material – The material that the function represents
- Throws:
std::invalid_argument – If the material is already in use.
-
void add_value(double value, uint8_t material)#
Adds a constant value to the attribute for a material (no spatial grading).
- Parameters:
value – The constant value for the material
material – The material that the value represents
- Throws:
std::invalid_argument – If the material is already in use.
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
virtual ReturnType return_type() override#
Retrieves the return type of the attribute.
- Returns:
The ReturnType enum value indicating the actual type stored in the Value variant.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
-
VolumeFractionsAttribute()#
Default constructor. The attribute holds no materials until some are added.
-
VolumeFractionsAttribute(const std::vector<double> &values, const std::vector<uint8_t> &materials)#
Constructor that takes a list of constant values and materials (no spatial grading).
Note
The number of values must match the number of materials. They are paired by index.
- Parameters:
values – A list of constant values for each material
materials – A list of materials that correspond to the values
-
VolumeFractionsAttribute(const std::vector<std::pair<double, uint8_t>> &value_material_pairs)#
Constructor that takes a list of value/material pairs (no spatial grading).
- Parameters:
value_material_pairs – A list of pairs where the first element is the value and the second element is the material
-
VolumeFractionsAttribute(const std::vector<std::pair<std::string, uint8_t>> &expression_material_pairs)#
Constructor that takes a list of expression/material pairs.
- Parameters:
expression_material_pairs – A list of pairs where the first element is the math expression and the second element is the material
-
VolumeFractionsAttribute(const std::vector<std::pair<VolumeFunction, uint8_t>> &function_material_pairs)#
Constructor that takes a list of function/material pairs.
- Parameters:
function_material_pairs – A list of pairs where the first element is the function and the second element is the material
-
VolumeFractionsAttribute(const std::vector<std::string> &expressions, const std::vector<uint8_t> &materials)#
Constructor that takes a list of expressions (string math expressions) and materials.
Note
The number of expressions must match the number of materials. They are paired by index.
- Parameters:
expressions – A list of math expressions that represent the volume fraction for each material
materials – A list of materials that correspond to the expressions
-
VolumeFractionsAttribute(const std::vector<VolumeFunction> &functions, const std::vector<uint8_t> &materials)#
Constructor that takes a list of functions (native/ lambdas) and materials.
Note
The number of functions must match the number of materials. They are paired by index.
- Parameters:
functions – A list of functions that represent the volume fraction for each material
materials – A list of materials that correspond to the functions
Public Static Functions
-
static VolumeFractionMapPtr GetValue(std::unordered_map<std::string, Attribute::Value> &attribute_samples)#
Extract the volume fractions map from a set of sampled attributes.
- Parameters:
attribute_samples – A map of all attribute samples retrieved at a given point.
- Throws:
std::runtime_error – If the map has no DefaultAttributes::VOLUME_FRACTIONS entry.
boost::bad_get – If that entry is not a volume-fraction map.
- Returns:
A shared pointer to the VolumeFractionMap stored under DefaultAttributes::VOLUME_FRACTIONS.
-
static VolumeFractionMapPtr mix_samples(const VolumeFractionMapPtr &left, const VolumeFractionMapPtr &right, double weight)#
Interpolate two sampled volume-fraction maps and renormalize the result.
- Parameters:
left – Fractions from the left side of a mix.
right – Fractions from the right side of a mix.
weight – Clamped right-side contribution in [0, 1].
- Returns:
A new normalized map containing the union of material IDs.
Private Members
-
std::unordered_map<uint8_t, std::string> m_expression_strings#
-
std::unordered_map<uint8_t, std::shared_ptr<FloatAttribute>> m_field_attributes#
-
double m_phic#
-
double m_phis#
-
double m_r#
-
double m_rho#
-
double m_signed_distance#
-
double m_theta#
-
std::unordered_map<uint8_t, VolumeFunction> m_volume_functions#
-
double m_x#
-
double m_y#
-
double m_z#
-
typedef std::function<double(double x, double y, double z, double d)> VolumeFunction#
Functions
Returns a DerivedFloatAttribute that applies a binary scalar operation.
- Parameters:
operation – add, subtract, multiply, divide or power.
left – The first operand.
right – The second operand.
- Returns:
The derived attribute.
Returns operand clamped to [0, 1] and eased (DerivedFloatAttribute::Operation::ease).
- Parameters:
operand – The input field, usually normalized to [0, 1].
easing – The easing curve.
shape – The exponent of power or the rate of exponential; std::nullopt for the default.
- Returns:
The derived attribute.
Returns operand mapped through a transfer curve (DerivedFloatAttribute::Operation::transfer).
- Parameters:
operand – The input field.
points – Control points (input, output); at least two, with distinct inputs.
interpolation – Linear, or smooth (monotone cubic, no overshoot).
- Returns:
The derived attribute.
Returns a DerivedFloatAttribute that applies a one-input scalar operation.
- Parameters:
operation – The operation, for example negate, clamp, normalize, map_range or fallback.
operand – The input field.
parameters – The operation’s parameters (see DerivedFloatAttribute::Operation).
- Returns:
The derived attribute.
Returns the normalized inverse-distance weight of one of several distance fields (DerivedFloatAttribute::Operation::inverse_distance_weight).
- Parameters:
distances – The distance fields, one per seed or body.
index – Which field’s weight to return.
exponent – The power p, positive.
- Returns:
The derived attribute.
Returns a DerivedVec3Attribute that applies a binary vector operation.
- Parameters:
operation – add, subtract (Vec3 right operand), multiply or divide (scalar right operand).
left – The vector operand.
right – The second operand.
- Returns:
The derived attribute.
Returns a scalar DerivedFloatAttribute computed from one or two vector fields.
- Parameters:
operation – vector_component, vector_magnitude, vector_dot or vector_angle.
left – The first vector field.
right – The second vector field for two-input operations, otherwise nullptr.
parameters – The operation’s parameters (see DerivedFloatAttribute::Operation).
- Returns:
The derived attribute.
Returns a DerivedVec3Attribute that applies negate or normalize.
- Parameters:
operation – negate or normalize.
operand – The vector field.
- Returns:
The derived attribute.
-
class DerivedFloatAttribute : public FloatAttribute#
- #include <derived_attribute.h>
An immutable scalar attribute computed from other typed attributes.
Dependencies form an immutable graph and are sampled in the same consumer-relative coordinates as this attribute: in double precision through sample(x, y, z, d), and with the caller’s context through sample(context). clone() recursively clones the full dependency graph. map_range accepts input bounds in either order (they must differ) and extrapolates linearly. fallback returns its single parameter wherever the dependency throws or produces a non-finite value, for example outside a CellMap domain.
Shaping operations:
ease: parameters {easing, shape}. The input is clamped to [0, 1] and passed through an Easing curve (see easing.h), so the result stays in [0, 1].
transfer: parameters {interpolation, x0, y0, x1, y1, …}, interpolation 0 for linear and 1 for smooth. A PiecewiseCurve through the control points; it holds the end values beyond them.
Geometry operations:
vector_angle: two Vec3 inputs, parameter {degrees}: the angle between them, in degrees (1) or radians (0). 90 degrees where either vector is zero.
inverse_distance_weight: N scalar distance inputs, parameters {index, exponent p}: the normalized inverse-distance weight d_i^-p / sum_j d_j^-p of input
index, in [0, 1]. Distances are clamped at 0 (inside a body counts as on it); where some are 0, those inputs share the weight equally. With two body distances and index 1 this is the two-body field, 0 at the first body and 1 at the second; with point distances it is inverse-distance (Shepard) weighting.
value_bounds() and lipschitz_bound() carry the inputs’ known range and slope through the operations that allow it (sums, products, clamp, normalize, map_range, ease, transfer, …).
Public Types
-
enum class Operation#
The built-in operation. Dependencies and parameters are listed per value.
Values:
-
enumerator add#
Two scalars: a + b.
-
enumerator subtract#
Two scalars: a - b.
-
enumerator multiply#
Two scalars: a * b.
-
enumerator divide#
Two scalars: a / b.
Throws where b is 0.
-
enumerator power#
Two scalars: a ^ b.
-
enumerator negate#
One scalar: -a.
-
enumerator absolute#
One scalar: |a|.
-
enumerator clamp#
One scalar, parameters {minimum, maximum} (finite, minimum <= maximum).
-
enumerator normalize#
One scalar, parameters {minimum, maximum} (finite, minimum < maximum): unclamped (a - minimum) / (maximum - minimum).
-
enumerator map_range#
One scalar, parameters {in_min, in_max, out_min, out_max}; linear, extrapolates.
-
enumerator vector_component#
One Vec3, parameter {index 0, 1 or 2}.
-
enumerator vector_magnitude#
One Vec3: its length.
-
enumerator vector_dot#
Two Vec3s: their dot product.
-
enumerator named_expression#
Named scalar inputs combined by an ExprTk expression (named-input constructor only).
-
enumerator fallback#
One scalar, parameter {value}: value wherever the input throws or is not finite.
-
enumerator ease#
One scalar, parameters {easing, shape} (see the class details).
-
enumerator transfer#
One scalar, parameters {interpolation, x0, y0, x1, y1, …} (see the class details).
-
enumerator vector_angle#
Two Vec3s, parameter {degrees} (see the class details).
-
enumerator inverse_distance_weight#
N scalars, parameters {index, exponent} (see the class details).
-
enumerator add#
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
Construct a named multi-input scalar expression.
- Parameters:
expression – ExprTk expression using the supplied input names.
inputs – Named scalar attribute dependencies.
- Throws:
std::runtime_error – If a name is empty, an input is null or not scalar, or the expression fails to compile.
Construct one validated built-in scalar graph operation.
- Parameters:
operation – Operation to evaluate.
dependencies – Typed immutable dependencies.
parameters – Numeric operation parameters such as explicit bounds.
- Throws:
std::runtime_error – If operation is named_expression, or the dependency count or types or the parameters do not suit the operation.
-
virtual std::optional<double> lipschitz_bound() const override#
Returns a known upper bound L on the field’s slope, |f(p) - f(q)| <= L |p - q|, or std::nullopt.
Known by construction, never estimated by sampling. A constant has L = 0. ScalarParameter adopts it, so operators can keep a distance bound (see ScalarParameter::lipschitz()).
- Returns:
The slope bound L, or std::nullopt when it is unknown.
-
inline Operation operation() const#
Returns the operation.
- Returns:
The operation this attribute evaluates.
-
virtual Value sample(const AttributeSampleContext &context) override#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Throws:
std::runtime_error – If a dependency throws or is not finite (except under fallback), or the result is not finite.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual std::optional<std::pair<double, double>> value_bounds() const override#
Returns the range of values this field is known to stay in, or std::nullopt.
Known by construction, never estimated by sampling. A constant knows its value; fields that know their range (noise, clamp(), ease(), transfer(), …) override this. ScalarParameter adopts it, so such a field can size an operator’s bounding box.
- Returns:
The (minimum, maximum) pair, or std::nullopt when the range is unknown.
Private Functions
-
void compile_named_expression()#
-
template<typename Sampler>
double evaluate(const Sampler &sample_dependency)# Evaluates the operation; sample_dependency(attribute) samples one input.
-
void validate() const#
Private Members
-
std::shared_ptr<const PiecewiseCurve> m_curve#
-
std::shared_ptr<ExpressionEvaluator> m_evaluator#
-
std::string m_expression#
-
std::shared_ptr<std::mutex> m_expression_mutex#
-
std::vector<std::string> m_input_names#
-
std::vector<double> m_input_values#
-
std::vector<double> m_parameters#
-
class DerivedVec3Attribute : public Vec3Attribute#
- #include <derived_attribute.h>
An immutable vector attribute computed from vector and scalar dependencies.
Sampling throws std::runtime_error on division by zero, when normalizing a zero vector, or when the result is not finite.
Public Types
-
enum class Operation#
The built-in vector operation.
Values:
-
enumerator add#
Two Vec3s: a + b.
-
enumerator subtract#
Two Vec3s: a - b.
-
enumerator multiply#
A Vec3 and a scalar: a * s.
-
enumerator divide#
A Vec3 and a scalar: a / s.
-
enumerator negate#
One Vec3: -a.
-
enumerator normalize#
One Vec3: a / |a|.
-
enumerator add#
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
Construct one validated vector operation.
- Parameters:
operation – Operation to evaluate.
dependencies – Operands in order: one Vec3 for unary operations, otherwise a Vec3 followed by a Vec3 (add, subtract) or a scalar (multiply, divide).
- Throws:
std::runtime_error – If an operand is null or the count or types do not suit the operation.
-
virtual Value sample(const AttributeSampleContext &context) override#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
Private Functions
-
void validate() const#
-
enum class Operation#
Enums
-
enum class AttributeCoordinateSpace#
Coordinate values supplied as x, y, and z to a wrapped attribute.
Values:
-
enumerator node#
The consuming node’s Cartesian coordinates (no reframing).
-
enumerator map#
Normalized CellMap coordinates: logical coordinates divided by the cell counts, in [0, 1].
-
enumerator cell_index#
Integer index of the logical cell that contains the point.
-
enumerator cell#
Position inside the repeating unit cell, in [0, 1) per axis.
-
enumerator node#
Functions
-
AttributeCoordinateSpace attribute_coordinate_space(const std::string &coordinates)#
Parses a coordinate-space name.
- Parameters:
coordinates – One of “node”, “map”, “logical”, “cell_index” or “cell”.
- Throws:
std::runtime_error – If the name is not recognized.
- Returns:
The matching AttributeCoordinateSpace.
Returns a CellMapCoordinateAttribute in cell_index mode.
- Parameters:
cell_map – The CellMap.
- Returns:
The cell-index field.
Returns a CellMapCoordinateAttribute in logical_position mode.
- Parameters:
cell_map – The CellMap.
- Returns:
The logical-position field.
Returns a CellMapJacobianAttribute that converts vector into the map’s logical frame.
- Parameters:
cell_map – The CellMap.
vector – The Cartesian vector field.
- Returns:
The converted field.
Returns a CellMapWorldDirectionAttribute that converts a logical vector into world space.
- Parameters:
cell_map – The CellMap.
vector – The vector field in logical coordinates.
- Returns:
The converted field.
Returns a CellMapCoordinateAttribute in unit_cell_phase mode.
- Parameters:
cell_map – The CellMap.
- Returns:
The unit-cell phase field.
Returns attribute sampled in the given coordinate space.
- Parameters:
attribute – The attribute to wrap.
coordinates – The coordinate space.
cell_map – The CellMap that defines mapped coordinates, or nullptr.
- Returns:
attribute itself for node coordinates without a CellMap, otherwise a CoordinateReframedAttribute.
-
class CellMapCoordinateAttribute : public Vec3Attribute#
- #include <cell_map_attribute.h>
A vector source for logical position, unit-cell phase, or deterministic cell index.
Cartesian coordinates remain the default for ordinary attributes. This adapter explicitly converts the consuming node’s coordinates through one CellMap.
Public Types
Public Functions
Constructs a CellMap coordinate source.
- Parameters:
cell_map – The CellMap that maps world positions to logical coordinates.
mode – The coordinate to return.
- Throws:
std::runtime_error – If cell_map is null.
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
virtual Value sample(const AttributeSampleContext &context) override#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Throws:
std::runtime_error – If the point is outside the CellMap domain.
- Returns:
A Value variant containing the evaluated attribute at the point.
Private Functions
-
glm::vec3 evaluate(const AttributeSampleContext &context) const#
-
class CellMapJacobianAttribute : public Vec3Attribute#
- #include <cell_map_attribute.h>
Explicitly converts a raw Cartesian vector into a CellMap’s local logical frame.
Public Functions
Constructs a world-to-logical vector conversion (inverse Jacobian times vector).
- Parameters:
cell_map – The CellMap whose local frame is used.
vector – The Cartesian vector field to convert.
- Throws:
std::runtime_error – If either argument is null.
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
virtual Value sample(const AttributeSampleContext &context) override#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Throws:
std::runtime_error – If the point is outside the CellMap domain, the Jacobian is singular, or the vector or result is not finite.
- Returns:
A Value variant containing the evaluated attribute at the point.
Private Functions
-
glm::vec3 evaluate(const AttributeSampleContext &context) const#
-
class CellMapWorldDirectionAttribute : public Vec3Attribute#
- #include <cell_map_attribute.h>
Explicitly converts a vector expressed in logical map coordinates into world space.
Public Functions
Constructs a logical-to-world vector conversion (Jacobian times vector).
- Parameters:
cell_map – The CellMap whose local frame is used.
vector – The vector field expressed in logical coordinates.
- Throws:
std::runtime_error – If either argument is null.
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
virtual Value sample(const AttributeSampleContext &context) override#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Throws:
std::runtime_error – If the point is outside the CellMap domain or the vector or result is not finite.
- Returns:
A Value variant containing the evaluated attribute at the point.
Private Functions
-
glm::vec3 evaluate(const AttributeSampleContext &context) const#
-
class ComponentDirectionAttribute : public Vec3Attribute#
- #include <cell_map_attribute.h>
The selected mapped component’s world-space direction as a Vec3Attribute.
Returns AttributeSampleContext::component_direction (a unit strut direction or plate normal, zero when undefined). Plain samples throw std::runtime_error.
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
ComponentDirectionAttribute() = default#
Default constructor.
-
virtual Value sample(const AttributeSampleContext &context) override#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Throws:
std::runtime_error – If the context has no component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Always throws: the direction needs a mapped-component sample context.
- Parameters:
x – Unused.
y – Unused.
z – Unused.
d – Unused.
- Throws:
std::runtime_error – Always.
- Returns:
Never returns.
-
virtual std::shared_ptr<Attribute> clone() override#
-
class ComponentScalarAttribute : public FloatAttribute#
- #include <cell_map_attribute.h>
A scalar field sourced from mapped-component provenance.
It can only be sampled with an AttributeSampleContext from a mapped lattice that sets component_kind; plain samples throw std::runtime_error.
Public Types
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
explicit ComponentScalarAttribute(Field field)#
Constructs a component scalar attribute.
- Parameters:
field – The provenance field to return.
-
virtual Value sample(const AttributeSampleContext &context) override#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Throws:
std::runtime_error – If the context has no component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Always throws: component fields need a mapped-component sample context.
- Parameters:
x – Unused.
y – Unused.
z – Unused.
d – Unused.
- Throws:
std::runtime_error – Always.
- Returns:
Never returns.
-
virtual std::shared_ptr<Attribute> clone() override#
-
class CoordinateReframedAttribute : public Attribute#
- #include <cell_map_attribute.h>
Samples any attribute in node, normalized-map, logical, cell-index, or cell coordinates.
The wrapped attribute retains its return type. Reframing changes only the position supplied to the wrapped attribute; signed distance and returned vector bases are unchanged.
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
Wraps an attribute so it is sampled in another coordinate space.
- Parameters:
- Throws:
std::runtime_error – If attribute is null.
-
virtual ReturnType return_type() override#
Returns the wrapped attribute’s return type.
- Returns:
The ReturnType of the wrapped attribute.
-
virtual Value sample(const AttributeSampleContext &context) override#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Throws:
std::runtime_error – If the point is outside the CellMap domain, or a mapped space is requested without any CellMap.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual std::shared_ptr<Attribute> clone() override#
-
class CellMapGuardedAttribute : public FloatAttribute#
- #include <cell_map_guarded_attribute.h>
A scalar attribute defined everywhere: a fallback outside a CellMap’s active domain.
Each sample first locates the point in the CellMap. Outside the active domain the fallback is returned without evaluating the wrapped attribute; inside, the wrapped attribute is sampled with the located CellMap context, so CellMap coordinate adapters (logical position, cell index, phase) reuse the location instead of inverting the map again. Any other failure or a non-finite value also returns the fallback. This avoids the exception that CellMap adapters raise outside the domain, which matters when a field-driven Mix samples its weight over a whole bounding box.
Public Functions
-
inline const std::shared_ptr<FloatAttribute> &attribute() const#
Return the wrapped attribute.
- Returns:
The attribute sampled inside the domain.
-
inline const std::shared_ptr<CellMap> &cell_map() const#
Return the guarding CellMap.
- Returns:
The CellMap whose active domain is tested.
Construct a guarded scalar attribute.
- Parameters:
cell_map – Map whose active domain defines where attribute is evaluated.
attribute – Scalar attribute, typically built on the map’s coordinates.
fallback – Finite value returned outside the domain or on failure.
- Throws:
std::runtime_error – If cell_map or attribute is null, or fallback is not finite.
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
inline double fallback() const#
Return the fallback value.
- Returns:
The value used outside the domain or on failure.
-
virtual Value sample(const AttributeSampleContext &context) override#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
-
inline const std::shared_ptr<FloatAttribute> &attribute() const#
Functions
Returns a field for one of the CurveCoordinates of a curve (“distance”, “parameter”, “length” or “normalized_length”).
- Parameters:
curve – The curve.
name – The coordinate name.
- Throws:
std::runtime_error – If the curve is null or the name is unknown.
- Returns:
-
class CoordinateFieldAttribute : public FloatAttribute#
- #include <coordinate_field_attribute.h>
A scalar field that reads one named coordinate from a CoordinateSource.
For example, the arc length along a curve, the angle around a tube, or the height in an extrusion. The field is defined everywhere in space, not only inside the node it came from; inside the node it is the node’s own parametric coordinate. Use it like any other FloatAttribute: set it on a node, map it with map_range(), or pass it as a ScalarParameter.
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
Constructor.
- Parameters:
source – The coordinate source.
name – The coordinate name; one of source->coordinate_names().
- Throws:
std::runtime_error – if the source is null or the name is unknown.
-
inline const std::string &name() const#
Returns the coordinate name.
- Returns:
The name passed to the constructor.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
-
inline const std::shared_ptr<CoordinateSource> &source() const#
Returns the source.
- Returns:
The coordinate source.
-
virtual std::shared_ptr<Attribute> clone() override#
-
class CoordinateSource#
- #include <coordinate_field_attribute.h>
Something that assigns named coordinates to points of space.
Curves, the curve-based nodes (Tube, Extrude, Revolve, Sweep) and the deformation maps of Warp (WarpMap) describe space in their own coordinates: position along a curve, angle around it, position in a profile, where a point pulls back to under a warp. A CoordinateSource evaluates those coordinates at any point, so CoordinateFieldAttribute can turn each one into a field for grading material or driving other geometry.
Thread safety: coordinate() may keep per-call state in fields it samples, so every thread uses its own clone(). Sources share immutable geometry between clones and deep-clone any ScalarParameter fields.
Subclassed by CurveCoordinates, ExtrudeGeometry, LoftGeometry, RevolveGeometry, SweepGeometry, TubeGeometry, WarpMap
Public Functions
-
virtual std::shared_ptr<CoordinateSource> clone_source() const = 0#
Returns a copy for another thread.
- Returns:
The copy.
-
virtual double coordinate(size_t index, const glm::dvec3 &point) const = 0#
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.
-
size_t coordinate_index(const std::string &name) const#
Returns the index of a coordinate name.
- Parameters:
name – The coordinate name.
- Throws:
std::runtime_error – listing the valid names when the name is unknown.
- Returns:
The index of name in coordinate_names().
-
virtual const std::vector<std::string> &coordinate_names() const = 0#
Returns the names of the coordinates, in index order.
- Returns:
The coordinate names.
-
virtual ~CoordinateSource() = default#
Virtual destructor.
-
virtual std::shared_ptr<CoordinateSource> clone_source() const = 0#
-
class CurveCoordinates : public CoordinateSource#
- #include <coordinate_field_attribute.h>
The coordinates of space relative to a curve, through each point’s closest curve point.
Coordinates:
”distance”: distance to the curve (exact, to the curve’s closest-point accuracy);
”parameter”: curve parameter of the closest point;
”length”: arc length from the curve start to the closest point;
”normalized_length”: that length divided by the curve length, in [0, 1].
Public Functions
-
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.
Constructor.
- Parameters:
curve – The curve.
- Throws:
std::runtime_error – if the curve is null.
Functions
Returns a field that is 0 at the first body, 1 at the second, and grades smoothly between them.
The value is d1^p / (d1^p + d2^p), with d1 and d2 the distances to the two bodies (0 inside), built from two DistanceFieldAttributes and DerivedFloatAttribute’s inverse_distance_weight. p = 1 gives an even grade; larger p keeps values near 0 and 1 longer and makes the switch sharper midway. The range is [0, 1]. Choose a bandwidth at least as large as the gap between the bodies, so both distances are accurate where the field grades (see DistanceFieldAttribute).
- Parameters:
first – The body where the field is 0.
second – The body where the field is 1.
exponent – The power p, positive.
voxel_size – Voxel size in mm used to prepare the bodies.
bandwidth – Distance in mm around each body’s box where its distance is evaluated.
-
class DistanceFieldAttribute : public FloatAttribute#
- #include <distance_field_attribute.h>
A scalar attribute whose value is the distance to another body (a node), evaluated natively so it can drive grading through map_range(), clamp(), and other modifiers.
The body is any OpenVCAD node: a primitive, a Mesh, a CAD part, a boolean tree, or a mapped structure. The constructor clones the body and prepares the clone with the given voxel size and bandwidth, so the caller’s node is never modified. Each sample evaluates the prepared body’s signed distance at the sample position (the consuming node’s coordinates), negative inside the body. With signed_distance false the absolute value is returned, which measures distance to the body’s surface from either side.
Range: the value is as accurate as the body’s own field within its prepared bounding box expanded by the bandwidth (exact for analytic primitives, voxel-accurate for mesh SDFs, which also clamp to the bandwidth). Beyond that region the body has no value, and the attribute returns the distance to the expanded box plus the bandwidth, a lower bound that keeps grading monotone far away. Choose a bandwidth at least as large as the distances the grading uses (for example the liner thickness).
Thread safety: clone() clones the prepared body, so every cloned tree evaluates its own body copy. Units are millimetres.
Public Functions
-
inline double bandwidth() const#
Returns the bandwidth in mm around the body’s box where the field is evaluated.
- Returns:
The bandwidth.
-
inline const std::shared_ptr<Node> &body() const#
Returns the prepared body clone that is evaluated.
- Returns:
The body.
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
Builds a distance field to a body.
- Parameters:
body – The node to measure distance to; it is cloned and the clone is prepared.
voxel_size – Positive voxel size in mm used to prepare the body (mesh SDF resolution).
bandwidth – Positive distance in mm around the body’s box where the field is evaluated.
signed_distance – True for signed distance (negative inside), false for unsigned.
-
virtual Value sample(const AttributeSampleContext &context) override#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
-
inline bool signed_distance() const#
Returns whether the field is signed.
- Returns:
True for a signed field, false for an unsigned one.
Private Members
-
double m_bandwidth = 10.0#
-
glm::vec3 m_maximum = {0.0f}#
-
glm::vec3 m_minimum = {0.0f}#
-
bool m_signed = true#
-
struct Prepared#
-
inline double bandwidth() const#
-
class NoiseFloatAttribute : public FloatAttribute#
- #include <noise_attribute.h>
A scalar noise field: simplex (gradient) noise or cellular (Worley) distances, with fractal octaves.
The value depends only on the point and the NoiseSettings (see noise.h), so the same seed gives the same field on every platform and in every thread. Sampling keeps no state.
Range: simplex noise is in [-1, 1]; cellular F1 is in [0, sqrt(3)] and F2 and F2 - F1 in [0, 2 sqrt(3)], in cell units (typical values stay below about 1.2). value_bounds() reports these and lipschitz_bound() an analytic slope bound per mm, so the field can drive geometry (an offset, a shell thickness) without extra hints. Units: frequency is in features per mm.
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
virtual std::optional<double> lipschitz_bound() const override#
Returns a known upper bound L on the field’s slope, |f(p) - f(q)| <= L |p - q|, or std::nullopt.
Known by construction, never estimated by sampling. A constant has L = 0. ScalarParameter adopts it, so operators can keep a distance bound (see ScalarParameter::lipschitz()).
- Returns:
The slope bound L, or std::nullopt when it is unknown.
-
explicit NoiseFloatAttribute(const NoiseSettings &settings = NoiseSettings())#
Constructor.
- Parameters:
settings – The noise settings.
- Throws:
std::runtime_error – if the settings are invalid (see NoiseSettings::validate()).
-
inline virtual Value sample(const AttributeSampleContext &context)#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
-
inline const NoiseSettings &settings() const#
Returns the settings.
- Returns:
The noise settings.
-
virtual std::optional<std::pair<double, double>> value_bounds() const override#
Returns the range of values this field is known to stay in, or std::nullopt.
Known by construction, never estimated by sampling. A constant knows its value; fields that know their range (noise, clamp(), ease(), transfer(), …) override this. ScalarParameter adopts it, so such a field can size an operator’s bounding box.
- Returns:
The (minimum, maximum) pair, or std::nullopt when the range is unknown.
Private Members
-
NoiseSettings m_settings#
-
virtual std::shared_ptr<Attribute> clone() override#
-
class NoiseVec3Attribute : public Vec3Attribute#
- #include <noise_attribute.h>
A vector noise field: three unrelated scalar noise fields with the same settings, one per component.
Use it to displace material (Warp.displace) or to perturb directions. Each component has the range of the scalar noise of the same type. Deterministic and stateless, like NoiseFloatAttribute.
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
explicit NoiseVec3Attribute(const NoiseSettings &settings = NoiseSettings())#
Constructor.
- Parameters:
settings – The noise settings.
- Throws:
std::runtime_error – if the settings are invalid (see NoiseSettings::validate()).
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
-
inline const NoiseSettings &settings() const#
Returns the settings.
- Returns:
The noise settings.
Private Members
-
NoiseSettings m_settings#
-
virtual std::shared_ptr<Attribute> clone() override#
Functions
Returns the angle in degrees (or radians) between a body’s surface normal and a direction.
0 where the surface faces the direction, 90 where it is parallel to it, 180 where it faces away. For example, with the build direction +Z, downward-facing overhangs read near 180. Off the surface it is the angle of the closest surface point’s normal (see NormalFieldAttribute); 90 where the normal is undefined. Built as a NormalFieldAttribute and DerivedFloatAttribute vector_angle.
- Parameters:
body – The node.
direction – The direction; it need not be unit length but must not be zero.
voxel_size – Voxel size in mm used to prepare the body.
bandwidth – Distance in mm around the body’s box where its field is evaluated.
degrees – True for degrees in [0, 180], false for radians in [0, pi].
- Throws:
std::runtime_error – for a zero direction.
-
class NormalFieldAttribute : public Vec3Attribute#
- #include <normal_field_attribute.h>
A vector field: the unit surface normal of another body (a node), extended through space.
The value is the normalized gradient of the body’s signed distance, by central differences of a DistanceFieldAttribute this attribute owns (so the body is cloned and prepared once, exactly as for a distance field, and the caller’s node is never modified). The step is half the voxel size.
On the surface it is the outward normal. Off the surface it is the gradient at the point, which for an exact signed distance is the normal at the closest surface point, so the field is constant along each normal line. Where the gradient vanishes (on a medial axis, for example a sphere’s centre) it is the zero vector. Beyond the distance field’s band it follows the band’s lower-bound fallback, which points away from the body’s bounding box.
Use it to grade by orientation (dot or angle with a direction, see DerivedFloatAttribute::Operation::vector_angle) or to move material along normals. Thread safety: clone() clones the prepared body, as DistanceFieldAttribute does.
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
inline const std::shared_ptr<DistanceFieldAttribute> &distance() const#
Returns the signed distance field whose gradient is taken.
- Returns:
The distance field.
Builds the normal field of a body.
- Parameters:
body – The node; it is cloned and the clone is prepared.
voxel_size – Positive voxel size in mm used to prepare the body; the gradient step is half of it.
bandwidth – Positive distance in mm around the body’s box where its field is evaluated.
- Throws:
std::runtime_error – for a null body or a non-positive voxel size or bandwidth.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
-
inline double step() const#
Returns the central-difference step in mm.
- Returns:
The step.
-
virtual std::shared_ptr<Attribute> clone() override#
-
class CurvatureAttribute : public FloatAttribute#
- #include <curvature_attribute.h>
A scalar field: the curvature of another body’s surface (a node), in 1/mm.
The value comes from the gradient g and Hessian H of the body’s signed distance, taken by central differences (19 samples) of a DistanceFieldAttribute this attribute owns. The body is cloned and prepared once, as for a distance field; the caller’s node is not modified. The step is half the voxel size. On the surface it is the surface’s curvature; off the surface it is the curvature of the level set through the point (for an exact distance, that of the offset surface).
Kinds:
mean: (|g|^2 tr H - g^T H g) / (2 |g|^3), the average of the principal curvatures. Positive on convex skin (1/R on a sphere of radius R), negative in hollows, 0 on planes and saddles balanced between the two.
gaussian: g^T adj(H) g / |g|^4, the product of the principal curvatures (1/R^2 on a sphere, 0 on cylinders and planes, negative on saddles).
maximum: the largest absolute principal curvature, 1 / (tightest bend radius). Tight bends and sharp edges read high; a sharp edge reads about 1 / step, so it marks where a fillet may be needed.
Where the gradient vanishes (a medial point) the value is 0. Accuracy: second-order in the step on smooth surfaces; features smaller than the step are smoothed over. Thread safety: clone() clones the prepared body, as DistanceFieldAttribute does.
Public Types
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
Builds the curvature field of a body.
- Parameters:
body – The node; it is cloned and the clone is prepared.
kind – Mean, Gaussian or largest absolute principal curvature.
voxel_size – Positive voxel size in mm used to prepare the body; the difference step is half of it.
bandwidth – Positive distance in mm around the body’s box where its field is evaluated.
- Throws:
std::runtime_error – for a null body or a non-positive voxel size or bandwidth.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
-
inline double step() const#
Returns the central-difference step in mm.
- Returns:
The step.
Public Static Functions
-
static double curvature(Kind kind, const glm::dvec3 &gradient, const glm::dmat3 &hessian)#
Curvature from a gradient and a symmetric Hessian (row-major), as described above.
- Parameters:
kind – The curvature kind.
gradient – The field gradient at the point.
hessian – The field Hessian at the point.
- Returns:
The curvature.
-
class ScatteredFloatAttribute : public FloatAttribute#
- #include <scattered_attribute.h>
A scalar field from values known at scattered points (measurements, simulation nodes, sensors).
Evaluates a shared, immutable ScatteredInterpolator (see it for the methods, their cost and their behaviour away from the data). clone() shares the interpolator, and sampling uses per-thread buffers, so clones evaluate in parallel. The field is defined everywhere, not only near the points. value_bounds() reports the data range for nearest and inverse-distance interpolation, which never leave it; radial-basis fits may overshoot and report none.
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
inline const std::shared_ptr<const ScatteredInterpolator> &interpolator() const#
Returns the interpolator.
- Returns:
The shared interpolator.
-
inline virtual Value sample(const AttributeSampleContext &context)#
Samples with optional provenance from a mapped lattice.
The default implementation ignores the CellMap and component fields and forwards position and signed_distance to sample(x, y, z, d). Attributes that depend on logical coordinates or component provenance override it.
- Parameters:
context – The sample location and optional CellMap/component provenance.
- Returns:
A Value variant containing the evaluated attribute at the point.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
Wraps a fitted interpolator.
- Parameters:
interpolator – The fitted interpolator.
- Throws:
std::runtime_error – unless the interpolator holds one component.
-
ScatteredFloatAttribute(std::vector<glm::dvec3> points, std::vector<double> values, const ScatteredOptions &options = ScatteredOptions())#
Fits an interpolator to points and their values.
- Parameters:
points – The points, in mm.
values – One value per point.
options – The method and its settings.
-
virtual std::optional<std::pair<double, double>> value_bounds() const override#
Returns the range of values this field is known to stay in, or std::nullopt.
Known by construction, never estimated by sampling. A constant knows its value; fields that know their range (noise, clamp(), ease(), transfer(), …) override this. ScalarParameter adopts it, so such a field can size an operator’s bounding box.
- Returns:
The (minimum, maximum) pair, or std::nullopt when the range is unknown.
Private Members
-
std::shared_ptr<const ScatteredInterpolator> m_interpolator#
-
virtual std::shared_ptr<Attribute> clone() override#
-
class ScatteredVec3Attribute : public Vec3Attribute#
- #include <scattered_attribute.h>
A vector field from vectors known at scattered points, for example measured displacements.
Each component is interpolated with the same weights. See ScatteredFloatAttribute.
Public Functions
-
virtual std::shared_ptr<Attribute> clone() override#
Deep copies the attribute instance.
- Returns:
A shared pointer to the new attribute instance.
-
inline const std::shared_ptr<const ScatteredInterpolator> &interpolator() const#
Returns the interpolator.
- Returns:
The shared interpolator.
-
virtual Value sample(double x, double y, double z, double d) override#
Evaluates the attribute at a specified spatial point.
- Parameters:
x – The x-coordinate of the sample point.
y – The y-coordinate of the sample point.
z – The z-coordinate of the sample point.
d – The signed distance at the sample point (often used for spatial grading).
- Returns:
A Value variant containing the evaluated attribute at the point.
Wraps a fitted interpolator.
- Parameters:
interpolator – The fitted interpolator.
- Throws:
std::runtime_error – unless the interpolator holds three components.
-
ScatteredVec3Attribute(std::vector<glm::dvec3> points, const std::vector<glm::dvec3> &vectors, const ScatteredOptions &options = ScatteredOptions())#
Fits an interpolator to points and their vectors.
- Parameters:
points – The points, in mm.
vectors – One vector per point.
options – The method and its settings.
Private Members
-
std::shared_ptr<const ScatteredInterpolator> m_interpolator#
-
virtual std::shared_ptr<Attribute> clone() override#
Attribute utilities#
Enums
-
namespace AttributeCombination#
Functions
Mix two sampled attribute sets with a spatial weight.
Compatible scalar and vector values interpolate linearly. Volume fractions are merged by material ID and renormalized. Attributes present on only one side pass through unchanged. Resolver entries take precedence over policies.
- Parameters:
left – Attributes sampled from the left child.
right – Attributes sampled from the right child.
weight – Clamped right-child contribution in [0, 1].
policies – Optional per-attribute policy overrides.
resolvers – Optional per-attribute conflict resolvers.
- Returns:
The combined attribute samples.
Converters#
-
class AttributeConverterBase#
- #include <attribute_converter_base.h>
Interface for converting one set of attribute samples into another.
An AttributeModifier node calls convert() on the samples its child produces at every point inside the part. Converters typically read the attributes named by required_attributes() and add or replace the attributes named by output_attributes().
Subclassed by ExpressionConverter, LookupTableConverter, RgbToRgbaConverter, RgbaToRgbConverter, ScalarsToVec3Converter, ScalarsToVec4Converter, Vec3ToScalarsConverter, Vec4ToScalarsConverter, VolumeFractionsExpressionConverter
Public Functions
-
AttributeConverterBase() = default#
Default constructor.
-
virtual std::shared_ptr<AttributeConverterBase> clone() = 0#
Create a deep copy of this converter.
Stateful converters (e.g. ExpressionConverter) must override this to return a genuinely independent instance for thread safety.
- Returns:
A new, independent converter.
-
virtual AttributeSamples convert(AttributeSamples samples) = 0#
Converts one point’s attribute samples.
- Parameters:
samples – The samples produced by the child node at one point (passed by value).
- Returns:
The converted samples, usually the input samples with the outputs added or replaced.
-
virtual std::vector<std::string> output_attributes() = 0#
Returns the names of the attributes this converter produces.
- Returns:
The output attribute names.
-
virtual std::vector<std::string> required_attributes() = 0#
Returns the names of the attributes this converter reads.
- Returns:
The input attribute names.
-
virtual ~AttributeConverterBase() = default#
Virtual destructor.
Protected Static Functions
-
static inline double scalar_input(const AttributeSamples &samples, const std::string &name, const std::string &converter_name)#
Read a scalar input sample, with a clear error when it holds another type.
- Parameters:
samples – The samples to read from. The attribute must be present.
name – The attribute name.
converter_name – Name used in the error message (e.g. “ExpressionConverter”).
- Throws:
std::runtime_error – If the sample is not a scalar.
- Returns:
The scalar value.
-
AttributeConverterBase() = default#
Enums
-
class LookupTableConverter : public AttributeConverterBase#
- #include <lookup_table_converter.h>
A generic lookup-table-based attribute converter.
This converter maps one or more input attribute values to one or more output attribute values using a lookup table. It supports two interpolation modes:
STEP: Range-based matching where the input value falls within [low, high] of each entry. First match wins. Output can be any Attribute::Value type (double, vec3, vec4, etc.).
LINEAR: Sorted-point interpolation where the input must be a double and the output values are interpolated/clamped between neighboring entries. Supported output types are double, vec3, vec4, and volume-fraction maps. LINEAR mode needs exactly one output attribute. With one input, entries are sorted by input_low. With two inputs, each entry’s input_points gives a grid point, the entries must form a complete rectilinear grid, and the output is bilinearly interpolated (clamped at the grid edges).
Inputs must be scalar (double) samples. In single-input STEP and in LINEAR mode, a missing input passes the samples through unchanged, as does a STEP input that matches no entry. Input samples are kept.
Multi-input STEP mode: When multiple input attributes are given, each entry must provide per-input ranges via input_ranges and one output value per input. Each input is matched independently against its own range (first match wins), and missing inputs are skipped. The matched output values are then written:
N inputs, several outputs: each matched input sets its own output attribute (outputs beyond N are ignored); unmatched inputs set nothing.
N inputs, 1 output: all-or-nothing. The output is written only when every input matched. The values are assembled: vec3 + double (in either order) becomes a vec4 with the double as alpha; any other combination writes the first input’s value.
Public Functions
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
Create a deep copy of this converter.
Stateful converters (e.g. ExpressionConverter) must override this to return a genuinely independent instance for thread safety.
- Returns:
A new, independent converter.
-
virtual AttributeSamples convert(AttributeSamples samples) override#
Converts one point’s attribute samples.
- Parameters:
samples – The samples produced by the child node at one point (passed by value).
- Returns:
The converted samples, usually the input samples with the outputs added or replaced.
-
LookupTableConverter(const std::vector<std::string> &input_attributes, const std::vector<std::string> &output_attributes, std::vector<LookupTableEntry> entries, InterpolationMode mode = InterpolationMode::STEP)#
Construct a LookupTableConverter.
- Parameters:
input_attributes – Names of the input attributes to read.
output_attributes – Names of the output attributes to produce.
entries – The lookup table entries.
mode – Interpolation mode (STEP or LINEAR).
- Throws:
std::runtime_error – If there are no inputs or outputs, LINEAR mode is given other than one or two inputs and exactly one output, a two-input LINEAR table is not a complete grid, or a multi-input STEP entry has the wrong number of ranges or values.
-
virtual std::vector<std::string> output_attributes() override#
Returns the names of the attributes this converter produces.
- Returns:
The output attribute names.
-
virtual std::vector<std::string> required_attributes() override#
Returns the names of the attributes this converter reads.
- Returns:
The input attribute names.
Private Functions
-
AttributeSamples convert_linear(AttributeSamples &samples)#
LINEAR mode conversion: sorted-point interpolation with clamping.
-
AttributeSamples convert_linear_multi(AttributeSamples &samples)#
LINEAR mode conversion for two input attributes on a grid.
-
AttributeSamples convert_linear_single(AttributeSamples &samples)#
LINEAR mode conversion for single input attributes.
-
AttributeSamples convert_step(AttributeSamples &samples)#
STEP mode conversion: range-based threshold matching.
-
AttributeSamples convert_step_multi(AttributeSamples &samples)#
Multi-input STEP: each input matched independently, outputs assembled.
Private Members
-
std::vector<LookupTableEntry> m_entries#
-
std::vector<std::string> m_input_attributes#
-
std::vector<double> m_linear_axis0#
-
std::vector<double> m_linear_axis1#
-
std::vector<size_t> m_linear_grid_entry_indices#
-
InterpolationMode m_mode#
-
std::vector<std::string> m_output_attributes#
-
struct LookupTableEntry#
- #include <lookup_table_converter.h>
A single entry in a lookup table.
Which fields are read depends on the converter’s mode and input count:
Single-input STEP: [input_low, input_high] is the matching window, and output_values holds one value per output attribute.
Multi-input STEP: input_ranges holds one [low, high] pair per input attribute, and output_values holds one value per input attribute.
Single-input LINEAR: input_low is the interpolation knot, and output_values[0] is the value at that knot.
Two-input LINEAR: input_points holds the (input 0, input 1) grid point, and output_values holds exactly one value.
The point and range constructors also set input_low and input_high from the first point or range.
Public Functions
-
inline LookupTableEntry(double input, Attribute::Value value)#
Convenience constructor for single-input LINEAR mode (one knot, one output).
- Parameters:
input – The input value of the knot.
value – The output value at the knot.
-
inline LookupTableEntry(double low, double high, Attribute::Value value)#
Single-output convenience constructor for single-input STEP mode.
- Parameters:
low – Inclusive lower bound of the input window.
high – Inclusive upper bound of the input window.
value – The output value.
-
inline LookupTableEntry(double low, double high, std::vector<Attribute::Value> values)#
Multi-output constructor for single-input STEP mode: one value per output attribute.
- Parameters:
low – Inclusive lower bound of the input window.
high – Inclusive upper bound of the input window.
values – Output values, one per output attribute.
-
inline LookupTableEntry(std::vector<double> points, Attribute::Value value)#
Single-output convenience constructor for two-input LINEAR mode.
- Parameters:
points – The grid point, one coordinate per input attribute.
value – The output value at the grid point.
-
inline LookupTableEntry(std::vector<double> points, std::vector<Attribute::Value> values)#
Point constructor for two-input LINEAR mode: one coordinate per input attribute.
- Parameters:
points – The grid point, one coordinate per input attribute.
values – The output values. Two-input LINEAR mode requires exactly one.
-
inline LookupTableEntry(std::vector<std::pair<double, double>> ranges, std::vector<Attribute::Value> values)#
Multi-input STEP constructor: one range per input attribute, one value per input.
Each input is matched independently and produces its corresponding output value.
- Parameters:
ranges – Inclusive [low, high] windows, one per input attribute.
values – Output values, one per input attribute.
Public Members
-
double input_high#
Upper bound of the STEP window (inclusive). Unused in LINEAR mode.
-
double input_low#
Lower bound of the STEP window, or the knot for single-input LINEAR mode.
-
std::vector<double> input_points#
Per-input grid coordinates for two-input LINEAR mode.
-
std::vector<std::pair<double, double>> input_ranges#
Per-input [low, high] windows (inclusive) for multi-input STEP mode.
-
bool is_valid = true#
False marks a hole in the table.
A lookup that matches, clamps to, or interpolates through an invalid entry throws std::runtime_error.
-
class ExpressionConverter : public AttributeConverterBase#
- #include <expression_converter.h>
An attribute converter that evaluates mathematical expressions.
Uses ExpressionEvaluator (exprtk) to compute output attributes from input attributes via user-defined math strings.
Input attribute names are used directly as variable names in the expression string. For example, if input_attributes = {“temperature”}, then the expression “20 * temperature + 100” will read the “temperature” attribute sample and compute the result.
Each output attribute has its own expression string.
Inputs must be scalar (double) samples. If any input is missing at a point, the samples pass through unchanged. Otherwise each output is added or replaced and the input samples are kept. Expressions are compiled on the first convert() call, so a bad expression throws there.
Note
This converter is stateful (owns mutable ExpressionEvaluator instances). The clone() method produces a fresh instance for thread safety.
Public Functions
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
Create a deep copy of this converter.
Stateful converters (e.g. ExpressionConverter) must override this to return a genuinely independent instance for thread safety.
- Returns:
A new, independent converter.
-
virtual AttributeSamples convert(AttributeSamples samples) override#
Converts one point’s attribute samples.
- Parameters:
samples – The samples produced by the child node at one point (passed by value).
- Returns:
The converted samples, usually the input samples with the outputs added or replaced.
-
ExpressionConverter(const std::vector<std::string> &input_attributes, const std::vector<std::string> &output_attributes, const std::vector<std::string> &expressions)#
Construct an ExpressionConverter.
- Parameters:
input_attributes – Names of the input attributes (also variable names in expressions).
output_attributes – Names of the output attributes to produce.
expressions – Expression strings, one per output attribute in the same order.
- Throws:
std::runtime_error – If there are no inputs or outputs, or the output and expression counts differ.
-
virtual std::vector<std::string> output_attributes() override#
Returns the names of the attributes this converter produces.
- Returns:
The output attribute names.
-
virtual std::vector<std::string> required_attributes() override#
Returns the names of the attributes this converter reads.
- Returns:
The input attribute names.
-
virtual ~ExpressionConverter()#
Destructor.
Private Functions
-
void initialize()#
Private Members
-
std::vector<std::unique_ptr<CompiledExpression>> m_compiled#
-
std::vector<std::string> m_expressions#
-
bool m_initialized = false#
-
std::vector<std::string> m_input_attributes#
-
std::vector<std::string> m_output_attributes#
-
std::unordered_map<std::string, double> m_variable_storage#
Storage for the variable values that exprtk reads from.
Keyed by variable (attribute) name.
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
-
class VolumeFractionsExpressionConverter : public AttributeConverterBase#
- #include <volume_fractions_expression_converter.h>
Converts scalar input attributes into volume fractions with math expressions.
Each expression evaluates to one material’s volume fraction. Input attribute names are available as variables inside every expression, and the converter writes the resulting material map to DefaultAttributes::VOLUME_FRACTIONS.
Inputs must be scalar (double) samples. If any input is missing at a point, the samples pass through unchanged. The fractions are written exactly as the expressions evaluate: they are not clamped or normalized to sum to 1. Expressions are compiled on the first convert() call.
Note
This converter is stateful because it owns compiled expression evaluators. clone() returns a fresh converter for thread-safe use.
Public Functions
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
Create a deep copy of this converter.
Stateful converters (e.g. ExpressionConverter) must override this to return a genuinely independent instance for thread safety.
- Returns:
A new, independent converter.
-
virtual AttributeSamples convert(AttributeSamples samples) override#
Converts one point’s attribute samples.
- Parameters:
samples – The samples produced by the child node at one point (passed by value).
- Returns:
The converted samples, usually the input samples with the outputs added or replaced.
-
virtual std::vector<std::string> output_attributes() override#
Returns the names of the attributes this converter produces.
- Returns:
The output attribute names.
-
virtual std::vector<std::string> required_attributes() override#
Returns the names of the attributes this converter reads.
- Returns:
The input attribute names.
-
VolumeFractionsExpressionConverter(const std::vector<std::string> &input_attributes, const std::vector<uint8_t> &materials, const std::vector<std::string> &expressions)#
Construct a volume-fractions expression converter.
- Parameters:
input_attributes – Names of scalar attributes used as expression variables.
materials – Material IDs aligned with the expressions.
expressions – Math expressions aligned with the materials.
- Throws:
std::runtime_error – If there are no inputs or materials, or the material and expression counts differ.
-
virtual ~VolumeFractionsExpressionConverter()#
Destructor.
Private Functions
-
void initialize()#
Private Members
-
std::vector<std::unique_ptr<CompiledExpression>> m_compiled#
-
std::vector<std::string> m_expressions#
-
bool m_initialized = false#
-
std::vector<std::string> m_input_attributes#
-
std::vector<uint8_t> m_materials#
-
std::unordered_map<std::string, double> m_variable_storage#
Storage for variable values read by exprtk.
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
-
class RgbaToRgbConverter : public AttributeConverterBase#
- #include <color_channel_converter.h>
Converts the default COLOR_RGBA attribute into COLOR_RGB.
The RGB channels are copied into COLOR_RGB and the alpha channel is dropped. The COLOR_RGBA sample itself is kept, and samples without it pass through unchanged.
Public Functions
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
Create a deep copy of this converter.
Stateful converters (e.g. ExpressionConverter) must override this to return a genuinely independent instance for thread safety.
- Returns:
A new, independent converter.
-
virtual AttributeSamples convert(AttributeSamples samples) override#
Converts one point’s attribute samples.
- Parameters:
samples – The samples produced by the child node at one point (passed by value).
- Returns:
The converted samples, usually the input samples with the outputs added or replaced.
-
virtual std::vector<std::string> output_attributes() override#
Returns the names of the attributes this converter produces.
- Returns:
The output attribute names.
-
virtual std::vector<std::string> required_attributes() override#
Returns the names of the attributes this converter reads.
- Returns:
The input attribute names.
-
RgbaToRgbConverter() = default#
Construct an RGBA-to-RGB converter.
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
-
class RgbToRgbaConverter : public AttributeConverterBase#
- #include <color_channel_converter.h>
Converts the default COLOR_RGB attribute into COLOR_RGBA.
The RGB channels are copied unchanged and the alpha channel is set to the constant value supplied at construction time. Samples without COLOR_RGB pass through unchanged; the COLOR_RGB sample is kept.
Public Functions
-
double alpha() const#
Return the configured alpha value.
- Returns:
Constant alpha channel value used for COLOR_RGBA outputs.
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
Create a deep copy of this converter.
Stateful converters (e.g. ExpressionConverter) must override this to return a genuinely independent instance for thread safety.
- Returns:
A new, independent converter.
-
virtual AttributeSamples convert(AttributeSamples samples) override#
Converts one point’s attribute samples.
- Parameters:
samples – The samples produced by the child node at one point (passed by value).
- Returns:
The converted samples, usually the input samples with the outputs added or replaced.
-
virtual std::vector<std::string> output_attributes() override#
Returns the names of the attributes this converter produces.
- Returns:
The output attribute names.
-
virtual std::vector<std::string> required_attributes() override#
Returns the names of the attributes this converter reads.
- Returns:
The input attribute names.
-
explicit RgbToRgbaConverter(double alpha = 1.0)#
Construct an RGB-to-RGBA converter.
- Parameters:
alpha – Constant alpha channel value assigned to every output sample.
- Throws:
std::runtime_error – If alpha is not finite.
Private Members
-
double m_alpha#
-
double alpha() const#
-
class ScalarsToVec3Converter : public AttributeConverterBase#
- #include <vector_component_converter.h>
Combines three named float attributes into a Vec3 (X, Y, Z).
If any input is missing, the samples pass through unchanged. The inputs are kept. Each input must be a scalar sample, or convert() throws std::runtime_error.
Public Functions
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
Create a deep copy of this converter.
Stateful converters (e.g. ExpressionConverter) must override this to return a genuinely independent instance for thread safety.
- Returns:
A new, independent converter.
-
virtual AttributeSamples convert(AttributeSamples samples) override#
Converts one point’s attribute samples.
- Parameters:
samples – The samples produced by the child node at one point (passed by value).
- Returns:
The converted samples, usually the input samples with the outputs added or replaced.
-
const std::string &output_attribute() const#
Return the output Vec3 attribute name.
- Returns:
The attribute name.
-
virtual std::vector<std::string> output_attributes() override#
Returns the names of the attributes this converter produces.
- Returns:
The output attribute names.
-
virtual std::vector<std::string> required_attributes() override#
Returns the names of the attributes this converter reads.
- Returns:
The input attribute names.
-
ScalarsToVec3Converter(const std::string &x_attribute, const std::string &y_attribute, const std::string &z_attribute, const std::string &output_attribute)#
Construct a scalars-to-Vec3 converter.
- Parameters:
x_attribute – Name of the input float attribute for the X component.
y_attribute – Name of the input float attribute for the Y component.
z_attribute – Name of the input float attribute for the Z component.
output_attribute – Name of the output Vec3 attribute.
- Throws:
std::runtime_error – If a name is empty or two names are equal.
-
const std::string &x_attribute() const#
Return the input X float attribute name.
- Returns:
The attribute name.
-
const std::string &y_attribute() const#
Return the input Y float attribute name.
- Returns:
The attribute name.
-
const std::string &z_attribute() const#
Return the input Z float attribute name.
- Returns:
The attribute name.
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
-
class ScalarsToVec4Converter : public AttributeConverterBase#
- #include <vector_component_converter.h>
Combines four named float attributes into a Vec4 (X, Y, Z, W).
If any input is missing, the samples pass through unchanged. The inputs are kept. Each input must be a scalar sample, or convert() throws std::runtime_error.
Public Functions
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
Create a deep copy of this converter.
Stateful converters (e.g. ExpressionConverter) must override this to return a genuinely independent instance for thread safety.
- Returns:
A new, independent converter.
-
virtual AttributeSamples convert(AttributeSamples samples) override#
Converts one point’s attribute samples.
- Parameters:
samples – The samples produced by the child node at one point (passed by value).
- Returns:
The converted samples, usually the input samples with the outputs added or replaced.
-
const std::string &output_attribute() const#
Return the output Vec4 attribute name.
- Returns:
The attribute name.
-
virtual std::vector<std::string> output_attributes() override#
Returns the names of the attributes this converter produces.
- Returns:
The output attribute names.
-
virtual std::vector<std::string> required_attributes() override#
Returns the names of the attributes this converter reads.
- Returns:
The input attribute names.
-
ScalarsToVec4Converter(const std::string &x_attribute, const std::string &y_attribute, const std::string &z_attribute, const std::string &w_attribute, const std::string &output_attribute)#
Construct a scalars-to-Vec4 converter.
- Parameters:
x_attribute – Name of the input float attribute for the X component.
y_attribute – Name of the input float attribute for the Y component.
z_attribute – Name of the input float attribute for the Z component.
w_attribute – Name of the input float attribute for the W component.
output_attribute – Name of the output Vec4 attribute.
- Throws:
std::runtime_error – If a name is empty or two names are equal.
-
const std::string &w_attribute() const#
Return the input W float attribute name.
- Returns:
The attribute name.
-
const std::string &x_attribute() const#
Return the input X float attribute name.
- Returns:
The attribute name.
-
const std::string &y_attribute() const#
Return the input Y float attribute name.
- Returns:
The attribute name.
-
const std::string &z_attribute() const#
Return the input Z float attribute name.
- Returns:
The attribute name.
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
-
class Vec3ToScalarsConverter : public AttributeConverterBase#
- #include <vector_component_converter.h>
Splits a Vec3 attribute into three named float attributes (X, Y, Z).
Samples without the input pass through unchanged; the input sample is kept. The input must be a Vec3 sample, or convert() throws std::runtime_error.
Public Functions
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
Create a deep copy of this converter.
Stateful converters (e.g. ExpressionConverter) must override this to return a genuinely independent instance for thread safety.
- Returns:
A new, independent converter.
-
virtual AttributeSamples convert(AttributeSamples samples) override#
Converts one point’s attribute samples.
- Parameters:
samples – The samples produced by the child node at one point (passed by value).
- Returns:
The converted samples, usually the input samples with the outputs added or replaced.
-
const std::string &input_attribute() const#
Return the source Vec3 attribute name.
- Returns:
The attribute name.
-
virtual std::vector<std::string> output_attributes() override#
Returns the names of the attributes this converter produces.
- Returns:
The output attribute names.
-
virtual std::vector<std::string> required_attributes() override#
Returns the names of the attributes this converter reads.
- Returns:
The input attribute names.
-
Vec3ToScalarsConverter(const std::string &input_attribute, const std::string &x_attribute, const std::string &y_attribute, const std::string &z_attribute)#
Construct a Vec3-to-scalars converter.
- Parameters:
input_attribute – Name of the source Vec3 attribute.
x_attribute – Name of the output float attribute for the X component.
y_attribute – Name of the output float attribute for the Y component.
z_attribute – Name of the output float attribute for the Z component.
- Throws:
std::runtime_error – If a name is empty or two names are equal.
-
const std::string &x_attribute() const#
Return the output X float attribute name.
- Returns:
The attribute name.
-
const std::string &y_attribute() const#
Return the output Y float attribute name.
- Returns:
The attribute name.
-
const std::string &z_attribute() const#
Return the output Z float attribute name.
- Returns:
The attribute name.
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
-
class Vec4ToScalarsConverter : public AttributeConverterBase#
- #include <vector_component_converter.h>
Splits a Vec4 attribute into four named float attributes (X, Y, Z, W).
Samples without the input pass through unchanged; the input sample is kept. The input must be a Vec4 sample, or convert() throws std::runtime_error.
Public Functions
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
Create a deep copy of this converter.
Stateful converters (e.g. ExpressionConverter) must override this to return a genuinely independent instance for thread safety.
- Returns:
A new, independent converter.
-
virtual AttributeSamples convert(AttributeSamples samples) override#
Converts one point’s attribute samples.
- Parameters:
samples – The samples produced by the child node at one point (passed by value).
- Returns:
The converted samples, usually the input samples with the outputs added or replaced.
-
const std::string &input_attribute() const#
Return the source Vec4 attribute name.
- Returns:
The attribute name.
-
virtual std::vector<std::string> output_attributes() override#
Returns the names of the attributes this converter produces.
- Returns:
The output attribute names.
-
virtual std::vector<std::string> required_attributes() override#
Returns the names of the attributes this converter reads.
- Returns:
The input attribute names.
-
Vec4ToScalarsConverter(const std::string &input_attribute, const std::string &x_attribute, const std::string &y_attribute, const std::string &z_attribute, const std::string &w_attribute)#
Construct a Vec4-to-scalars converter.
- Parameters:
input_attribute – Name of the source Vec4 attribute.
x_attribute – Name of the output float attribute for the X component.
y_attribute – Name of the output float attribute for the Y component.
z_attribute – Name of the output float attribute for the Z component.
w_attribute – Name of the output float attribute for the W component.
- Throws:
std::runtime_error – If a name is empty or two names are equal.
-
const std::string &w_attribute() const#
Return the output W float attribute name.
- Returns:
The attribute name.
-
const std::string &x_attribute() const#
Return the output X float attribute name.
- Returns:
The attribute name.
-
const std::string &y_attribute() const#
Return the output Y float attribute name.
- Returns:
The attribute name.
-
const std::string &z_attribute() const#
Return the output Z float attribute name.
- Returns:
The attribute name.
-
virtual std::shared_ptr<AttributeConverterBase> clone() override#
Conflict resolvers#
Strategies that combine one attribute where several children of a node overlap.
-
class AttributeConflictResolver#
- #include <attribute_conflict_resolver.h>
Combines the values of one attribute where several children of a node overlap.
A composition node (e.g. Union) uses a resolver when more than one child defines the same attribute at a sample point. All values passed to resolve() share the attribute’s return type.
Subclassed by AverageConflictResolver, CustomFloatConflictResolver, CustomVec4ConflictResolver, MaxConflictResolver, MinConflictResolver, SumConflictResolver
Public Functions
-
virtual Attribute::Value resolve(const std::vector<Attribute::Value> &values) = 0#
Combine overlapping attribute values into one.
- Parameters:
values – The values from each overlapping child, all of the same type. Must not be empty.
- Returns:
The combined value, of the same type as the inputs.
-
virtual ~AttributeConflictResolver() = default#
-
virtual Attribute::Value resolve(const std::vector<Attribute::Value> &values) = 0#
Enums
-
enum class Vec4Mode#
How MinConflictResolver and MaxConflictResolver compare Vec3 and Vec4 values.
Values:
-
enumerator PerChannel#
Take the min/max of each component independently.
-
enumerator Magnitude#
Keep the whole vector with the smallest/largest length.
-
enumerator PerChannel#
-
class AverageConflictResolver : public AttributeConflictResolver#
- #include <builtins.h>
Resolves overlaps with the arithmetic mean of the values.
Volume-fraction maps are averaged per material and renormalized to sum to 1.
Public Functions
-
class MaxConflictResolver : public AttributeConflictResolver#
- #include <builtins.h>
Resolves overlaps with the maximum value.
Scalars take the maximum. Vec3/Vec4 values follow the Vec4Mode. Volume-fraction maps are first averaged, then only the material(s) with the largest averaged fraction (within 1e-6) are kept and renormalized to sum to 1.
Public Functions
-
MaxConflictResolver(Vec4Mode mode = Vec4Mode::PerChannel)#
- Parameters:
mode – How Vec3/Vec4 values are compared. Defaults to per-channel.
-
MaxConflictResolver(Vec4Mode mode = Vec4Mode::PerChannel)#
-
class MinConflictResolver : public AttributeConflictResolver#
- #include <builtins.h>
Resolves overlaps with the minimum value.
Scalars take the minimum. Vec3/Vec4 values follow the Vec4Mode. Volume-fraction maps are first averaged, then only the material(s) with the smallest averaged fraction (within 1e-6) are kept and renormalized to sum to 1.
Public Functions
-
MinConflictResolver(Vec4Mode mode = Vec4Mode::PerChannel)#
- Parameters:
mode – How Vec3/Vec4 values are compared. Defaults to per-channel.
-
MinConflictResolver(Vec4Mode mode = Vec4Mode::PerChannel)#
-
class SumConflictResolver : public AttributeConflictResolver#
- #include <builtins.h>
Resolves overlaps by adding the values.
Volume-fraction maps are summed per material and then renormalized to sum to 1.
Public Functions
-
class CustomFloatConflictResolver : public AttributeConflictResolver#
- #include <custom_resolvers.h>
Resolves overlapping scalar values with a user-supplied binary reduction.
The function is folded left to right:
f(f(v0, v1), v2) ....Public Types
Public Functions
-
inline CustomFloatConflictResolver(const FloatBinaryFunc &func)#
- Parameters:
func – Reduction function. Throws std::invalid_argument if empty.
-
inline virtual Attribute::Value resolve(const std::vector<Attribute::Value> &values) override#
Combine overlapping attribute values into one.
- Parameters:
values – The values from each overlapping child, all of the same type. Must not be empty.
- Returns:
The combined value, of the same type as the inputs.
Private Members
-
FloatBinaryFunc m_func#
-
inline CustomFloatConflictResolver(const FloatBinaryFunc &func)#
-
class CustomVec4ConflictResolver : public AttributeConflictResolver#
- #include <custom_resolvers.h>
Resolves overlapping Vec4 values with one user-supplied binary reduction per channel.
Each channel is folded left to right independently.
Public Types
Public Functions
-
inline CustomVec4ConflictResolver(const FloatBinaryFunc &r, const FloatBinaryFunc &g, const FloatBinaryFunc &b, const FloatBinaryFunc &a)#
- Parameters:
r – Reduction for the red channel.
g – Reduction for the green channel.
b – Reduction for the blue channel.
a – Reduction for the alpha channel. Throws std::invalid_argument if any function is empty.
-
inline virtual Attribute::Value resolve(const std::vector<Attribute::Value> &values) override#
Combine overlapping attribute values into one.
- Parameters:
values – The values from each overlapping child, all of the same type. Must not be empty.
- Returns:
The combined value, of the same type as the inputs.
Private Members
-
FloatBinaryFunc m_func_a#
-
FloatBinaryFunc m_func_b#
-
FloatBinaryFunc m_func_g#
-
FloatBinaryFunc m_func_r#
-
inline CustomVec4ConflictResolver(const FloatBinaryFunc &r, const FloatBinaryFunc &g, const FloatBinaryFunc &b, const FloatBinaryFunc &a)#