entities.trajectory.selections.SelectionManager
entities.trajectory.selections.SelectionManager(trajectory)Manages all atom selections for a trajectory.
The SelectionManager coordinates between Selection objects (Python side), Blender UI properties, and geometry node attributes. It provides methods to create, retrieve, and remove selections, and maintains synchronization between the different representation layers.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| trajectory | Trajectory | The parent trajectory object this manager belongs to. | required |
Attributes
| Name | Type | Description |
|---|---|---|
| trajectory | Trajectory | Reference to the parent trajectory. |
Methods
| Name | Description |
|---|---|
| add | Create and register a new selection from a selection string. |
| append | Register an existing Selection object with this manager. |
| create_selection | Create and register a new selection with validation. |
| from_atomgroup | Create a Selection from an existing MDAnalysis AtomGroup. |
| from_ui_item | Create a Selection from a Blender UI property item. |
| get | Retrieve a Selection by name. |
| has_selection | Check if a selection exists. |
| register_selection | Register an existing Selection object with this manager. |
| remove | Remove a selection from the manager and clean up all references. |
| sync_all_from_ui | Synchronize all selections from UI properties. |
add
entities.trajectory.selections.SelectionManager.add(
string,
name='selection_0',
updating=True,
periodic=False,
)Create and register a new selection from a selection string.
Creates a new Selection object with the specified parameters and registers it with both the manager’s internal dictionary and the Blender UI property collection.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| string | str | MDAnalysis selection string (e.g., “name CA”, “resid 1:10”). | required |
| name | str | Unique name for this selection. Default is “selection_0”. | 'selection_0' |
| updating | bool | Whether the selection updates every frame. Default is True. | True |
| periodic | bool | Whether to consider periodic boundary conditions. Default is False. | False |
Returns
| Name | Type | Description |
|---|---|---|
| Selection | The newly created and registered Selection object. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If a selection with the given name already exists. |
append
entities.trajectory.selections.SelectionManager.append(selection)Register an existing Selection object with this manager.
.. deprecated:: Use register_selection() instead for clearer intent.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| selection | Selection | The Selection object to register. | required |
create_selection
entities.trajectory.selections.SelectionManager.create_selection(
string,
name='selection_0',
updating=True,
periodic=False,
validate_unique=True,
)Create and register a new selection with validation.
This is the preferred method for creating new selections as it includes proper validation.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| string | str | MDAnalysis selection string (e.g., “name CA”, “resid 1:10”). | required |
| name | str | Unique name for this selection. Default is “selection_0”. | 'selection_0' |
| updating | bool | Whether the selection updates every frame. Default is True. | True |
| periodic | bool | Whether to consider periodic boundary conditions. Default is False. | False |
| validate_unique | bool | Whether to validate that the name is unique. Default is True. | True |
Returns
| Name | Type | Description |
|---|---|---|
| Selection | The newly created and registered Selection object. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If validate_unique=True and a selection with the given name already exists. |
from_atomgroup
entities.trajectory.selections.SelectionManager.from_atomgroup(
atomgroup,
name='NewSelection',
)Create a Selection from an existing MDAnalysis AtomGroup.
Wraps an AtomGroup in a Selection object and stores the initial mask as a Blender geometry attribute. Useful for creating selections from programmatically defined AtomGroups.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| atomgroup | mda.AtomGroup |
MDAnalysis AtomGroup or UpdatingAtomGroup to wrap. | required |
| name | str | Name for the new selection. Default is “NewSelection”. | 'NewSelection' |
Returns
| Name | Type | Description |
|---|---|---|
| Selection | The newly created Selection object. |
See Also
Selection.from_atomgroup : The underlying classmethod used to create the Selection.
from_ui_item
entities.trajectory.selections.SelectionManager.from_ui_item(item)Create a Selection from a Blender UI property item.
Creates a new Selection based on the properties stored in a Blender UI property item, typically used when loading from a saved .blend file.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| item | TrajectorySelectionItem |
Blender property group containing selection parameters. | required |
Returns
| Name | Type | Description |
|---|---|---|
| Selection | The newly created Selection object. |
get
entities.trajectory.selections.SelectionManager.get(name, lazy_init=True)Retrieve a Selection by name.
If the selection exists in the UI properties but not in the Python runtime (common when loading from saved .blend files), it will be lazily initialized from the UI property.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| name | str | Name of the selection to retrieve. | required |
| lazy_init | bool | If True, attempts to initialize the selection from UI properties if it doesn’t exist in Python runtime. Default is True. | True |
Returns
| Name | Type | Description |
|---|---|---|
| Selection | The Selection object with the given name. |
Raises
| Name | Type | Description |
|---|---|---|
| KeyError | If no selection with the given name exists in either Python runtime or UI properties. |
Notes
Lazy initialization ensures that selections persist correctly when loading .blend files, where UI properties are restored but Python objects need to be reconstructed.
has_selection
entities.trajectory.selections.SelectionManager.has_selection(name)Check if a selection exists.
Checks both the Python runtime and UI properties for the selection.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| name | str | Name of the selection to check. | required |
Returns
| Name | Type | Description |
|---|---|---|
| bool | True if the selection exists, False otherwise. |
register_selection
entities.trajectory.selections.SelectionManager.register_selection(selection)Register an existing Selection object with this manager.
Adds a Selection object to the internal dictionary without creating a new UI property (assumes the Selection was created via a classmethod that already handled UI property creation).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| selection | Selection | The Selection object to register. | required |
Notes
This method is typically used internally by factory methods like from_atomgroup() after they’ve created both the UI property and the Selection object.
remove
entities.trajectory.selections.SelectionManager.remove(name)Remove a selection from the manager and clean up all references.
Removes the selection from the internal dictionary, the Blender UI property collection, and the geometry node attribute. Handles cases where the selection may be partially registered.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| name | str | Name of the selection to remove. | required |
Notes
Silently ignores KeyError or AttributeError if the selection was not fully registered in all locations.
sync_all_from_ui
entities.trajectory.selections.SelectionManager.sync_all_from_ui()Synchronize all selections from UI properties.
Iterates through all UI property items and ensures that each has a corresponding Python Selection object. This is useful when loading from saved .blend files where the UI properties are restored but Python objects need to be reconstructed.
Notes
This method is typically called during trajectory initialization or when loading from disk. It ensures that the Python runtime state matches the persistent UI property state.