API¶

class cosmol_viewer.Animation(interval, loops, interpolate)¶

A container for handling frame-based animations in the viewer.

Parameters:

interval (float) – Time in seconds between frames.
loops (int) – Number of times to loop the animation. Use -1 for infinite looping.
interpolate (bool) – Whether to interpolate between frames for smoother visualization.

Examples

animation = Animation(interval=0.1, loops=-1, interpolate=True)
for _ in range(100):
    scene = Scene()
    scene.add_shape(..)
    animation.add_frame(scene)

Viewer.play(animation, width=800.0, height=500.0)

add_frame(scene)¶

Add a frame to the animation.

Parameters:: scene (Scene) – A scene object representing a single frame of the animation.

set_static_scene(scene)¶

Set a static scene that remains constant throughout the animation.

Parameters:: scene (Scene) – A scene object to be rendered statically. This is useful for background elements or reference structures.

class cosmol_viewer.Molecule¶

A molecular shape object.

This class is typically created from an SDF-format string parsed by COSMolKit.

Examples

content = open("structure.sdf", "r").read()
mol = Molecule.from_sdf(content).centered()

ball_and_stick()¶

Use the default ball-and-stick molecule style.

Atoms are rendered as spheres and bonds are rendered as sticks.

Returns:: The updated molecule object.
Return type:: Molecule

centered()¶

Center the molecule around the origin.

Returns:: The centered molecule object.
Return type:: Molecule

color(self, c: tuple[int, int, int]) → Molecule¶
color(self, c: str) → Molecule: Set the shape color.

disable_outline()¶

Disable the outline around this molecule.

Returns:: The updated molecule object.
Return type:: Molecule

enable_outline(color=None, width=None)¶

Enable an outline around this molecule.

Parameters:

color (tuple[int, int, int] or str, optional) – The outline color as an RGB tuple or a hex string. If omitted, the current outline color is kept.
width (float, optional) – The outline width in scene units. If omitted, the current outline width is kept.

Returns:

The updated molecule object.

Return type:

Molecule

static from_cosmolkit(molecule)¶

Create a viewer molecule from a Python cosmolkit.Molecule object.

The conversion is performed on the Rust side by exporting the COSMolKit molecule atoms, bonds, and coordinates into the viewer molecule format. 3D conformer coordinates are preferred over 2D coordinates. If the COSMolKit molecule has no stored coordinates, 2D coordinates are computed first.

Parameters:: molecule (cosmolkit.Molecule) – A molecule object from the Python cosmolkit package built against a compatible COSMolKit version.
Returns:: The converted viewer molecule object.
Return type:: Molecule

static from_sdf(sdf)¶

Create a molecule from an SDF-format string.

SDF parsing is delegated to COSMolKit; the viewer receives atoms, bonds, and coordinates from the parsed molecule.

Parameters:: sdf (str) – The SDF file content as a string.
Returns:: The parsed molecule object.
Return type:: Molecule

get_center()¶

Get the geometric center of the molecule.

Returns:: The center coordinates of the molecule.
Return type:: [float, float, float]

metallic(self, metallic: float) → Molecule¶: Set the surface metallic factor.

opacity(self, opacity: float) → Molecule¶: Set the surface opacity.

roughness(self, roughness: float) → Molecule¶: Set the surface roughness.

set_outline(enabled, color=None, width=None)¶

Configure the molecule outline.

Parameters:

enabled (bool) – Whether to render an outline around this molecule.
color (tuple[int, int, int] or str, optional) – The outline color as an RGB tuple or a hex string. If omitted, the current outline color is kept.
width (float, optional) – The outline width in scene units. If omitted, the current outline width is kept.

Returns:

The updated molecule object.

Return type:

Molecule

sphere()¶

Use a sphere-only molecule style.

Atoms are rendered as spheres and bonds are not rendered.

Returns:: The updated molecule object.
Return type:: Molecule

stick()¶

Use a stick-only molecule style.

