Meshes ¶

Meshes(mesh=None, mesh_id=None, attr_from=None, **attributes)

Bases: Geometry

Bucketed mesh instances.

Meshes looks like instances, the difference being the each instance is different: - Instances : each point instance points on a model with model_index - Meshes : each point refers to vertices within Mesh.mesh attributes

To allow handling the individual pieces in with vectorization, the pieces are groupded in buckets of the same size (same number of vertices).

It is possible to iterate on pieces sharing the same size:

for bucket, offset in meshes:
    # bucket is an array (npieces, nverts) of vertex indices in `meshes.mesh.points`
    # offset is the first point index in `meshes.points`
    # meshes.points[offset:offset + bucket.shape[0]] represent all the bucket pieces
    pass

Attributes:

Name	Type	Description
`mesh`	`[Mesh][Mesh]`	The source mesh containing all vertices (possibly many concatenated copies).
`points`	`[Point][Point]`	Per-piece attributes. At least `position` is present (piece centroid).
`buckets`	`list[ndarray]`	List of arrays with shape `(n_pieces, piece_vertex_count)` indexing rows into `mesh.points` for each bucket size.

Notes

Buckets are created by grouping vertices per piece size (same vertex count), then stacking each contiguous group into a 2D array; points.position holds the centroid of each row and the mesh is recentered so that row-local vertices are around the origin. :contentReference[oaicite:1]{index=1}

Initialize bucketed mesh instances.

Parameters:

Name	Type	Description	Default
`mesh`	`[Mesh][Mesh] or None`	Mesh to be bucketized. If `None`, creates an empty container.	`None`
`mesh_id`	`array - like or None`	Per-vertex group id used to split the mesh into pieces (passed to `mesh.points.make_buckets`).	`None`
`attr_from`	`[Geometry][Geometry] or None`	Geometry to copy attribute schemas from (matching domain names).	`None`
`**attributes`		Extra per-piece attributes appended to `points`.	`{}`

bounding_box `property` ¶

bounding_box

Axis-aligned bounding box of the point positions.

Returns:

Type	Description
`tuple of numpy.ndarray`	`(min_xyz, max_xyz)`. If empty, returns two zero vectors.

bounding_box_dims `property` ¶

bounding_box_dims

Extents of the axis-aligned bounding box.

Returns:

Type	Description
`numpy.ndarray of shape (3,)`	`max_xyz - min_xyz`.

max_size `property` ¶

max_size

Maximum dimension of the bounding box.

Returns:

Type	Description
`float`	`max(bounding_box_dims)`.

mesh_id `property` ¶

mesh_id

Per-piece identifiers aligned with the flattened bucket rows.

Returns:

Type	Description
`numpy.ndarray of dtype int`	Vector of ids assigning each row (piece) to its bucket index. The length matches the concatenation of bucket rows (see iteration order). :contentReference[oaicite:7]{index=7}

add_materials ¶

add_materials(materials)

Append material name(s) to the geometry.

Parameters:

Name	Type	Description	Default
`materials`	`str or sequence of str`	One name or a sequence of names to append.	required

Returns:

Type	Description
`None`

Notes

This method does not deduplicate names; duplicates may be appended.

apply_scale ¶

apply_scale(scale, pivot=None)

Scale points (convenience wrapper).

See: transformation

Parameters:

Name	Type	Description	Default
`scale`	`ndarray`	Per-point or broadcastable scales.	required
`pivot`	`ndarray`	Optional pivot(s) for scaling.	`None`

Returns:

Type	Description
`Geometry`	`self`.

check ¶

check(title='Meshes Check', halt=True)

Validate internal consistency between buckets and points.

Verifies that the total number of rows across all buckets equals len(points). When invalid, prints diagnostics and either raises (if halt=True) or returns False.

Parameters:

Name	Type	Description	Default
`title`	`str`	Message prefix for diagnostics.	`"Meshes Check"`
`halt`	`bool`	If True, raise via assertion on failure.	`True`

Returns:

Type	Description
`bool`	True when consistent; False when inconsistent and `halt=False`.

Raises:

Type	Description
`AssertionError`	If inconsistent and `halt=True`. :contentReference[oaicite:6]{index=6}

clear_geometry ¶

clear_geometry()

Reset to an empty state.

Clears the mesh, empties points, and removes all buckets.

