entities.StreamingTrajectory

entities.StreamingTrajectory(
    universe,
    name='StreamingTrajectory',
    create_object=True,
)

Molecule subclass for IMD streaming connections.

Handles real-time molecular dynamics trajectories streamed via the IMD protocol. Unlike regular trajectories with random frame access, streaming trajectories read frames sequentially as they become available.

Parameters

Name	Type	Description	Default
universe	`MDAnalysis`.`Universe`	MDAnalysis Universe with IMD reader	required
name	str	Name for the trajectory object, by default “StreamingTrajectory”	`'StreamingTrajectory'`
create_object		Create the mesh object to be linked to this trajectory	`True`

Attributes

Name	Description
atoms	All atoms as MDAnalysis AtomGroup.
n_frames	Return None for streaming trajectories (unknown frame count).
props	The custom Blender properties for the molecule object.
uframe	Current frame number in MDAnalysis Universe.

Methods

Name	Description
add_style	Add a visual style to the trajectory.
assemblies	Get the biological assemblies parsed from the source file.
create_asset_nodes	Create asset nodes for the entity object.
create_data_object	Create the data object holding the biological assembly transforms.
create_object	Create and initialize Blender object for trajectory.
fetch	Fetch a structure from an online database into a Universe-backed entity.
frames_to_collection	Bake a range of trajectory frames into a collection of frame objects.
from_file	Load a single structure file into a Universe-backed entity.
get_view	The world-space positions of a view onto this molecule.
reset_playback	Set the playback settings to their default values
set_frame	Update trajectory state for scene frame.

add_style

entities.StreamingTrajectory.add_style(
    style='spheres',
    selection=None,
    material=_UNSET,
    color=None,
    assembly=False,
    name=None,
    **kwargs,
)

Add a visual style to the trajectory.

Provides a simple interface for adding visual styles to the molecule. For more complex styling, use the manual node tree creation via the with mol.tree: context manager.

Parameters

Name	Type	Description	Default
style	str \| Callable	The style to apply. Either a string naming a predefined style (“spheres”, “cartoon”, “ribbon”, “surface”, “sticks”, “ball_and_stick”), or a zero-argument callable returning a style node, evaluated inside the node tree context:: mol.add_style(lambda: mg.StyleCartoon(quality=5, loop_radius=0.6)) A callable defines the style node itself, so `selection`, `material` and extra keyword arguments cannot be combined with it - set them inside the callable. Default is “spheres”.	`'spheres'`
selection	str \| AtomGroup \| Callable \| None	Apply the style only to atoms matching this selection. Can be: - A string naming an existing boolean attribute on the molecule (used directly) - A string MDAnalysis selection phrase (evaluated and stored as a new managed selection attribute) - A AtomGroup object defining a selection criteria - A zero-argument callable returning a boolean socket, evaluated inside the node tree context, e.g. `lambda: mg.IsPeptide() & mg.IsSideChain()` - None to apply to all atoms (default) A string is treated as an existing attribute name first; only if no such attribute exists is it interpreted as an MDAnalysis selection phrase.	`None`
material	`bpy`.types.Material \| PresetMaterial \| `MaterialBuilder` \| str \| None	The material to apply to the styled atoms. Can be one of the preset materials from `mn.material` (e.g. `mn.material.AmbientOcclusion()`), a Blender Material object, a nodebpy MaterialBuilder, a string with a material name to append from the asset file, or None for no material. Default is “MN Default”.	`_UNSET`
color	str \| Sequence[float] \| Callable \| None	Coloring to apply upstream of the style via a `Set Color` node. Can be: - `"common"` / `"default"` for standard element colors with carbons colored randomly per chain - `"plddt"` to color by pLDDT (B-factor) confidence - the name of an existing color attribute on the geometry - an RGBA sequence of floats for a single uniform color - a zero-argument callable returning a color socket, evaluated inside the node tree context, e.g. `lambda: mg.ColorRainbow()`. This is the way to reach the full set of `Color*` nodes without writing out a whole node tree. - None (default) to add no color node, leaving the baked `Color` attribute in use. A string that is neither a keyword nor an existing color attribute raises a `UserWarning` and no color is applied.	`None`
assembly	bool	Instance the style over the biological assembly transforms parsed from the source file, via an `Assembly Instance` node. Default is False.	`False`
name	str \| None	Optional label for the added style node, shown in the node editor and style lists. Default is None.	`None`
**kwargs	`optional`	Additional keyword arguments passed to the style node, matching that node’s inputs (e.g. `quality`, `scale`, `sphere` for `spheres`). Unknown names raise a `TypeError`. Cannot be combined with a callable `style`.	`{}`

Returns

Name	Type	Description
	Molecule	Returns self for method chaining.

Raises

Name	Type	Description
	ValueError	If an unsupported style string is passed
	TypeError	If a callable `style` is combined with `selection`, `material` or extra keyword arguments, or if a keyword argument does not match an input on the style node

