Vertex ¶
Vertex(a=None, mode='COPY', selector=None, attr_from=None, **attrs)
Vertex (mesh point) domain.
This domain represents mesh vertices. It provides fast utilities to transfer (map/average) any per-vertex attribute onto other mesh domains (faces, corners, edges).
Attributes:
Name | Type | Description |
---|---|---|
position |
(N, 3) float
|
World-space vertex positions inherited from :class: |
Notes
- Attribute transfers are implemented with Numba-jitted kernels for performance.
- When mapping to faces, values are averaged over all corners of each face.
Examples:
Map a per-vertex scalar to faces:
face_attr = vertices.compute_attribute_on_faces("mass", corners, faces)
Map a per-vertex vector to edges:
edge_attr = vertices.compute_attribute_on_edges("normal", edges)
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
|
mode
|
(COPY, CAPTURE, EMPTY)
|
Initialization mode. |
'COPY'
|
selector
|
Any
|
Optional row/element selector applied to |
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.
transdom_names
property
¶
transdom_names
List the names of trans-domain attributes.
Returns:
Type | Description |
---|---|
list of str
|
Names of attributes flagged with |
Examples:
names = D.transdom_names()
x
property
writable
¶
x
X coordinate accessor.
Shorthand for position[..., 0]
. Reading returns a view; assigning to
this property writes into the underlying position
field.
Returns:
Type | Description |
---|---|
ndarray
|
View of shape |
Examples:
Read and write x in place:
xs = points.x # view on position[..., 0]
points.x = xs + 1.0 # shift x by +1
Note: This is equivalent to
points.position[..., 0]
.
y
property
writable
¶
y
Y coordinate accessor.
Shorthand for position[..., 1]
. Reading returns a view; assigning to
this property writes into the underlying position
field.
Returns:
Type | Description |
---|---|
ndarray
|
View of shape |
Examples:
points.y = 0.0 # flatten all y to 0
z
property
writable
¶
z
Z coordinate accessor.
Shorthand for position[..., 2]
. Reading returns a view; assigning to
this property writes into the underlying position
field.
Returns:
Type | Description |
---|---|
ndarray
|
View of shape |
Examples:
points.z += 2.5
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. |
{}
|
apply_scale ¶
apply_scale(scale, pivot=None)
Apply per-axis scales to points, optionally about a pivot.
The scaling is broadcast across the domain using
[_get_shape_for_operation
][npblender._get_shape_for_operation].
If a pivot is given, points are moved to the local frame, scaled, then moved back.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
scale
|
array-like of shape ``(..., 3)``
|
Per-axis scale factors broadcastable to the domain size. |
required |
pivot
|
array-like of shape ``(..., 3)`` or None
|
Pivot location(s). If |
None
|
Returns:
Type | Description |
---|---|
PointDomain
|
Self (for chaining). |
Examples:
# A mesh made of 8 cubes
cubes = Mesh.cube(size=.2)*8
pv = np.random.uniform(-1, 1, (8, 3))
sc = np.random.uniform(.1, 1, (8, 3))
# Scale each cube individually
cubes.points.apply_scale(sc, pivot=pv)
Note: If broadcasting fails, a
ValueError
is raised by [_get_shape_for_operation
][npblender._get_shape_for_operation].
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. |
compute_attribute_on_corners ¶
compute_attribute_on_corners(attr, corners)
Scatter a per-vertex attribute to corners.
For each corner, copies the attribute of its associated vertex (via
corners.vertex_index
). The attribute is validated with
[_check_attribute_to_compute
][npblender._check_attribute_to_compute].
Parameters:
Name | Type | Description | Default |
---|---|---|---|
attr
|
str or ndarray, shape ``(N, ...)``
|
Vertex attribute to scatter. If a string, the field is looked up on this
domain; if an array, it must have length |
required |
corners
|
Corner
|
Corner domain providing the |
required |
Returns:
Type | Description |
---|---|
ndarray, shape ``(len(corners), ...)``
|
Corner attribute array (one value per corner), preserving the trailing item shape and dtype. |
Raises:
Type | Description |
---|---|
AttributeError
|
If |
IndexError
|
If |
Examples:
# Duplicate per-vertex colors to corners
corner_col = V.compute_attribute_on_corners("color", corners)
compute_attribute_on_edges ¶
compute_attribute_on_edges(attr, edges)
Average a per-vertex attribute over each edge.
For every edge, returns the mean of the attribute at its two endpoint
vertices ((v0, v1)
). The attribute is validated with
[_check_attribute_to_compute
][npblender._check_attribute_to_compute].
Parameters:
Name | Type | Description | Default |
---|---|---|---|
attr
|
str or ndarray, shape ``(N, ...)``
|
Vertex attribute to average. If a string, the field is looked up on this
domain; if an array, it must have length |
required |
edges
|
Edge
|
Edge domain providing |
required |
Returns:
Type | Description |
---|---|
ndarray, shape ``(len(edges), ...)``
|
Edge-wise averaged attribute. The trailing item shape is preserved and the dtype follows the input attribute. |
Raises:
Type | Description |
---|---|
AttributeError
|
If |
IndexError
|
If |
TypeError
|
If the attribute dtype is non-numeric or cannot be averaged (e.g., integer types with in-place division). |
Examples:
# Edge midpoints from vertex positions
edge_pos = V.compute_attribute_on_edges("position", edges)
# Average a custom per-vertex scalar on edges
edge_w = V.compute_attribute_on_edges(weights, edges)
Note: The average is unweighted:
0.5 * (attr[v0] + attr[v1])
.
compute_attribute_on_faces ¶
compute_attribute_on_faces(attr, corners, faces)
Average a per-vertex attribute over each face.
For every face, this computes the mean of the source vertex attribute over
all its incident corners (i.e., the face-wise average). The input attribute
can be given by name or as an array aligned with the vertex domain. The
attribute is validated with
[_check_attribute_to_compute
][npblender._check_attribute_to_compute].
Parameters:
Name | Type | Description | Default |
---|---|---|---|
attr
|
str or ndarray, shape ``(N, ...)``
|
Vertex attribute to aggregate. If a string, the corresponding field is
looked up on this domain; if an array, it must have length |
required |
corners
|
Corner
|
Corner domain providing the |
required |
faces
|
Face
|
Face domain providing |
required |
Returns:
Type | Description |
---|---|
ndarray, shape ``(len(faces), ...)``
|
Face-wise averaged attribute. The trailing item shape is preserved and the dtype follows the input attribute. |
Raises:
Type | Description |
---|---|
AttributeError
|
If |
IndexError
|
If |
TypeError
|
If the attribute dtype is non-numeric or cannot be averaged (e.g., integer types with in-place division). |
Notes
This routine computes an unweighted arithmetic mean over each face's corners.
See Also
compute_attribute_on_corners
:
Scatter vertex attributes to corners.
compute_attribute_on_edges
:
Average vertex attributes on edges.
Examples:
# Face centroids (average of vertex positions)
face_pos = V.compute_attribute_on_faces("position", corners, faces)
# Average any custom per-vertex float attribute
face_weight = V.compute_attribute_on_faces(weights, corners, faces)
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
|
target
|
(SCREEN, ...)
|
Output target. |
'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
( |
required |
copy
|
bool
|
|
False
|
Returns:
Type | Description |
---|---|
FieldArray
|
A new instance holding exactly |
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 |
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 |
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 |
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.FLOAT
data type is implemented asnp.float32
and 'INT' asnp.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 |
False
|
transfer
|
bool
|
If |
True
|
transdom
|
bool
|
If |
True
|
See Also
new_float
, new_vector
, new_int
, new_bool
, new_color
, new_vector2
,
new_quaternion
, new_matrix
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., |
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 |
(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 |
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 |
None
|
other_shape
|
tuple of int or None
|
Source reshape for |
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.
|
|
transform ¶
transform(transfo, pivot=None)
Apply a linear transform (e.g., rotation or transformation) to points.
If the transformation or pivot size is less than the domain size, the scale / pivot is applied on buckets of the same size if possible, otherwise an exception is raised.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
transfo
|
(Transformation, Rotation or Quaternion)
|
Transform(s) broadcastable to the domain size. Typical shapes include
|
required |
pivot
|
array-like of shape ``(..., 3)`` or None
|
Pivot location(s). If |
None
|
Returns:
Type | Description |
---|---|
PointDomain
|
Self (for chaining). |
Examples:
# A mesh made of 8 cubes
cubes = Mesh.cube(size=1)*8
pv = np.random.uniform(-1, 1, (8, 3))
rot = Rotation.from_euler(np.random.uniform(0, 2*np.pi, (8, 3)))
# Transform the 8 cubes indivicually
cubes.points.transform(rot, pivot=pv)
Examples:
# A mesh made of 8 cubes
cubes = Mesh.cube(size=1)*8
pv = np.random.uniform(-1, 1, (8, 3))
rot = Rotation.from_euler(np.random.uniform(0, 2*np.pi, (8, 3)))
# Transform the 8 cubes indivicually
cubes.points.transform(rot, pivot=pv)
translate ¶
translate(translation)
Translate points position by a vector or a batch of vectors.
Supports per-domain translation (single vector), or grouped/batched translations that broadcast over buckets of equal size.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
translation
|
array-like of shape ``(..., 3)``
|
Translation vectors broadcastable to the domain size. |
required |
Returns:
Type | Description |
---|---|
PointDomain
|
Self (for chaining). |
Examples:
# Per-point random translation
D.translate(np.random.uniform(-0.1, 0.1, (len(D), 3)))
```python
# A mesh made of 8 cubes
cubes = Mesh.cube(size=.2)*8
tr = np.random.uniform(-1, 1, (8, 3))
# Translate each cube individually
cubes.points.translate(tr)
Caution: If a provided batch cannot be aligned with the domain, a
ValueError
is raised by [_get_shape_for_operation
][npblender._get_shape_for_operation].