Domain ¶

Domain(a=None, mode='COPY', selector=None, attr_from=None, **attrs)

Initialize a domain array and its attribute schema.

Initializes the storage from an existing array/domain or creates an empty structure. Optionally merges attribute definitions/values from another domain and keyword-provided attributes.

Domains are never instancied directly but by owning geometries.

Actual Domains are Vertex, [Faces][npblender.Faces], Corner, Edge, ControlPoint, Spline and Point.

Domains are initialized with their defaults attributes, for instance position for point domaines.

Use attributes can be freely added.

Note: user attributes are saved in Blender Mesh objects only, Blender Curve objects don't store user attributes.

Parameters:

Name	Type	Description	Default
`a`	`array - like or FieldArray or None`	Source data used to initialize the domain. If `None`, an empty domain is created and `_declare_attributes()` is called to register defaults.	`None`
`mode`	`(COPY, CAPTURE, EMPTY)`	Initialization mode. `'COPY'` duplicates the input data, `'CAPTURE'` references the input buffer when supported, `'EMPTY'` creates the structure without copying values.	`'COPY'`
`selector`	`Any`	Optional row/element selector applied to `a` prior to initialization.	`None`
`attr_from`	`Domain or Mapping or None`	Attribute schema (and possibly values) to merge into this domain.	`None`
`**attrs`		Additional attribute name/value pairs to inject or override.	`{}`

Notes

The effective attribute list results from _declare_attributes(), then attr_from, then **attrs (later entries take precedence).

Examples:

cube = Mesh.cube() # points, corners, faces and edges domains are created
# Adding named attribute to point domain
cube.points.new_float('age')
# Setting the age
cube.points.age = np.random.uniforme(10, 10, len(cube.points))

actual_names `property` ¶

actual_names

Column names.

Returns the actual field names, excluding optional fields.

all_names `property` ¶

all_names

Column names.

Returns all the field names, including optional ones.

dtype `property` ¶

dtype

Array structured dtype

Returns the dtype property of the structured array.

transdom_names `property` ¶

transdom_names

List the names of trans-domain attributes.

Returns:

Type	Description
`list of str`	Names of attributes flagged with `transdom=True`.

Examples:

names = D.transdom_names()

array ¶

__array__(dtype=None)

Allow implicit conversion to np.ndarray

add ¶

add(count, **fields)

Add count records

New records are set with default values or values provided by the user in fields dict.

Parameters:

Name	Type	Description	Default
`count`	`int`	Number of records to add.	required
`fields`	`dict`	Keyword arguments mapping field names to values.	`{}`

append ¶

append(**fields)

Append values to the structured array.

The number of records to append is determined by the number of fields provided in the fields dictionary. The values of the fields are copied to the new records.

Parameters:

Name	Type	Description	Default
`fields`	`dict`	Keyword arguments mapping field names to values.	`{}`

as_kwargs ¶

as_kwargs(selector=None, include=None, exclude=None)

Return a dictionary of field values formatted as kwargs.

Parameters:

Name	Type	Description	Default
`selector`	`slice, int, list, or mask`	Optional selection of elements to extract.	`None`
`include`	`list[str]`	List of field names (original or python names) to include.	`None`
`exclude`	`list[str]`	List of field names (original or python names) to exclude.	`None`

Returns:

Type	Description
`dict`	Mapping from python-safe field names to array values.

copy_field ¶

copy_field(field_name, new_name, **infos)

Duplicate an existing field under a new name, with optional metadata overrides.

Parameters:

Name	Type	Description	Default
`field_name`	`str`	The name of the existing field to copy.	required
`new_name`	`str`	The name of the new field to create.	required
`infos`	`keyword arguments`	Optional metadata (e.g. default, unit, description...) to override or supplement the original field's metadata.	`{}`

Raises:

Type	Description
`KeyError`	If the source field does not exist.
`ValueError`	If the target name already exists or is reserved.

delete ¶

delete(index)

Delete a selection of items from the array.

Parameters:

Name	Type	Description	Default
`index`	`int, slice, or array-like`	The indices of the elements to delete from the current data.	required

Notes

This operates only on the valid range [0:self._length]. The internal buffer is preserved (no reallocation).

