This is databpy!

This is intended as a cleaner way to work with data and attributes on mesh objects in Blender. The goal is to help make importing and working with tabular datasets from outside of Blender as objects inside of blender a whole lot easier.

Not Stable

Active development and refinements are still ongoing. The main functions store_named_attribute and named_attribute are stable, but a lot of the other functionality is still in development. They provide the majority of the useful functionality.

databpy originally started as a submodule inside of Molecular Nodes but has been split off into it’s own package for use by other projects. Some internal code is still quite specific to the use case of Molecular Nodes, but the majority is more general.

Hello World

The ‘Hello World’ example is storing and retrieving data from a mesh objects inside of Blender.

While the bpy API is robust, it is a bit too verbose for what we are after, and there are many particulars that you can’t intuit (you have to store the value for floats, vector for 2 & 3 component vectors, but value for a Quaternion which is a 4-component vector).

See the enums in the API documentation for the different Attribute Types and Attribute Domains.

Regular bpy API

import bpy
import numpy as np

np.random.seed(6)

new_float_values = np.random.randn(8 * 3).reshape(-1, 3)

obj = bpy.data.objects["Cube"]

# create new attribute, then fill with data from a 1D numpy array
att = obj.data.attributes.new("test_float", "FLOAT_VECTOR", "POINT")
att.data.foreach_set("vector", new_float_values.reshape(-1))

# initialise empty array to fill, get data and then reshape to correct dimensions
empty_vector = np.zeros(len(att.data) * 3, dtype=float)
att.data.foreach_get("vector", empty_vector)
empty_vector.reshape((-1, 3))

array([[-0.31178367,  0.72900391,  0.21782079],
       [-0.89909178, -2.48678064,  0.91325152],
       [ 1.12706375, -1.51409328,  1.63929105],
       [-0.42989361,  2.63128066,  0.60182226],
       [-0.33588162,  1.23773789,  0.11112817],
       [ 0.12915125,  0.07612761, -0.15512815],
       [ 0.63422537,  0.810655  ,  0.3548086 ],
       [ 1.81259036, -1.35647583, -0.46363196]])

databpy API

We can get and set values with single function calls. Data types are inferred from the numpy array data types, but can be manually specified. The point domain is the default domain, but domain can also be specified. See the AttributeDomains for more which domains can be chosen.

import databpy as db
db.store_named_attribute(obj, new_float_values, "example_values")
db.named_attribute(obj, "example_values")

array([[-0.31178367,  0.72900391,  0.21782079],
       [-0.89909178, -2.48678064,  0.91325152],
       [ 1.12706375, -1.51409328,  1.63929105],
       [-0.42989361,  2.63128066,  0.60182226],
       [-0.33588162,  1.23773789,  0.11112817],
       [ 0.12915125,  0.07612761, -0.15512815],
       [ 0.63422537,  0.810655  ,  0.3548086 ],
       [ 1.81259036, -1.35647583, -0.46363196]])

A more friendly Blender Object (bob)

Doing some common data-oriented operations on objects in Blender can be a bit of a pain, so databpy provides a BlenderObject class that wraps mesh objects and provides some convenience functions.

The most useful are the store_named_attribute and named_attribute functions that just work on the mesh object, so you can quickly get and set attributes with bob.

bob = db.BlenderObject(bpy.data.objects["Cube"])

bob.store_named_attribute(new_float_values, "example_values")
bob.named_attribute("example_values")

array([[-0.31178367,  0.72900391,  0.21782079],
       [-0.89909178, -2.48678064,  0.91325152],
       [ 1.12706375, -1.51409328,  1.63929105],
       [-0.42989361,  2.63128066,  0.60182226],
       [-0.33588162,  1.23773789,  0.11112817],
       [ 0.12915125,  0.07612761, -0.15512815],
       [ 0.63422537,  0.810655  ,  0.3548086 ],
       [ 1.81259036, -1.35647583, -0.46363196]])