ddg.blender.mesh module

Collection of functions for Blender Mesh objects.

The related functions on the level of bmesh are found in bmeshutils.py module.

ddg.blender.mesh.mesh(name, points, edges, faces, /)

Create a mesh from points, edges and faces.

Parameters:

namestr

The name attribute of the mesh.

pointsarray_like of shape (num_points, 3)

The points of the mesh. The dtype must be some kind of floating point dtype.

edgesarray_like of shape (num_edges, 2)

The faces already encode manifold edges, but edges can encode additional non-manifold edges. Each row must contain two indices to points. The dtype must be some kind of integer dtype.

facesarray_like of shape (num_faces, k)

The faces of the mesh, where k is the number of vertices of each face. Each row must contain k indices to points. The dtype must be some kind of integer dtype.

Returns:

bpy.types.Mesh

Raises:

ValueError

If there already exists a mesh with the same name.

See also

ddg.curve_as_mesh

ddg.blender.mesh.mesh_object(points, edges, faces, mesh_and_object_name, collection)

Create a Blender mesh from points and faces and wrap it in a Blender object.

Parameters:

pointsarray_like of shape (num_points, 3)

The points of the mesh. The dtype must be some kind of floating point dtype.

edgesarray_like of shape (num_edges, 2)

The faces already encode manifold edges, but edges can encode additional non-manifold edges. Each row must contain two indices to points. The dtype must be some kind of integer dtype.

facesarray_like of shape (num_faces, k)

The faces of the mesh, where k is the number of vertices of each face. The dtype must be some kind of integer dtype.

mesh_and_object_namestr or tuple[str, str]

The name attribute of the mesh and the object. If only one string is passed, then use the same name for both.

collectionbpy.types.Collection, str, None

If None, then the Blender object is not linked. Otherwise, the Collection or name of collection to link the object to.

Returns:

bpy.types.Object

Raises:

ValueError

If there already exists a Blender mesh or Blender object with the same name.

ddg.blender.mesh.from_bmesh(bm, name, free=False)

Write a BMesh to a new mesh.

Parameters:

bmbmesh.types.BMesh

namestr

The name of the new mesh.

freebool (default=False)

If True, bm is freed.

Returns:

bpy.types.Mesh

ddg.blender.mesh.duplicate_by_properties(bobj, properties, collection=None, material=None, unlink_initial_object=True)

Create duplicate Blender objects with certain properties

Parameters:

bobjbpy.types.Object

Blender object to duplicate.

propertiesList

List of dictionaries that define the properties that are each applied to a duplicate

collectionbpy.types.Collection or List, (default=None)

if bpy.types.Collection, links all duplicate object to single given collection if List, expects list of bpy.types.Collection, links one duplicate to each collection given

materialbpy.types.Material or str, (default=None)

Name of Material or bpy.types.Material to be applied to the duplicate objects

unlink_initial_objectbool, (default=True)

If True, unlink bobj.

Returns:

duplicateslist

A list of Blender objects : the created linked and transformed duplicates.

ddg.blender.mesh.duplicate_by_transformation_matrices(bobj, transformation_matrices, collection=None, material=None, unlink_initial_object=True)

Function creating duplicates of a Blender object. each duplicated has its properties changed given by properties.

Parameters:

bobjbpy.types.Object

Blender object to duplicate.

transformation_matricesList

List of 4x4 matrices corresponding to the transformations.

collectionbpy.types.Collection or List, (default=None)

bpy.types.Collection: links all duplicate object to single given collection List: expects list of bpy.types.Collection, links one duplicate to each collection given

materialsbpy.types.Material or str or List, (default=None)

Name of the material or bpy.types.Material or List same length as properties populted with str (Name of the material) or bpy.types.Material (actual material object)

unlink_initial_objectbool, (default=True)

unlinks the given originally Blender object from the scene

Returns

——-

duplicateslist

A list of Blender objects : the created linked and transformed duplicates.

ddg.blender.mesh.duplicate_linked(bobj, n, collection=None)

Creates n duplicate Blender objects.

Parameters:

bobjbpy.types.Object

Blender object to duplicate.

nInteger

Integer of wanted number of duplicates

collectionbpy.types.Collection or List of length n of bpy.types.Collection

a single bpy.types.Collection: links all duplicate object to single given collection List of length n populated with bpy.types.Collection : links one duplicate to each collection given

Returns

——-

duplicateslist

List of Blender objects : Created linked duplicates.

ddg.blender.mesh.transform(bobj_or_mesh, M)

Transform vertices by a matrix.

Parameters:

bobj_or_meshbpy.types.Object or bpy.types.Mesh

