ddg.blender.object module

Collection of utility functions dealing with Blender objects

ddg.blender.object.random(/)

ddg.blender.object.blender_data_to_object(name, data)

Wrap a Blender data-block in a Blender object.

Parameters:

namestr

The name attribute of the object.

databpy.types.ID

A Blender data-block, e.g. curves and meshes whose types - bpy.types.Mesh and bpy.types.Curve respectively - are subclasses of bpy.types.ID.

Returns:

bpy.types.Object

ddg.blender.object.to_blender_object_V2(convertible, name, /, material=None, collection=None, bounding_box=(inf, inf, inf), curve_sampling=(100, 0.1), surface_sampling=(30, 0.1), subspace_size=100)

Convert pyddg objects, points, curves and meshes to Blender objects.

Parameters:

convertible

This must be an instance of:

- `ddg.geometry.Subspace` of dimension <= 2
- `ddg.geometry.Quadric` of dimension <= 2
- `ddg.geometry.QuadricIntersection` of dimension_complex == 1
- `ddg.geometry.spheres.QuadricSphere` of dimension <= 2
- `ddg.indexedfaceset.IndexedFaceSet` with coordinate attribute "co"
- `ddg.halfedge.Surface` with coordinate attribute "co"
- `ddg.nets.DiscreteCurve`
- `ddg.nets.DiscreteNet`
- `ddg.nets.PointNet`
- `ddg.nets.EmptyNet`
- `ddg.nets.NetCollection` of discrete nets of the same dimension
- `ddg.conversion.arrays.Points`
- `ddg.conversion.arrays.Curve`
- `ddg.conversion.arrays.CurveList`
- `ddg.conversion.arrays.Mesh`

namestr

Sets bobj.name and bobj.data.name to this value.

materialstr or bpy.types.Material (default=None)

The resulting Blender object is assigned this material if it isn’t None.

collectionbpy.types.Collection (default=None)

The resulting Blender object is linked to this collection if it isn’t None.

bounding_boxarray_like of shape (3,) of type float

(default=(np.inf, np.inf, np.inf)) Bounding box of the resulting blender object.

curve_samplingtuple of an int and a float

(default=(100,0.1)) Determines the sample number and stepsize for curves

surface_samplingtuple of an int and a float

(default=(30,0.1)) Determines the sample number and stepsize for surfaces

subspace_sizefloat

(default=100) Determines the size of subspaces

Returns:

bpy.types.Object

The data attribute is of type bpy.types.Curve if convertible represents a curve curve and bpy.types.Mesh represents a point, points or a mesh.

Examples

>>> import bpy
>>> import numpy as np
>>> import ddg

To display a 2-dimensional subspace

>>> plane = ddg.geometry.subspace_from_affine_points(
...     (0, 0, 0), (1, 0, 0), (0, 1, 0)
... )
>>> ddg.blender.object.to_blender_object_V2(plane, "plane")
bpy.data.objects['plane']

To display a quadric

>>> two_sheeted_hyperboloid = ddg.geometry.Quadric(np.diag([1, 1, -1, 1]))
>>> ddg.blender.object.to_blender_object_V2(
...     two_sheeted_hyperboloid, "two sheeted hyperboloid"
... )
bpy.data.objects['two sheeted hyperboloid']

To display a curve represented by a discrete curve

>>> discrete_curve = ddg.nets.DiscreteCurve(
...     lambda t: (np.cos(t), np.sin(t), t), (-10, 10)
... )
>>> ddg.blender.object.to_blender_object_V2(discrete_curve, "discrete_curve")
bpy.data.objects['discrete_curve']

To display a surface represented by a discrete net

>>> discrete_net = ddg.nets.DiscreteNet(
...     lambda u, v: (u, v, np.cos(v)), ((-10, 10), (-10, 10))
... )
>>> ddg.blender.object.to_blender_object_V2(discrete_net, "discrete_net")
bpy.data.objects['discrete_net']

To create a curve object manually

>>> curve = ddg.conversion.arrays.Curve([(0, 0, 0), (1, 0, 0)], False)
>>> curve_object = ddg.blender.object.to_blender_object_V2(curve, "Curve")
>>> type(curve_object.data)
<class 'bpy.types.Curve'>
>>> curve_object.data.name
'Curve'
>>> curve_object.name
'Curve'

To create a mesh object manually

>>> mesh = ddg.conversion.arrays.Mesh(
...     [(0, 0, 0), (1, 0, 0), (0, 1, 0)], [(0, 1, 2)]
... )
>>> mesh_object = ddg.blender.object.to_blender_object_V2(mesh, "Triangle")
>>> type(mesh_object.data)
<class 'bpy_types.Mesh'>
>>> mesh_object.data.name
'Triangle'
>>> mesh_object.name
'Triangle'

To create non-manifold meshes manually

