Mesh ¶

Mesh(points=None, corners=None, faces=None, edges=None, materials=None, attr_from=None, **attrs)

Bases: Geometry

Initialize a Mesh Geometry object.

Parameters:

Name	Type	Description	Default
`points`	`array_like`	The vertices of the mesh (default is None).	`None`
`corners`	`array_like of int`	Corners, i.e., indices on the array of points (default is None).	`None`
`faces`	`array_like of int`	Sizes of the faces; the sum of this array must be equal to the length of the corners array (default is None).	`None`
`edges`	`array_like of tuple of int`	List of edges defined by pairs of vertex indices (default is None).	`None`
`materials`	`str or list of str`	List of materials used in the geometry. If a single string is provided, it is converted to a list containing that string (default is None).	`None`
`attr_from`	`Geometry`	Domain attributes to copy from another Geometry object (default is None).	`None`
`**attrs`	`dict`	Additional geometry attributes.	`{}`

Attributes:

Name	Type	Description
`points`	`Vertex`	The vertices of the mesh.
`corners`	`Corner`	The corners of the mesh.
`faces`	`Face`	The faces of the mesh.
`edges`	`Edge`	The edges of the mesh.
`materials`	`list of str`	The list of materials used in the geometry.

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_geometry ¶

add_geometry(points=None, corners=None, faces=None, edges=None, safe_mode=False, **attrs)

Add geometry components (vertices, corners, faces, edges) to the mesh.

This method appends the specified geometry to the mesh without altering existing indices. It supports referencing existing vertices through corners or adding new vertices.

Note: To add independent geometry with new vertices, use [Mesh.join_geometry][npblender.Mesh.joint_geometry] instead.

Examples:

``` python
cube = Mesh.cube()
# Add a triangle on existing vertices
# corners argument refers to cube vertices
cube.add_geometry(corners=[0, 1, 2], faces=3)

# Add a triangle with additional vertices
# corners argument refers to the new vertices, passed values [0, 1, 2]
# will be shifted to actual values [8, 9, 10]
cube.join_geometry(points=[[0, 0, 0], [0, 1, 0], [1, 0, 0]], corners=[0, 1, 2], faces=3)
```

Parameters:

Name	Type	Description	Default
`points`	`array-like of vectors`	Vertices to add to the mesh.	`None`
`corners`	`array-like of int`	Indices referring to vertices in the points array.	`None`
`faces`	`int, array-like of int, or list of lists`	Defines the faces topology: - If `corners` is provided: - None: Single face made of all corners. - int: All faces have the same size (must divide the number of corners). - array-like: Face sizes; sum must equal the number of corners. - If `corners` is None: - Must be a list of lists, each sublist is a list of corners.	`None`
`edges`	`array-like of pairs of int`	Edges defined by pairs of vertex indices.	`None`
`safe_mode`	`bool`	If True, perform a mesh integrity check after adding geometry.	`False`
`**attrs`	`dict`	Additional geometry attributes to apply.	`{}`

Returns:

Type	Description
`dict`	Dictionary with keys {'points', 'corners', 'faces', 'edges'} mapping to lists of added geometry indices.

Raises:

Type	Description
`ValueError`	If faces and corners lengths are inconsistent or invalid.

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.

add_points ¶

add_points(points, **attributes)

Add vertices.

Arguments

- points (array of vectors) : the vertices to add
- attributes (name=value) : value for named attributes

Returns:

Type	Description
`- array of ints : indices of the added vertices`

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

arrow `classmethod` ¶

arrow(vector=(0, 0, 1), radius=0.05, angle=24.0, segments=8, adjust_norm=None, materials=None)

Create an arrow mesh oriented along a given vector.

The arrow is composed of a cylindrical shaft and a conical head, proportionally scaled to the length of the input vector.

Parameters:

Name	Type	Description	Default
`vector`	`array-like of float, shape (3,)`	Direction and length of the arrow. The norm of the vector defines the arrow length. Default is (0, 0, 1).	`(0, 0, 1)`
`radius`	`float`	Radius of the cylindrical shaft. Default is 0.05.	`0.05`
`angle`	`float`	Opening angle of the conical head in degrees. Default is 24.	`24.0`
`segments`	`int`	Number of segments around the circumference. Default is 8.	`8`
`adjust_norm`	`(callable, float, None)`	If callable: a function applied to the vector norm to adjust the arrow length. If float: the arrow length is clamped to this maximum. If None: use the norm of `vector` directly. Default is None.	`callable`
`materials`	`list of str`	List of material names to assign to the arrow. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the arrow.

Notes

The shaft is created with cylinder.
The head is created with cone using fill_type='FANS' for proper triangulation.
The arrow is aligned to vector using [Rotation.look_at][npblender.rotation.Rotation.look_at].
A small correction is applied to avoid overlap between shaft and head.

Examples:

Create a default arrow of length 1 along Z:

arrow = Mesh.arrow()

Create an arrow along vector (1, 2, 0.5) with custom shaft radius:

arrow = Mesh.arrow(vector=(1, 2, 0.5), radius=0.1)

Create an arrow clamped to maximum length 2:

arrow = Mesh.arrow(vector=(0, 0, 5), adjust_norm=2)

See Also

cylinder : Used to create the arrow shaft. cone : Used to create the arrow head. [Rotation.look_at][npblender.rotation.Rotation.look_at] : Utility to orient the arrow along a target vector.

Caution: If vector has zero length, the arrow cannot be constructed properly.

Note: The conical head radius is set to 3 * radius by default, and its height is determined by the opening angle.

bl_circle `classmethod` ¶

bl_circle(radius=1, segments=16, fill_tris=False, materials=None)

Create a circle mesh.

Blender constructor for generating a circle primitive using bmesh.ops.create_circle.

Parameters:

Name	Type	Description	Default
`radius`	`float`	Radius of the circle. Default is 1.	`1`
`segments`	`int`	Number of segments (vertices) forming the circle. Default is 16.	`16`
`fill_tris`	`bool`	If True, fills the circle with a triangle fan. Default is False.	`False`
`materials`	`list of str`	List of material names to assign to the circle. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the circle.

Notes

The circle is created using bmesh.ops.create_circle with calc_uvs=True so UV coordinates are automatically generated.
By default (fill_tris=False), the circle is an open ring. With fill_tris=True, the circle is filled with triangles (fan topology).

Examples:

Create an empty circle of radius 2 with 32 segments:

circle = Mesh.bl_circle(radius=2, segments=32)

Create a filled circle (disk) of radius 1 with 24 segments:

circle = Mesh.bl_circle(radius=1, segments=24, fill_tris=True)

See Also

bmesh.ops.create_circle : BMesh operator used for creating a circle primitive.

Note: UVs are automatically calculated when the circle is created.

bl_cone `classmethod` ¶

bl_cone(radius1=1, radius2=0, depth=2, segments=16, side_segments=1, cap_ends=True, cap_tris=False, materials=None)

Create a cone mesh.

Blender constructor for generating a cone (or cylinder) primitive using bmesh.ops.create_cone.

Parameters:

Name	Type	Description	Default
`radius1`	`float`	Base radius of the cone. Default is 1.	`1`
`radius2`	`float`	Top radius of the cone. If set to 0, produces a true cone; if equal to `radius1`, produces a cylinder. Default is 0.	`0`
`depth`	`float`	Height of the cone along the Z axis. Default is 2.	`2`
`segments`	`int`	Number of segments around the circumference. Default is 16.	`16`
`side_segments`	`int`	Number of subdivisions along the vertical side edges. Default is 1 (no subdivision).	`1`
`cap_ends`	`bool`	If True, fill the top and bottom caps. Default is True.	`True`
`cap_tris`	`bool`	If True, fill the caps using triangle fans instead of n-gons. Default is False.	`False`
`materials`	`list of str`	List of material names to assign to the cone. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the cone.

Notes

The cone is created using bmesh.ops.create_cone with calc_uvs=True so UV coordinates are automatically generated.
When side_segments > 1, vertical edges crossing the top and bottom are subdivided using bmesh.ops.subdivide_edges.

Examples:

Create a simple cone with radius 1 and height 2:

cone = Mesh.bl_cone(radius1=1, radius2=0, depth=2, segments=16)

Create a cylinder with 32 segments and subdivided sides:

cylinder = Mesh.bl_cone(radius1=1, radius2=1, depth=3,
                        segments=32, side_segments=4)

Create a cone with filled caps using triangle fans:

cone = Mesh.bl_cone(radius1=1, radius2=0, depth=2,
                    cap_ends=True, cap_tris=True)

See Also

bmesh.ops.create_cone : BMesh operator used for creating cone and cylinder primitives. bmesh.ops.subdivide_edges : BMesh operator used for subdividing vertical edges when side_segments > 1.

Note: UVs are automatically calculated when the cone is created.

bl_grid `classmethod` ¶

bl_grid(x_segments=1, y_segments=1, size=2, materials=None)

Create a grid mesh.

Blender constructor for generating a grid primitive using bmesh.ops.create_grid.

Parameters:

Name	Type	Description	Default
`x_segments`	`int`	Number of segments along the X axis. Default is 1.	`1`
`y_segments`	`int`	Number of segments along the Y axis. Default is 1.	`1`
`size`	`float or tuple of float`	Size of the grid. If a single float is given, the grid is square. If a tuple is given, defines the grid dimensions along X and Y. Default is 2.	`2`
`materials`	`list of str`	List of material names to assign to the grid. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the grid.

Notes

The grid is created using bmesh.ops.create_grid with calc_uvs=True so UV coordinates are automatically generated.

Examples:

Create a 10x10 grid of size 5:

grid = Mesh.bl_grid(x_segments=10, y_segments=10, size=5)

Create a rectangular grid 4x8 of size (2, 5):

grid = Mesh.bl_grid(x_segments=4, y_segments=8, size=(2, 5))

See Also

