Attributes

Core attribute types, samples, default name/type constants, and converters.

Core types

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 FloatAttribute, Vec4Attribute, VolumeFractionsAttribute

Public Types

enum ReturnType

The data type returned by the attribute evaluation.

Values:

enumerator none

enumerator dbl

enumerator vec3

enumerator vec4

enumerator vfm_ptr

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.

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

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

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

void set_attribute(const std::string &name, const std::shared_ptr<Attribute> &attribute)

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.

Private Members

std::unordered_map<std::string, std::shared_ptr<Attribute>> m_attributes

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

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.

Parameters:

name – The string name of the attribute.
value – The Attribute::Value variant to store.

Private Members

std::unordered_map<std::string, Attribute::Value> m_samples

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 COLOR_RGB = "color_rgb"

Attribute::ReturnType COLOR_RGB_TYPE = Attribute::ReturnType::vec3 

const std::string COLOR_RGBA = "color_rgba"

Attribute::ReturnType COLOR_RGBA_TYPE = Attribute::ReturnType::vec4 

const std::string DENSITY = "density"

Attribute::ReturnType DENSITY_TYPE = Attribute::ReturnType::dbl 

const std::string ELONGATION = "elongation"

Attribute::ReturnType ELONGATION_TYPE = Attribute::ReturnType::dbl 

const std::string FLOW_RATE = "flow_rate"

Attribute::ReturnType FLOW_RATE_TYPE = Attribute::ReturnType::dbl 

const std::string FUZZY_SKIN_POINT_DISTANCE = "fuzzy_skin_point_distance"

Attribute::ReturnType FUZZY_SKIN_POINT_DISTANCE_TYPE = Attribute::ReturnType::dbl 

const std::string HU = "hu"

Attribute::ReturnType HU_TYPE = Attribute::ReturnType::dbl 

const std::string INFILL_DENSITY = "infill_density"

Attribute::ReturnType INFILL_DENSITY_TYPE = Attribute::ReturnType::dbl 

const std::string MODULUS = "modulus"

Attribute::ReturnType MODULUS_TYPE = Attribute::ReturnType::dbl 

const std::string NONE = "none"

Attribute::ReturnType NONE_TYPE = Attribute::ReturnType::none 

const std::string SHORE_HARDNESS = "shore_hardness"

Attribute::ReturnType SHORE_HARDNESS_TYPE = Attribute::ReturnType::dbl 

const std::string TEMPERATURE = "temperature"

Attribute::ReturnType TEMPERATURE_TYPE = Attribute::ReturnType::dbl 

const std::string TOUGHNESS = "toughness"

Attribute::ReturnType TOUGHNSS_TYPE = Attribute::ReturnType::dbl 

const std::string VOLUME_FRACTIONS = "volume_fractions"

Attribute::ReturnType VOLUME_FRACTIONS_TYPE = Attribute::ReturnType::vfm_ptr 

class FloatAttribute : public Attribute 

#include <float_attribute.h>

An attribute that stores a function for spatial grading that returns a floating point value.

This class is abstract and is meant to be inherited from to complete an attribute.

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.

FloatAttribute() = default: Default constructor.

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

FloatAttribute(const std::shared_ptr<FloatVDBVolume> &volume)

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: https://github.com/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

virtual ReturnType return_type() override

See also

Attribute::return_type()

virtual Value sample(double x, double y, double z, double d) override

See also

Attribute::sample()

void set_expression(const std::string &expression)

Sets the math expression for the attribute.

Note

Either this function or set_function() can be used, but not both

Parameters:: expression – The math expression that represents the attribute

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

void set_value(double value)

Sets the constant value for the attribute (no spatial grading).

Note

This cannot be called if the attribute was created with a math expression or function (or one was set later)

Parameters:: value – The constant value for the attribute

void set_volume(std::shared_ptr<FloatVDBVolume> volume)

Sets the attribute to be sampled from a VDB volume.

Parameters:: volume – A shared pointer to a FloatVDBVolume to sample the attribute from

