Molecule

Molecule(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.
get_view	Get the 3D bounding box of the entity object
load	Load a molecule from a file.
set_frame	Update the underlying data to correspond to changes in the scene frame.

add_style

Molecule.add_style(
    style='spheres',
    color='common',
    selection=None,
    assembly=False,
    material=None,
    name=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`
name	str \| None	The label for this style	`None`

Returns

Name	Type	Description
	Molecule	Returns self for method chaining.

Raises

Name	Type	Description
	ValueError	If an unsupported style string is passed

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

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

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

Molecule.create_object(name='NewObject')

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

fetch

Molecule.fetch(
    code,
    format='.bcif',
    centre=None,
    remove_solvent=True,
    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`
remove_solvent	bool	Whether to remove solvent from the molecule. Default is True.	`True`
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.

get_view

Molecule.get_view()

Get the 3D bounding box of the entity object

load

Molecule.load(file_path, name=None, remove_solvent=True)

Load a molecule from a file.

Parameters

Name	Type	Description	Default
file_path	str or Path	The path to the file containing molecular data	required
name	str or None	The name to give the molecule object. If None, uses the filename stem	`None`
remove_solvent	bool	Whether to remove solvent molecules from the structure, default True	`True`

Returns

Name	Type	Description
mol	Molecule	The loaded molecule object with associated data and 3D representation

Notes

Supports various file formats including .cif, .bcif, .pdb, .sdf, and .mol

set_frame

Molecule.set_frame(frame)

Update the underlying data to correspond to changes in the scene frame.

This method should be implemented by subclasses to update the entity’s data based on the given frame number. This can include updating positions and performing other necessary calculations.

Args: frame (int): The frame number to update the entity’s data to.

Raises: NotImplementedError: If the method is not implemented by a subclass.