dump ¶

dump(title='Dump', attributes=None, target='SCREEN')

Pretty-print or export domain content.

Formats attribute values and prints to screen or builds a tabular dump suitable for spreadsheets.

Parameters:

Name	Type	Description	Default
`title`	`str`	Title displayed in the report.	`'Dump'`
`attributes`	`Sequence[str] or None`	Subset of attribute names to include. If `None`, all attributes are shown.	`None`
`target`	`(SCREEN, ...)`	Output target. `'SCREEN'` prints to stdout; other targets may trigger file creation depending on the implementation.	`'SCREEN'`

Returns:

Type	Description
`None`

Examples:

Domain(points).dump(title="Vertices")

Note: Formatting adapts to the chosen target.

extend ¶

extend(other, join_fields=True)

Append multiple records from another array or FieldArray.

Parameters:

Name	Type	Description	Default
`other`	`FieldArray or structured np.ndarray`	The array of records to append. Must have named fields matching a subset of the current array's fields.	required

filtered ¶

filtered(selector, *, copy=False)

Return a FieldArray containing only the selected records.

Parameters:

Name	Type	Description	Default
`selector`	`array‑like, slice or int`	Any valid NumPy 1‑D index: boolean mask, integer index/array, or slice. It is applied to the current valid part of the buffer (`self._data[:self._length]`).	required
`copy`	`bool`	False (default) => the new array shares the same memory (changes propagate both ways). True => the data are physically copied.	`False`

Returns:

Type	Description
`FieldArray`	A new instance holding exactly `len(selector)` records and inheriting the current field‑infos.

from_bl_attributes ¶

from_bl_attributes(bl_attributes)

Import attributes from a Blender attribute collection.

Reads geometry attributes from a Blender data-block and creates/updates the corresponding domain attributes, resizing the domain if needed.

Parameters:

Name	Type	Description	Default
`bl_attributes`	`Mapping[str, Any]`	Blender attributes collection (name → attribute descriptor) providing at least `.domain`, `.is_internal`, `.data_type`, and `.data`.	required

Returns:

Type	Description
`None`
`> *Note:* Only external (non-internal) Blender attributes matching this`
domain are imported. Missing attributes are created with `transfer=True`.

from_dict `classmethod` ¶

from_dict(data)

