Attributes

Attribute types, samples, converters, and the DefaultAttributes submodule.

Core types

class pyvcad.Attribute

Base class for all attributes.

Defines the common interface for sampling an attribute map, including material volume fractions and values like density or elastic modulus.

class ReturnType

Members:

dbl

vec3

vec4

vfm_ptr

__init__(self: pyvcad.pyvcad.Attribute.ReturnType, value: SupportsInt) → None
dbl = <ReturnType.dbl: 0>
Attribute.ReturnType.name -> str
property value
vec3 = <ReturnType.vec3: 1>
vec4 = <ReturnType.vec4: 2>
vfm_ptr = <ReturnType.vfm_ptr: 3>
__init__(*args, **kwargs)
clone(self: pyvcad.pyvcad.Attribute) → pyvcad.pyvcad.Attribute

Clones the attribute and returns a pointer to the new attribute.

return_type(self: pyvcad.pyvcad.Attribute) → pyvcad.pyvcad.Attribute.ReturnType

Returns the return type of the attribute.

sample(self: pyvcad.pyvcad.Attribute, x: SupportsFloat, y: SupportsFloat, z: SupportsFloat, d: SupportsFloat) → boost::variant<double, glm::vec<3, float, (glm::qualifier)0>, glm::vec<4, float, (glm::qualifier)0>, std::__1::shared_ptr<std::__1::unordered_map<unsigned char, double, std::__1::hash<unsigned char>, std::__1::equal_to<unsigned char>, std::__1::allocator<std::__1::pair<unsigned char const, double>>>>>

Samples the attribute at the given point.

Parameters:

  • x (double) – The x-coordinate of the point to sample.

  • y (double) – The y-coordinate of the point to sample.

  • z (double) – The z-coordinate of the point to sample.

  • d (double) – The signed distance to the surface.

class pyvcad.FloatAttribute

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

__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.FloatAttribute) -> None

Default constructor.

  1. __init__(self: pyvcad.pyvcad.FloatAttribute, expression: str) -> None

Constructor that takes a math expression string.

:param expression : A math expression representing the attribute. :type expression : str

  1. __init__(self: pyvcad.pyvcad.FloatAttribute, function: collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float]) -> None

Constructor that takes a native function.

:param function : A function returning a float value. :type function : callable

  1. __init__(self: pyvcad.pyvcad.FloatAttribute, value: typing.SupportsFloat) -> None

Constructor that takes a constant value.

:param value : A constant value for the attribute. :type value : float

  1. __init__(self: pyvcad.pyvcad.FloatAttribute, volume: VDBVolume<openvdb::v13_0::Grid<openvdb::v13_0::tree::Tree<openvdb::v13_0::tree::RootNode<openvdb::v13_0::tree::InternalNode<openvdb::v13_0::tree::InternalNode<openvdb::v13_0::tree::LeafNode<float, 3u>, 4u>, 5u>>>>>) -> None

Constructor that takes a VDB volume to sample the attribute from.

:param volume : A FloatVDBVolume to sample the attribute from. :type volume : FloatVDBVolume

clone(self: pyvcad.pyvcad.FloatAttribute) → pyvcad.pyvcad.Attribute

Clones the attribute and returns a pointer to the new attribute.

return_type(self: pyvcad.pyvcad.FloatAttribute) → pyvcad.pyvcad.Attribute.ReturnType

Returns the return type of the attribute.

sample(self: pyvcad.pyvcad.FloatAttribute, x: SupportsFloat, y: SupportsFloat, z: SupportsFloat, d: SupportsFloat) → boost::variant<double, glm::vec<3, float, (glm::qualifier)0>, glm::vec<4, float, (glm::qualifier)0>, std::__1::shared_ptr<std::__1::unordered_map<unsigned char, double, std::__1::hash<unsigned char>, std::__1::equal_to<unsigned char>, std::__1::allocator<std::__1::pair<unsigned char const, double>>>>>

Samples the attribute at the given point.

:param x : The x-coordinate. :type x : double:param y : The y-coordinate. :type y : double:param z : The z-coordinate. :type z : double:param d : The signed distance. :type d : double

