molsysviewer.shapes package

Submodules

molsysviewer.shapes.anisotropy_ellipsoids module

class molsysviewer.shapes.anisotropy_ellipsoids.AnisotropyEllipsoids(view)

Bases: object

Visualize oriented ellipsoids/disks from eigenvalues/eigenvectors or tensors.

add_anisotropy_ellipsoids(*, centers, eigenvalues=None, eigenvectors=None, tensors=None, principal_directions=None, scale=None, max_eccentricity=None, color_mode=None, colors=None, color_map=None, values=None, alpha=None, tag=None, name=None)

Send oriented ellipsoids or flat disks based on anisotropy inputs.

Parameters:

• centers (Iterable[Sequence[float]])

• eigenvalues (Iterable[Sequence[float]] | None)

• eigenvectors (Iterable[Sequence[Sequence[float]]] | None)

• tensors (Iterable[Sequence[Sequence[float]]] | None)

• principal_directions (Iterable[Sequence[float]] | None)

• scale (float | None)

• max_eccentricity (float | None)

• color_mode (str | None)

• colors (Sequence[int] | None)

• color_map (Sequence[int] | str | None)

• values (Sequence[float] | None)

• alpha (float | None)

• tag (str | None)

• name (str | None)

molsysviewer.shapes.channel_tubes module

class molsysviewer.shapes.channel_tubes.ChannelTubes(view)

Bases: object

API to build channel tubes along ordered centers/radii (e.g., TopoMT routes).

add_channel_tube(*, centers, radii, color_mode=None, solvent_distances=None, colors=None, color_map=None, radial_segments=None, smoothing_subdivisions=None, alpha=None, tag=None, name=None)

Generate a smoothed tube from ordered centers/radii (e.g., TopoMT routes).

Parameters:

• centers (Iterable[Sequence[float]])

• radii (Iterable[float])

• color_mode (str | None)

• solvent_distances (Iterable[float] | None)

• colors (Sequence[int] | None)

• color_map (Sequence[int] | str | None)

• radial_segments (int | None)

• smoothing_subdivisions (int | None)

• alpha (float | None)

• tag (str | None)

• name (str | None)

molsysviewer.shapes.displacements module

Helpers to render displacement vectors.

class molsysviewer.shapes.displacements.DisplacementVectors(view)

Bases: object

add_displacement_vectors(origins, vectors, *, atom_indices=None, length_scale=1.0, min_length=0.0, max_length=None, color_mode='norm', color_component=2, color_map=None, radius_scale=0.05, radial_segments=None, tag=None)

Add arrows (cylinder + cone) for displacement vectors.

Parameters:

• origins (Iterable[Sequence[float]] | ndarray | None) – Origin coordinates (n, 3). Optional if you use atom_indices.

• vectors (Iterable[Sequence[float]] | ndarray) – Displacement vectors (n, 3).

• atom_indices (Iterable[int] | None) – Atom indices to use the current structure coordinates as origins.

• length_scale (float) – Global scale factor for vector lengths.

• min_length (float) – Minimum length after scaling; shorter vectors are skipped.

• max_length (float | None) – Normalize the resulting maximum length to this value (if set).

• color_mode (str) – “norm” or “component” to map colors by norm or by component.

• color_component (int) – Component used for “component” coloring (0, 1, or 2).

• color_map (Sequence[int] | str | None) – Optional palette (color list or a Mol*-recognized name).

• radius_scale (float) – Relative radius factor (relative to final length).

• radial_segments (int | None) – Optional radial segments for cylinder/cone.

• tag (str | None) – Optional tag for the Mol* state node.

molsysviewer.shapes.links module

Helpers to render custom links/cylinders.

class molsysviewer.shapes.links.LinkShapes(view)

Bases: object

add_links(*, atom_pairs=None, coordinate_pairs=None, radii=0.2, colors=4495871, pocket_ids=None, chain_ids=None, color_mode='link', alpha=1.0, radial_segments=None, tag=None)

