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, smooth=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 by parsing an SDF-format string.

Examples

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

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.

static from_sdf(sdf)¶

Create a molecule from an SDF-format string.

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.

class cosmol_viewer.Protein¶

A protein shape object.

This class is typically created by parsing an mmCIF-format string.

Examples

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

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.

Parameters:: mmcif (str) – The mmCIF 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.

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

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 and background color.

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, this method may fail or behave strictly.

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.

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_scale(scale)¶

Set the global scale factor of the scene.

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

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 rendering 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, or Viewer.play(animation, width, height) to play an animation.

static get_environment()¶

Get the current runtime environment.

Returns:: One of "Jupyter", "Colab", "PlainScript", or "IPython-Terminal".
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

save_image(path)¶

Save the current image to a file.

Parameters:: path (str) – The file path where the image will be saved.

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.