>>> non_manifold_edges = np.array([(0, 3)])
>>> non_manifold_mesh = ddg.conversion.arrays.Mesh(
...     [(0, 0, 0), (1, 0, 0), (0, 1, 0), (1, 1, 0)],
...     [(0, 1, 2)],
...     non_manifold_edges,
... )
>>> non_manifold_mesh_object = ddg.blender.object.to_blender_object_V2(
...     non_manifold_mesh, "Triangle with extra edge"
... )
>>> [tuple(e.vertices) for e in non_manifold_mesh_object.data.edges]
[(1, 2), (0, 1), (0, 2), (0, 3)]

It is usually unnecessary to create the input arrays manually. The functions in ddg.conversion.arrays convert most ddg objects into suitable input for ddg.blender.object.to_blender_object_V2.

ddg.blender.object.scatter(convertible, name, /, radius_or_point_mesh=0.05, material=None, collection=None)

Convert pyddg objects and points to points as Blender objects.

Parameters:

convertible

This must be an instance of:

- `ddg.geometry.Point`
- `ddg.nets.PointNet`
- `ddg.conversion.arrays.Points`

namestr

Sets bobj.name and bobj.data.name to this value.

radius_or_point_mesh: float or mesh, (default=0.05)

Radius of a default icosphere mesh or a mesh that will be used for each point.

materialstr or bpy.types.Material (default=None)

The resulting Blender object is assigned this material if it isn’t None.

collectionbpy.types.Collection (default=None)

The resulting Blender object is linked to this collection if it isn’t None.

Returns:

bpy.types.Object

The data attribute is of type bpy.types.Mesh` represents a point or points.

Raises:

TypeError

If convertible has the wrong type

ValueError

If convertible cannot be converted to point/points.

Examples

>>> import bpy
>>> import numpy as np
>>> import ddg

>>> point = ddg.conversion.arrays.Points((1, 2, 3))
>>> ddg.blender.object.scatter(point, "one_point")
bpy.data.objects['one_point']

>>> points = ddg.conversion.arrays.Points([(1, 2, 3), (3, 4, 5)])
>>> ddg.blender.object.scatter(points, "two_points")
bpy.data.objects['two_points']

To change the radius of the visualized points

>>> ddg.blender.object.scatter(points, "radius_points", radius_or_point_mesh=1.0)
bpy.data.objects['radius_points']

To change the mesh representing the points

>>> cube = ddg.conversion.arrays.Mesh(
...     [
...         (0, 0, 0),
...         (0, 0, 1),
...         (0, 1, 0),
...         (0, 1, 1),
...         (1, 0, 0),
...         (1, 0, 1),
...         (1, 1, 0),
...         (1, 1, 1),
...     ],
...     [
...         (0, 1, 2, 3),
...         (4, 5, 6, 7),
...         (0, 1, 4, 5),
...         (2, 3, 6, 7),
...         (0, 2, 4, 6),
...         (1, 3, 5, 7),
...     ],
... )
>>> ddg.blender.object.scatter(points, "cube_points", radius_or_point_mesh=cube)
bpy.data.objects['cube_points']

ddg.blender.object.link(bobj, collection)

Link a Blender object to a collection.

Parameters:

bobjbpy.types.Object

Blender object to be linked.

collectionbpy.types.Collection or str

Collection or name of collection to link the object to.

Notes

If no collection exists with the given name, a new one will be created.

ddg.blender.object.delete(bobj)

Delete a Blender object.

Parameters:

bobjbpy.types.Object

Blender object to be deleted.

ddg.blender.object.copy(bobj, collection=None)

Makes a Copy of a Blender object and links it.

Parameters:

bobjbpy.types.Object

Blender object to be duplicated.

collectionbpy.types.Collection (default=None)

Links copy to the given collection, if None, object will not be linked.

Returns:

bpy.types.Curve of bpy.types.Object

the copy of the given object.

ddg.blender.object.set_matrix_world(bobj, matrix)

Set the matrix_world of bobj to matrix.

Parameters:

bobjbpy.types.Object

Blender object to set matrix_world.

matrixnumpy.ndarray or mathutils.Matrix

4x4 matrix.

Raises:

ValueError

If dimensions of matrix are not 4x4. If type of matrix is not numpy.ndarray or mathutils.Matrix.

ddg.blender.object.matrix_world_transformation_function(matrix)

Creates a function that transforms Blender objects by a matrix.

Parameters:

matrixnumpy.ndarray or mathutils.Matrix

4x4 matrix.

Returns:

object_trafoPython function

ddg.blender.object.set_prop(bobj, prop, val)

Set a single property of a Blender object.

Parameters:

bobjbpy.types.Object

Blender object to set prperty to.

propstr

Name of the property.

valany

New value of the property.

ddg.blender.object.look_at_point(bobj, point, bobj_front=(0, -1, 0), bobj_up=(0, 0, 1), world_up=(0, 0, 1), distance=None, atol=None, rtol=None)

Rotates an object such that it looks at the given point.

If a distance is given, the object is additionally translated along the viewing direction to match the given distance to the point. If no distance is given, the object remains at its position.

The default directions are set to fit the Suzanne object.

Parameters:

bobjbpy.types.Object

Blenders object to move.

pointiterable of 3 floats

Point of reference to turn object.

bobj_frontiterable of 3 floats (default=(0,-1,0))

Viewing direction of the object in the object space. That is the direction in which the object is looking in the object space.

bobj_upiterable of 3 floats (default=(0,0,1))

Up direction of the object in the object space. That is where the top is situed in the object space.

world_upiterable of 3 floats (default=(0,0,1))

Where the up direction should end up.

distance: float, default=None

Distance the object should have from the point.

atol, rtolfloat, default=None

Tolerances used to determine whether object is located at point.

If None, the global defaults will be used.

Raises:

ValueError

If the object is located at the target point.

ddg.blender.object.empty(collection=None, location=array([0, 0, 0]), empty_type='PLAIN_AXES', name='root', parent=None)

Creates an empty blender object.

Parameters:

collection: bpy.types.Collection (default=None)

Links copy to the given collection. If None, object will not be linked.

location: numpy.ndarray (default=np.array((0, 0, 0)))

location of empty object.

empty_type: str (default=”PLAIN_AXES”)

Viewport display style for empty object.

name: str (default=”root”)

Name of empty object.

parent: bpy.types.Object (default=None)

Parent of empty object.

Returns:

bpy.types.Object

ddg.blender.object.clear(objects=None, do_unlink=True, deep=True)

Delete all given objects.

Parameters:

objectsIterable of bpy.type.Object (default=None)

Objects to be deleted. If the argument is not provided or None, all objects will be deleted.

do_unlinkbool (default=True)

Unlink objects from their collections, if needed, before deleting them.

deepbool (default=True)

Delete the data corresponding to the object.

ddg.blender.object.clear_empty_objects(do_unlink=True, deep=True)

Delete all empty objects.

Parameters:

do_unlinkbool (default=True)

Unlink objects from their collections, if needed, before deleting them.

deepbool (default=True)

Delete the data corresponding to the object.

ddg.blender.object.clear_lattices(lattices=None, do_unlink=True)

Delete all given lattices.

Parameters:

latticesIterable of bpy.type.Lattice (default=None)

Lattices to be deleted. If the argument is not provided or None, all lattices will be deleted.

do_unlinkbool (default=True)

Unlink lattices from their scenes, if needed, before deleting them.

ddg.blender.object.get_data(x)

Return the data attribute if it exists or the input itself.

Parameters:

xAny

Returns:

Any

Examples

>>> import bpy
>>> from ddg.blender.object import get_data
>>>
>>> bpy.ops.mesh.primitive_cube_add()
{'FINISHED'}
>>> data = bpy.context.object.data
>>> assert data == get_data(bpy.context.object)
>>> assert data == get_data(bpy.context.object.data)

ddg.blender.object.edges(mesh, name, /, material=None, collection=None)

Convert mesh to edges as Blender objects.

Parameters:

meshMesh

The mesh that should be converted.

namestr

Sets bobj.name and bobj.data.name to this value.

materialstr or bpy.types.Material (default=None)

The resulting Blender object is assigned this material if it isn’t None.

collectionbpy.types.Collection (default=None)

The resulting Blender object is linked to this collection if it isn’t None.

Returns:

bpy.types.Object

The data attribute is of type bpy.types.Mesh` represents the edges.