Add cylinders/bars connecting pairs of points or atoms.

Parameters:

• atom_pairs (Iterable[Sequence[int]] | None) – Pairs of atom indices (0-based) to connect. If provided, the current coordinates of the loaded structure are used.

• coordinate_pairs (Iterable[Sequence[Sequence[float]]] | None) – Lista de pares de coordenadas [[x1, y1, z1], [x2, y2, z2]].

• radii (float | Sequence[float]) – Scalars or lists (one per link) for radius and color.

• colors (int | Sequence[int]) – Scalars or lists (one per link) for radius and color.

• pocket_ids (Sequence[int | str] | None) – Optional identifiers to color by pocket or chain.

• chain_ids (Sequence[str] | None) – Optional identifiers to color by pocket or chain.

• color_mode (str) – “link” | “pocket” | “chain”.

• alpha (float) – Global alpha (0-1).

• radial_segments (int | None) – Cylinder radial segments (>=3). Default is 16.

• tag (str | None) – Optional tag for the Mol* state node.

molsysviewer.shapes.pharmacophore module

class molsysviewer.shapes.pharmacophore.PharmacophoreShapes(view)

Bases: object

API for pharmacophore glyphs (spheres/disks/arrows).

add_pharmacophore_features(*, centers, kinds, radii=None, directions=None, alphas=None, colors=None, tag=None, name=None)

Render standard pharmacophore glyphs (sphere/disk/arrow).

Parameters:

• centers (Iterable[Sequence[float]])

• kinds (Sequence[str])

• radii (float | Sequence[float] | None)

• directions (Iterable[Sequence[float]] | None)

• alphas (float | Sequence[float] | None)

• colors (Sequence[int] | None)

• tag (str | None)

• name (str | None)

Return type:

None

molsysviewer.shapes.pocket_blobs module

class molsysviewer.shapes.pocket_blobs.PocketBlobs(view)

Bases: object

API for volumetric blobs (Gaussian fields) built from alpha-spheres.

add_pocket_blob(*, centers, radii, radius_scale=None, resolution=None, iso_level=None, smoothing=None, values=None, color_map=None, alpha=None, tag=None, name=None)

Create a volumetric blob (iso-surface) from alpha-spheres.

Parameters:

• centers (Iterable[Sequence[float]])

• radii (Iterable[float])

• radius_scale (float | None)

• resolution (float | None)

• iso_level (float | None)

• smoothing (float | None)

• values (Iterable[float] | None)

• color_map (Sequence[int] | str | None)

• alpha (float | None)

• tag (str | None)

• name (str | None)

molsysviewer.shapes.pocket_surfaces module

class molsysviewer.shapes.pocket_surfaces.PocketSurfaces(view)

Bases: object

Helpers for pocket/void surfaces based on selected atoms.

add_pocket_surface(*, atom_indices, scalars=None, grid=None, alpha=None, iso_levels=None, iso_colors=None, iso_alphas=None, color_map=None, mouth_atom_indices=None, clip_plane=None, tag=None)

Send a pocket/void surface request to the frontend.

Parameters:

• atom_indices (Sequence[int])

• scalars (Sequence[float] | None)

• grid (dict | None)

• alpha (float | None)

• iso_levels (Sequence[float] | None)

• iso_colors (Sequence[int] | None)

• iso_alphas (Sequence[float] | None)

• color_map (Sequence[int] | str | None)

• mouth_atom_indices (Sequence[int] | Sequence[Sequence[int]] | None)

• clip_plane (dict | None)

• tag (str | None)

molsysviewer.shapes.spheres module

class molsysviewer.shapes.spheres.SphereShapes(view)

Bases: object

Sphere helpers for the scene.

add_set_alpha_spheres(*, centers, radii, atom_centers=None, atom_radius=1.0, color_alpha_spheres=65280, color_atoms=255, alpha_alpha_spheres=0.3, alpha_atoms=0.5, tag=None)