A Blender object (whose data is a mesh) or a mesh.

Mnumpy.ndarray of shape (3, 3) or (4, 4)

Returns:

bpy.types.Object or bpy.types.Mesh

The input Blender object or mesh.

ddg.blender.mesh.join(bobjs_or_meshes, name=None, keep_original=True, collection=None, remove_doubles_dist=None)

Join Blender objects or meshes into a single Blender object.

Parameters:

bobjs_or_meshesSequence of bpy.types.Object or bpy.types.Mesh

Must be non-empty. Objects must have mesh data.

namestr (default=None)

Name of the new object.

keep_originalbool (default=True)

If False, elements of bobjs_or_meshes including their data are deleted.

collectionbpy.types.Collection (default=None)

Collection to link the object to. If None, the object is not linked.

remove_doubles_distfloat or None (default=None)

If this parameter isn’t None, redundant vertices are removed with bmesh.ops.remove_doubles where dist=remove_doubles_dist.

Returns:

bpy.types.Object

ddg.blender.mesh.connected_components(bobj, keep_original=True)

Separates a Blender object into its connected components.

This is a fancier version of bpy.ops.mesh.separate which takes care of mode switches and can handle objects which are hidden from the viewport.

Parameters:

bobjbpy.types.Object

Object to be separated. Must have mesh data.

keep_originalbool (default=True)

If True, then bobj is copied before separation.

Returns:

list of bpy.types.Object

The connected components of the Blender object.

See also

bpy.ops.mesh.separate

ddg.blender.mesh.shade_smooth(bobj_or_mesh, smooth=True)

Apply smooth or flat shading to each polygon of bobj_or_mesh.

Parameters:

bobj_or_meshbpy.types.Object or bpy.types.Mesh

An object (whose data is a mesh) or a mesh.

smoothbool (default=True)

The use_smooth attribute of every polygon is set to this value.

Returns:

bpy.types.Object or bpy.types.Mesh

The input Blender object or mesh.

ddg.blender.mesh.clear(meshes=None, do_unlink=True, only_unused=False)

Delete all given meshes.

Parameters:

meshesIterable of bpy.type.Mesh (default=None)

Meshes to be deleted. If the argument is not provided or None all meshes will be deleted.

do_unlinkbool (default=True)

Unlink meshes from their objects and scenes, if needed, before deleting them.

only_unusedbool (default=False)

Removes all unused meshes. If an Iterable of meshes is given as first parameter only those are effected, otherwise all meshes.

Returns:

None

ddg.blender.mesh.intersection(bobj1, bobj2, collection, name='Intersection', intersection_operator=<function <lambda>>, remove_doubles_dist=0.001, attempt_curve_conversion=True)

Intersects two mesh objects.

This function relies on Blender’s intersection operators. The intersection_operator parameter allows customization of the operator options, which usually need to be adjusted on a case by case basis. Note that the Blender’s intersection operators aren’t always reliable, especially for 2-dimensional intersections.

Parameters:

bobj1bpy.types.Object

First object to intersect. Must have mesh data.

bobj2bpy.types.Object

Second object to intersect. Must have mesh data.

collectionbpy.types.Collection

Collection to add the intersection object to.

namestr (default=”Intersection”)

Name of the intersection object.

intersection_operatorCallable (default=lambda: bpy.ops.mesh.intersect(mode=”SELECT”))

Must have no input arguments. Called internally to compute the intersection.

remove_doubles_distfloat or None (default=0.001)

If this parameter isn’t None, redundant vertices are removed with bmesh.ops.remove_doubles where dist=remove_doubles_dist.

attempt_curve_conversionbool (default=True)

If True, then bpy.ops.object.convert(target="CURVE") is applied to the intersection. This operator tries to convert the intersection’s data from bpy.types.Mesh to bpy.types.Curve, but it may fail silently. If it does succeed, it may have unexpected results. For example, it converts a mesh consisting of a single triangle to the triangle’s boundary curve.

Returns:

bpy.types.Object or None

The intersection or None if it is empty. If the intersection is non-empty, its data attribute is of type bpy.types.Curve or bpy.types.Mesh.

Notes

The intersection is computed as follows:

• join bobj1 and bobj2

• for each connected component

  • select all vertices in edit mode

  • call intersection_operator which should compute the intersection and select its vertices

  • delete unselected vertices, leaving just the intersection

• join the intersections (if there are any)

• optionally, delete redundant vertices

• optionally, attempt to convert the intersection’s data to a curve using bpy.ops.convert

Joining relies on ddg.blender.mesh.join() which avoids bpy.ops including bpy.ops.object.join.