Bonds are rendered as sticks with same-radius endpoint spheres for smooth joins, following the ChimeraX stick-style model. Double and triple bonds remain visible as thinner parallel sticks, with spacing derived from the ChimeraX stick radius. Aromatic ring bonds render as a single stick plus an inner aromatic line. Van der Waals atom spheres are not rendered, so the result remains a compact stick depiction where atom colors are carried by the bond segments and junction caps.

Returns:: The updated molecule object.
Return type:: Molecule

class cosmol_viewer.Protein¶

A protein shape object.

This class is typically created from an mmCIF- or PDB-format string parsed by COSMolKit’s protein reader. The viewer core assigns secondary structure from backbone geometry and generates the displayed ChimeraX-style cartoon ribbon.

Examples

content = open("2AMD.cif", "r", encoding="utf-8").read()
prot = Protein.from_mmcif(content).centered().rainbow_residues()

Use .color("\#F9FAFB") for a uniform cartoon color.

centered()¶

Center the protein around the origin.

Returns:: The centered protein object.
Return type:: Protein

color(self, c: tuple[int, int, int]) → Protein¶
color(self, c: str) → Protein: Set the shape color.

static from_mmcif(mmcif)¶

Create a protein from an mmCIF-format string.

Parsing is delegated to COSMolKit’s protein reader. The viewer core assigns secondary structure from the resulting backbone geometry before mesh generation.

Parameters:: mmcif (str) – The mmCIF file content as a string.
Returns:: The parsed protein object.
Return type:: Protein

static from_pdb(pdb)¶

Create a protein from a PDB-format string.

Parsing is delegated to COSMolKit’s protein reader. The viewer core assigns secondary structure from the resulting backbone geometry before mesh generation.

Parameters:: pdb (str) – The PDB file content as a string.
Returns:: The parsed protein object.
Return type:: Protein

get_center()¶

Get the geometric center of the protein.

Returns:: The center coordinates of the protein.
Return type:: [float, float, float]

metallic(self, metallic: float) → Protein¶: Set the surface metallic factor.

opacity(self, opacity: float) → Protein¶: Set the surface opacity.

rainbow_residues()¶

Color the protein cartoon with ChimeraX-style rainbow coloring by residue.

Each biopolymer chain is colored independently from blue at the first rendered residue to red at the last rendered residue, matching ChimeraX rainbow / color sequential residues default behavior for cartoon ribbons.

Returns:: The updated protein object.
Return type:: Protein

ribbon()¶

Display the protein as a cartoon ribbon.

Returns:: The updated protein object.
Return type:: Protein

roughness(self, roughness: float) → Protein¶: Set the surface roughness.

solvent_accessible_surface()¶

Display the protein as a solvent-accessible surface.

Returns:: The updated protein object.
Return type:: Protein

surface()¶

Display the protein as a ChimeraX-compatible solvent-excluded surface.

The default probe radius is 1.4 angstrom and the grid spacing is 0.5 angstrom. The generated surface participates in scene opacity and depth cueing.

Returns:: The updated protein object.
Return type:: Protein

surface_with_options(probe_radius=1.4, grid_spacing=0.5, solvent_accessible=False, sharp_boundaries=True)¶

Display the protein as a molecular surface with explicit parameters.

Parameters:

probe_radius (float) – Solvent probe radius in angstrom.
grid_spacing (float) – Distance-grid spacing in angstrom.
solvent_accessible (bool) – Return the solvent-accessible surface instead of the solvent-excluded surface.
sharp_boundaries (bool) – Subdivide atom patches so their shared edges are exact.

Returns:

The updated protein object.

Return type:

Protein

class cosmol_viewer.Scene¶

A 3D scene container for visualizing molecular or geometric shapes.

This class allows adding, updating, and removing shapes in a scene, as well as modifying scene-level properties such as scale, camera, and background color. Static image export is also a scene-level operation via scene.save_image(...) and scene.to_png(...); it does not depend on a Viewer instance or the current notebook/browser/window size.