Render a set of alpha-spheres (and optionally contact atoms) in a single message.

• centers, radii: alpha-sphere positions and radii.

• atom_centers: contact atom centers (optional).

• Separate colors and alpha for alpha-spheres and atoms.

• Uses a single message to minimize per-shape overhead.

Parameters:

• centers (Sequence[Sequence[float]])

• radii (Sequence[float])

• atom_centers (Sequence[Sequence[float]] | None)

• atom_radius (float)

• color_alpha_spheres (int)

• color_atoms (int)

• alpha_alpha_spheres (float)

• alpha_atoms (float)

• tag (str | None)

Return type:

Layer

add_sphere(center=(0.0, 0.0, 0.0), radius=10.0, color=65280, alpha=0.4, tag=None)

Add a (possibly transparent) sphere to the scene.

Parameters:

• radius (float)

• color (int)

• alpha (float)

• tag (str | None)

Return type:

Layer

add_spheres(centers, radii=1.0, colors=65280, alphas=0.4, tags=None)

Add multiple spheres to the scene.

Parameters:

• centers (Sequence[Sequence[float]]) – Sequence of centers, each (x, y, z).

• radii (float | Sequence[float]) – Radius (scalar for all) or a list of radii (one per sphere).

• colors (int | Sequence[int]) – Color in 0xRRGGBB (scalar or list).

• alphas (float | Sequence[float]) – Alpha (0.0-1.0), scalar or list.

• tags (str | Sequence[str] | None) – Optional tag (scalar or list, one per sphere).

clear(tag=None)

Delete shapes in the frontend (all or by tag).

Parameters:

tag (str | None)

molsysviewer.shapes.tetrahedra module

class molsysviewer.shapes.tetrahedra.Tetrahedra(view)

Bases: object

add_tetrahedra(*, tetra_coords=None, atom_quads=None, colors=16746496, alphas=0.6, labels=None, exterior_only=True, show_all_faces=None, draw_edges=None, edge_radius=None, edge_color=None, show_normals=None, normal_length=None, normal_color=None, tag=None, name=None)

Add tetrahedra as a triangle mesh, using coordinates or atom indices.

Optional flags: - draw_edges: draw edges as cylinders (edge_radius/edge_color). - show_normals: draw face normals as arrows (normal_length/normal_color).

Parameters:

• tetra_coords (Iterable[Sequence[Sequence[float]]] | None)

• atom_quads (Iterable[Sequence[int]] | None)

• colors (int | Sequence[int])

• alphas (float | Sequence[float])

• labels (Sequence[str] | str | None)

• exterior_only (bool)

• show_all_faces (bool | None)

• draw_edges (bool | None)

• edge_radius (float | None)

• edge_color (int | None)

• show_normals (bool | None)

• normal_length (float | None)

• normal_color (int | None)

• tag (str | None)

• name (str | None)

molsysviewer.shapes.triangle_faces module

class molsysviewer.shapes.triangle_faces.TriangleFaces(view)

Bases: object

add_triangle_faces(*, vertices=None, atom_triplets=None, colors=13421772, alpha=1.0, labels=None, draw_edges=None, edge_radius=None, edge_color=None, show_normals=None, normal_length=None, normal_color=None, tag=None)

Add custom triangle faces using coordinates or atom indices.

Extra parameters: - draw_edges: draw edges as thin cylinders (edge_radius/edge_color). - show_normals: draw normals as arrows (normal_length/normal_color).

Parameters:

• vertices (Iterable[Sequence[float]] | None)

• atom_triplets (Iterable[Sequence[int]] | None)

• colors (int | Sequence[int])

• alpha (float)

• labels (Sequence[str] | str | None)

• draw_edges (bool | None)

• edge_radius (float | None)

• edge_color (int | None)

• show_normals (bool | None)

• normal_length (float | None)

• normal_color (int | None)

• tag (str | None)

Module contents

class molsysviewer.shapes.AnisotropyEllipsoids(view)

Bases: object