bmesh.ops.create_grid : BMesh operator used for creating a grid primitive.

Note: UVs are automatically calculated when the grid is created.

blender_data ¶

blender_data(readonly=False)

Context manager to access the Blender Mesh API with a temporary mesh.

This method transfers the current mesh geometry to a temporary Blender Mesh data block, yields it for reading or modification, and optionally captures the changes back into the mesh.

Example usage:

mesh = Mesh.Cube()

with mesh.blender_data() as data:
    normals = np.array([poly.normal for poly in data.polygons])

print(normals)
# Output:
# [[-1. -0.  0.]
#  [ 0.  1.  0.]
#  [ 1. -0.  0.]
#  [ 0. -1.  0.]
#  [ 0.  0. -1.]
#  [ 0. -0.  1.]]

Parameters:

Name	Type	Description	Default
`readonly`	`bool`	If True, the geometry is not read back from the Blender Mesh after modification. Default is False.	`False`

Yields:

Type	Description
`Mesh`	A temporary Blender Mesh data block representing the mesh geometry.

bmesh ¶

bmesh(readonly=False)

Context manager to access and manipulate the mesh using Blender's BMesh API.

This method creates a temporary BMesh from the mesh data, yields it for modification, and then writes back the changes to the mesh data unless in readonly mode.

Example usage:

mesh = Mesh.Cube()

# Move the vertices with bmesh
with mesh.bmesh() as bm:
    for v in bm.verts:
        v.co.x += 1.0

# Move the vertices directly in numpy array
mesh.points.position[:, 1] += 1

# Cube moved along x and y
mesh.to_object("Cube")

Parameters:

Name	Type	Description	Default
`readonly`	`bool`	If True, changes made to the BMesh are not written back to the mesh data (default is False).	`False`

Yields:

Type	Description
`BMesh`	A BMesh object representing the mesh data, which can be modified within the context.

boolean ¶

boolean(other, operation='DIFFERENCE')

Apply a boolean CSG operation with another mesh object and return the result.

Parameters:

Name	Type	Description	Default
`other`	`Mesh`	The mesh used as the boolean operand.	required
`operation`	`(INTERSECT, UNION, DIFFERENCE)`	Type of boolean operation to perform. Default is 'DIFFERENCE'.	`'INTERSECT'`

Returns:

Type	Description
`Mesh`	A new mesh instance created from the object after applying the Boolean modifier.

Notes

Internally, a Blender Boolean modifier is added to self, pointing to other, and then applied via bpy.ops.object.modifier_apply.
The result is read back as a new mesh using Mesh.from_object.
Context managers object are used to obtain temporary Blender objects for both meshes.

Examples:

Subtract B from A:

result = A.boolean(B, operation='DIFFERENCE')

Compute the union:

result = A.boolean(B, operation='UNION')

Keep only the intersection:

result = A.boolean(B, operation='INTERSECT')

See Also

Mesh.from_object : Converts a Blender object back into a mesh wrapper. object : Context manager yielding a temporary Blender object.

Warning: Applying the modifier is destructive to the underlying Blender object for self (its mesh data is changed). The method returns a new mesh instance representing the modified result.

Caution: Ensure operation is one of {'INTERSECT', 'UNION', 'DIFFERENCE'}; other values are invalid for Blender's Boolean modifier.

bridge_loops ¶

bridge_loops(loop0, loop1, close=False, segments=1, **attributes)

Create a grid connecting two vertex loops of equal size.

The operation selects the edges forming each loop and bridges them using bmesh.ops.bridge_loops. If segments > 1, the newly created edges are subdivided to form a denser grid between the loops.

Parameters:

Name	Type	Description	Default
`loop0`	`array-like of int`	The first loop of vertex indices.	required
`loop1`	`array-like of int`	The second loop of vertex indices. Must have the same length as `loop0`.	required
`close`	`bool`	If True, the loops are treated as closed and the first vertex is appended at the end to close the cycle. Default is False.	`False`
`segments`	`int`	Number of segments to subdivide between the loops. Must be >= 1. Default is 1 (no subdivision).	`1`
`**attributes`	`dict`	Additional attributes to set on the mesh after bridging (passed as keyword arguments).	`{}`

Returns:

Type	Description
`None`	Modifies the mesh in place. Returns `None`.

Notes

Edges belonging to each loop are identified by sorting endpoint pairs and matching them against the current BMesh edge list via a structured dtype view and np.isin.
Bridging is performed with bmesh.ops.bridge_loops.
When segments > 1, subdivision of the bridge edges is performed with bmesh.ops.subdivide_edges using cuts=segments - 1 and use_grid_fill=False.

Examples:

Bridge two loops with no subdivision:

obj.bridge_loops(loop0, loop1, segments=1)

Bridge two closed loops with 3 subdivisions:

obj.bridge_loops(loop0, loop1, close=True, segments=3)

See Also

bmesh.ops.bridge_loops : BMesh operator for bridging edge loops. bmesh.ops.subdivide_edges : BMesh operator for subdividing edges.

Warning: This function modifies the mesh in place and may create new vertices/edges/faces. Handle undo/history in Blender if needed.

Caution: Both loops must have the same number of vertices for correct bridging.

Note: When close=True, the first vertex of each loop is duplicated at the end to ensure cyclic connectivity.

bvh_tree ¶

bvh_tree(count=None)

Build a Blender BVH tree for fast spatial queries (ray casting, overlap, nearest point, etc.).

Parameters:

Name	Type	Description	Default
`count`	`int`	If `None`, build a single BVH tree for the whole mesh. If an integer `count` is provided, the mesh is assumed to represent a batch of `count` sub-meshes laid out in a structured array, and a list of BVH trees (one per sub-mesh) is returned.	`None`

Returns:

Type	Description
`BVHTree or list of BVHTree`	If `count` is `None`, a single `BVHTree` instance built from the current mesh. If `count` is an integer, a list of `BVHTree` objects, one for each sub-mesh.

Notes

Internally uses mathutils.bvhtree.BVHTree.FromPolygons.
When count is given, vertices are reshaped to (count, n, 3) and faces are assumed to be identical across all sub-meshes.
epsilon=0.0 is used for exact geometry.

Examples:

Build a single BVH tree:

tree = mesh.bvh_tree()
loc, normal, index, dist = tree.ray_cast((0, 0, 10), (0, 0, -1))

Build multiple BVH trees for a batch of 5 sub-meshes:

trees = mesh.bvh_tree(count=5)
for t in trees:
    print(t.find_nearest((0, 0, 0)))

Caution: When count is provided, the mesh must be structured consistently: faces are taken from the first sub-mesh and reused for all.

capture ¶

capture(other)

Capture the data of another Mesh.

Arguments

- other (Mesh) : the mesh to capture

Returns:

Type	Description
`- self`

chain_link `classmethod` ¶

chain_link(major_segments=48, minor_segments=12, radius=1.0, section=0.5, length=4.0, materials=None)

Create a single chain link (oval torus with straightened sides).

The link is built from a torus of major radius radius and tube radius section / 2. If length > 2 * radius, the torus is split in half, translated to open a gap of size delta = length - 2 * radius, mirrored, then the opposite borders are bridged to form the elongated link. UVs are adjusted to keep a clean seam layout.

Parameters:

Name	Type	Description	Default
`major_segments`	`int`	Number of segments around the major loop. Default is 48.	`48`
`minor_segments`	`int`	Number of segments around the tube section. Default is 12.	`12`
`radius`	`float`	Major radius of the link (half the distance between opposite sides on the long axis before elongation). Default is 1.0.	`1.0`
`section`	`float`	Diameter of the link cross-section (tube thickness). Default is 0.5.	`0.5`
`length`	`float`	Target overall length of the link along its long axis. If close to `2 * radius`, the result is essentially a pure torus. Default is 4.0.	`4.0`
`materials`	`list of str`	Material names to assign to the link. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the chain link.

Notes

Construction steps: 1) Create a torus with torus. 2) Delete approximately half the vertices on the negative Y side with delete_vertices. 3) Duplicate and mirror the remaining half to the other side. 4) Bridge the facing border loops with bridge_loops (twice, crossing). 5) Recompute and assign UVs using [grid_uv_map][npblender.grid_uv_map] to distribute the texture coordinates and minimize stretching.
When length - 2 * radius is smaller than ~radius / 10, the method returns the original torus since elongation would be negligible.

Examples:

Create a standard chain link:

link = Mesh.chain_link(major_segments=64, minor_segments=16,
                    radius=0.5, section=0.12, length=1.6)

Create a thicker, longer link:

link = Mesh.chain_link(radius=1.0, section=0.25, length=3.0)

See Also

torus : Base primitive used to start the link. delete_vertices : Used to remove half of the torus before mirroring. bridge_loops : Used to reconnect mirrored borders. [grid_uv_map][npblender.grid_uv_map] : Generates UVs for the final link surface. from_mesh : Utility for duplicating mesh halves before joining.

Caution: Very small section relative to major_segments can create skinny triangles near the bridged areas. Increase segment counts or section for cleaner topology.

Note: If length <= 2 * radius, no elongation is performed and the result is (nearly) identical to a torus of the given parameters.

check ¶

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

Check if mesh domains (corners, faces, edges) are consistent.

This method verifies the consistency of the mesh domains by checking the validity of corners, faces, and edges relative to the number of points. In development mode, it raises an exception to prevent Blender from crashing if inconsistencies are found.

Parameters:

Name	Type	Description	Default
`title`	`str`	Title prefix for error messages (default is "Mesh Check").	`'Mesh Check'`
`halt`	`bool`	If True, raise an exception on failure; otherwise, print a warning (default is True).	`True`

Returns:

Type	Description
`bool`	True if all checks pass; otherwise, raises an exception or prints an error.

Raises:

Type	Description
`Exception`	If the check fails and halt is True.

circle `classmethod` ¶

circle(radius=1, segments=16, fill_segments=0, cap='NONE', materials=None)