set_expression(self: pyvcad.pyvcad.FloatAttribute, expression: str) → None

Sets the math expression for the attribute.

:param expression : The math expression. :type expression : str

set_function(self: pyvcad.pyvcad.FloatAttribute, function: collections.abc.Callable[[SupportsFloat, SupportsFloat, SupportsFloat, SupportsFloat], float]) → None

Sets the native function for the attribute.

:param function : A function returning a float value. :type function : callable

set_value(self: pyvcad.pyvcad.FloatAttribute, value: SupportsFloat) → None

Sets a constant value for the attribute.

:param value : A constant value. :type value : float

set_volume(self: pyvcad.pyvcad.FloatAttribute, volume: VDBVolume<openvdb::v13_0::Grid<openvdb::v13_0::tree::Tree<openvdb::v13_0::tree::RootNode<openvdb::v13_0::tree::InternalNode<openvdb::v13_0::tree::InternalNode<openvdb::v13_0::tree::LeafNode<float, 3u>, 4u>, 5u>>>>>) → None

Sets the attribute to be sampled from a VDB volume.

:param volume : A FloatVDBVolume to sample the attribute from. :type volume : FloatVDBVolume

class pyvcad.Vec4Attribute

An attribute that stores a function for spatial grading that returns a vec4.

When used for representing color, the components should be in the range [0, 1].

__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.Vec4Attribute) -> None

Default constructor.

  1. __init__(self: pyvcad.pyvcad.Vec4Attribute, r_expression: str, g_expression: str, b_expression: str, a_expression: str) -> None

Constructor that takes math expression strings for each component.

:param r_expression : Expression for the red component. :type r_expression : str:param g_expression : Expression for the green component. :type g_expression : str:param b_expression : Expression for the blue component. :type b_expression : str:param a_expression : Expression for the alpha component. :type a_expression : str

  1. __init__(self: pyvcad.pyvcad.Vec4Attribute, r_function: collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float], g_function: collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float], b_function: collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float], a_function: collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float]) -> None

Constructor that takes native functions for each component.

:param r_function : Function for the red component. :type r_function : callable:param g_function : Function for the green component. :type g_function : callable:param b_function : Function for the blue component. :type b_function : callable:param a_function : Function for the alpha component. :type a_function : callable

  1. __init__(self: pyvcad.pyvcad.Vec4Attribute, function: collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], pyvcad.pyvcad.Vec4]) -> None

Constructor that takes a native vec4 function.

:param function : A function returning a vec4. :type function : callable

  1. __init__(self: pyvcad.pyvcad.Vec4Attribute, r: typing.SupportsFloat, g: typing.SupportsFloat, b: typing.SupportsFloat, a: typing.SupportsFloat) -> None

Constructor that takes constant values for each component.

clone(self: pyvcad.pyvcad.Vec4Attribute) → pyvcad.pyvcad.Attribute

Clones the attribute and returns a pointer to the new object.

return_type(self: pyvcad.pyvcad.Vec4Attribute) → pyvcad.pyvcad.Attribute.ReturnType

Returns the return type of the attribute.

sample(self: pyvcad.pyvcad.Vec4Attribute, x: SupportsFloat, y: SupportsFloat, z: SupportsFloat, d: SupportsFloat) → boost::variant<double, glm::vec<3, float, (glm::qualifier)0>, glm::vec<4, float, (glm::qualifier)0>, std::__1::shared_ptr<std::__1::unordered_map<unsigned char, double, std::__1::hash<unsigned char>, std::__1::equal_to<unsigned char>, std::__1::allocator<std::__1::pair<unsigned char const, double>>>>>

Samples the attribute at the given point.

:param x : The x-coordinate. :type x : double:param y : The y-coordinate. :type y : double:param z : The z-coordinate. :type z : double:param d : The signed distance. :type d : double

set_expression(self: pyvcad.pyvcad.Vec4Attribute, r_expression: str, g_expression: str, b_expression: str, a_expression: str) → None

Sets the math expressions for the attribute.

:param r_expression : Expression for the red component. :type r_expression : str:param g_expression : Expression for the green component. :type g_expression : str:param b_expression : Expression for the blue component. :type b_expression : str:param a_expression : Expression for the alpha component. :type a_expression : str