Visualize oriented ellipsoids/disks from eigenvalues/eigenvectors or tensors.

add_anisotropy_ellipsoids(*, centers, eigenvalues=None, eigenvectors=None, tensors=None, principal_directions=None, scale=None, max_eccentricity=None, color_mode=None, colors=None, color_map=None, values=None, alpha=None, tag=None, name=None)

Send oriented ellipsoids or flat disks based on anisotropy inputs.

Parameters:

• centers (Iterable[Sequence[float]])

• eigenvalues (Iterable[Sequence[float]] | None)

• eigenvectors (Iterable[Sequence[Sequence[float]]] | None)

• tensors (Iterable[Sequence[Sequence[float]]] | None)

• principal_directions (Iterable[Sequence[float]] | None)

• scale (float | None)

• max_eccentricity (float | None)

• color_mode (str | None)

• colors (Sequence[int] | None)

• color_map (Sequence[int] | str | None)

• values (Sequence[float] | None)

• alpha (float | None)

• tag (str | None)

• name (str | None)

class molsysviewer.shapes.ChannelTubes(view)

Bases: object

API to build channel tubes along ordered centers/radii (e.g., TopoMT routes).

add_channel_tube(*, centers, radii, color_mode=None, solvent_distances=None, colors=None, color_map=None, radial_segments=None, smoothing_subdivisions=None, alpha=None, tag=None, name=None)

Generate a smoothed tube from ordered centers/radii (e.g., TopoMT routes).

Parameters:

• centers (Iterable[Sequence[float]])

• radii (Iterable[float])

• color_mode (str | None)

• solvent_distances (Iterable[float] | None)

• colors (Sequence[int] | None)

• color_map (Sequence[int] | str | None)

• radial_segments (int | None)

• smoothing_subdivisions (int | None)

• alpha (float | None)

• tag (str | None)

• name (str | None)

class molsysviewer.shapes.DisplacementVectors(view)

Bases: object

add_displacement_vectors(origins, vectors, *, atom_indices=None, length_scale=1.0, min_length=0.0, max_length=None, color_mode='norm', color_component=2, color_map=None, radius_scale=0.05, radial_segments=None, tag=None)

Add arrows (cylinder + cone) for displacement vectors.

Parameters:

• origins (Iterable[Sequence[float]] | ndarray | None) – Origin coordinates (n, 3). Optional if you use atom_indices.

• vectors (Iterable[Sequence[float]] | ndarray) – Displacement vectors (n, 3).

• atom_indices (Iterable[int] | None) – Atom indices to use the current structure coordinates as origins.

• length_scale (float) – Global scale factor for vector lengths.

• min_length (float) – Minimum length after scaling; shorter vectors are skipped.

• max_length (float | None) – Normalize the resulting maximum length to this value (if set).

• color_mode (str) – “norm” or “component” to map colors by norm or by component.

• color_component (int) – Component used for “component” coloring (0, 1, or 2).

• color_map (Sequence[int] | str | None) – Optional palette (color list or a Mol*-recognized name).

• radius_scale (float) – Relative radius factor (relative to final length).

• radial_segments (int | None) – Optional radial segments for cylinder/cone.

• tag (str | None) – Optional tag for the Mol* state node.

class molsysviewer.shapes.LinkShapes(view)

Bases: object

add_links(*, atom_pairs=None, coordinate_pairs=None, radii=0.2, colors=4495871, pocket_ids=None, chain_ids=None, color_mode='link', alpha=1.0, radial_segments=None, tag=None)

Add cylinders/bars connecting pairs of points or atoms.

Parameters:

• atom_pairs (Iterable[Sequence[int]] | None) – Pairs of atom indices (0-based) to connect. If provided, the current coordinates of the loaded structure are used.

• coordinate_pairs (Iterable[Sequence[Sequence[float]]] | None) – Lista de pares de coordenadas [[x1, y1, z1], [x2, y2, z2]].

• radii (float | Sequence[float]) – Scalars or lists (one per link) for radius and color.