Build a FieldArray from a dictionary with field data and optional metadata.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, array - like or (array, dict)]`	Mapping field names to arrays or (array, infos). Infos must include NAME.	required
`copy`	`bool`	Whether to copy the data. Default: True.	required

Returns:

Type	Description
`FieldArray`

get ¶

get(name, default=None, broadcast_shape=None)

Get attribute by name.

If name is not an actual field, return default value. Name can be an array.

pos = field_array.get("position", (0, 0, 1))
pos = field_array.get([[0, 0, 1], [0, 0, 0]])

join_attributes ¶

join_attributes(other)

Merge trans-domain attributes from another domain.

Copies or aligns attributes from other into the current domain, excluding any attributes not flagged as trans-domain in other.

Parameters:

Name	Type	Description	Default
`other`	`Domain or None`	Source domain. If `None`, the call is a no-op.	required

Returns:

Type	Description
`Domain`	The domain itself (for chaining).

join_fields ¶

join_fields(other, exclude=[])

Add all missing fields from another FieldArray.

For every field in other that is not present in self, a new field is created with the same dtype and shape, and initialized with its default value across all existing records.

Parameters:

Name	Type	Description	Default
`other`	`FieldArray`	Another FieldArray instance whose fields will be checked for missing fields.	required

Returns:

Type	Description
`self`

make_buckets ¶

make_buckets(attr)

Group items into buckets by attribute value.

When a domain is to be considered as a collection of packets of various sizes, buckets mechanism groups pakets by size, allowing further operation with numpy vectorization.

Parameters:

Name	Type	Description	Default
`attr`	`array - like or str`	Either an integer of shape `(N,)` or the name of an existing integer attribute in the domain.	required

Returns:

Type	Description
`list[ndarray(count, n)]`	A list of int arrays (count, n): count is the number of buckets of length n.

Examples:

buckets = mesh.make_buckets('material')
for bucket in buckets:
    print(bucket.shape)

Note: The bucket attribute can be read with attr[bucket[:, 0]].

multiply ¶

multiply(count)

Duplicate the current records count times.

Parameters:

Name	Type	Description	Default
`count`	`int`	Number of times to repeat the current records.	required

Notes

This duplicates the current valid records (up to self._length). If the array is empty or count <= 1, nothing happens.

Example:

If the array has 3 records and count == 4, the result will be:

[rec0, rec1, rec2, rec0, rec1, rec2, rec0, rec1, rec2, rec0, rec1, rec2]

new_attribute ¶

new_attribute(name, data_type, default, optional=False, transfer=True, transdom=True)

Register a new attribute in the domain schema.

Creates (or ensures) an attribute with a given name, logical data type, default value, and flags controlling Blender transfer and cross-domain propagation.

Note: data_type argument is a Blender data type not a python data type. The data type name is compatible with Blender internal storage. FLOATdata type is implemented as np.float32 and 'INT' as np.int32.

Parameters:

Name	Type	Description	Default
`name`	`str`	Attribute name (Python identifier recommended).	required
`data_type`	`(FLOAT, INT, BOOL, VECTOR, VECTOR2, COLOR, QUATERNION, MATRIX, STRING, ...)`	Logical data type used by the domain.	`'FLOAT'`
`default`	`Any`	Default value for newly allocated elements.	required
`optional`	`bool`	If `True`, the attribute may be absent on some elements.	`False`
`transfer`	`bool`	If `True`, eligible to be transferred to Blender as a geometry attribute.	`True`
`transdom`	`bool`	If `True`, considered a trans-domain attribute that can be copied across compatible domains.	`True`

new_bool ¶

new_bool(name, default=False, optional=False, transfer=True, transdom=True)

Create or ensure a boolean attribute.

Parameters:

Name	Type	Description	Default
`name`	`str`	Attribute name.	required
`default`	`bool`	Default value.	`False`
`optional`	`bool`		`False`
`transfer`	`bool`		`True`
`transdom`	`bool`		`True`

new_color ¶

new_color(name, default=(0.5, 0.5, 0.5, 1.0), optional=False, transfer=True, transdom=True)

Create or ensure a color attribute.

Parameters:

Name	Type	Description	Default
`name`	`str`	Attribute name.	required
`default`	`array-like of shape (3,) or (4,)`	Default color as RGB or RGBA.	`(0.5, 0.5, 0.5, 1.0)`
`optional`	`bool`		`False`
`transfer`	`bool`		`True`
`transdom`	`bool`		`True`

new_field ¶

new_field(name, dtype, shape=None, default=0, optional=False, **infos)

Add a field to the structured array.

Arguments

- name (str) : field name
- dtype (type) : a valid numpy dtype
- shape (tuple = None) : the shape of the field
- default (any = 0) : default value
- optional (bool = False) : the field is created only when accessed
- infos (dict) : field infos

new_float ¶

new_float(name, default=0.0, optional=False, transfer=True, transdom=True)

Create or ensure a scalar float attribute.

Parameters:

Name	Type	Description	Default
`name`	`str`	Attribute name.	required
`default`	`float`	Default value.	`0.0`
`optional`	`bool`		`False`
`transfer`	`bool`		`True`
`transdom`	`bool`		`True`

new_int ¶

new_int(name, default=0, optional=False, transfer=True, transdom=True)

Create or ensure an integer attribute.

Parameters:

Name	Type	Description	Default
`name`	`str`	Attribute name.	required
`default`	`int`	Default value.	`0`
`optional`	`bool`		`False`
`transfer`	`bool`		`True`
`transdom`	`bool`		`True`

new_matrix ¶

new_matrix(name, default=np.eye(4), optional=False, transfer=True, transdom=True)

Create or ensure a matrix attribute.

Parameters:

Name	Type	Description	Default
`name`	`str`	Attribute name.	required
`default`	`array - like`	Default matrix. By convention this is a square matrix per element (e.g., `(3, 3)` rotation or `(4, 4)` transform).	`np.eye(4)`
`optional`	`bool`		`False`
`transfer`	`bool`		`True`
`transdom`	`bool`		`True`
`order`			required

new_quaternion ¶

new_quaternion(name, default=(0.0, 0.0, 0.0, 1.0), optional=False, transfer=True, transdom=True)

Create or ensure a quaternion attribute.

Parameters:

Name	Type	Description	Default
`name`	`str`	Attribute name.	required
`default`	`array-like of shape (4,)`	Default quaternion in `(x, y, z, w)` convention.	`(0.0, 0.0, 0.0, 1.0)`
`optional`	`bool`		`False`
`transfer`	`bool`		`True`
`transdom`	`bool`		`True`

new_vector ¶

new_vector(name, default=(0.0, 0.0, 0.0), optional=False, transfer=True, transdom=True)

Create or ensure a 3D vector attribute.

Parameters:

Name	Type	Description	Default
`name`	`str`	Attribute name.	required
`default`	`array-like of shape (3,)`	Default XYZ vector.	`(0.0, 0.0, 0.0)`
`optional`	`bool`		`False`
`transfer`	`bool`		`True`
`transdom`	`bool`		`True`

new_vector2 ¶

new_vector2(name, default=(0.0, 0.0), optional=False, transfer=True, transdom=True)

Create or ensure a 2D vector attribute.

Parameters:

Name	Type	Description	Default
`name`	`str`	Attribute name.	required
`default`	`array-like of shape (2,)`	Default XY vector.	`(0.0, 0.0)`
`optional`	`bool`		`False`
`transfer`	`bool`		`True`
`transdom`	`bool`		`True`

to_bl_attributes ¶

to_bl_attributes(attributes, update=False)

Export attributes to a Blender attribute collection.

Writes eligible domain attributes to a Blender data-block, creating missing attributes and adjusting sizes as needed.

Parameters:

Name	Type	Description	Default
`attributes`	`Any`	Blender attributes collection receiving the values.	required
`update`	`bool`	If `True`, update existing attributes in-place; otherwise create them when missing.	`False`

Returns:

Type	Description
`None`
> *Caution:* Only attributes with `transfer=True` are exported. Optional
`attributes are skipped.`
`> *Caution:* Curve domains user attributes are not saved.`

to_dict ¶

to_dict(*, copy=True, with_infos=True)

Convert the array to a dictionary of fields or (field, infos) pairs.

Parameters:

Name	Type	Description	Default
`copy`	`bool`	Whether to copy the arrays.	`True`
`with_infos`	`bool`	If True, return (array, infos) for each field.	`True`

Returns:

Type	Description
`dict[str, array or (array, dict)]`

transfer_attributes ¶

transfer_attributes(other, shape=None, other_shape=None)

Transfer values of trans-domain attributes from another domain.

Copies values for each trans-domain attribute present in other into the corresponding attributes of self, with optional reshaping for batched assignments.

Parameters:

Name	Type	Description	Default
`other`	`Domain`	Source domain providing attribute values.	required
`shape`	`tuple of int or None`	Target reshape for `self` before assignment. If `None`, uses `(self._length,)`.	`None`
`other_shape`	`tuple of int or None`	Source reshape for `other` before assignment. If `None`, uses `(other._length,)`.	`None`

Returns:

Type	Description
`Domain`	The domain itself (for chaining).
> *Note:* Each attribute is reshaped as `shape + item_shape` on `self`
and `other_shape + item_shape` on `other` prior to assignment.

Domain ¶

actual_names property ¶

all_names property ¶

dtype property ¶

transdom_names property ¶

__array__ ¶

add ¶

append ¶

as_kwargs ¶

copy_field ¶

delete ¶

dump ¶

extend ¶

filtered ¶

from_bl_attributes ¶

from_dict classmethod ¶

get ¶

join_attributes ¶

join_fields ¶

make_buckets ¶

multiply ¶

new_attribute ¶

new_bool ¶

new_color ¶

new_field ¶

new_float ¶

new_int ¶

new_matrix ¶

new_quaternion ¶

new_vector ¶

new_vector2 ¶

to_bl_attributes ¶

to_dict ¶

transfer_attributes ¶

actual_names `property` ¶

all_names `property` ¶

dtype `property` ¶

transdom_names `property` ¶

array ¶

from_dict `classmethod` ¶