Supported shape types include Sphere, Stick, Molecule, and Protein. Shapes can optionally be assigned a string id so they can be updated or removed later.

Examples

scene = Scene()

add_shape(shape)¶

Add a shape to the scene without assigning an explicit ID.

Parameters:: shape (Sphere or Stick or Molecule or Protein) – A shape instance to add to the scene.

add_shape_with_id(id, shape)¶

Add a shape to the scene with a specific ID.

Parameters:

id (str) – A unique string identifier for the shape.
shape (Sphere or Stick or Molecule or Protein) – A shape instance to add to the scene.

Notes

If a shape with the same ID already exists, it is replaced.

display(width=1200, height=900, background=None)¶

Display this scene as a static PNG in a notebook.

This method does not create an interactive viewer. It renders through the same offscreen path as scene.to_png(...) and displays the resulting PNG with IPython.display. The optional background argument follows scene.to_png(...).

recenter(center)¶

Recenter the scene at a given point.

Parameters:: center ([float, float, float]) – The new scene center as XYZ coordinates.

remove_shape(id)¶

Remove a shape from the scene by its ID.

Parameters:: id (str) – The ID of the shape to remove.

replace_shape(id, shape)¶

Replace an existing shape in the scene by its ID.

Parameters:

id (str) – The ID of the shape to replace.
shape (Sphere or Stick or Molecule or Protein) – The new shape object.

rotate_camera(azimuth_delta, elevation_delta, roll_delta=0.0)¶

Rotate the current camera by orbit-style angle deltas.

Parameters:

azimuth_delta (float) – Horizontal angle delta in degrees.
elevation_delta (float) – Vertical angle delta in degrees.
roll_delta (float, optional) – Roll angle delta in degrees.

save_image(path, width=800, height=600, background=None)¶

Render this scene directly to a PNG file.

This path uses the native offscreen renderer and does not depend on a Viewer, notebook JavaScript, or the current display size. On platforms with a headless GL path, the in-process renderer avoids creating a GUI event loop. If the in-process renderer cannot be created after a native viewer has already run, save_image automatically retries in an isolated Python subprocess. Set COSMOL_VIEWER_RENDER_ISOLATED=1 to force the isolated path.

Parameters:

path (str) – Output PNG path.
width (int, optional) – Output image width in pixels.
height (int, optional) – Output image height in pixels.
background (str or [int, int, int] or [int, int, int, int], optional) – Export background. If omitted, use the scene background. Use "transparent" for a transparent PNG, a hex color such as #ffffff, #ffffffff, or an RGB/RGBA sequence.

set_ambient_light(intensity)¶

Set the global ambient light strength.

Defaults to 0.55, matching the renderer’s previous hard-coded ambient term.

set_auto_rotate(enabled=True, speed=20.0)¶

Enable or disable automatic camera rotation for the scene.

Parameters:

enabled (bool, optional) – If True, the camera keeps orbiting around the current target while normal drag rotation remains enabled. Defaults to True.
speed (float, optional) – Horizontal orbit speed in degrees per second. Defaults to 20.0.

set_background_color(background_color)¶

Set the background color of the scene.

Parameters:: background_color (tuple[int, int, int] or str) – The background color as an RGB tuple or a hex string such as “#FFFFFF”.

set_camera_distance(distance)¶: Set the camera distance while keeping the current target and rotation.

set_camera_fov(fov)¶: Set the camera field of view in degrees.

set_camera_target(target)¶: Set the camera target while keeping the current distance and rotation.

set_camera_view(azimuth=0.0, elevation=0.0, roll=0.0, distance=35.0, target=Ellipsis, fov=15.0)¶

Set the camera with orbit-style angles.

Parameters:

azimuth (float, optional) – Horizontal camera angle in degrees around the target.
elevation (float, optional) – Vertical camera angle in degrees around the target.
roll (float, optional) – Camera roll in degrees.
distance (float, optional) – Distance from the camera to the target.
target ([float, float, float], optional) – XYZ point the camera looks at.
fov (float, optional) – Vertical field of view in degrees.

