Structure Sessions

Overview

StructureSession (in codemol/structure_session.py) tracks which objects belong to each loaded structure. This enables per-structure visibility toggling, scene saving, and automatic cleanup.

Core Class

class StructureSession:
    def __init__(self):
        self._objects: dict[str, set[str]] = {}  # structure → object names
        self._active: str | None = None
        self._has_scene: set[str] = set()        # structures with saved scenes

Key Operations

Register a Structure

When a structure is loaded:

session.register_structure("1AKE")
# Creates entry: {"1AKE": set()}

Associate Objects

As the user creates measurements, selections, or other visual objects, they're linked to the active structure:

session.associate("dist_0", "1AKE")  # distance measurement
session.associate("hbonds_1AKE", "1AKE")  # interaction visualization

Activate a Structure

Switching to a different structure:

session.activate("4AKE", cmd)

This triggers a cascade:

graph TD
    A["activate('4AKE', cmd)"] --> B[Save scene for old structure]
    B --> C[Disable old structure + its objects]
    C --> D[Enable new structure + its objects]
    D --> E[Recall saved scene for new structure]
    E --> F[Update active reference]

Remove a Structure

session.remove_structure("1AKE", cmd)
# Deletes all associated objects
# Removes from tracking

Object Association Flow

sequenceDiagram
    participant User
    participant Tool as Distance Tool
    participant Registry as MeasurementRegistry
    participant Session as StructureSession

    User->>Tool: /measure distance A/45/CA A/120/CA
    Tool->>Tool: cmd.distance("dist_0", ...)
    Tool->>Registry: register("dist_0", "distance", 3.45, ...)
    Note over Session: Window associates after tool returns
    Session->>Session: associate("dist_0", active_structure)

Internal Object Filtering

Objects starting with _ are considered internal and excluded from the sidebar display:

# Internal objects (not shown in sidebar):
_ribbons, _nearby, _metals, _sel_indicator, _click_indicator, _pick_indicators

# Also filtered: dist_*, metal_coord*

Scene Save/Restore

Each structure can have a saved scene (camera position, object visibility, representation state):

session.save_scene(cmd)       # Saves current view for active structure
session.has_scene("1AKE")     # True if scene was saved

Scenes are automatically saved/restored during activate() to preserve per-structure camera angles and visual state.

Enable All

For side-by-side comparison:

session.enable_all(cmd)
# Shows all structures simultaneously
# Scope becomes None (no auto-scoping)