Returns:

Name	Type	Description
`None`	`contentReference[oaicite:17]{index=17}`

compute_attribute_on_domain ¶

compute_attribute_on_domain(domain_from, attr, domain_to)

Transfer an attribute from one domain to another.

Performs a domain mapping (e.g., points → faces) using the appropriate domain operator, and returns the computed array on the target domain.

Parameters:

Name	Type	Description	Default
`domain_from`	`str`	Source domain name (e.g., `"points"`, `"faces"`, `"edges"`, `"corners"`, `"splines"`).	required
`attr`	`str or ndarray`	Source attribute to transfer. If a string, it is looked up on the source domain; if an array, it must match the source domain length.	required
`domain_to`	`str`	Target domain name.	required

Returns:

Type	Description
`ndarray`	Attribute values on the target domain. If `domain_from == domain_to`, returns `attr` unchanged.

Raises:

Type	Description
`AttributeError`	If either `domain_from` or `domain_to` is not a valid domain of this geometry.
`Exception`	If the requested mapping is not implemented.

Notes

Implemented mappings include: - points → faces: [Point.compute_attribute_on_faces][npblender.Point.compute_attribute_on_faces] - points → edges: [Point.compute_attribute_on_edges][npblender.Point.compute_attribute_on_edges] - points → corners: [Point.compute_attribute_on_corners][npblender.Point.compute_attribute_on_corners] - points → splines: [Point.compute_attribute_on_splines][npblender.Point.compute_attribute_on_splines] - faces → points: Face.compute_attribute_on_points - edges → points: Edge.compute_attribute_on_points - corners → points: Corner.compute_attribute_on_points

from_dict `classmethod` ¶

from_dict(d)

Deserialize a Meshes produced by to_dict.

Parameters:

Name	Type	Description	Default
`d`	`dict`	Serialized payload.	required

Returns:

Type	Description
`Meshes`	Reconstructed instance with mesh, points and buckets restored. :contentReference[oaicite:11]{index=11}

from_mesh_islands `classmethod` ¶

from_mesh_islands(mesh)

Build Meshes by splitting a mesh into face islands.

Computes face islands on mesh, transfers the island id to the point domain, then uses it as mesh_id to create buckets.

Parameters:

Name	Type	Description	Default
`mesh`	`[Mesh][Mesh]`	Source mesh.	required

Returns:

Type	Description
`Meshes`	New instance with one piece per island. :contentReference[oaicite:9]{index=9}

from_meshes `classmethod` ¶

from_meshes(meshes)

Copy-construct a Meshes from another Meshes.

Duplicates the source mesh, copies the bucket lists, and clones the per-piece point domain.

Parameters:

Name	Type	Description	Default
`meshes`	`Meshes`	Source `Meshes` to copy from.	required

Returns:

Type	Description
`Meshes`

Raises:

Type	Description
`AttributeError`	If `meshes` is not a `Meshes` instance. :contentReference[oaicite:8]{index=8}

get_cubic_envelop ¶

get_cubic_envelop()

Return a cube mesh that encloses the geometry’s bounding box.

Uses the bounding box dimensions to build a cube via Mesh.cube, forwarding this geometry’s materials if present.

Returns:

Type	Description
`Mesh`	A cube mesh sized to the bounding box.

get_material_index ¶

get_material_index(mat_name)

Return the index of a material name, creating it if needed.

Parameters:

Name	Type	Description	Default
`mat_name`	`str`	Material name to look up or append.	required

Returns:

Type	Description
`int`	Index of `mat_name` in `self.materials`.

Notes

If mat_name is not present, it is appended to self.materials and the new index is returned.

get_points_selection ¶

get_points_selection()

Selection of points relevant to operations.

Returns slice(None) in the base class (all points). Subclasses (e.g., curves) may override to select only referenced points.

Returns:

Type	Description
`slice`	`slice(None)` by default.

join ¶

join(*others)

Concatenate other Meshes into this one.

Appends the other mesh data, then merges their buckets: rows with the same piece vertex count are concatenated; new sizes create new entries.

Parameters:

Name	Type	Description	Default
`*others`	`Meshes`	Other `Meshes` objects to append.	`()`

Returns:

Type	Description
`Meshes`	`self`, for chaining.

Raises:

