entities.Molecule

entities.Molecule(self, array, reader=None)

Primary Molecular Nodes class that coordinates the conversion of structural bioinformatic data into raw Blender data. Most notable the conversion of atoms and bonds into a collection of vertices and lines.

It associates the atomic data (the array) with the created 3D model inside of Blender (the object). If multiple conformations are imported, then a frames collection is also instantiated.

The named_attribute() and store_named_attribute() methods access and set attributes on object that is in the Blender scene.

Attributes

Name	Type	Description
object	bpy.types.Object	The Blender object representing the molecule.
frames	bpy.types.Collection	The Blender collection which holds the objects making up the frames to animate.
array	AtomArray \| AtomArrayStack:	The numpy array which stores the atomic coordinates and associated attributes.
select	MoleculeSelector	A selector object that provides methods for creating atom selections based on various criteria such as atom name, residue type, chain ID, etc. These selections can be used with the `add_style` method to apply visual styles to specific parts of the molecule.

Methods

Name	Description
add_style	Add a visual style to the molecule.
assemblies	Get the biological assemblies of the molecule.
centre_molecule	Offset positions to centre the atoms and vertices over either the geometric centroid
create_object	Create a 3D model of the molecule, with one vertex for each atom.
fetch	Fetch a molecule from the RCSB database.
load	Load a molecule from a file.

add_style

entities.Molecule.add_style(
    style='spheres',
    color='common',
    selection=None,
    assembly=False,
    material=None,
)

Add a visual style to the molecule.

Parameters

Name	Type	Description	Default
style	bpy.types.GeometryNodeTree \| str	The style to apply to the molecule. Can be a GeometryNodeTree or a string identifying a predefined style (e.g., “spheres”, “sticks”, “ball_stick”). Default is “spheres”.	`'spheres'`
color	str \| None	The coloring scheme to apply. Can be “common” (element-based coloring), “chain”, “residue”, or other supported schemes. If None, no coloring is applied. Default is “common”.	`'common'`
selection	str \| MoleculeSelector \| None	Apply the style only to atoms matching this selection. Can be: - A string referring to an existing boolean attribute on the molecule - A MoleculeSelector object defining a selection criteria - None to apply to all atoms (default)	`None`
assembly	bool	If True, set up the style to work with biological assemblies. Default is False.	`False`
material	bpy.types.Material \| str \| None	The material to apply to the styled atoms. Can be a Blender Material object, a string with a material name, or None to use default materials. Default is None.	`None`

Returns

Name	Type	Description
	Molecule	Returns self for method chaining.

Notes

If a MoleculeSelector is provided, it will be evaluated and stored as a new named attribute on the molecule with an automatically generated name (sel_N).

assemblies

entities.Molecule.assemblies(as_array=False)

Get the biological assemblies of the molecule.

Parameters

Name	Type	Description	Default
as_array	bool	Whether to return the assemblies as an array of quaternions. Default is False.	`False`

Returns

Name	Type	Description
	dict or None	The biological assemblies of the molecule, as a dictionary of transformation matrices, or None if no assemblies are available.

centre_molecule

entities.Molecule.centre_molecule(method='centroid')

Offset positions to centre the atoms and vertices over either the geometric centroid or the centre of mass.

create_object

entities.Molecule.create_object(name='NewObject')

Create a 3D model of the molecule, with one vertex for each atom.

fetch

entities.Molecule.fetch(
    code,
    format='.bcif',
    centre=None,
    cache=download.CACHE_DIR,
    database='rcsb',
)

Fetch a molecule from the RCSB database.

Parameters

Name	Type	Description	Default
code	str	The PDB ID code of the molecule to fetch.	required
format	str	The file format to download. Default is “.bcif”.	`'.bcif'`
centre	str \| None	Method to use for centering the molecule. Options are “centroid” (geometric center) or “mass” (center of mass). If None, no centering is performed. Default is None.	`None`
cache	str	Path to cache directory. If None, no caching is performed.	`download.CACHE_DIR`
database	str	The database to fetch from. Default is “rcsb”.	`'rcsb'`

Returns

Name	Type	Description
	Molecule	A new Molecule instance created from the downloaded data.

load

entities.Molecule.load(file_path, name=None)

Load a molecule from a file.

Parameters

Name	Type	Description	Default
file_path	str \| Path	Path to the molecular structure file.	required
name	str \| None	Name to assign to the created molecule object. If None, the file’s stem (filename without extension) will be used as the name. Default is None.	`None`

Returns

Name	Type	Description
	Molecule	A new Molecule instance created from the loaded file data.

Notes

This method automatically filters out solvent molecules from the structure. Future versions may make this behavior optional.