set_depth_cue(enabled=True)¶

Enable or disable depth cueing for the scene.

Depth cueing uses the ChimeraX model: fragments are linearly mixed toward the depth cue color according to camera-space depth. Depth cueing is disabled by default. When enabled, the default cue color follows the scene background color, so distant fragments fade out. It applies to molecules, ribbons, and protein surfaces.

set_depth_cue_color(color)¶

Set the depth cue color.

Parameters:: color (tuple[int, int, int] or str) – RGB color tuple or hex string such as "#FFFFFF". If unset, the scene background color is used.

set_depth_cue_range(start, end)¶

Set the fractional depth cue range.

Parameters:

start (float) – Fraction of the current scene depth range where dimming starts. Defaults to 0.5.
end (float) – Fraction of the current scene depth range where dimming reaches the depth cue color. Defaults to 1.0.

set_light_color(color)¶

Set the scene light color.

The color affects both ambient and directional light. The default light color is [255, 247, 247], matching the renderer’s previous hard-coded color.

Parameters:: color (tuple[int, int, int] or str) – RGB light color tuple or hex string such as "#fff7f7".

set_light_intensity(intensity)¶

Set the final directional light intensity multiplier.

Defaults to 1.0. Increasing this brightens the whole lit scene while keeping the current ambient, diffuse, specular, and light color settings.

set_lighting(ambient=0.55, diffuse=0.65, specular=1.0, intensity=1.0, color=None)¶

Set scene lighting parameters.

The defaults match the renderer’s historical hard-coded lighting, so calling this method with no arguments preserves the old appearance.

Parameters:

ambient (float, optional) – Global ambient light strength. Defaults to 0.55.
diffuse (float, optional) – Directional diffuse light strength. Defaults to 0.65.
specular (float, optional) – Multiplier for the existing material-dependent specular highlight curve. Defaults to 1.0.
intensity (float, optional) – Final directional light multiplier. Defaults to 1.0.
color (tuple[int, int, int] or str, optional) – RGB light color as a tuple or hex string such as "#fff7f7". Defaults to the previous light color [255, 247, 247].

set_scale(scale)¶

Set the global scale factor of the scene.

Parameters:: scale (float) – A positive scaling factor applied uniformly to all shapes.

set_transparent_background(enabled=True)¶

Enable or disable transparent scene background rendering.

Parameters:: enabled (bool, optional) – If True, render the scene background with alpha 0 so browser canvas content behind the viewer can show through. Defaults to True.

set_zoom_disabled(disabled=True)¶

Enable or disable interactive zooming for the scene.

Parameters:: disabled (bool, optional) – If True, mouse wheel and trackpad scroll zooming are ignored while drag rotation remains enabled. Defaults to True.

to_png(width=800, height=600, background=None)¶

Render this scene directly to PNG bytes.

This is useful in notebooks when you want to display or store an image without round-tripping through the browser canvas. On platforms with a headless GL path, the in-process renderer avoids creating a GUI event loop. If the in-process renderer cannot be created after a native viewer has already run, to_png automatically retries in an isolated Python subprocess. Set COSMOL_VIEWER_RENDER_ISOLATED=1 to force the isolated path.

Parameters:: background (str or sequence, optional) – If omitted, use the scene background. Use "transparent" for transparent PNG output or pass a color such as #ffffff or [255, 255, 255, 255].

use_black_background()¶: Set the background color of the scene to black.

class cosmol_viewer.Sphere(center, radius)¶

A sphere shape in the scene.

Parameters:

center ([float, float, float]) – The [x, y, z] coordinates of the sphere center.
radius (float) – The radius of the sphere.

Examples

sphere = Sphere([0, 0, 0], 1.0).color("\#FF0000")
sphere = Sphere([0, 0, 0], 1.0).color((255, 0, 0))