Type	Description
`AttributeError`	If any input is not a `Meshes`. :contentReference[oaicite:13]{index=13}

join_attributes ¶

join_attributes(other, **kwargs)

Merge attribute schemas from another geometry.

For each domain listed in self.domain_names and also present in other, copies (joins) the attribute definitions (names, dtypes, metadata) from other into this geometry's domains. Use keyword flags to include/exclude domains by name (e.g., faces=False).

Parameters:

Name	Type	Description	Default
`other`	`Geometry or None`	Source geometry. If `None`, does nothing and returns `self`.	required
`**kwargs`		Per-domain boolean switches to filter which domains to join.	`{}`

Returns:

Type	Description
`Geometry`	`self`, for chaining.

Examples:

mesh.join_attributes(other_mesh, faces=False)
curve.join_attributes(mesh)  # only common domains are merged

load_models `staticmethod` ¶

load_models(*specs)

Load multiple geometries from collections, objects, or instances.

Accepts mixed inputs such as Blender collections, Blender objects, lists/ tuples of either, or already-instantiated Mesh/Curve. Returns a flat list of geometries discovered or constructed.

This method is mainly intended to be used by Instances to load its models.

Parameters:

Name	Type	Description	Default
`*specs`		Collections, objects, lists/tuples, or `Mesh`/`Curve` instances.	`()`

Returns:

Type	Description
`list`	List of geometries (`Mesh`/`Curve`).

Raises:

Type	Description
`ValueError`	If a spec cannot be resolved to a geometry.

load_object `staticmethod` ¶

load_object(name)

Load a Blender object and return a Mesh or a Curve.

Resolves name to a Blender object, inspects its data type, and returns a matching geometry by calling the subclass' from_object.

Parameters:

Name	Type	Description	Default
`name`	`str or Object`	Object name or object instance.	required

Returns:

Type	Description
`Mesh or Curve or None`	A `Mesh` or a `Curve`, or `None` if the object is not found.

Raises:

Type	Description
`Exception`	If the object exists but is neither a `bpy.types.Mesh` nor `bpy.types.Curve`.

Examples:

geo = Geometry.load_object("MyObject")
if geo is not None:
    print(type(geo).__name__)

multiply ¶

multiply(count, in_place=True)

Duplicate all pieces count times.

Buckets are offset by the source mesh vertex count to index the newly appended mesh copies; both the points domain and the mesh are multiplied accordingly.

Parameters:

Name	Type	Description	Default
`count`	`int`	Number of copies to create.	required
`in_place`	`bool`	If True, expand this instance; otherwise return a new expanded copy.	`True`

Returns:

Type	Description
`Meshes or None`	`self` (in place) or a new `Meshes`; `None` if `count == 0`. :contentReference[oaicite:14]{index=14}

object ¶

object(index=0, readonly=True, **kwargs)

Temporary access to a Blender Object built from this geometry.

Creates a transient object (named "BPBL Temp {index}" unless index is a string), selects and activates it, yields it for editing, then cleans up. If readonly=True, the edited object is captured back into self.

This method can be used to set and apply a modifier (see exemple below).

Parameters:

Name	Type	Description	Default
`index`	`int or str`	Index or name used to label the temporary object.	`0`
`readonly`	`bool`	If `False`, re-capture the possibly edited object back into this geometry.	`True`
`kwargs`	`dict`	Keyword arguments passed to `self.to_object`.	`{}`

Yields:

Type	Description
`Object`	The temporary Blender object built from `self`.

Examples:

plane = Mesh.Grid()
with plane.object(readonly=False) as obj:
    mod = obj.modifiers.new("Solidify", 'SOLIDIFY')
    mod.thickness = .1
    bpy.ops.object.modifier_apply(modifier=mod.name)

# plane is now solidifed

realize ¶

realize()

Realize the bucketed pieces into a concrete mesh.

Copies the source mesh, joins per-piece point attributes (other than position) additively into the mesh per-vertex fields for each row, and applies per-piece transforms (rotation/scale/translation) to the vertices addressed by each bucket.

Returns:

Type	Description
`[Mesh][Mesh]`	A mesh with all pieces transformed into world placement. :contentReference[oaicite:12]{index=12}

rotate ¶

rotate(rotation, pivot=None)

Rotate points (convenience wrapper).

See: transformation