Create a circle mesh.

The circle can be created as: - An open ring (cap='NONE'). - A filled n-gon (cap='NGON'). - A triangle fan (cap='FANS').

The argument fill_segments controls how the interior of the circle is filled: - If fill_segments == 0 and cap='NGON', the circle is filled with a single polygon. - If fill_segments > 0, the circle is filled with concentric rings and triangle fans (not yet implemented in this method, but the behavior corresponds to cap='FANS').

Note: The disk method provides the same functionality with cap='NGON' as its default mode.

Parameters:

Name	Type	Description	Default
`radius`	`float`	Radius of the circle. Default is 1.	`1`
`segments`	`int`	Number of segments (vertices) around the circle. Default is 16.	`16`
`fill_segments`	`int`	Number of internal subdivisions (concentric circles). If 0, the circle is filled with a single polygon when `cap='NGON'`. Default is 0.	`0`
`cap`	`(NONE, NGON, FANS)`	How to fill the interior of the circle. Default is 'NONE'.	`'NONE'`
`materials`	`list of str`	List of material names to assign to the circle. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the circle.

Notes

cap='NONE': returns only the ring of edges.
cap='NGON': fills the circle with a polygon face.
cap='FANS': fills the circle with a fan of triangles around a central point.
UV coordinates are generated with [disk_uv_map][npblender.disk_uv_map].
Fan topology is generated with [fans_corners][npblender.fans_corners].

Examples:

Create an open circle with 32 segments:

circle = Mesh.circle(radius=1, segments=32, cap='NONE')

Create a filled disk using an n-gon:

circle = Mesh.circle(radius=2, segments=24, cap='NGON')

Create a filled disk with triangle fans:

circle = Mesh.circle(radius=1, segments=16, cap='FANS')

See Also

disk : Equivalent method for creating disks (default cap='NGON'). [disk_uv_map][npblender.disk_uv_map] : Generates UV coordinates for circular caps. [fans_corners][npblender.fans_corners] : Generates corner topology for triangle fans.

Caution: When using cap='FANS', a new center vertex is added.

clear_geometry ¶

clear_geometry()

Clear the geometry by deleting all geometric content.

This method clears the points, corners, faces, and edges collections, effectively removing all geometric data from the mesh.

Note: The materials list associated with the mesh remains unchanged.

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

cone `classmethod` ¶

cone(vertices=32, side_segments=1, fill_segments=1, radius_top=0, radius_bottom=1, depth=2, fill_type='NGON', materials=None)

Create a cone (or cylinder) mesh.

Parameters:

Name	Type	Description	Default
`vertices`	`int`	Number of vertices around the circumference. Default is 32.	`32`
`side_segments`	`int`	Number of subdivisions along the vertical side edges. Default is 1 (no subdivision).	`1`
`fill_segments`	`int`	Number of concentric circles added to the caps. Currently unused. Default is 1.	`1`
`radius_top`	`float`	Radius of the top face. Default is 0 (cone).	`0`
`radius_bottom`	`float`	Radius of the bottom face. Default is 1.	`1`
`depth`	`float`	Height of the cone along the Z axis. Default is 2.	`2`
`fill_type`	`(NGON, FANS, NONE)`	Type of filling for the top and bottom caps: - `'NGON'`: fill with n-gons. - `'FANS'`: fill with triangle fans. - `'NONE'`: no cap filling. Default is `'NGON'`.	`'NGON'`
`materials`	`list of str`	List of material names to assign to the mesh. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the cone.

Notes

If both radius_top and radius_bottom are zero, the result is an empty mesh.
Internally calls bl_cone with cap_ends and cap_tris derived from fill_type.
UVs are generated automatically by Blender's cone operator.

Examples:

Create a simple cone of height 2 and base radius 1:

cone = Mesh.cone(vertices=32, radius_top=0, radius_bottom=1, depth=2)

Create a cylinder with 16 vertices and subdivided sides:

cylinder = Mesh.cone(vertices=16, radius_top=1, radius_bottom=1,
                    depth=3, side_segments=3)

Create a cone with triangle fan caps:

cone = Mesh.cone(vertices=24, radius_top=0, radius_bottom=2,
                depth=4, fill_type='FANS')

See Also

bl_cone : Low-level constructor for cones and cylinders. bl_circle : For creating circle primitives with optional triangle fan filling.

Note: Use fill_type='NONE' to create an open-ended cone or cylinder.

cube `classmethod` ¶

cube(size=2, materials=None)

Create a cube mesh.

Parameters:

Name	Type	Description	Default
`size`	`float or array-like of shape (3,)`	Size of the cube. If a single float is given, the cube is uniform in all dimensions. If an array of three floats is given, it specifies the size along the X, Y, and Z axes. Default is 2.	`2`
`materials`	`list of str`	List of material names to assign to the cube. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the cube.

Notes

The cube is created centered at the origin with side length size.
UV coordinates are assigned so that all six faces are unwrapped into a cross-like layout.

Examples:

Create a default cube of size 2:

cube = Mesh.cube()

Create a cube of size 5:

cube = Mesh.cube(size=5)

Create a rectangular box of dimensions (2, 3, 4):

box = Mesh.cube(size=(2, 3, 4))

See Also

Mesh : The mesh class used to construct and manage geometry.

Note: The cube is centered at the origin and scaled by size/2 after construction.

cylinder `classmethod` ¶

cylinder(vertices=32, side_segments=1, radius=1, depth=2, fill_type='NGON', materials=None)

Create a cylinder mesh.

Parameters:

Name	Type	Description	Default
`vertices`	`int`	Number of vertices around the circumference. Default is 32.	`32`
`side_segments`	`int`	Number of subdivisions along the vertical side edges. Default is 1 (no subdivision).	`1`
`radius`	`float`	Radius of both the top and bottom faces. Default is 1.	`1`
`depth`	`float`	Height of the cylinder along the Z axis. Default is 2.	`2`
`fill_type`	`(NGON, FANS, NONE)`	Type of filling for the top and bottom caps: - `'NGON'`: fill with n-gons. - `'FANS'`: fill with triangle fans. - `'NONE'`: no cap filling. Default is `'NGON'`.	`'NGON'`
`materials`	`list of str`	List of material names to assign to the mesh. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the cylinder.

Notes

Internally calls bl_cone with radius1 = radius2 = radius.
UVs are generated automatically by Blender's cone operator.

Examples:

Create a default cylinder of radius 1 and height 2:

cyl = Mesh.cylinder()

Create a cylinder with 64 vertices and 4 vertical subdivisions:

cyl = Mesh.cylinder(vertices=64, side_segments=4, radius=2, depth=5)

Create an open cylinder without caps:

cyl = Mesh.cylinder(radius=1, depth=3, fill_type='NONE')

See Also

bl_cone : Low-level constructor for cones and cylinders. cone : Generalized method for cones and cylinders.

Note: This method is a convenience wrapper for bl_cone with equal top and bottom radii.

delete_faces ¶

delete_faces(selection)

Delete only the selected faces from the mesh.

Parameters:

Name	Type	Description	Default
`selection`	`array-like of int or bool`	Indices or boolean mask specifying which faces to delete.	required

Returns:

Type	Description
`None`	Modifies the mesh in place. Returns `None`.

See Also

[delete_loops][npblender.Faces.delete_loops] : Method used internally to remove the corners and faces. [corners][npblender.Mesh.corners] : Corner array of the mesh, used to identify face connectivity.

Warning: This function permanently deletes faces and their associated corners. Handle undo/history in Blender if needed.

Note: Only faces are removed. Edges and vertices remain in the mesh unless explicitly deleted by other operations.

delete_vertices ¶

delete_vertices(points=None, faces=None, edges=None)

Delete vertices from the mesh, with optional selection by points, faces, or edges.

A vertex is deleted if it is explicitly listed in points, or if it belongs to any of the given faces or edges.

Parameters:

Name	Type	Description	Default
`points`	`array-like of int or bool`	Vertex indices (or boolean mask) specifying which vertices to delete directly.	`None`
`faces`	`array-like of int or bool`	Face indices (or boolean mask). Any vertex belonging to these faces will be deleted.	`None`
`edges`	`array-like of int or bool`	Edge indices (or boolean mask). Any vertex belonging to these edges will be deleted.	`None`

Returns:

Type	Description
`None`	Modifies the mesh in place. Returns `None`.

Notes

At least one of points, faces, or edges must be provided, otherwise the function does nothing.
The deletion is executed using bmesh.ops.delete with context='VERTS'.

Examples:

Delete specific vertices:

obj.delete_vertices(points=[0, 1, 2])

Delete all vertices belonging to certain faces:

obj.delete_vertices(faces=[10, 11])

Delete all vertices belonging to certain edges:

obj.delete_vertices(edges=[5, 6, 7])

See Also

bmesh.ops.delete : Blender BMesh operator used for deleting geometry.

Warning: This function permanently removes vertices and any connected geometry (edges, faces). Handle undo/history in Blender if needed.

Note: If multiple selectors (points, faces, edges) are provided, the union of all matched vertices will be deleted.

disk `classmethod` ¶

disk(radius=1, segments=16, fill_segments=0, cap='NGON', materials=None)

Create a disk mesh.

This is equivalent to circle, but with cap='NGON' as the default filling mode.

Parameters:

Name	Type	Description	Default
`radius`	`float`	Radius of the disk. Default is 1.	`1`
`segments`	`int`	Number of segments (vertices) around the disk. Default is 16.	`16`
`fill_segments`	`int`	Number of internal subdivisions (concentric circles). Default is 0 (single n-gon when `cap='NGON'`).	`0`
`cap`	`(NONE, NGON, FANS)`	How to fill the interior of the disk. Default is 'NGON'.	`'NONE'`
`materials`	`list of str`	List of material names to assign to the disk. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the disk.

Examples:

Create a default disk of radius 2 with 32 segments:

disk = Mesh.disk(radius=2, segments=32)

Create a disk filled with triangle fans:

disk = Mesh.disk(radius=1, segments=16, cap='FANS')

See Also

circle : General method for circle/disk creation with customizable cap. [disk_uv_map][npblender.disk_uv_map] : Generates UV coordinates for circular caps. [fans_corners][npblender.fans_corners] : Generates corner topology for triangle fans.

Note: This method is a shorthand for circle(..., cap='NGON').

dual ¶

dual(center='median')

Construct the dual mesh: one vertex per original face, and one face per original vertex (linking adjacent face-centers around that vertex).

Parameters:

Name	Type	Description	Default
`center`	`(median, bounds, weighted)`	Method to compute the position of each dual vertex (i.e., the center of the corresponding original face): - `'median'`: face median center (`BMFace.calc_center_median`). - `'bounds'`: face bounds center (`BMFace.calc_center_bounds`). - `'weighted'`: area-weighted center (`BMFace.calc_center_median_weighted`). Default is `'median'`.	`'median'`

Returns:

Type	Description
`Mesh`	The dual mesh, where: - points = centers of original faces, - faces = polygons formed by chaining the adjacent original faces around each original vertex.

Raises:

Type	Description
`ValueError`	If `center` is not one of `{'median', 'bounds', 'weighted'}`.

Notes

For each original face f, a dual vertex is computed using the chosen center method and stored at index f.index.
For each original vertex v, its incident faces are ordered by walking across v’s incident edges (each with exactly two linked faces) to form a cyclic sequence of face indices; this ordered loop becomes a polygon in the dual.
Non-manifold or boundary configurations (edges with a number of linked faces different from 2) are skipped for that vertex; no dual face is created in such cases.

Examples:

Build the dual using area-weighted face centers:

d = mesh.dual(center='weighted')

Build the dual with bounds centers:

d = mesh.dual(center='bounds')

See Also

triangulate : Triangulation can improve robustness before dualization. remove_doubles : Helpful for cleaning geometry prior to constructing the dual.

Caution: On meshes with boundaries or non-manifold edges, some vertices may not yield a valid cyclic ordering of adjacent faces; those dual faces are omitted.

Note: Dualization does not, in general, invert perfectly (i.e., the dual of the dual is not guaranteed to reproduce the original mesh), especially in the presence of boundaries or irregular valences.

extrude_faces ¶

extrude_faces(selection, offset=None, scale=1.0)

Extrude individual faces by duplicating them, optionally displacing them by offset, and connecting side faces.

Parameters:

Name	Type	Description	Default
`selection`	`array-like of int or bool, or None`	Indices (or mask) of faces to extrude. If `None`, all faces are extruded.	required
`offset`	`(array - like, shape(3) or (N, 3))`	Extrusion vector(s). A single vector is broadcast to all faces. If `None`, each face is extruded along its own normal.	`None`
`scale`	`float`	Scale factor applied to `offset` (or to the face normal if `offset=None`). Default is 1.0.	`1.0`
`dissolve`	`bool`	Not implemented in this version. Placeholder for removing the starting faces after extrusion.	required

Returns:

Type	Description
`dict`	Dictionary with two keys: - `'top'`: indices of the extruded (displaced) faces. - `'side'`: indices of the side faces connecting the original and new faces.

Raises:

Type	Description
`ValueError`	If `offset` cannot be broadcast to shape `(len(faces), 3)`.
`AssertionError`	If a side edge of an extruded face does not have exactly two linked faces.

Notes

Uses bmesh.ops.extrude_discrete_faces to duplicate each selected face independently.
If offset is None, displacement is along each face's local normal.
Side faces are identified by checking edges linked to the extruded faces.

Examples:

Extrude all faces along their normals:

res = Mesh.extrude_faces(selection=None, scale=0.2)

Extrude a subset of faces by a fixed offset:

res = Mesh.extrude_faces(selection=[0, 2, 5], offset=(0, 0, 1))

Extrude faces with per-face offsets:

offs = np.random.randn(len(sel), 3) * 0.1
res = Mesh.extrude_faces(selection=sel, offset=offs)

See Also

extrude_vertices : Extrude isolated vertices. extrude_loop : Extrude a vertex loop into a quad strip.

Caution: If offset is given per-face, its length must match the number of extruded faces or broadcasting will fail.

Note: Side face indices may be repeated if multiple extrusions share edges.

extrude_loop ¶

extrude_loop(loop, offset, close=False, clockwise=False, **attributes)

Extrude a loop of vertices by duplicating the loop, offsetting it, and creating a quad strip between the original and the offset loop.

Parameters:

Name	Type	Description	Default
`loop`	`array-like of int`	Vertex indices defining the loop to extrude. Must contain at least 2 vertices.	required
`offset`	`(array - like, shape(3) or (N, 3))`	Extrusion vector(s). A single 3D vector is broadcast to all vertices in `loop`, or provide one vector per vertex (N == len(loop)).	required
`close`	`bool`	If True, treats the input as a closed loop and connects the last vertex back to the first when building side quads. Default is False.	`False`
`clockwise`	`bool`	Controls the orientation (winding) of the generated faces and the UV layout. Default is False.	`False`
`**attributes`	`dict`	Extra attributes intended for the new geometry (see *Caution*).	`{}`

Returns:

Type	Description
`dict`	Dictionary describing the created geometry as returned by `add_geometry`. Contains at least: - `'points'`: indices of the duplicated (offset) vertices. - `'corners'`: indices of the generated quad strip corners. - `'faces'`: face arity (4 for quads).

Raises:

Type	Description
`AttributeError`	If `offset` is neither a single `(3,)` vector nor an array of shape `(len(loop), 3)`.

Notes

New vertices are computed as points[loop] + offset (with broadcasting if offset is a single vector).
Side faces are constructed using the topology from [grid_corners][npblender.grid_corners] with two rows (original and offset loop).
UVs for the side strip are generated by [grid_uv_map][npblender.grid_uv_map] with matching parameters.

Examples:

Extrude an open loop along a single vector:

new = Mesh.extrude_loop(loop, offset=(0, 0, 1), close=False)

Extrude a closed loop with per-vertex offsets and flipped winding:

offs = np.random.randn(len(loop), 3) * 0.02
new = Mesh.extrude_loop(loop, offset=offs, close=True, clockwise=True)

See Also

extrude_vertices : Extrude isolated vertices with edges to their duplicates. add_geometry : Adds the new points/corners/faces and returns their indices. [grid_corners][npblender.grid_corners] : Builds the quad topology of the side strip. [grid_uv_map][npblender.grid_uv_map] : Generates UVs for the side strip.

Caution: offset must be either a single (3,) vector or an array of shape (len(loop), 3). Any other shape will raise an error.

Caution: The attributes kwargs are currently not forwarded to add_geometry in this implementation. If you need them applied, pass them through explicitly in the call to add_geometry.

extrude_region ¶

extrude_region(selection, offset=(0, 0, 1), dissolve=False)

Extrude a connected face region, translate the new geometry by offset, and optionally dissolve the original faces.

Parameters:

Name	Type	Description	Default
`selection`	`array-like of int or bool, or None`	Indices (or mask) of faces to extrude. If `None`, all faces are used.	required
`offset`	`array-like of float, shape (3,)`	Translation vector applied to the newly created vertices of the region. Default is (0, 0, 1).	`(0, 0, 1)`
`dissolve`	`bool`	If True, delete the original (pre-extrusion) faces after the region has been extruded. Default is False.	`False`

Returns:

Type	Description
`dict`	Dictionary with two keys: - `'top'`: indices of the newly extruded faces (translated region). - `'side'`: indices of the side faces that connect original and new faces.

Raises:

Type	Description
`AssertionError`	If a side edge of an extruded face does not have exactly two linked faces (non-manifold condition).

Notes

Region extrusion is performed via bmesh.ops.extrude_face_region, then the new vertices are moved using bmesh.ops.translate.
Side faces are discovered by scanning the edges of the extruded faces and collecting the adjacent face opposite to each extruded face.

Examples:

Extrude a region upward and keep the original faces:

res = Mesh.extrude_region(selection=[0, 1, 2], offset=(0, 0, 0.2), dissolve=False)

Extrude a region and dissolve the starting faces:

res = Mesh.extrude_region(selection=mask, offset=(0.1, 0, 0), dissolve=True)

See Also

extrude_faces : Extrude faces individually (discrete), not as a connected region. extrude_loop : Create a quad strip by offsetting a vertex loop. extrude_vertices : Duplicate and connect selected vertices.

Caution: offset must be a 3D vector. Non-3D inputs may cause the translation operator to fail.

Note: With dissolve=True, the original faces are removed, leaving only the extruded shell.

extrude_vertices ¶

extrude_vertices(selection, offset, **attributes)

Extrude individual vertices by creating new points displaced by offset and connecting each original vertex to its duplicate with an edge.

Parameters:

Name	Type	Description	Default
`selection`	`array-like of int or bool, or None`	Vertex indices or boolean mask selecting the vertices to extrude. If `None`, all vertices are extruded.	required
`offset`	`(array - like, shape(3) or (N, 3))`	Extrusion vector(s). Can be a single 3D vector applied to every selected vertex, or an array of vectors with one per selected vertex.	required
`**attributes`	`dict`	Optional attributes to attach to the created geometry (forwarded to `add_geometry`).	`{}`

Returns:

Type	Description
`dict`	Dictionary describing the created geometry as returned by `add_geometry`. Contains at least: - `'points'`: indices of newly added vertices. - `'edges'`: indices of newly added edges.

Raises:

Type	Description
`AttributeError`	If `offset` is neither a single `(3,)` vector nor an array of shape `(len(loop), 3)`.

Notes

New vertices are positioned at points[selection] + offset.
One edge is created between each original vertex and its newly created counterpart using [edges_between][npblender.edges_between].

