databpy is still before its 1.0 release, so there may be breaking changes before then. The main interfaces for getting and setting attributes are expected to stay stable.
databpy reads and writes the attributes of mesh, curves and point cloud objects in Blender as NumPy arrays. It is built for importing tabular data from outside Blender as objects inside Blender, and working with it there. It supports Blender 5.1 and later.
TipGetting started
The attributes guide covers the attribute system: the attribute types and domains, reading and writing attributes, performance, and errors.
databpy started as a submodule of Molecular Nodes and was split off into its own package for use by other projects. Some internal code is still specific to Molecular Nodes, but most of it is general.
Hello world
The ‘Hello world’ example stores data on a mesh object in Blender and reads it back.
The bpy API needs several calls for this, and the property that holds the values depends on the type: value for floats, vector for 2 and 3 component vectors, but value for a quaternion, which also has 4 components.
import bpyimport numpy as npnp.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 arrayatt = 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 dimensionsempty_vector = np.zeros(len(att.data) *3, dtype=float)att.data.foreach_get("vector", empty_vector)empty_vector.reshape((-1, 3))
Getting and setting values takes one function call each. The attribute type is inferred from the array’s dtype and shape, or can be given explicitly. Attributes are stored on the point domain unless another domain is given; see AttributeDomains for the domains available.
import databpy as dbdb.store_named_attribute(obj, new_float_values, "example_values")db.named_attribute(obj, "example_values")
create_bob() creates a mesh object from an array of vertex positions and wraps it. Attributes can also be read as properties and items, such as bob.position and bob["position"], which return an AttributeArray that writes changes back to Blender:
Columns of a data frame can be stored as attributes. Here each column of a JSON table holds a list of 3D points, which are stored as FLOAT_VECTOR attributes on a new object with one vertex per row:
import polars as plfrom io import StringIOjson_file = StringIO("""{ "Dino": [ [55.3846, 97.1795, 0.0], [51.5385, 96.0256, 0.0] ], "Star": [ [58.2136, 91.8819, 0.0], [58.1961, 92.215, 0.0] ]}""")df = pl.read_json(json_file)columns_to_explode = [col for col in df.columns if df[col].dtype == pl.List(pl.List)]df = df.explode(columns_to_explode, empty_as_null=True)vertices = np.zeros((len(df), 3), dtype=np.float32)bob = db.create_bob(vertices, name="DinoStar")for col in df.columns: data = np.vstack(df.get_column(col).to_numpy()) bob.store_named_attribute(data, col)bob.named_attribute("Dino")