• colors (int | Sequence[int]) – Scalars or lists (one per link) for radius and color.

• pocket_ids (Sequence[int | str] | None) – Optional identifiers to color by pocket or chain.

• chain_ids (Sequence[str] | None) – Optional identifiers to color by pocket or chain.

• color_mode (str) – “link” | “pocket” | “chain”.

• alpha (float) – Global alpha (0-1).

• radial_segments (int | None) – Cylinder radial segments (>=3). Default is 16.

• tag (str | None) – Optional tag for the Mol* state node.

class molsysviewer.shapes.PharmacophoreShapes(view)

Bases: object

API for pharmacophore glyphs (spheres/disks/arrows).

add_pharmacophore_features(*, centers, kinds, radii=None, directions=None, alphas=None, colors=None, tag=None, name=None)

Render standard pharmacophore glyphs (sphere/disk/arrow).

Parameters:

• centers (Iterable[Sequence[float]])

• kinds (Sequence[str])

• radii (float | Sequence[float] | None)

• directions (Iterable[Sequence[float]] | None)

• alphas (float | Sequence[float] | None)

• colors (Sequence[int] | None)

• tag (str | None)

• name (str | None)

Return type:

None

class molsysviewer.shapes.PocketBlobs(view)

Bases: object

API for volumetric blobs (Gaussian fields) built from alpha-spheres.

add_pocket_blob(*, centers, radii, radius_scale=None, resolution=None, iso_level=None, smoothing=None, values=None, color_map=None, alpha=None, tag=None, name=None)

Create a volumetric blob (iso-surface) from alpha-spheres.

Parameters:

• centers (Iterable[Sequence[float]])

• radii (Iterable[float])

• radius_scale (float | None)

• resolution (float | None)

• iso_level (float | None)

• smoothing (float | None)

• values (Iterable[float] | None)

• color_map (Sequence[int] | str | None)

• alpha (float | None)

• tag (str | None)

• name (str | None)

class molsysviewer.shapes.PocketSurfaces(view)

Bases: object

Helpers for pocket/void surfaces based on selected atoms.

add_pocket_surface(*, atom_indices, scalars=None, grid=None, alpha=None, iso_levels=None, iso_colors=None, iso_alphas=None, color_map=None, mouth_atom_indices=None, clip_plane=None, tag=None)

Send a pocket/void surface request to the frontend.

Parameters:

• atom_indices (Sequence[int])

• scalars (Sequence[float] | None)

• grid (dict | None)

• alpha (float | None)

• iso_levels (Sequence[float] | None)

• iso_colors (Sequence[int] | None)

• iso_alphas (Sequence[float] | None)

• color_map (Sequence[int] | str | None)

• mouth_atom_indices (Sequence[int] | Sequence[Sequence[int]] | None)

• clip_plane (dict | None)

• tag (str | None)

class molsysviewer.shapes.ShapesManager(view)

Bases: object

Shape manager bound to a MolSysView.

Provides high-level shortcuts (add_sphere, add_pocket_surface, etc.) and exposes specialized submodules (spheres, pockets, tubes, ellipsoids, pharmacophore, etc.).

add_anisotropy_ellipsoids(*args, **kwargs)

add_channel_tube(*args, **kwargs)

add_displacement_vectors(*args, **kwargs)

add_links(*args, **kwargs)

add_pharmacophore_features(*args, **kwargs)

add_pocket_blob(*args, **kwargs)

add_pocket_surface(*args, **kwargs)

add_set_alpha_spheres(*args, **kwargs)

add_sphere(*args, **kwargs)

add_spheres(*args, **kwargs)

add_tetrahedra(*args, **kwargs)

add_triangle_faces(*args, **kwargs)

clear(tag=None)

Delete shapes (all if tag is None, or by tag).

Parameters:

tag (str | None)

class molsysviewer.shapes.SphereShapes(view)

Bases: object

Sphere helpers for the scene.

