The Functions to_blender_object and to_blender_object_helper

Note

First steps on how to run a script in Blender can be found here.

The functions that visualize ddg objects in Blender are located in the package ddg.conversion.blender. The main function is to_blender_object(), which converts ddg objects to Blender objects, i.e. visualizes them.

The following objects can be passed to to_blender_object() directly:

Other objects, e. g. geometric objects or SmoothNet have to be converted to one of the above and can not be handed to_blender_object() directly. The conversion can either be done manually or the function to_blender_object_helper() can be used to internally convert and visualize. For all ddg objects there exist specific guides:

Here we provide an overview of the general usage of to_blender_object() and to_blender_object_helper():

Using to_blender_object

The usage of to_blender_object() is straight forward:

>>> import ddg
>>> cube = ddg.datastructures.halfedge.surface_generator.cube()
>>> blender_object = ddg.to_blender_object(cube)

The signature to_blender_object() reads

>>> def to_blender_object(
...     obj,
...     accept_all=False,
...     depth_bounding=10,
...     attributes={},
...     material=None,
...     collection=None,
...     mesh_transformations=[],
...     bmesh_transformations=[],
...     obj_transformations=[],
...     link=True,
...     **options
... ):
...     ...

with the parameters/docstring

Parameters

objddg.datastructure

DDG datastructure to convert into a Blender object.

accept_allbool (optional default=False)

When True all options are accepted, but no warning will be given when the conversion does not support one of them.

depth_boundingint (optional, default=10)

Bounding used for the highest layer of Nets with depth

attributesdict (optional, default={})

Attributes that will be assigned to the resulting Blender object such as name, parent, matrix_world, location, hide_viewport etc. in a dictionary as {‘attribute’: value}

materialstring (optional, default=None)

Material of the created Blender object

collectionbpy.types.Collection (optional, default=None)

Collection to link the blender object to. If set to None the object will be linked to bpy.context.scene.collection.

mesh_transformationsfunction or list of functions (optional, default=[])

Functions which should be applied to the mesh of the object. The transformation functions need to be defined such that they only take one (required) parameter, namely the mesh.

bmesh_transformationsfunction or list of functions (optional, default=[])

Functions which should be applied to the bmesh of the object. The transformation functions need to be defined such that they only take one (required) parameter, namely the bmesh.

obj_transformationsfunction or list of functions (optional, default=[])

Functions which should be applied to the object. The transformation functions need to be defined such that they only take one (required) parameter, namely the object.

link: bool (optional, default=True)

If set to True, the object will be linked to the given collection. If set to False, the object will be created but not linked to any collection.

**options

Options to use in the conversion. Available options depend on the type of the given object.

Options for DiscreteNet:

boundingint (default=10)

Used to bound unbounded domains of nets.

only_wirebool (default=False)

When True, only the wireframe of the net will be created.

Options for DiscreteCurve:

boundingint (default=10)

Used to bound unbounded domains of nets.

curve_typestring (default=’POLY’)

Blender curve type. See the Blender docs for all available types.

curve_propertiesdictionary (default={‘bevel_depth’: 0.015})

Dictionary containing Blender curve properties. See the Blender docs for all available properties.

Options for PointNet:

sphere_radiusfloat (default=0)

Radius of the sphere representing a point.

sphere_subdivisionint (default=3)

How many subdivisions will be applied to the sphere.

Options for HalfEdge surfaces:

co_attrstr (default=’co’)

The name of the vertex attribute that contains the coordinates.

Returns

Blender object

See also

Api documentation of to_blender_object().

Here are some examples:

>>> ddg.to_blender_object(
...     cube,
...     attributes={
...         "name": "Cube",
...         "location": [1, 1, 1],
...         "hide_viewport": False,
...         "hide_render": False,
...         "scale": [0.5, 0.5, 1],
...     },
... )
bpy.data.objects['Cube']

>>> col = ddg.visualization.blender.collection.collection("cube_collection")
>>> black = ddg.visualization.blender.material.material(color=(0, 0, 0))
>>> ddg.to_blender_object(
...     cube,
...     attributes={"name": "Cube with material"},
...     collection=col,
...     material=black,
... )
bpy.data.objects['Cube with material']

>>> from ddg.visualization.blender.mesh import shade_smooth
>>> from ddg.visualization.blender.bmesh import cut_bounding_box
>>> import numpy as np

>>> def cut_bb_trafo(bmesh):
...     return cut_bounding_box(
...         bmesh, np.array([1, 1, 1]), center=np.array([1, 1, 1])
...     )
...

>>> ddg.to_blender_object(
...     cube,
...     attributes={"name": "Transformed cube"},
...     mesh_transformations=[shade_smooth],
...     bmesh_transformations=[cut_bb_trafo],
... )
bpy.data.objects['Transformed cube']

Using to_blender_object_helper

The function to_blender_object_helper() combines the following

  • easy handling of commonly used keyword arguments

  • conversion to objects that can be visualized

  • calling the function to_blender_object().

Its signature and docstring reads

>>> def to_blender_object_helper(
...     obj,
...     name=None,
...     location=None,
...     hide_viewport=None,
...     hide_render=None,
...     scale=None,
...     shade_smooth=False,
...     bounding_box=None,
...     accept_all=False,
...     material=None,
...     collection=None,
...     **kwargs
... ):
...     ...

See also

Api documentation of to_blender_object_helper().

Here are the examples from above using the helper function:

>>> ddg.to_blender_object_helper(
...     cube,
...     name="Cube to_blender_object_helper version",
...     location=[1, 1, 1],
...     hide_viewport=False,
...     hide_render=False,
...     scale=[0.5, 0.5, 1],
... )
bpy.data.objects['Cube to_blender_object_helper version']

>>> col = ddg.visualization.blender.collection.collection("cube_collection")
>>> black = ddg.visualization.blender.material.material(color=(0, 0, 0))
>>> ddg.to_blender_object_helper(
...     cube,
...     name="Cube with material to_blender_object_helper version",
...     collection=col,
...     material=black,
... )
bpy.data.objects['Cube with material to_blender_object_helper version']

>>> ddg.to_blender_object_helper(
...     cube,
...     name="Cube with smooth shading and bounding box",
...     shade_smooth=True,
...     bounding_box=[1, 1, 1],
... )
bpy.data.objects['Cube with smooth shading and bounding box']

Note

The function to_blender_object_helper() only supports bounding boxes with center=[0,0,0].