set_function(*args, **kwargs)

Overloaded function.

  1. set_function(self: pyvcad.pyvcad.Vec4Attribute, r_function: collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float], g_function: collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float], b_function: collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float], a_function: collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float]) -> None

Sets the native functions for each component of the attribute.

  1. set_function(self: pyvcad.pyvcad.Vec4Attribute, function: collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], pyvcad.pyvcad.Vec4]) -> None

Sets the native function that returns a vec4.

set_value(self: pyvcad.pyvcad.Vec4Attribute, r: SupportsFloat, g: SupportsFloat, b: SupportsFloat, a: SupportsFloat) → None

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

class pyvcad.VolumeFractionsAttribute

An attribute that stores a set of volume fraction functions for different materials. It can be sampled to get the fractions for each material.

__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.VolumeFractionsAttribute) -> None

Default constructor.

  1. __init__(self: pyvcad.pyvcad.VolumeFractionsAttribute, expressions: collections.abc.Sequence[str], materials: collections.abc.Sequence[typing.SupportsInt]) -> None

Constructor that takes lists of math expressions and materials.

  1. __init__(self: pyvcad.pyvcad.VolumeFractionsAttribute, expression_material_pairs: collections.abc.Sequence[tuple[str, typing.SupportsInt]]) -> None

Constructor that takes expression/material pairs.

  1. __init__(self: pyvcad.pyvcad.VolumeFractionsAttribute, functions: collections.abc.Sequence[collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float]], materials: collections.abc.Sequence[typing.SupportsInt]) -> None

Constructor with native functions and materials.

  1. __init__(self: pyvcad.pyvcad.VolumeFractionsAttribute, function_material_pairs: collections.abc.Sequence[tuple[collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float], typing.SupportsInt]]) -> None

Constructor with function/material pairs.

  1. __init__(self: pyvcad.pyvcad.VolumeFractionsAttribute, values: collections.abc.Sequence[typing.SupportsFloat], materials: collections.abc.Sequence[typing.SupportsInt]) -> None

Constructor with constant values and materials.

  1. __init__(self: pyvcad.pyvcad.VolumeFractionsAttribute, value_material_pairs: collections.abc.Sequence[tuple[typing.SupportsFloat, typing.SupportsInt]]) -> None

Constructor with value/material pairs.

add_expression(*args, **kwargs)

Overloaded function.

  1. add_expression(self: pyvcad.pyvcad.VolumeFractionsAttribute, expression: str, material: typing.SupportsInt) -> None

Adds a math expression for a material.

  1. add_expression(self: pyvcad.pyvcad.VolumeFractionsAttribute, expression_material_pair: tuple[str, typing.SupportsInt]) -> None

Adds an expression/material pair.

add_function(*args, **kwargs)

Overloaded function.

  1. add_function(self: pyvcad.pyvcad.VolumeFractionsAttribute, function: collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float], material: typing.SupportsInt) -> None

Adds a native function for a material.

  1. add_function(self: pyvcad.pyvcad.VolumeFractionsAttribute, function_material_pair: tuple[collections.abc.Callable[[typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat, typing.SupportsFloat], float], typing.SupportsInt]) -> None

Adds a function/material pair.

add_value(self: pyvcad.pyvcad.VolumeFractionsAttribute, value: SupportsFloat, material: SupportsInt) → None

Adds a constant value for a material.

clone(self: pyvcad.pyvcad.VolumeFractionsAttribute) → pyvcad.pyvcad.Attribute

Clones the attribute.

static get_value(attribute_samples: collections.abc.Mapping[str, boost::variant<double, glm::vec<3, float, (glm::qualifier)0>, glm::vec<4, float, (glm::qualifier)0>, std::__1::shared_ptr<std::__1::unordered_map<unsigned char, double, std::__1::hash<unsigned char>, std::__1::equal_to<unsigned char>, std::__1::allocator<std::__1::pair<unsigned char const, double>>>>>]) → dict[int, float]

Extracts the volume fraction map from sampled attributes.

return_type(self: pyvcad.pyvcad.VolumeFractionsAttribute) → pyvcad.pyvcad.Attribute.ReturnType

