cosmol_viewer 

1from .cosmol_viewer import *
2
3__doc__ = cosmol_viewer.__doc__
4if hasattr(cosmol_viewer, "__all__"):
5    __all__ = cosmol_viewer.__all__
class Scene:

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

This class allows adding, updating, and removing shapes in a 3D scene, as well as modifying scene-level properties like scale and background color.

Supported shape types:

  • Sphere
  • Stick
  • Molecule
  • Protein

Shapes can be optionally identified with a string id, which allows updates and deletion.

Scene()

Creates a new empty scene.

Example

scene = Scene()
def add_shape(self, shape: Any) -> None:

Add a shape to the scene without an explicit ID.

Args

  • shape: A shape instance (Sphere, Stick, Molecule, or Protein).

Example

scene.add_shape(sphere)
def add_shape_with_id(self, id: str, shape: Any) -> None:

Add a shape to the scene with a specific ID which can be used to update or remove the shape later. If a shape with the same ID exists, this method may fail or behave strictly;

Args

  • id: Unique string ID for the shape.
  • shape: A shape instance.

Example

scene.add_shape_with_id("bond1", stick)
def replace_shape(self, id: str, shape: Any) -> None:

Replace an existing shape in the scene by its ID.

Args

  • id: ID of the shape to update.
  • shape: New shape object to replace the existing one.

Example

scene.replace_shape("mol", updated_molecule)
def remove_shape(self, id: str) -> None:

Remove a shape from the scene by its ID.

Args

  • id: ID of the shape to remove.

Example

scene.remove_shape("bond1")
def recenter(self, center: Sequence[float]) -> None:

Recenter the scene at a given point.

Args

  • center: An XYZ array of 3 float values representing the new center.

Example

scene.recenter([0.0, 0.0, 0.0])
def set_scale(self, scale: float) -> None:

Set the global scale factor of the scene. This affects the visual size of all shapes uniformly.

Args

  • scale: A positive float scaling factor.

Example

scene.set_scale(1.5)
def set_background_color(self, background_color: Any) -> None:

Set the background color of the scene.

Args

  • background_color: An RGB array of 3 float values between 0.0 and 1.0.

Example

scene.set_background_color("\#FFFFFF") # white background
def use_black_background(self) -> None:

Set the background color of the scene to black.

class Animation:

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

Animation(interval: float, loops: int, interpolate: bool)

Create a new Animation container.

Args

  • interval: Time in seconds between frames.
  • loops: Number of times to loop the animation (-1 for infinite).
  • smooth: Whether to interpolate between frames for smoother visualization.

Example

anim = Animation(interval=0.1, loops=-1, smooth=True)
def add_frame(self, scene: Scene) -> None:

Add a frame (Scene) to the animation.

Args

  • frame: A Scene object representing a single frame of the animation.
def set_static_scene(self, scene: Scene) -> None:

Set a static scene that remains constant throughout the animation. Useful for background elements or reference structures.

Args

  • scene: A Scene object to be rendered statically.
class Viewer:

A viewer that renders 3D scenes in different runtime environments (e.g., Jupyter, Colab, or native GUI).

The Viewer automatically selects a backend:

  • Jupyter/Colab → WebAssembly canvas (inline display)
  • Python script/terminal → native GUI window (if supported)

Use Viewer.render(scene) to create and display a viewer instance.

def get_environment() -> str:

Get the current runtime environment.

Returns

  • str: One of "Jupyter", "Colab", "PlainScript", or "IPythonTerminal".

Example

env = Viewer.get_environment()
print(env) # e.g., "Jupyter"
def render( scene: Scene, width: float, height: float) -> Viewer:

Render a 3D scene.

Args

  • scene: The scene to render.
  • width: The viewport width in pixels (default: 800).
  • height: The viewport height in pixels (default: 600).

Returns

  • Viewer: The created viewer instance.

Example

from cosmol_viewer import Viewer, Scene, Sphere
scene = Scene()
scene.add_shape(Sphere([0, 0, 0], 1.0))
viewer = Viewer.render(scene)
def play( animation: Animation, width: float, height: float) -> Viewer:

Play an animation.

Args

  • animation: An Animation object containing frames and settings.
  • width: The viewport width in pixels.
  • height: The viewport height in pixels.

Returns

  • Viewer: The created viewer instance playing the animation.

Example

from cosmol_viewer import Viewer, Animation
anim = Animation(0.1, 10, True)
# ... add frames to anim ...
viewer = Viewer.play(anim, 800.0, 600.0)
def update(self, scene: Scene) -> None:

Update the viewer with a new scene. Works for both Web-based rendering (Jupyter/Colab) and native GUI windows.

⚠️ Note (Jupyter/Colab): Animation updates may be limited by notebook rendering capacity.

Args

  • scene: The updated scene.

Example

scene.add_shape(Sphere([1, 1, 1], 0.5))
viewer.update(scene)
def save_image(self, path: str) -> None:

Save the current image to a file.

Args

  • path: File path for the saved image.

Example

viewer.save_image("output.png")
class Sphere:

A sphere shape in the scene.

Args

  • center: [x, y, z] coordinates of the sphere center.
  • radius: Radius of the sphere.

Example

sphere = Sphere([0, 0, 0], 1.0).color([1.0, 0.0, 0.0])
def set_radius(self, radius: float) -> Sphere:

The type of the None singleton.

def set_center(self, center: Sequence[float]) -> Sphere:

The type of the None singleton.

def color(*args, **kwds):

color(self, c: tuple[int, int, int]) -> Sphere color(self, c: str) -> Sphere

Set the shape color.

def opacity(self, opacity: float) -> Sphere:

opacity(self, opacity: float) -> Sphere

Set the surface opacity.

def roughness(self, roughness: float) -> Sphere:

roughness(self, roughness: float) -> Sphere

Set the surface roughness.

def metallic(self, metallic: float) -> Sphere:

metallic(self, metallic: float) -> Sphere

Set the surface metallic factor.

class Stick:

A cylindrical stick (or capsule) connecting two points.

Args

  • start: Starting point [x, y, z].
  • end: Ending point [x, y, z].
  • thickness: Stick radius.

Example

stick = Stick([0,0,0], [1,1,1], 0.1).opacity(0.5)
def color(*args, **kwds):

color(self, c: tuple[int, int, int]) -> Stick color(self, c: str) -> Stick

Set the shape color.

def opacity(self, opacity: float) -> Stick:

opacity(self, opacity: float) -> Stick

Set the surface opacity.

def roughness(self, roughness: float) -> Stick:

roughness(self, roughness: float) -> Stick

Set the surface roughness.

def metallic(self, metallic: float) -> Stick:

metallic(self, metallic: float) -> Stick

Set the surface metallic factor.

def set_thickness(self, thickness: float) -> Stick:

The type of the None singleton.

def set_start(self, start: Sequence[float]) -> Stick:

The type of the None singleton.

def set_end(self, end: Sequence[float]) -> Stick:

The type of the None singleton.

class Molecule:

A molecular shape object. Typically created by parsing an SDF format string.

Example

# Load from file content
content = open("structure.sdf", "r").read()
mol = Molecule.from_sdf(content).centered()
def color(*args, **kwds):

color(self, c: tuple[int, int, int]) -> Molecule color(self, c: str) -> Molecule

Set the shape color.

def opacity(self, opacity: float) -> Molecule:

opacity(self, opacity: float) -> Molecule

Set the surface opacity.

def roughness(self, roughness: float) -> Molecule:

roughness(self, roughness: float) -> Molecule

Set the surface roughness.

def metallic(self, metallic: float) -> Molecule:

metallic(self, metallic: float) -> Molecule

Set the surface metallic factor.

def from_sdf(sdf: str) -> Molecule:

Create a Molecule from an SDF format string.

Args

  • sdf: The SDF file content as a string.

Returns

  • Molecule: The parsed molecule object.
def get_center(self) -> list[float]:

The type of the None singleton.

def centered(self) -> Molecule:

The type of the None singleton.

class Protein:

A protein shape object. Typically created by parsing an mmCIF format string.

Example

# Load from file content
content = open("2AMD.cif", "r").read()
prot = Protein.from_mmcif(content).centered().color("\#F9FAFB")
def color(*args, **kwds):

color(self, c: tuple[int, int, int]) -> Protein color(self, c: str) -> Protein

Set the shape color.

def opacity(self, opacity: float) -> Protein:

opacity(self, opacity: float) -> Protein

Set the surface opacity.

def roughness(self, roughness: float) -> Protein:

roughness(self, roughness: float) -> Protein

Set the surface roughness.

def metallic(self, metallic: float) -> Protein:

metallic(self, metallic: float) -> Protein

Set the surface metallic factor.

def from_mmcif(mmcif: str) -> Protein:

Create a Protein from an mmCIF format string.

Args

  • mmcif: The mmCIF file content as a string.

Returns

  • Protein: The parsed protein object.
def get_center(self) -> list[float]:

The type of the None singleton.

def centered(self) -> Protein:

The type of the None singleton.