Private Members

std::string m_expression

FloatFunction m_function

uint8_t m_mode = 0

double m_phic

double m_phis

double m_r

double m_rho

double m_signed_distance

double m_theta

std::shared_ptr<FloatVDBVolume> m_volume

double m_x

double m_y

double m_z

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

See also

Attribute::clone()

virtual ReturnType return_type() override

See also

Attribute::return_type()

virtual Value sample(double x, double y, double z, double d) override

See also

Attribute::sample()

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

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

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

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

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

double m_x

double m_y

double m_z

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.

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: https://github.com/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

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

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

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

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

See also

Attribute::type()

virtual Value sample(double x, double y, double z, double d) override

See also

Attribute::sample()

VolumeFractionsAttribute(): Default constructor.

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.
Returns:: A shared pointer to the VolumeFractionMap, or nullptr if none exists in the sample map under DefaultAttributes::VOLUME_FRACTIONS.

Private Members

std::unordered_map<uint8_t, std::string> m_expression_strings

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

Attribute utilities

namespace AttributeCombination

Functions

AttributeSamples intersection_attributes(const std::vector<AttributeSamples> &samples)

AttributeSamples union_attributes(const std::vector<AttributeSamples> &samples)

Converters

class AttributeConverterBase

#include <attribute_converter_base.h>

Subclassed by ExpressionConverter, LookupTableConverter

Public Functions

AttributeConverterBase() = default

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.

virtual AttributeSamples convert(AttributeSamples samples) = 0

virtual std::vector<std::string> output_attributes() = 0

virtual std::vector<std::string> required_attributes() = 0

virtual ~AttributeConverterBase() = default

Enums

enum class InterpolationMode

Interpolation mode for lookup table entries.

Values:

enumerator STEP: Range-based step lookup: value falls within [low, high].

enumerator LINEAR: Sorted point-based lookup with linear interpolation and clamping.

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 and output must both be double. Clamps to first/last entry at extremes.

Multi-input STEP mode: When multiple input attributes are given, each entry must provide per-input ranges via input_ranges. Each input is matched independently against its own range. The matched output values are assembled into the output:

N inputs, N outputs: each match sets its own output attribute.
N inputs, 1 output: matched values are assembled (e.g. vec3 + double -> vec4 for color_rgba).

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.

virtual AttributeSamples convert(AttributeSamples samples) override

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

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

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

Private Functions

AttributeSamples convert_linear(AttributeSamples &samples): LINEAR mode conversion: sorted-point interpolation with clamping.

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

InterpolationMode m_mode

std::vector<std::string> m_output_attributes

Private Static Functions

static Attribute::Value assemble_values(const std::vector<Attribute::Value> &values)

Assemble multiple matched values into a single Attribute::Value.

Combines vec3 + double -> vec4, or other supported patterns.

struct LookupTableEntry

#include <lookup_table_converter.h>

A single entry in a lookup table.

For single-input mode, [input_low, input_high] defines a range. For multi-input mode, input_ranges holds one [low, high] pair per input attribute.

output_values holds one value per output attribute (single-input) or one value per input attribute (multi-input independent matching).

Public Functions

inline LookupTableEntry(double input, Attribute::Value value): Convenience constructor for LINEAR mode (single input point, single output).

inline LookupTableEntry(double low, double high, Attribute::Value value): Single-output convenience constructor.

inline LookupTableEntry(double low, double high, std::vector<Attribute::Value> values): Multi-output constructor: one value per output attribute.

inline LookupTableEntry(std::vector<std::pair<double, double>> ranges, std::vector<Attribute::Value> values)

Multi-input constructor: one range per input attribute, one value per input.

Each input is matched independently and produces its corresponding output.

Public Members

double input_high

double input_low

std::vector<std::pair<double, double>> input_ranges

std::vector<Attribute::Value> output_values

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.

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.

virtual AttributeSamples convert(AttributeSamples samples) override

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.

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

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

virtual ~ExpressionConverter()

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.