Parameters:

Name	Type	Description	Default
`rotation`	`ndarray or Rotation - like`	Rotation(s) to apply as `R @ v`.	required
`pivot`	`ndarray`	Optional pivot(s) for rotation.	`None`

Returns:

Type	Description
`Geometry`	`self`.

set_mesh_points_attribute ¶

set_mesh_points_attribute(domain_name, name, value)

Broadcast a per-piece value to a per-vertex mesh attribute.

Looks up mesh.points[name], broadcasts value to (len(self), *attr_shape), then writes the piece value to all vertices of each row in the buckets.

Parameters:

Name	Type	Description	Default
`domain_name`	`str`	Unused placeholder (kept for API symmetry).	required
`name`	`str`	Name of the mesh point attribute to write.	required
`value`	`array - like`	Value(s) per piece, broadcastable to the attribute shape.	required

Returns:

Type	Description
`None`

Raises:

Type	Description
`KeyError`	If the mesh point attribute `name` does not exist. :contentReference[oaicite:18]{index=18}

to_dict ¶

to_dict()

Serialize to a plain dictionary.

Returns:

Type	Description
`dict`	Keys: `"geometry" = "Meshes"`, `"points"`, `"mesh"`, `"buckets"`. :contentReference[oaicite:10]{index=10}

transform ¶

transform(transformation)

Apply a rotation matrix or batch of matrices.

See: transformation

Parameters:

Name	Type	Description	Default
`transformation`	`ndarray`	Rotation matrix or batch of rotation matrices.	required

Returns:

Type	Description
`Geometry`	`self`.

transformation ¶

transformation(rotation=None, scale=None, translation=None, pivot=None)

Apply rotation/scale/translation (with optional per-packet broadcasting).

Operates in-place on points.position and, when present, Bezier handles (points.handle_left, points.handle_right). Shapes can represent packets of points: broadcasting rules are handled by [Point._get_shape_for_operation][npblender.Point._get_shape_for_operation].

Parameters:

Name	Type	Description	Default
`rotation`	`ndarray or Rotation - like`	Rotation matrix/matrices applied as `R @ v`. Shape may broadcast over points (see notes).	`None`
`scale`	`ndarray`	Per-axis scaling. Shape may broadcast over points.	`None`
`translation`	`ndarray`	Per-point translation. Shape may broadcast over points.	`None`
`pivot`	`ndarray`	Pivot(s) subtracted before, and added after, the rotation/scale; same broadcasting rules as `scale`/`translation`.	`None`

Returns:

Type	Description
`Geometry`	`self`, for chaining.

Notes

If handles exist, they are transformed consistently with positions.

Examples:

# 12 cubes laid out randomly with per-instance transforms
cubes = Mesh.cube(size=1).multiply(12)
T = np.random.uniform(-1, 1, (12, 3))
S = np.random.uniform(0.5, 2.0, (12, 3))
R = Rotation.from_euler(np.random.uniform(0, 2*np.pi, (12, 3)))
cubes.transformation(rotation=R, scale=S, translation=T)

translate ¶

translate(translation)

Translate points (convenience wrapper).

See: transformation

Parameters:

Name	Type	Description	Default
`translation`	`ndarray`	Per-point or broadcastable translation vectors.	required

Returns:

Type	Description
`Geometry`	`self`.

Meshes ¶

bounding_box property ¶

bounding_box_dims property ¶

max_size property ¶

mesh_id property ¶

add_materials ¶

apply_scale ¶

check ¶

clear_geometry ¶

compute_attribute_on_domain ¶

from_dict classmethod ¶

from_mesh_islands classmethod ¶

from_meshes classmethod ¶

get_cubic_envelop ¶

get_material_index ¶

get_points_selection ¶

join ¶

join_attributes ¶

load_models staticmethod ¶

load_object staticmethod ¶

multiply ¶

object ¶

realize ¶

rotate ¶

set_mesh_points_attribute ¶

to_dict ¶

transform ¶

transformation ¶

translate ¶

bounding_box `property` ¶

bounding_box_dims `property` ¶

max_size `property` ¶

mesh_id `property` ¶

from_dict `classmethod` ¶

from_mesh_islands `classmethod` ¶

from_meshes `classmethod` ¶

load_models `staticmethod` ¶

load_object `staticmethod` ¶