Examples:

Extrude all vertices by (0, 0, 1):

added = Mesh.extrude_vertices(selection=None, offset=(0, 0, 1))

Extrude a subset with per-vertex offsets:

sel = np.array([0, 2, 5, 7])
offs = np.random.randn(len(sel), 3) * 0.1
added = Mesh.extrude_vertices(selection=sel, offset=offs)

See Also

add_geometry : Adds new points/edges/faces and returns their indices. [edges_between][npblender.edges_between] : Builds edge pairs between two index arrays of equal length.

Caution: When offset is an array, its length must match the number of selected vertices.

Note: This operation creates only points and edges. Faces are not generated automatically.

faces_neighbors ¶

faces_neighbors()

Compute the neighboring faces for each face, defined as faces sharing at least one edge.

Returns:

Type	Description
`list of list of int`	For each face (by index), a list of indices of adjacent faces.

Notes

Each face’s neighbors are determined by scanning its incident edges and collecting the two faces linked to each edge.
The current face index is excluded from its own neighbor list.
Non-manifold edges (with more or fewer than two linked faces) are not expected; if present, results may be incomplete or inconsistent.

Examples:

Get adjacency information for all faces:

neighbors = mesh.faces_neighbors()
for i, ns in enumerate(neighbors):
    print(f"Face {i} neighbors: {ns}")

Note: The output is a Python list of lists (not a NumPy array).

fill_cap ¶

fill_cap(loop, mode='NGON', center=None, segments=1, clockwise=False, **attributes)

Fill a cap between vertices forming a loop.

Supports two modes: - NGON: creates a single n-gon face from the loop. No center point is required. - FANS: creates a fan of triangles around a center point. The center can be: * None: automatically computed as the centroid of the loop. * int: the index of an existing vertex to use as center. * array-like: explicit coordinates of the center, which will be added as a new vertex.

Parameters:

Name	Type	Description	Default
`loop`	`array-like of int`	The vertex indices defining the loop.	required
`mode`	`(NGON, FANS)`	Fill mode to use. Default is 'NGON'.	`'NGON'`
`center`	`int or array - like or None`	Center of the cap (used only in 'FANS' mode). - `None`: computed centroid. - `int`: index of an existing vertex. - array-like: coordinates of a new vertex.	`None`
`segments`	`int`	Number of radial subdivisions for FANS mode. Must be >= 1. Default is 1 (no subdivision).	`1`
`clockwise`	`bool`	Whether the loop is ordered clockwise. Default is False.	`False`
`**attributes`	`dict`	Additional attributes to add to the mesh (passed to `add_geometry`).	`{}`

Returns:

Type	Description
`dict`	A dictionary of the newly added geometry, as returned by `add_geometry`. Includes at least keys for 'faces' and 'corners'. In FANS mode, also includes the added 'points' if a new center is created.

Notes

In 'NGON' mode, a UV map is generated using [disk_uv_map][npblender.Mesh.disk_uv_map].
In 'FANS' mode, the fan topology is created with [fans_corners][npblender.Mesh.fans_corners] and UVs are generated with [disk_uv_map][npblender.Mesh.disk_uv_map].
If segments > 1 in FANS mode, radial edges are subdivided using split_edges.

Examples:

Fill a loop with an n-gon:

obj.fill_cap(loop, mode='NGON')

Fill a loop with a triangle fan around an automatically computed center:

obj.fill_cap(loop, mode='FANS')

Fill a loop with a fan using an existing vertex as the center and add 3 subdivisions:

obj.fill_cap(loop, mode='FANS', center=42, segments=3)

See Also

add_geometry : Method used to add the created geometry to the mesh. split_edges : Used to subdivide radial edges in FANS mode. [disk_uv_map][npblender.Mesh.disk_uv_map] : Generates UV coordinates for circular caps. [fans_corners][npblender.Mesh.fans_corners] : Generates corner topology for FANS mode.

Warning: This function modifies the mesh in place and may create new vertices, faces, and edges.

Caution: In FANS mode, if center=None, a new vertex is added at the centroid of the loop.

Note: The segments parameter only applies to FANS mode; NGON mode always produces a single polygon face.

from_dict `classmethod` ¶

from_dict(d)

Create a Mesh instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
`d`	`dict`	Dictionary containing mesh data with keys 'materials', 'points', 'corners', 'faces', and 'edges'.	required

Returns:

Type	Description
`Mesh`	A new Mesh instance initialized with the data from the dictionary.

from_mesh `classmethod` ¶

from_mesh(other, points=None, faces=None, edges=None)

Create a copy of a Mesh object, optionally excluding specified points, faces, or edges.

Parameters:

Name	Type	Description	Default
`other`	`Mesh`	The source Mesh object to copy.	required
`points`	`array-like of int`	Indices of points to exclude from the copy.	`None`
`faces`	`array-like of int`	Indices of faces to exclude from the copy.	`None`
`edges`	`array-like of int`	Indices of edges to exclude from the copy.	`None`

Returns:

Type	Description
`Mesh`	A new Mesh instance copied from the source, with specified elements excluded.

from_mesh_data `classmethod` ¶

from_mesh_data(data)

Initialize the geometry from a Blender Mesh data.

This method creates and returns an instance of the mesh class initialized with vertices, edges, faces, corners, materials, and attributes extracted from the provided Blender mesh data.

Args: data: Blender mesh data or object that can be processed by the blender.get_mesh function to obtain a Blender Mesh instance.

Returns: An instance of the mesh class initialized with the geometry and attributes from the Blender Mesh.

Raises: ImportError: If the local blender module cannot be imported. Any exceptions raised by blender.get_mesh if the data is invalid.

from_model `classmethod` ¶

from_model(model, materials=None)

Create a Mesh instance from various types of input models.

Parameters:

Name	Type	Description	Default
`model`	`str, bpy.types.Object, dict, Mesh, or bpy.types.Mesh`	The input model to create the Mesh from. It can be: - A string or Blender object to be evaluated and converted. - A dictionary representing the mesh data. - An existing Mesh instance. - A Blender Mesh data block.	required
`materials`	`list or None`	Materials to associate with the mesh (currently unused in this method).	`None`

Returns:

Type	Description
`Mesh`	The created Mesh instance based on the input model.

Raises:

Type	Description
`Exception`	If the type of the model is not supported.

from_object `classmethod` ¶

from_object(obj, evaluated=False)

Create a Mesh instance from an existing Blender object.

This method initializes a mesh from a Blender object, optionally using the evaluated version of the object (i.e., after applying modifiers).

Parameters:

Name	Type	Description	Default
`obj`	`str or Object`	The Blender object or its name from which to create the mesh.	required
`evaluated`	`bool`	If True, use the evaluated object with modifiers applied. If False, use the raw mesh data. Default is False.	`False`

Returns:

Type	Description
`Mesh`	A new Mesh instance created from the specified Blender object.

Raises:

Type	Description
`ImportError`	If the local blender module cannot be imported.

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_islands ¶

get_islands()

Compute connected components of faces (islands) and assign an island ID to each face.

Returns:

Type	Description
`ndarray of int, shape (n_faces,)`	Array of island IDs, one per face. Faces in the same connected component share the same integer ID. Empty mesh returns an empty list.

Notes

Islands are defined as groups of faces connected through shared edges.
A breadth-first search (BFS) is used to traverse each connected component.
IDs are assigned sequentially starting from 0.

Examples:

Get island IDs for all faces:

ids = mesh.get_islands()
print("Unique islands:", np.unique(ids))

Map faces by island:

ids = mesh.get_islands()
for island_id in np.unique(ids):
    faces = np.where(ids == island_id)[0]
    print(f"Island {island_id}: faces {faces}")

Note: Non-manifold meshes are still handled, but faces that share only a vertex (not an edge) are considered separate islands.

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.

grid `classmethod` ¶

grid(size_x=1, size_y=1, vertices_x=3, vertices_y=3, materials=None)

Create a rectangular grid mesh.

The grid is constructed in the XY plane with indexing set to 'ij', meaning the generated arrays have shape (vertices_x, vertices_y).

Parameters:

Name	Type	Description	Default
`size_x`	`float`	Size of the grid along the X axis. Default is 1.	`1`
`size_y`	`float`	Size of the grid along the Y axis. Default is 1.	`1`
`vertices_x`	`int`	Number of vertices along the X axis. Must be >= 2. Default is 3.	`3`
`vertices_y`	`int`	Number of vertices along the Y axis. Must be >= 2. Default is 3.	`3`
`materials`	`list of str`	List of material names to assign to the grid. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the rectangular grid.

Notes

The grid is created with 'ij' indexing, so coordinates follow NumPy's meshgrid(..., indexing='ij') convention.
UV coordinates are generated using [grid_uv_map][npblender.grid_uv_map].
The grid topology is built using [grid_corners][npblender.grid_corners].

Examples:

Create a 2x2 grid with 10 vertices along X and 5 along Y:

grid = Mesh.grid(size_x=2, size_y=2, vertices_x=10, vertices_y=5)

Create a square grid of size 5 with default vertex count:

grid = Mesh.grid(size_x=5, size_y=5)

See Also

[grid_corners][npblender.grid_corners] : Helper for constructing the corner topology of the grid. [grid_uv_map][npblender.grid_uv_map] : Generates UV coordinates for a regular grid.

Important: The grid is always created with 'ij' indexing (shape = (vertices_x, vertices_y)).

icosphere `classmethod` ¶

icosphere(radius=1, subdivisions=2, materials=None)

Create an icosphere mesh.

Parameters:

Name	Type	Description	Default
`radius`	`float`	Radius of the icosphere. Default is 1.	`1`
`subdivisions`	`int`	Number of recursive subdivisions applied to the base icosahedron. Higher values yield smoother spheres. Clamped to a maximum of 10. Default is 2.	`2`
`materials`	`list of str`	List of material names to assign to the icosphere. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the icosphere.