Returns the return type.

sample(self: pyvcad.pyvcad.VolumeFractionsAttribute, x: SupportsFloat, y: SupportsFloat, z: SupportsFloat, d: SupportsFloat) → boost::variant<double, glm::vec<3, float, (glm::qualifier)0>, glm::vec<4, float, (glm::qualifier)0>, std::__1::shared_ptr<std::__1::unordered_map<unsigned char, double, std::__1::hash<unsigned char>, std::__1::equal_to<unsigned char>, std::__1::allocator<std::__1::pair<unsigned char const, double>>>>>

Samples the attribute.

class pyvcad.AttributeSamples

A collection of attribute samples returned by a tree sample.

Acts as a key-value store mapping attribute names to their evaluated values.

__init__(self: pyvcad.pyvcad.AttributeSamples) → None
get_sample(self: pyvcad.pyvcad.AttributeSamples, name: str) → object

Returns the sampled value for the given attribute name.

get_type(self: pyvcad.pyvcad.AttributeSamples, name: str) → pyvcad.pyvcad.Attribute.ReturnType

Returns the ReturnType enum of the sample (e.g. pv.Attribute.ReturnType.dbl).

has_sample(self: pyvcad.pyvcad.AttributeSamples, name: str) → bool

Checks if the sample contains an attribute with the given name.

set_sample(self: pyvcad.pyvcad.AttributeSamples, name: str, value: object) → None

Sets the sampled value for the given attribute name.

Converters

class pyvcad.AttributeConverterBase

Base class for converting attribute samples to new attributes.

__init__(self: pyvcad.pyvcad.AttributeConverterBase) → None

Constructs a new attribute converter base.

clone(self: pyvcad.pyvcad.AttributeConverterBase) → pyvcad.pyvcad.AttributeConverterBase

Create a deep copy of this converter for thread-safe use.

Returns:

A new independent instance.

Return type:

AttributeConverterBase

convert(self: pyvcad.pyvcad.AttributeConverterBase, samples: pyvcad.pyvcad.AttributeSamples) → pyvcad.pyvcad.AttributeSamples

Converts input samples to output samples.

Parameters:

samples (AttributeSamples) – The input samples to convert.

output_attributes(self: pyvcad.pyvcad.AttributeConverterBase) → list[str]

Returns the list of output attribute names produced by this converter.

required_attributes(self: pyvcad.pyvcad.AttributeConverterBase) → list[str]

Returns the list of required input attribute names.

class pyvcad.LookupTableEntry

A single entry in a lookup table.

For single-input STEP mode, [input_low, input_high] defines a threshold window. For multi-input STEP mode, pass a list of [low, high] ranges (one per input). For LINEAR mode, only input_low is used as the interpolation key.

__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: pyvcad.pyvcad.LookupTableEntry, input_low: typing.SupportsFloat, input_high: typing.SupportsFloat, output_values: collections.abc.Sequence[object]) -> None

Create a multi-output entry for single-input STEP mode.

  1. __init__(self: pyvcad.pyvcad.LookupTableEntry, input_low: typing.SupportsFloat, input_high: typing.SupportsFloat, output_value: object) -> None

Create a single-output entry for single-input STEP mode.

  1. __init__(self: pyvcad.pyvcad.LookupTableEntry, input: typing.SupportsFloat, output_value: object) -> None

Create a point-based entry for LINEAR mode.

  1. __init__(self: pyvcad.pyvcad.LookupTableEntry, input_ranges: collections.abc.Sequence[tuple[typing.SupportsFloat, typing.SupportsFloat]], output_values: collections.abc.Sequence[object]) -> None

Create a multi-input entry for independent STEP matching.

input_ranges: list of [low, high] pairs, one per input attribute. output_values: list of values, one per input (matched independently).

When the converter has 1 output, matched values are assembled (e.g. Vec3 + float -> Vec4 for color_rgba).

property input_high

Upper bound of the input range.

property input_low

Lower bound of the input range.

property input_ranges

Per-input ranges for multi-input mode.

property output_values

The output values for this entry.

class pyvcad.LookupTableConverter