Examples

>>> import bpy
>>> import numpy as np
>>> import ddg

>>> mesh = ddg.arrays(ddg.halfedge.dodecahedron())
>>> bobj = ddg.blender.object.edges(mesh, "Edges of Dodecahedron")
>>> bobj.data.bevel_depth = 0.1

ddg.blender.object.convert_qsic(intersection_object, name, material=None, collection=None, bounding_box=(inf, inf, inf), bevel_depth=0.01, sampling=(100, 0.1), subspace_size=100)

Converts a ddg.geometry.QuadricIntersection object into a blender object containing the intersection curve of the two quadrics

Parameters:

intersection_objectddg.geometry.QuadricIntersection

The intersection to depict with attributes Q1, Q2 representing the quadrics that span it

namestr

Sets bobj.name and bobj.data.name to this value.

materialstr or bpy.types.Material (default=None)

The resulting Blender object is assigned this material if it isn’t None.

collectionbpy.types.Collection (default=None)

The resulting Blender object is linked to this collection if it isn’t None.

bounding_boxarray_like of shape (3,) of type float

(default=(np.inf, np.inf, np.inf)) Bounding box of the resulting blender object.

bevel_depthfloat

Sets the bevel depth of the intersection curve to this value

samplingtuple of an int and a float

(default=(100,0.1)) Determines the sample number and stepsize for quadrics used to intersect

subspace_sizefloat

(default=100) Determines the size of subspaces

Returns:

bpy.types.Object