moleculekit.viewer.molstar.registry module

Slot registry and topology hashing for the molstar viewer.

class moleculekit.viewer.molstar.registry.Registry

Bases: object

Thread-safe slot table for the molstar viewer.

Maps slot uuids to Slot entries, each holding a live Molecule reference and a snapshot for change detection. All mutating operations are guarded by an internal lock so the monitor thread and request handlers can share it.

diff_and_snapshot()

Diff each slot’s live mol against its snapshot.

Updates each changed slot’s snapshot (and topo_hash on a topology change) in place after diffing.

Returns:

changes – One (kind, slot_uuid, payload_hints) tuple per changed slot, where kind is "topology" or "coords". Empty when nothing changed.

Return type:

list[tuple[str, str, dict]]

register(mol)

Register a molecule and return its slot uuid.

If mol is already registered (same object identity), its existing uuid is returned and no new slot is created.

Parameters:

mol (Molecule) – The live molecule to track.

Returns:

uid – The slot uuid for mol.

Return type:

str

remove(uid)

Remove the slot with the given uuid, if present.

Parameters:

uid (str) – The slot uuid to remove. A missing uuid is a no-op.

Return type:

None

class moleculekit.viewer.molstar.registry.Slot(uuid, mol_ref, snapshot, topo_hash, label, visible=True)

Bases: object

A single registered molecule tracked by the viewer Registry.

uuid

Short uppercase hex identifier for the slot.

Type:

str

mol_ref

The live, mutable Molecule reference held by the user.

Type:

moleculekit.molecule.Molecule

snapshot

A mol.copy() snapshot used for diffing against mol_ref.

Type:

moleculekit.molecule.Molecule

topo_hash

The topology hash of snapshot (see topo_hash).

Type:

str

label

Human-readable label shown in the viewer.

Type:

str

visible

Whether the slot is currently shown. Defaults to True.

Type:

bool

label: str

mol_ref: Any

snapshot: Any

topo_hash: str

uuid: str

visible: bool = True

moleculekit.viewer.molstar.registry.coords_to_bytes(mol)

Return all frames as little-endian float32 bytes.

Layout: per frame, the flat [x0..xN, y0..yN, z0..zN] vector matching the per-frame layout used by molecule_to_dict.

Parameters:

mol (Molecule) – The molecule whose coordinates are encoded.

Returns:

blob – Little-endian float32 bytes for all frames, frame-major.

Return type:

bytes

moleculekit.viewer.molstar.registry.topo_hash(mol)

Stable sha1 hex over the topology-defining fields of a Molecule.

Skipped: coords, beta, occupancy, charge (partial charge) — these can vary without a structural change to the rendered scene.

Parameters:

mol (Molecule) – The molecule to hash.

Returns:

digest – The hex sha1 digest of the topology fields and bonds.

Return type:

str