Cloud ¶

Cloud(points=None, attr_from=None, **attrs)

Bases: Geometry

Point-cloud geometry container.

Cloud stores a set of points and their attributes, with helpers to import/export from Blender data (Mesh or PointCloud), join other clouds, apply basic transforms, and generate common point distributions.

Attributes:

Name	Type	Description
`points`	`[Point][Point]`	Point domain storing per-point attributes (e.g., `position`, `normal`, ...).

Notes

This class focuses on point-only data. For topological data (faces/edges), use Mesh.
Blender interoperability accepts both bpy.types.Mesh and bpy.types.PointCloud when reading, but writing currently targets a Mesh data block (see to_data).

Initialize an empty cloud, optionally with points and attributes.

Parameters:

Name	Type	Description	Default
`points`	`array-like of shape (N, 3) or (N, D)`	Coordinates to append as `points.position`. If extra keys are present, pass them via `**attrs`.	`None`
`attr_from`	`object`	Source whose attribute schemas should be merged into this geometry, see `join_attributes`.	`None`
`**attrs`		Additional per-point attributes to append alongside `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)`.

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

capture ¶

capture(other)

Capture another cloud's buffers (no copy).

Parameters:

Name	Type	Description	Default
`other`	`Cloud`	Source cloud whose `points` buffer is adopted.	required

Returns:

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

check ¶

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

Validate the geometry consistency.

Placeholder in the base class: returns True. Subclasses may override to perform domain-level checks.

Parameters:

Name	Type	Description	Default
`title`	`str`	Label for messages or errors.	`"Geometry Check"`
`halt`	`bool`	Whether to raise on failure (in subclasses that implement checks).	`True`

Returns:

Type	Description
`bool`	Always `True` in the base class.

clear_geometry ¶

clear_geometry()

Clear all point data (schemas kept, values cleared).

Returns:

Type	Description
`None`

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_cloud `classmethod` ¶

from_cloud(other, selection=None)

Synonym of from_geometry.

Parameters:

Name	Type	Description	Default
`other`	`Cloud`		required
`selection`	`selection or None`		`None`

Returns:

Type	Description
`Cloud`

from_data `classmethod` ¶

from_data(data)

Initialize the cloud from Blender data (Mesh or PointCloud).

Parameters:

Name	Type	Description	Default
`data`	`Mesh or PointCloud or str`	A Blender data-block or a resolvable identifier accepted by [`blender.get_data`][npblender.blender.get_data].	required

Returns:

Type	Description
`Cloud`

Raises:

Type	Description
`ValueError`	If the data-block type is not supported.

from_dict `classmethod` ¶

from_dict(d)

Deserialize a cloud from a dictionary produced by to_dict.

Parameters:

Name	Type	Description	Default
`d`	`dict`	Serialized payload with at least the `"points"` key.	required

Returns:

Type	Description
`Cloud`	New instance with points loaded from `d`.

from_geometry `classmethod` ¶

from_geometry(other, selection=None)

Build a cloud from another geometry that has a point domain.

Parameters:

Name	Type	Description	Default
`other`	`[Geometry][Geometry]`	Source geometry (must have a `points` domain).	required
`selection`	`selection or None`	Selection on points to keep; if provided, the complement is deleted after copying.	`None`

Returns:

Type	Description
`Cloud`

Raises:

Type	Description
`ValueError`	If `other` has no `points` domain.

from_object `classmethod` ¶

from_object(obj, evaluated=False)

Create a cloud from an existing Blender object.

Parameters:

Name	Type	Description	Default
`obj`	`str or Object`	Object or name resolvable by [`blender.get_object`][npblender.blender.get_object].	required
`evaluated`	`bool`	If True, read from the evaluated object (modifiers applied).	`False`

Returns:

Type	Description
`Cloud`

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)

Append other clouds' points to this cloud.

Parameters:

Name	Type	Description	Default
`*others`	`Geometry`	One or more Geometries to concatenate.	`()`

Returns:

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

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

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

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

to_data ¶

to_data(data)

Write this cloud into a Blender Mesh data-block.

Parameters:

Name	Type	Description	Default
`data`	`Mesh or str`	Target mesh data (or identifier resolvable by [`blender.get_data`][npblender.blender.get_data]). The geometry is cleared and repopulated.	required

Returns:

Type	Description
`None`

Notes

Vertices are created to match the point count; per-point attributes are written to data.attributes.

Caution: This writes to a Mesh data-block (not PointCloud) because Blender’s Python API does not allow changing the point count of a PointCloud at runtime.

to_dict ¶

to_dict()

Serialize the cloud to a plain Python dictionary.

Returns:

Type	Description
`dict`	A dictionary with keys: `"geometry"` (`"Cloud"`) and `"points"`.

to_object ¶

to_object(obj, point_cloud=False, collection=None)

Create or update a Blender object from this cloud.

Parameters:

Name	Type	Description	Default
`obj`	`str or Object`	Object or name. If it does not exist, it is created.	required
`point_cloud`	`bool`	If True, convert the created mesh object to a `PointCloud` object.	`False`
`collection`	`str or Collection or None`	Collection to link a newly created object into.	`None`

Returns:

Type	Description
`Object`	The created/updated Blender object.

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

Cloud ¶

bounding_box property ¶

bounding_box_dims property ¶

max_size property ¶

add_materials ¶

apply_scale ¶

capture ¶

check ¶

clear_geometry ¶

compute_attribute_on_domain ¶

from_cloud classmethod ¶

from_data classmethod ¶

from_dict classmethod ¶

from_geometry classmethod ¶

from_object classmethod ¶

get_cubic_envelop ¶

get_material_index ¶

get_points_selection ¶

join ¶

join_attributes ¶

load_models staticmethod ¶

load_object staticmethod ¶

object ¶

rotate ¶

to_data ¶

to_dict ¶

to_object ¶

transform ¶

transformation ¶

translate ¶

bounding_box `property` ¶

bounding_box_dims `property` ¶

max_size `property` ¶

from_cloud `classmethod` ¶

from_data `classmethod` ¶

from_dict `classmethod` ¶

from_geometry `classmethod` ¶

from_object `classmethod` ¶

load_models `staticmethod` ¶

load_object `staticmethod` ¶