color(self, c: tuple[int, int, int]) → Sphere¶
color(self, c: str) → Sphere: Set the shape color.

metallic(self, metallic: float) → Sphere¶: Set the surface metallic factor.

opacity(self, opacity: float) → Sphere¶: Set the surface opacity.

roughness(self, roughness: float) → Sphere¶: Set the surface roughness.

set_center(center)¶

Set the center of the sphere.

Parameters:: center ([float, float, float]) – The new center coordinates of the sphere.
Returns:: The updated sphere object.
Return type:: Sphere

set_radius(radius)¶

Set the radius of the sphere.

Parameters:: radius (float) – The new radius of the sphere.
Returns:: The updated sphere object.
Return type:: Sphere

class cosmol_viewer.Stick(start, end, thickness)¶

A cylindrical stick shape connecting two points.

Parameters:

start ([float, float, float]) – The starting point of the stick.
end ([float, float, float]) – The ending point of the stick.
thickness (float) – The radius or thickness of the stick.

Examples

stick = Stick([0, 0, 0], [1, 1, 1], 0.1).opacity(0.5)

color(self, c: tuple[int, int, int]) → Stick¶
color(self, c: str) → Stick: Set the shape color.

metallic(self, metallic: float) → Stick¶: Set the surface metallic factor.

opacity(self, opacity: float) → Stick¶: Set the surface opacity.

roughness(self, roughness: float) → Stick¶: Set the surface roughness.

set_end(end)¶

Set the ending point of the stick.

Parameters:: end ([float, float, float]) – The new ending point.
Returns:: The updated stick object.
Return type:: Stick

set_start(start)¶

Set the starting point of the stick.

Parameters:: start ([float, float, float]) – The new starting point.
Returns:: The updated stick object.
Return type:: Stick

set_thickness(thickness)¶

Set the thickness of the stick.

Parameters:: thickness (float) – The new thickness of the stick.
Returns:: The updated stick object.
Return type:: Stick

class cosmol_viewer.Viewer¶

A viewer for interactively displaying 3D scenes in different runtime environments.

Depending on the runtime environment, the viewer automatically selects an appropriate backend:

Jupyter or Colab uses an inline WebAssembly canvas.
A Python script or terminal uses a native GUI window when supported.

Use Viewer.render(scene, width, height) to display a scene interactively, or Viewer.play(animation, width, height) to play an animation. Use scene.save_image(path, width, height) or scene.to_png(width, height) for static image output.

static get_environment()¶

Get the current runtime environment.

Returns:: One of "Jupyter", "Colab", "Plain Script", "IPython-Terminal", "Other IPython", or "Unknown".
Return type:: str

static play(animation, width, height)¶

Play an animation.

Parameters:

animation (Animation) – An animation object containing frames and playback settings.
width (float) – The viewport width in pixels.
height (float) – The viewport height in pixels.

Returns:

The created viewer instance playing the animation.

Return type:

Viewer

static render(scene, width, height)¶

Render a 3D scene.

Parameters:

scene (Scene) – The scene to render.
width (float) – The viewport width in pixels.
height (float) – The viewport height in pixels.

Returns:

The created viewer instance.

Return type:

Viewer

set_camera_parameter_logging(enabled=True)¶

Enable or disable logging camera parameters whenever the native viewer camera moves.

When enabled, native viewer interaction logs one line of orbit-style camera parameters after drag, zoom, or auto-rotation changes the camera. The printed values can be passed back to scene.set_camera_view(...) to reproduce the view. Logging is disabled by default, and the angle conversion is only computed while this option is enabled.

Parameters:: enabled (bool, optional) – Whether to print camera parameters on camera movement. Defaults to True.

update(scene)¶

Update the viewer with a new scene.

Parameters:: scene (Scene) – The updated scene.

Notes

In Jupyter or Colab, frequent animation updates may be limited by notebook rendering capacity, which can lead to delayed or incomplete rendering.