add_set_alpha_spheres(*, centers, radii, atom_centers=None, atom_radius=1.0, color_alpha_spheres=65280, color_atoms=255, alpha_alpha_spheres=0.3, alpha_atoms=0.5, tag=None)

Render a set of alpha-spheres (and optionally contact atoms) in a single message.

• centers, radii: alpha-sphere positions and radii.

• atom_centers: contact atom centers (optional).

• Separate colors and alpha for alpha-spheres and atoms.

• Uses a single message to minimize per-shape overhead.

Parameters:

• centers (Sequence[Sequence[float]])

• radii (Sequence[float])

• atom_centers (Sequence[Sequence[float]] | None)

• atom_radius (float)

• color_alpha_spheres (int)

• color_atoms (int)

• alpha_alpha_spheres (float)

• alpha_atoms (float)

• tag (str | None)

Return type:

Layer

add_sphere(center=(0.0, 0.0, 0.0), radius=10.0, color=65280, alpha=0.4, tag=None)

Add a (possibly transparent) sphere to the scene.

Parameters:

• radius (float)

• color (int)

• alpha (float)

• tag (str | None)

Return type:

Layer

add_spheres(centers, radii=1.0, colors=65280, alphas=0.4, tags=None)

Add multiple spheres to the scene.

Parameters:

• centers (Sequence[Sequence[float]]) – Sequence of centers, each (x, y, z).

• radii (float | Sequence[float]) – Radius (scalar for all) or a list of radii (one per sphere).

• colors (int | Sequence[int]) – Color in 0xRRGGBB (scalar or list).

• alphas (float | Sequence[float]) – Alpha (0.0-1.0), scalar or list.

• tags (str | Sequence[str] | None) – Optional tag (scalar or list, one per sphere).

clear(tag=None)

Delete shapes in the frontend (all or by tag).

Parameters:

tag (str | None)

class molsysviewer.shapes.Tetrahedra(view)

Bases: object

add_tetrahedra(*, tetra_coords=None, atom_quads=None, colors=16746496, alphas=0.6, labels=None, exterior_only=True, show_all_faces=None, draw_edges=None, edge_radius=None, edge_color=None, show_normals=None, normal_length=None, normal_color=None, tag=None, name=None)

Add tetrahedra as a triangle mesh, using coordinates or atom indices.

Optional flags: - draw_edges: draw edges as cylinders (edge_radius/edge_color). - show_normals: draw face normals as arrows (normal_length/normal_color).

Parameters:

• tetra_coords (Iterable[Sequence[Sequence[float]]] | None)

• atom_quads (Iterable[Sequence[int]] | None)

• colors (int | Sequence[int])

• alphas (float | Sequence[float])

• labels (Sequence[str] | str | None)

• exterior_only (bool)

• show_all_faces (bool | None)

• draw_edges (bool | None)

• edge_radius (float | None)

• edge_color (int | None)

• show_normals (bool | None)

• normal_length (float | None)

• normal_color (int | None)

• tag (str | None)

• name (str | None)

class molsysviewer.shapes.TriangleFaces(view)

Bases: object

add_triangle_faces(*, vertices=None, atom_triplets=None, colors=13421772, alpha=1.0, labels=None, draw_edges=None, edge_radius=None, edge_color=None, show_normals=None, normal_length=None, normal_color=None, tag=None)

Add custom triangle faces using coordinates or atom indices.

Extra parameters: - draw_edges: draw edges as thin cylinders (edge_radius/edge_color). - show_normals: draw normals as arrows (normal_length/normal_color).

Parameters:

• vertices (Iterable[Sequence[float]] | None)

• atom_triplets (Iterable[Sequence[int]] | None)

• colors (int | Sequence[int])

• alpha (float)

• labels (Sequence[str] | str | None)

• draw_edges (bool | None)

• edge_radius (float | None)

• edge_color (int | None)

• show_normals (bool | None)

• normal_length (float | None)

• normal_color (int | None)

• tag (str | None)