cosmol-viewer 0.2.0.dev1

Molecular visualization tools

COSMol-viewer

A high-performance molecular viewer for Python and Rust, powered by a unified Rust core. It supports both in-notebook visualization and native desktop rendering, with smooth playback for scientific animations.

COSMol-viewer is a compact, cross-platform renderer for molecular and geometric scenes. Unlike purely notebook-bound solutions such as py3Dmol, COSMol-viewer runs everywhere:

• Native desktop window (Python or Rust) via egui
• Jupyter / IPython notebook via WASM backend
• Rust applications

All implementations share the same Rust rendering engine, ensuring consistent performance and visual output.

---

Quick concepts

• Scene: container for shapes (molecules, proteins, spheres, etc.).
• Viewer.render(scene, ...): create a static viewer bound to a canvas (native or notebook). Good for static visualization.
• viewer.update(scene): push incremental changes after Viewer.render() (real-time / streaming use-cases).
• Viewer.play(frames, interval, loops, width, height, smooth): recommended for precomputed animations and demonstrations. The viewer takes care of playback timing and looping.

Why prefer play for demos?

• Single call API (hand off responsibility to the viewer).
• Built-in timing & loop control.
• Optional smooth interpolation between frames for visually pleasing playback even when input frame rate is low.

Why keep update?

• update is ideal for real-time simulations, MD runs, or streaming data where frames are not precomputed. It provides strict fidelity (no interpolation) and minimal latency.

---

Usage

python

See examples in Google Colab.

Install with pip install cosmol-viewer

1. Static molecular rendering

from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules
    
mol_data  = parse_sdf(open("molecule.sdf", "r", encoding="utf-8").read())

mol = Molecules(mol_data).centered()

scene = Scene()
scene.add_shape(mol, "mol")

viewer = Viewer.render(scene, width=600, height=400)

print("Press Any Key to exit...", end='', flush=True)
_ = input()  # Keep the viewer open until you decide to close

2. Animation playback with Viewer.play

from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules

frames = []

for i in range(1, 10):
    with open(f"frames/frame_{i}.sdf", "r") as f:
        sdf = f.read()
        mol = Molecules(parse_sdf(sdf)).centered()

    scene = Scene()
    scene.add_shape(mol, "mol")
    frames.append(scene)

Viewer.play(frames, interval=0.033, loops=-1, width=800, height=500, smooth=True) # loops=-1 for infinite repeat

more examples can be found in the examples folder:

cd cosmol_viewer
python .\examples\render_protein.py

Documentation

Please check out our documentation at here.

---

Contact

For any questions, issues, or suggestions, please contact [e-mail] or open an issue in the repository. We will review and address them as promptly as possible.