Notes

The icosphere is created using bmesh.ops.create_icosphere with calc_uvs=True so UV coordinates are automatically generated.
Unlike a UV sphere, an icosphere has more uniform vertex distribution, making it suitable for certain simulation and subdivision tasks.
Subdivisions are internally capped at 10 for performance reasons.

Examples:

Create a default icosphere of radius 1 with 2 subdivisions:

ico = Mesh.icosphere()

Create a larger icosphere with 4 subdivisions:

ico = Mesh.icosphere(radius=3, subdivisions=4)

See Also

uvsphere : Sphere primitive based on UV parameterization. bmesh.ops.create_icosphere : BMesh operator used for creating icospheres.

Note: Use uvsphere when you require consistent UV mapping, and icosphere for uniform tessellation.

inset_faces ¶

inset_faces(selection, thickness=0.1, depth=0.0, use_even_offset=True, use_relative_offset=False)

Inset selected faces individually, optionally adding depth (local extrusion).

Parameters:

Name	Type	Description	Default
`selection`	`array-like of int or bool, or None`	Indices (or mask) of faces to inset. If `None`, all faces are used.	required
`thickness`	`float`	Inset thickness applied per face. Default is 0.1.	`0.1`
`depth`	`float`	Local extrusion depth along each face normal. Default is 0.0.	`0.0`
`use_even_offset`	`bool`	Keep thickness consistent across faces (even offset). Default is True.	`True`
`use_relative_offset`	`bool`	Scale thickness relative to face size. Default is False.	`False`

Returns:

Type	Description
`dict`	Dictionary with: - `'top'`: indices of the original (selected) faces. - `'side'`: indices of the new faces created by the inset operation (typically the rim/side faces around each inset).

Notes

Implementation uses bmesh.ops.inset_individual.
The 'top' entry mirrors the input selection; 'side' comes from d["faces"] returned by the BMesh operator.

Examples:

Inset a set of faces with even offset:

res = Mesh.inset_faces(selection=[0, 2, 5], thickness=0.05, depth=0.0)

Inset all faces with relative offset and a small depth:

res = Mesh.inset_faces(selection=None, thickness=0.02,
                    depth=0.01, use_relative_offset=True)

See Also

extrude_faces : Extrude faces discretely instead of insetting. extrude_region : Extrude connected face regions.

join ¶

join(*others)

Join other Mesh instances into this mesh.

This method appends the geometry and materials of the given meshes to the current mesh, updating indices to maintain consistency.

Parameters:

Name	Type	Description	Default
`*others`	`Mesh`	One or more Mesh instances to be joined with the current mesh.	`()`

Returns:

Name	Type	Description
`self`	`Mesh`	The updated mesh instance with joined geometry.

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

join_geometry ¶

join_geometry(points=None, corners=None, faces=None, edges=None, safe_mode=False, **attrs)

Join geometry defined by components into the current mesh.

This method creates a new independent mesh from the provided geometry components (points, corners, faces, edges) which do not refer to existing vertices. The new mesh is then joined to the current mesh instance.

To add geometry using existing vertices, see Mesh.add_geometry.

Parameters:

Name	Type	Description	Default
`points`	`iterable`	Iterable of points (vertices) to add to the mesh.	`None`
`corners`	`iterable`	Iterable of corner indices defining the mesh topology.	`None`
`faces`	`iterable`	Iterable of faces defined by indices of corners.	`None`
`edges`	`iterable`	Iterable of edges defined by indices of vertices.	`None`
`safe_mode`	`bool`	Flag to enable safe mode operations (currently unused).	`False`
`**attrs`	`dict`	Additional attributes to be passed to the geometry addition.	`{}`

Returns:

Name	Type	Description
`self`	`Mesh`	The current mesh instance with the new geometry joined.

line `classmethod` ¶

line(start=(0, 0, 0), end=(0, 0, 1), segments=1, materials=None)

Create a mesh representing a straight line (or multiple lines) subdivided into segments.

Parameters:

Name	Type	Description	Default
`start`	`array-like of float, shape (..., 3)`	Coordinates of the start point(s). Can be a single 3D vector or an array of multiple vectors. Default is (0, 0, 0).	`(0, 0, 0)`
`end`	`array-like of float, shape (..., 3)`	Coordinates of the end point(s). Can be a single 3D vector or an array of multiple vectors with the same shape as `start`. Default is (0, 0, 1).	`(0, 0, 1)`
`segments`	`int`	Number of line segments (subdivisions) between each pair of start and end points. Must be >= 1. Default is 1.	`1`
`materials`	`list of str`	List of material names to assign to the line mesh. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the subdivided line(s).

Notes

The function interpolates segments + 1 points between start and end using np.linspace.
If start and end are arrays of shape (N, 3), the method generates N independent polylines, each subdivided into segments.
For higher-dimensional batched input, the function reshapes the grid and constructs edges using [col_edges][npblender.col_edges].

Examples:

Create a simple line with 5 segments between (0, 0, 0) and (0, 0, 1):

line = Mesh.line(start=(0, 0, 0), end=(0, 0, 1), segments=5)

Create three parallel lines defined by arrays of start and end points:

starts = np.array([[0, 0, 0],
                [1, 0, 0],
                [2, 0, 0]])
ends = np.array([[0, 0, 1],
                [1, 0, 1],
                [2, 0, 1]])
lines = Mesh.line(start=starts, end=ends, segments=4)

See Also

[border_edges][npblender.border_edges] : Helper for constructing consecutive edges in a single polyline. [col_edges][npblender.col_edges] : Helper for constructing edges in multi-dimensional point grids.

Note: The line mesh consists only of vertices and edges, no faces are created.

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

monkey `classmethod` ¶

monkey(materials=None)

Create the famous Blender "Suzanne" monkey mesh.

Parameters:

Name	Type	Description	Default
`materials`	`list of str`	List of material names to assign to the mesh. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the Suzanne primitive.

Notes

The monkey head is created using bmesh.ops.create_monkey.
Suzanne is often used as a test model and is considered Blender’s mascot.

Examples:

Create a Suzanne mesh:

monkey = Mesh.monkey()

See Also

bmesh.ops.create_monkey : BMesh operator used to generate the Suzanne primitive.

Note: Suzanne is widely used as a benchmark and test object in Blender.

multiply ¶

multiply(count, in_place=True)

Duplicate the geometry.

Multiplying is a way to efficiently duplicate the geometry a great number of times. Once duplicated, the vertices can be reshapped to address each instance individually.

count = 16

cube = Mesh.Cube() * count

# Shape the points as 16 blocks of 8 vertices
points = np.reshape(cube.points.position, (16, 8, 3))

# Place the cubes in a circle
ags = np.linspace(0, 2*np.pi, count, endpoint=False)
points[..., 0] += 6 * np.cos(ags)[:, None]
points[..., 1] += 6 * np.sin(ags)[:, None]

cube.to_object("Cubes")

Arguments

- count (int=10) : number of instances
- attributes (name=value) : value for named attributes

Returns:

Type	Description
`- Mesh`

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

points_cloud `classmethod` ¶

points_cloud(points=None, materials=None)

Create a mesh containing only points at the given positions.

Parameters:

Name	Type	Description	Default
`points`	`array-like of shape (N, 3)`	Coordinates of the points. If None, an empty mesh is created.	`None`
`materials`	`list of str`	List of material names to assign to the mesh. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the given points.

Notes

This method does not create any edges or faces, only isolated points.

Examples:

Create a point cloud with three points:

pts = np.array([[0, 0, 0],
                [1, 0, 0],
                [0, 1, 0]])
cloud = Mesh.points_cloud(points=pts)

See Also

Mesh : The mesh class used to construct and manage geometry.

Note: This constructor is useful for importing raw point data or initializing a mesh before adding edges and faces.

pyramid `classmethod` ¶

pyramid(size=1, materials=None)

Create a pyramid mesh.

The pyramid is generated as a cone with 3 vertices at the base (a triangle) and an apex at the top.

Parameters:

Name	Type	Description	Default
`size`	`float`	Size of the pyramid. Determines both the base dimensions and the height. Default is 1.	`1`
`materials`	`list of str`	List of material names to assign to the mesh. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the pyramid.

Notes

The base radius is scaled by size * sqrt(3)/2 so that the pyramid has approximately unit proportions when size=1.
Internally calls cone with vertices=3.

Examples:

Create a default pyramid of size 1:

pyramid = Mesh.pyramid()

Create a larger pyramid of size 5:

pyramid = Mesh.pyramid(size=5)

See Also

cone : Generalized method for cones and pyramids. bl_cone : Low-level constructor for cone-based primitives.

Note: This method is equivalent to creating a triangular-based cone.

remove_doubles ¶

remove_doubles(dist=0.001)

Merge duplicate vertices within a distance threshold.

Parameters:

Name	Type	Description	Default
`dist`	`float`	Maximum distance between vertices to be merged. Default is 0.001.	`0.001`

Returns:

Type	Description
`Mesh`	The current mesh instance (`self`) with duplicate vertices removed.

Notes

Internally uses bmesh.ops.remove_doubles.
All vertices in the mesh are considered for merging.
Useful for cleaning geometry after operations that may generate coincident vertices (e.g., mirroring, joining, or extrusion).

Examples:

Remove doubles with default threshold:

mesh.remove_doubles()

Remove doubles with a larger threshold:

mesh.remove_doubles(dist=0.01)

Note: This method modifies the mesh in place and returns self for chaining.

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

separate_faces ¶

separate_faces(groups=None)

Split faces into isolated islands, either one per face or grouped by provided IDs.

Parameters:

Name	Type	Description	Default
`groups`	`array-like of int, shape (n_faces,)`	Group IDs for each face. If `None`, each face is isolated as its own island. If provided, must be the same length as the number of faces.	`None`

Returns:

Type	Description
`Mesh`	A new mesh where faces are separated into independent islands with duplicated vertices.