Notes

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

assemblies

entities.StreamingTrajectory.assemblies(as_array=False)

Get the biological assemblies parsed from the source file.

Parameters

Name	Type	Description	Default
as_array	bool	Return the assemblies as a structured array of per-chain 4x4 transforms rather than a dict.	`False`

Returns

Name	Type	Description
	dict \| np.ndarray \| None	The biological assemblies as transformation matrices, or `None` when the structure has no assembly data.

create_asset_nodes

entities.StreamingTrajectory.create_asset_nodes()

Create asset nodes for the entity object.

This creates Select and Color nodes for each property combination. Chains, entities, and segments have nodes created for them if they have IDs. Nodes are created and registered as assets for the current Blender session so they can be added through drag-to-search in the node editor.

create_data_object

entities.StreamingTrajectory.create_data_object()

Create the data object holding the biological assembly transforms.

create_object

entities.StreamingTrajectory.create_object(name='NewUniverseObject')

Create and initialize Blender object for trajectory.

Creates mesh, computes attributes, sets up modifiers, registers with MolecularNodes.

Parameters

Name	Type	Description	Default
name	str	Name for the Blender object	`"NewUniverseObject"`

Returns

Name	Type	Description
	`bpy`.types.Object	Created Blender object

fetch

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

Fetch a structure from an online database into a Universe-backed entity.

Parameters

Name	Type	Description	Default
code	str	The database accession code (e.g. a PDB id).	required
format	str	File format to download, by default `".bcif"`.	`'.bcif'`
cache	Path \| str \| None	Directory to cache downloads in.	`download.CACHE_DIR`
database	str	The database to fetch from, by default `"rcsb"`.	`'rcsb'`

Returns

Name	Type	Description
	Molecule	The Universe-backed entity representing the fetched structure.

frames_to_collection

entities.StreamingTrajectory.frames_to_collection(
    start=0,
    stop=None,
    step=1,
    name=None,
)

Bake a range of trajectory frames into a collection of frame objects.

Each object in the returned collection holds the atom positions (in Blender world units) for a single frame, in the same vertex order as this molecule’s mesh. The collection can then be read inside geometry nodes (e.g. with the Animate Frames node) to drive positions from baked data, rather than updating the Universe every scene frame.

Re-baking replaces any objects previously baked into the same collection.

Parameters

Name	Type	Description	Default
start	int	First trajectory frame to bake (inclusive).	`0`
stop	int \| None	One past the last frame to bake. Defaults to the number of frames in the trajectory (i.e. bake through the final frame).	`None`
step	int	Stride between baked frames.	`1`
name	str \| None	Name for the frames collection. Defaults to this molecule’s name.	`None`

Returns

Name	Type	Description
	`bpy`.types.Collection	The collection of baked frame objects.

Raises

Name	Type	Description
	ValueError	If `step` is not a positive integer.

from_file

entities.StreamingTrajectory.from_file(file_path, name=None)

Load a single structure file into a Universe-backed entity.

The file (.pdb/.cif/.bcif/.sdf/.mol) is parsed by the biotite readers and converted into an MDAnalysis Universe via :func:~molecularnodes.converters.universe_from_atoms. Multi-model files become multi-frame universes. Biological assembly and entity/chain metadata parsed from the file are stored on the Blender object.

Small-molecule crystallographic .cif files (e.g. from the ICSD or COD) are instead read by :mod:~molecularnodes.entities.molecule.corecif, which expands the asymmetric unit by the file’s symmetry operators to fill one unit cell. .xyz files are read natively by MDAnalysis, with elements taken from the atom names.

Parameters

Name	Type	Description	Default
file_path	str \| Path \| io.BytesIO	Path to the structure file (or an in-memory `bcif` buffer).	required
name	str \| None	Name for the Blender object. Defaults to the file name (extension included).	`None`

Returns

Name	Type	Description
	Molecule	The Universe-backed entity representing the structure.

get_view

entities.StreamingTrajectory.get_view(selection=None, frame=None)

The world-space positions of a view onto this molecule.

Without a selection these are the positions of the geometry the molecule renders; with one they are the positions of the selected atoms. Pass the result to look_at to frame it, or combine views from several selections with + to frame all of them together.

Parameters

Name	Type	Description	Default
selection	str \| AtomGroup	A selection phrase or AtomGroup When not specified, the whole entity is considered	`None`
frame	int \| None	Frame number of trajectory to use for calculating bounds. When not specified, current trajectory frame is used	`None`

reset_playback

entities.StreamingTrajectory.reset_playback()

Set the playback settings to their default values

set_frame

entities.StreamingTrajectory.set_frame(frame)

Update trajectory state for scene frame.

Main entry point called by Blender’s animation system. Updates positions, selections, and calculations with recursion prevention.

Parameters

Name	Type	Description	Default
frame	int	Scene frame number (mapping applied to get Universe frame)	required

Notes

Typically called automatically by frame change handlers, not user code.