A generic lookup-table-based attribute converter.

Maps input attribute value(s) to output attribute value(s) using a lookup table. Supports STEP (range-based threshold matching) and LINEAR (sorted-point interpolation with clamping) modes.

Single-input STEP example (HU to Color):
>>> entries = [
...     pv.LookupTableEntry(-1000, -500, pv.Vec4(0,0,0,0)),
...     pv.LookupTableEntry(-500, 0, pv.Vec4(1,0,0,0.5)),
... ]
>>> conv = pv.LookupTableConverter(['hu'], ['color_rgba'], entries, pv.InterpolationMode.STEP)
Multi-input STEP example (temperature -> RGB, density -> alpha):
>>> entries = [
...     pv.LookupTableEntry([(0, 1), (0, 0.01)], [pv.Vec3(1,1,1), 0.0]),
...     pv.LookupTableEntry([(1, 10), (0.01, 0.5)], [pv.Vec3(1,0,0), 0.5]),
... ]
>>> conv = pv.LookupTableConverter(
...     ['temperature', 'density'], ['color_rgba'],
...     entries, pv.InterpolationMode.STEP)
LINEAR example (temperature to flow rate):
>>> entries = [pv.LookupTableEntry(180, 1.0), pv.LookupTableEntry(220, 0.5)]
>>> conv = pv.LookupTableConverter(['temperature'], ['flow_rate'], entries, pv.InterpolationMode.LINEAR)
__init__(self: pyvcad.pyvcad.LookupTableConverter, input_attributes: collections.abc.Sequence[str], output_attributes: collections.abc.Sequence[str], entries: collections.abc.Sequence[pyvcad.pyvcad.LookupTableEntry], mode: pyvcad.pyvcad.InterpolationMode = <InterpolationMode.STEP: 0>) → None

Create a LookupTableConverter.

Parameters:

  • input_attributes (list[str]) – Names of the input attributes to read.

  • output_attributes (list[str]) – Names of the output attributes to produce.

  • entries (list[LookupTableEntry]) – The lookup table entries.

  • mode (InterpolationMode) – STEP or LINEAR (default: STEP).

clone(self: pyvcad.pyvcad.LookupTableConverter) → pyvcad.pyvcad.AttributeConverterBase
convert(self: pyvcad.pyvcad.LookupTableConverter, samples: pyvcad.pyvcad.AttributeSamples) → pyvcad.pyvcad.AttributeSamples
output_attributes(self: pyvcad.pyvcad.LookupTableConverter) → list[str]
required_attributes(self: pyvcad.pyvcad.LookupTableConverter) → list[str]
class pyvcad.ExpressionConverter

An attribute converter that evaluates mathematical expressions.

Input attribute names are used directly as variable names in the expression strings. 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.

Example (single output):
>>> conv = pv.ExpressionConverter(
...     input_attributes=['temperature'],
...     output_attributes=['flow_rate'],
...     expressions=['20 * temperature + 100'])
Example (multiple outputs):
>>> conv = pv.ExpressionConverter(
...     input_attributes=['hu'],
...     output_attributes=['modulus', 'toughness'],
...     expressions=['hu * 1000 + 500', '0.5 * hu + 10'])
__init__(self: pyvcad.pyvcad.ExpressionConverter, input_attributes: collections.abc.Sequence[str], output_attributes: collections.abc.Sequence[str], expressions: collections.abc.Sequence[str]) → None

Create an ExpressionConverter.

Parameters:

  • input_attributes (list[str]) – Names of the input attributes (used as variable names).

  • output_attributes (list[str]) – Names of the output attributes to produce.

  • expressions (list[str]) – Math expression strings, one per output attribute.

clone(self: pyvcad.pyvcad.ExpressionConverter) → pyvcad.pyvcad.AttributeConverterBase
convert(self: pyvcad.pyvcad.ExpressionConverter, samples: pyvcad.pyvcad.AttributeSamples) → pyvcad.pyvcad.AttributeSamples
output_attributes(self: pyvcad.pyvcad.ExpressionConverter) → list[str]
required_attributes(self: pyvcad.pyvcad.ExpressionConverter) → list[str]

Default attribute names and types

Default attribute constants