Raises:

Type	Description
`ValueError`	If `groups` is provided but its shape does not match `(n_faces,)`.

Notes

When groups is None, the output mesh has one disconnected island per face.
When grouping, faces sharing the same group ID are kept together in the same island, with vertices duplicated so that each group is independent.
Face attributes are preserved except for 'loop_total' and 'loop_start'.

Examples:

Separate every face:

islands = mesh.separate_faces()

Separate faces into two groups:

groups = np.array([0, 0, 1, 1, 1, 0])  # one group ID per face
split = mesh.separate_faces(groups=groups)

See Also

join_geometry : Utility to assemble new meshes from points, corners, faces, and attributes. join : Used internally to accumulate separated islands.

Caution: The number of groups must equal the number of faces in the mesh, otherwise a ValueError is raised.

simplified ¶

simplified(scale, dist=0.001)

Return a simplified copy of the mesh by merging close vertices, with a fallback to a cubic envelope if the result is too small.

Parameters:

Name	Type	Description	Default
`scale`	`float`	Scale factor applied to the distance threshold.	required
`dist`	`float`	Base merge distance for vertices. The effective threshold is `dist / scale`. Default is 0.001.	`0.001`

Returns:

Type	Description
`Mesh`	A simplified copy of the mesh. If the simplification produces fewer than 8 vertices, returns a cubic envelope instead.

Notes

The copy is created with Mesh.from_mesh.
Duplicate vertices are merged with remove_doubles.
If too few vertices remain, a fallback is generated using get_cubic_envelop.

Examples:

Simplify a mesh with scale factor 10:

simp = mesh.simplified(scale=10, dist=0.002)

See Also

remove_doubles : Merges vertices within a distance threshold. get_cubic_envelop : Provides a fallback cubic mesh when simplification collapses geometry.

solidify ¶

solidify(thickness=0.01, offset=-1)

Apply a Solidify modifier to give thickness to a surface mesh.

Parameters:

Name	Type	Description	Default
`thickness`	`float`	Thickness of the shell to generate. Positive values expand outward, negative values inward. Default is 0.01.	`0.01`
`offset`	`float`	Offset factor determining the solidification direction relative to the original surface: -1 → inward, 0 → centered, +1 → outward. Default is -1.	`-1`

Returns:

Type	Description
`Mesh`	A new mesh instance resulting from the solidify operation.

Notes

Internally creates a Blender Solidify modifier with use_even_offset=True for consistent thickness.
The modifier is applied destructively via bpy.ops.object.modifier_apply, and the resulting mesh is retrieved with Mesh.from_object.
Works best on manifold surfaces (open meshes may produce artifacts).

Examples:

Solidify a circular glass mesh:

glass = Mesh.circle(segments=128)
glass.extrude_faces(0, -0.01)
glass.extrude_faces(0, -2)
glass.extrude_faces(0, -0.01)
glass.points.translate((0, 0, 2))

glass = glass.solidify(thickness=0.1)
glass.to_object("Solidify", shade_smooth=True)

See Also

Mesh.from_object : Converts a Blender object back into a mesh wrapper. object : Context manager yielding a temporary Blender object.

Caution: Applying the modifier is destructive to the underlying Blender object; the method returns a new mesh instance of the result.

solidify_socle ¶

solidify_socle(shape, z=0, bottom_material_index=0)

Build a solid base (“socle”) by extruding the outer boundary of a grid mesh down (or up) to a given Z level, then bridging the side wall.

Parameters:

Name	Type	Description	Default
`shape`	`tuple of int`	Grid shape `(nx, ny)` of the mesh topology (using `'ij'` indexing).	required
`z`	`float`	Target Z coordinate for the base ring (the new bottom boundary). Default is 0.	`0`
`bottom_material_index`	`int`	Material index assigned to the bottom face created by the operation. Default is 0.	`0`

Returns:

Type	Description
`None`	Modifies the mesh in place. Returns `None`. The bottom face indices produced by `add_geometry` are stored internally and their `material_index` is set to `bottom_material_index`.

Notes

The outer boundary loop is derived from the provided grid shape assuming a regular lattice of nx * ny points laid out with NumPy’s 'ij' indexing.
A new ring of points is created at Z = z via add_points.
The vertical side wall is created by bridging loops with bridge_loops using close=True.
The bottom face material is assigned by ensuring and editing the optional material_index field on self.faces.

Examples:

Solidify a 20×30 grid down to Z = -0.1 with material index 2:

Mesh.solidify_socle(shape=(20, 30), z=-0.1, bottom_material_index=2)

See Also

add_points : Adds the new base ring vertices at Z = z. add_geometry : Creates the bottom polygon from the added ring. bridge_loops : Connects the side wall between original and new boundary loops.

Caution: This method assumes the mesh vertices correspond to a regular (nx, ny) grid ordered consistently with 'ij' indexing; inconsistent layouts will produce incorrect boundaries.

Note: The function does not return the created face indices; it sets their material_index internally based on bottom_material_index.

split_edges ¶

split_edges(loop0, loop1, cuts=1)

Subdivide in place the edges whose endpoints match the pairs (loop0[i], loop1[i]) regardless of order (edges are treated as undirected).

The inputs loop0 and loop1 can be: - scalars (a single vertex index), - sequences of the same length, - or a mix of both (a scalar is broadcast to match the length of the other).

The vertex pairs are normalized by sorting (min, max) so that order does not matter, and then compared against the BMesh edge list to determine which edges should be subdivided.

Parameters:

Name	Type	Description	Default
`loop0`	`int or array-like of int`	First vertex (or list of vertices) of the edges to be selected. If scalar, it will be broadcast to the length of `loop1` if needed.	required
`loop1`	`int or array-like of int`	Second vertex (or list of vertices) of the edges to be selected. If scalar, it will be broadcast to the length of `loop0` if needed.	required
`cuts`	`int`	Number of cuts per selected edge, as defined by `bmesh.ops.subdivide_edges`. Default is `1`. Must be >= 1.	`1`

Returns:

Type	Description
`None`	Modifies the geometry in place. Returns `None`. If no edge matches the given pairs, the function returns immediately without modifying the mesh.

Notes

Edge selection is performed by constructing an array of sorted vertex pairs (min(v0, v1), max(v0, v1)) and checking membership (via np.isin on a structured dtype view) against the BMesh edge list.
Subdivision is executed with bmesh.ops.subdivide_edges and use_grid_fill=False.

Examples:

Subdivide a single edge (vertices 12 and 34) with 2 cuts:

obj = ...  # wrapper object providing .bmesh() and ._bm_edges(...)
obj.split_edges(12, 34, cuts=2)

Subdivide multiple edges defined by pairs of vertices:

v0 = [1, 5, 9]
v1 = [2, 6, 10]
obj.split_edges(v0, v1, cuts=1)

Use a scalar broadcast against a vector:

# All edges (7, x) for x in [8, 9, 10]
obj.split_edges(7, [8, 9, 10], cuts=1)

See Also

bmesh.ops.subdivide_edges : The underlying BMesh operator used for subdivision.

Warning: This operation modifies the mesh in place and may create new vertices/edges/faces. Handle undo/history in Blender if needed.

Caution: use_grid_fill=False prevents automatic grid filling. Depending on topology, additional n-gons or triangles may be introduced.

Note: Edges are considered undirected: (a, b) and (b, a) are equivalent when matching edges.

symmetrical ¶

symmetrical(x=-1.0, y=1.0, z=1.0, flip=True)

Construct the symmetrical mesh, flip the faces if requested.

Parameters:

Name	Type	Description	Default
`x`	`float`	x multiplicator. Default is -1.0.	`-1.0`
`y`	`float`	y multiplicator. Default is 1.0.	`1.0`
`z`	`float`	z multiplicator. Default is 1.0.	`1.0`
`flip`	`bool`	flip the faces (invert the normals). Default is `'median'`.	`True`

Returns:

Type	Description
`Mesh`	The symmetrical mesh.

to_curve_REVIEW ¶

to_curve_REVIEW()

Convert mesh to curve

Simple conversion when edges domain is defined

to_dict ¶

to_dict()

Serialize the Mesh object to a dictionary representation.

Returns:

Type	Description
`dict`	A dictionary containing the serialized data of the mesh, including: - 'geometry': The type of geometry (always 'Mesh'). - 'materials': List of material names. - 'points': Serialized points data. - 'corners': Serialized corners data. - 'faces': Serialized faces data. - 'edges': Serialized edges data.

to_mesh_data ¶

to_mesh_data(data)

Write the geometry data from this mesh into a Blender Mesh instance.

This method transfers the mesh's vertices, edges, faces, corners, materials, and custom attributes into the provided Blender Mesh data structure.

Parameters:

Name	Type	Description	Default
`data`	`Blender Mesh instance`	The Blender Mesh object to which the geometry will be written.	required

Returns:

Type	Description
`None`

Side Effects

Modifies the provided Blender Mesh instance by clearing its current geometry and populating it with the data from this mesh. Updates the mesh to reflect the changes.

to_object ¶

to_object(obj, shade_smooth=None, shapekeys=None, collection=None)

Create or update a Blender mesh object from this mesh data.

This method creates a new Blender mesh object if it does not already exist, or updates the existing object's mesh data. It does not perform object type conversion; the existing object must be a mesh.

After the object is created or updated, use 'update_object' to modify vertices.

Parameters:

Name	Type	Description	Default
`obj`	`str or Object`	The Blender object or its name to create or update.	required
`shade_smooth`	`bool or None`	If specified, sets the shading mode of the mesh polygons to smooth or flat.	`None`
`shapekeys`	`ShapeKeys or iterable of ShapeKeys`	Shape keys to apply to the mesh object.	`None`
`collection`	`Collection or None`	The collection to which the object should be linked.	`None`

Returns:

Type	Description
`Object`	The created or updated Blender mesh object.

torus `classmethod` ¶

torus(major_segments=48, minor_segments=12, major_radius=1.0, minor_radius=0.25, materials=None)

Create a torus mesh.

Parameters:

Name	Type	Description	Default
`major_segments`	`int`	Number of segments around the major (outer) radius. Default is 48.	`48`
`minor_segments`	`int`	Number of segments around the minor (inner) radius (the cross-section). Default is 12.	`12`
`major_radius`	`float`	The distance from the center of the torus to the center of the tube. Default is 1.	`1.0`
`minor_radius`	`float`	The radius of the tube itself. Default is 0.25.	`0.25`
`materials`	`list of str`	List of material names to assign to the torus. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the torus.

Notes

The torus is constructed by sweeping a circle of radius minor_radius around a larger circle of radius major_radius.
The transformation of the cross-section is handled by [Transformation][npblender.transform.Transformation] and [Rotation][npblender.rotation.Rotation].
UV coordinates are generated using [grid_uv_map][npblender.grid_uv_map], resulting in a square parameterization.
Topology is constructed with [grid_corners][npblender.grid_corners] with both axes closed.

Examples:

Create a standard torus:

torus = Mesh.torus()

Create a torus with a larger tube and finer resolution:

torus = Mesh.torus(major_segments=64, minor_segments=32,
                major_radius=2, minor_radius=0.5)

See Also

[grid_corners][npblender.grid_corners] : Helper for constructing the corner topology of the torus grid. [grid_uv_map][npblender.grid_uv_map] : Generates UV coordinates for grid-like surfaces. [Transformation][npblender.transform.Transformation] : Used to position and orient the swept circle. [Rotation][npblender.rotation.Rotation] : Used to orient the minor circle along the sweep path.

Note: UV coordinates are generated with an offset of π to match Blender's default torus orientation.

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

triangulate ¶

triangulate(selection=None)

Triangulate selected faces (or all faces) and return a new mesh.

Parameters:

Name	Type	Description	Default
`selection`	`array-like of int or bool, or None`	Indices (or mask) of faces to triangulate. If `None`, all faces are triangulated. Default is None.	`None`

Returns:

Type	Description
`Mesh or None`	A new mesh instance with the selected faces triangulated. Returns `None` if no faces were selected.

Notes

Creates a copy of the current mesh with Mesh.from_mesh.
Triangulation is applied in-place on the copy via bmesh.ops.triangulate.
The original mesh is left unchanged.

Examples:

Triangulate all faces:

tri_mesh = mesh.triangulate()

Triangulate only a subset:

tri_mesh = mesh.triangulate(selection=[0, 5, 7])

See Also

Mesh.from_mesh : Utility to duplicate the mesh before applying triangulation.

Note: If selection is empty, the method returns None.

uvsphere `classmethod` ¶

uvsphere(segments=32, rings=16, radius=1, materials=None)

Create a UV sphere mesh.

Parameters:

Name	Type	Description	Default
`segments`	`int`	Number of longitudinal segments (meridians). Default is 32.	`32`
`rings`	`int`	Number of latitudinal rings (parallels). Default is 16.	`16`
`radius`	`float`	Radius of the sphere. Default is 1.	`1`
`materials`	`list of str`	List of material names to assign to the sphere. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A new mesh instance containing the UV sphere.

Notes

The sphere is created using bmesh.ops.create_uvsphere with calc_uvs=True so UV coordinates are automatically generated.
The geometry is distributed evenly in the UV parameterization, which means denser vertices near the poles.

Examples:

Create a default UV sphere of radius 1:

sphere = Mesh.uvsphere()

Create a high-resolution sphere:

sphere = Mesh.uvsphere(segments=64, rings=32, radius=2)

See Also

icosphere : Alternative sphere primitive with more uniform vertex distribution. bmesh.ops.create_uvsphere : BMesh operator used for creating UV spheres.

Note: Use icosphere if you need a more uniform tessellation without poles.

vectors_field `classmethod` ¶

vectors_field(locations, vectors, radius=0.05, scale_length=1.0, angle=24.0, segments=8, head=None, adjust_norm=None, materials=None)

Create an arrow at each location oriented and scaled by the corresponding vector.

Each arrow consists of a cylindrical shaft and a conical head aligned with the vector direction. Arrow length is derived from the vector norm, optionally transformed by adjust_norm. For very short vectors, the arrow is scaled down to preserve proportions.

Parameters:

Name	Type	Description	Default
`locations`	`array-like of shape (N, 3)`	Positions where arrows are placed.	required
`vectors`	`array-like of shape (N, 3)`	Direction (and base length) of each arrow. Must match the length of `locations`.	required
`radius`	`float`	Shaft radius for the arrows. Default is 0.05.	`0.05`
`scale_length`	`float`	Length threshold below which arrows are uniformly scaled down (radius and shaft) while keeping proportions. Default is 1.0.	`1.0`
`angle`	`float`	Opening angle (in degrees) of the conical head. Default is 24.	`24.0`
`segments`	`int`	Number of radial segments for both shaft and head. Default is 8.	`8`
`head`	`Mesh or None`	Optional mesh to use as the arrow head. If `None`, a cone is created. When provided, its Z size defines the head height.	`None`
`adjust_norm`	`(callable, float, None)`	Controls how vector norms are mapped to arrow lengths: - callable: applied to the array of norms. - float: acts as a maximum length (clamp). - None: use the raw norms. Default is None.	`callable`
`materials`	`list of str`	Material names to assign to created geometry. Default is None.	`None`

Returns:

Type	Description
`Mesh`	A mesh containing all arrows.

Notes

The head radius is 3 * radius; its height is derived from angle via head_height = head_radius / tan(angle).
Arrows with very small vectors are handled specially to avoid degenerate geometry (a minimum total length of approximately 2 * head_height is enforced).
Alignment is achieved with [Rotation.look_at][npblender.rotation.Rotation.look_at].
The shaft is built from cylinder, and the head from cone (when head is None).

Examples:

Create a field of unit arrows from a grid:

P = np.stack(np.meshgrid(np.linspace(-1, 1, 5),
                        np.linspace(-1, 1, 5),
                        [0.0], indexing='ij'), axis=-1).reshape(-1, 3)
V = np.tile(np.array([0, 0, 1.0]), (len(P), 1))
field = Mesh.vectors_field(P, V, radius=0.03, segments=12)

Clamp arrow lengths to 2 units:

field = Mesh.vectors_field(P, V * 5.0, adjust_norm=2.0)

Map norms nonlinearly (e.g., sqrt):

field = Mesh.vectors_field(P, V, adjust_norm=np.sqrt)

See Also

arrow : Convenience method to create a single arrow. cylinder : Used to create the arrow shafts. cone : Used to create the arrow heads (when head is None). [Rotation.look_at][npblender.rotation.Rotation.look_at] : Used to orient arrows along their vectors.

Caution: locations and vectors must have the same length (N). Mismatched inputs will lead to incorrect alignment or runtime errors.

Note: Zero-length vectors are handled safely; corresponding arrows collapse to length 0 and are effectively omitted.

Mesh ¶

bounding_box property ¶

bounding_box_dims property ¶

max_size property ¶

add_geometry ¶

add_materials ¶

add_points ¶

apply_scale ¶

arrow classmethod ¶

bl_circle classmethod ¶

bl_cone classmethod ¶

bl_grid classmethod ¶

blender_data ¶

bmesh ¶

boolean ¶

bridge_loops ¶

bvh_tree ¶

capture ¶

chain_link classmethod ¶

check ¶

circle classmethod ¶

clear_geometry ¶

compute_attribute_on_domain ¶

cone classmethod ¶

cube classmethod ¶

cylinder classmethod ¶

delete_faces ¶

delete_vertices ¶

disk classmethod ¶

dual ¶

extrude_faces ¶

extrude_loop ¶

extrude_region ¶

extrude_vertices ¶

faces_neighbors ¶

fill_cap ¶

from_dict classmethod ¶

from_mesh classmethod ¶

from_mesh_data classmethod ¶

from_model classmethod ¶

from_object classmethod ¶

get_cubic_envelop ¶

get_islands ¶

get_material_index ¶

get_points_selection ¶

grid classmethod ¶

icosphere classmethod ¶

inset_faces ¶

join ¶

join_attributes ¶

join_geometry ¶

line classmethod ¶

load_models staticmethod ¶

load_object staticmethod ¶

monkey classmethod ¶

multiply ¶

object ¶

points_cloud classmethod ¶

pyramid classmethod ¶

remove_doubles ¶

rotate ¶

separate_faces ¶

simplified ¶

solidify ¶

solidify_socle ¶

split_edges ¶

symmetrical ¶

to_curve_REVIEW ¶

to_dict ¶

to_mesh_data ¶

to_object ¶

torus classmethod ¶

transform ¶

transformation ¶

translate ¶

triangulate ¶

uvsphere classmethod ¶

vectors_field classmethod ¶

bounding_box `property` ¶

bounding_box_dims `property` ¶

max_size `property` ¶

arrow `classmethod` ¶

bl_circle `classmethod` ¶

bl_cone `classmethod` ¶

bl_grid `classmethod` ¶

chain_link `classmethod` ¶

circle `classmethod` ¶

cone `classmethod` ¶

cube `classmethod` ¶

cylinder `classmethod` ¶

disk `classmethod` ¶

from_dict `classmethod` ¶

from_mesh `classmethod` ¶

from_mesh_data `classmethod` ¶

from_model `classmethod` ¶

from_object `classmethod` ¶

grid `classmethod` ¶

icosphere `classmethod` ¶

line `classmethod` ¶

load_models `staticmethod` ¶

load_object `staticmethod` ¶

monkey `classmethod` ¶

points_cloud `classmethod` ¶

pyramid `classmethod` ¶

torus `classmethod` ¶

uvsphere `classmethod` ¶

vectors_field `classmethod` ¶