cosmol-viewer 0.1.3.dev1__tar.gz → 0.1.3.dev3__tar.gz

{cosmol_viewer-0.1.3.dev1 → cosmol_viewer-0.1.3.dev3}/Cargo.lock

@@ -727,7 +727,7 @@ dependencies = [
 
 [[package]]
 name = "cosmol_viewer"
-version = "0.1.3-nightly.1"
+version = "0.1.3-nightly.3"
 dependencies = [
  "bytemuck",
  "cosmol_viewer_core",
@@ -740,7 +740,7 @@ dependencies = [
 
 [[package]]
 name = "cosmol_viewer_core"
-version = "0.1.3-nightly.1"
+version = "0.1.3-nightly.3"
 dependencies = [
  "bytemuck",
  "eframe",
@@ -770,7 +770,7 @@ dependencies = [
 
 [[package]]
 name = "cosmol_viewer_wasm"
-version = "0.1.3-nightly.1"
+version = "0.1.3-nightly.3"
 dependencies = [
  "base64",
  "cosmol_viewer_core",
@@ -1746,9 +1746,9 @@ checksum = "00810f1d8b74be64b13dbf3db89ac67740615d6c891f0e7b6179326533011a07"
 
 [[package]]
 name = "js-sys"
-version = "0.3.77"
+version = "0.3.81"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1cfaf33c695fc6e08064efbc1f72ec937429614f25eef83af942d0e227c3a28f"
+checksum = "ec48937a97411dcb524a265206ccd4c90bb711fca92b2792c407f268825b9305"
 dependencies = [
  "once_cell",
  "wasm-bindgen",
@@ -3501,21 +3501,22 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.100"
+version = "0.2.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1edc8929d7499fc4e8f0be2262a241556cfc54a0bea223790e71446f2aab1ef5"
+checksum = "c1da10c01ae9f1ae40cbfac0bac3b1e724b320abfcf52229f80b547c0d250e2d"
 dependencies = [
  "cfg-if",
  "once_cell",
  "rustversion",
  "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
 ]
 
 [[package]]
 name = "wasm-bindgen-backend"
-version = "0.2.100"
+version = "0.2.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2f0a0651a5c2bc21487bde11ee802ccaf4c51935d0d3d42a6101f98161700bc6"
+checksum = "671c9a5a66f49d8a47345ab942e2cb93c7d1d0339065d4f8139c486121b43b19"
 dependencies = [
  "bumpalo",
  "log",
@@ -3527,9 +3528,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-futures"
-version = "0.4.50"
+version = "0.4.54"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "555d470ec0bc3bb57890405e5d4322cc9ea83cebb085523ced7be4144dac1e61"
+checksum = "7e038d41e478cc73bae0ff9b36c60cff1c98b8f38f8d7e8061e79ee63608ac5c"
 dependencies = [
  "cfg-if",
  "js-sys",
@@ -3540,9 +3541,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.100"
+version = "0.2.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7fe63fc6d09ed3792bd0897b314f53de8e16568c2b3f7982f468c0bf9bd0b407"
+checksum = "7ca60477e4c59f5f2986c50191cd972e3a50d8a95603bc9434501cf156a9a119"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -3550,9 +3551,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.100"
+version = "0.2.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8ae87ea40c9f689fc23f209965b6fb8a99ad69aeeb0231408be24920604395de"
+checksum = "9f07d2f20d4da7b26400c9f4a0511e6e0345b040694e8a75bd41d578fa4421d7"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -3563,9 +3564,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.100"
+version = "0.2.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1a05d73b933a847d6cccdda8f838a22ff101ad9bf93e33684f39c1f5f0eece3d"
+checksum = "bad67dc8b2a1a6e5448428adec4c3e84c43e561d8c9ee8a9e5aabeb193ec41d1"
 dependencies = [
  "unicode-ident",
 ]
@@ -3681,9 +3682,9 @@ dependencies = [
 
 [[package]]
 name = "web-sys"
-version = "0.3.77"
+version = "0.3.81"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "33b6dd2ef9186f1f2072e409e99cd22a975331a6b3591b12c764e0e55c60d5d2"
+checksum = "9367c417a924a74cae129e6a2ae3b47fabb1f8995595ab474029da749a8be120"
 dependencies = [
  "js-sys",
  "wasm-bindgen",

{cosmol_viewer-0.1.3.dev1 → cosmol_viewer-0.1.3.dev3}/Cargo.toml

@@ -1,6 +1,6 @@
 [workspace.package]
 edition = "2024"
-version = "0.1.3-nightly.1"
+version = "0.1.3-nightly.3"
 authors = ["9028 wjt@cosmol.org"]
 repository = "https://github.com/COSMol-repl/COSMol-viewer"
 homepage = "https://github.com/COSMol-repl/COSMol-viewer"
@@ -13,8 +13,8 @@ resolver = "2"
 members = ["crates/python"]
 
 [workspace.dependencies]
-cosmol_viewer = { version = "0.1.3-nightly.1", path = "cosmol_viewer"}
-cosmol_viewer_core = { version = "0.1.3-nightly.1", path = "crates/core" }
+cosmol_viewer = { version = "0.1.3-nightly.3", path = "cosmol_viewer"}
+cosmol_viewer_core = { version = "0.1.3-nightly.3", path = "crates/core" }
 
 eframe = { version = "0.32.0", features = ["wayland","x11"] }
 pyo3 = { version = "0.25.1", features = ["extension-module", "abi3-py37"] }

cosmol_viewer-0.1.3.dev3/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: cosmol-viewer
+Version: 0.1.3.dev3
+Summary: Molecular visualization tools
+Author-email: 95028 <wjt@cosmol.org>
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Repository, https://github.com/COSMol-repl/COSMol-viewer
+
+# COSMol-viewer
+
+<div align="center">
+  <a href="https://crates.io/crates/cosmol_viewer">
+    <img src="https://img.shields.io/crates/v/cosmol_viewer.svg" alt="crates.io Latest Release"/>
+  </a>
+  <a href="https://pypi.org/project/cosmol_viewer/">
+    <img src="https://img.shields.io/pypi/v/cosmol_viewer.svg" alt="PyPi Latest Release"/>
+  </a>
+  <a href="https://cosmol-repl.github.io/COSMol-viewer">
+    <img src="https://img.shields.io/badge/docs-latest-blue.svg" alt="Documentation Status"/>
+  </a>
+</div>
+
+**COSMol-viewer** is a high-performance molecular visualization library, written in **Rust** and powered by **WebGPU**, designed for seamless integration into **Python** workflows.  
+
+- ⚡ **High-speed rendering** — GPU-accelerated performance at native speed  
+- 🧬 **Flexible input** — Load structures from `.sdf`, `.pdb`, or dynamically generated coordinates  
+- 📓 **Notebook-ready** — Fully compatible with Jupyter and Google Colab, ideal for teaching, research, and interactive demos  
+- 🔁 **Dynamic visualization** — Update molecular structures on-the-fly or play smooth preloaded animations  
+- 🎨 **Customizable** — Fine-grained control of rendering styles, camera, and scene parameters  
+
+---
+
+## Installation
+
+```sh
+pip install cosmol-viewer
+```
+
+---
+
+## Quick Start
+
+```python
+from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules
+
+# === Step 1: Load and render a molecule ===
+with open("molecule.sdf", "r") as f:
+    sdf = f.read()
+    mol = Molecules(parse_sdf(sdf)).centered()
+
+scene = Scene()
+scene.scale(0.1)
+scene.add_shape(mol, "mol")
+
+viewer = Viewer.render(scene, width=600, height=400)  # Launch viewer
+
+print("Press Any Key to exit...", end='', flush=True)
+_ = input()  # Keep the viewer open until you decide to close
+```
+
+---
+
+## Animation Modes
+
+COSMol-viewer supports **two complementary animation workflows**, depending on whether you prefer **real-time updates** or **preloaded playback**.
+
+### 1. Real-Time Updates (Frame-by-Frame Streaming)
+
+Update the molecule directly inside an existing scene:
+
+```python
+import time
+from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules
+
+scene = Scene()
+scene.scale(0.1)
+
+# Initial load
+with open("frames/frame_1.sdf", "r") as f:
+    sdf = f.read()
+    mol = Molecules(parse_sdf(sdf)).centered()
+scene.add_shape(mol, "mol")
+
+viewer = Viewer.render(scene, width=600, height=400)
+
+# Update in real time
+for i in range(2, 10):
+    with open(f"frames/frame_{i}.sdf", "r") as f:
+        sdf = f.read()
+        updated_mol = Molecules(parse_sdf(sdf)).centered()
+
+    scene.update_shape("mol", updated_mol)
+    viewer.update(scene)
+
+    time.sleep(0.033)  # ~30 FPS
+
+print("Press Any Key to exit...", end='', flush=True)
+_ = input()
+```
+
+**Use cases:**  
+- Visualizing the *progress* of a simulation step-by-step  
+- Interactive experiments or streaming scenarios where frames are not known in advance  
+
+**Trade-offs:**  
+- ✅ Low memory usage — no need to preload frames  
+- ⚠️ Playback smoothness depends on computation / I/O speed → may stutter if frame generation is slow  
+
+---
+
+### 2. Preloaded Playback (One-Shot Animation) (Start from 0.1.3)
+
+Load all frames into memory first, then play them back smoothly:
+
+```python
+from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules
+
+frames = []
+interval = 0.033  # ~30 FPS
+
+# Preload all 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.scale(0.1)
+    scene.add_shape(mol, "mol")
+    frames.append(scene)
+
+# Playback once
+Viewer.play(frames, interval=interval, loops=1, width=600, height=400)
+
+print("Press Any Key to exit...", end='', flush=True)
+_ = input()
+```
+
+**Use cases:**  
+- Smooth, stable playback for presentations or teaching  
+- Demonstrating precomputed trajectories (e.g., molecular dynamics snapshots)  
+
+**Trade-offs:**  
+- ✅ Very smooth playback, independent of computation speed  
+- ⚠️ Requires preloading all frames → higher memory usage  
+- ⚠️ Longer initial load time for large trajectories  
+
+---
+
+## Choosing the Right Mode
+
+- ✅ Use **real-time updates** if your frames are generated on-the-fly or memory is limited  
+- ✅ Use **preloaded playback** if you want guaranteed smooth animations and can preload your trajectory  
+
+---
+
+## Exiting the Viewer
+
+> **Important:** The viewer is bound to the Python process.  
+> When your script finishes, the rendering window will close automatically.
+
+To keep the visualization alive until you are ready to exit, always add:
+
+```python
+print("Press Any Key to exit...", end='', flush=True)
+_ = input()
+```
+
+This ensures:  
+- The window stays open for inspection  
+- The user decides when to end visualization  
+- Prevents premature termination at the end of the script  
+
+---
+
+## Documentation
+
+For API reference and advanced usage, please see the [latest documentation](https://cosmol-repl.github.io/COSMol-viewer).  
+

cosmol_viewer-0.1.3.dev3/README.md

@@ -0,0 +1,170 @@
+# COSMol-viewer
+
+<div align="center">
+  <a href="https://crates.io/crates/cosmol_viewer">
+    <img src="https://img.shields.io/crates/v/cosmol_viewer.svg" alt="crates.io Latest Release"/>
+  </a>
+  <a href="https://pypi.org/project/cosmol_viewer/">
+    <img src="https://img.shields.io/pypi/v/cosmol_viewer.svg" alt="PyPi Latest Release"/>
+  </a>
+  <a href="https://cosmol-repl.github.io/COSMol-viewer">
+    <img src="https://img.shields.io/badge/docs-latest-blue.svg" alt="Documentation Status"/>
+  </a>
+</div>
+
+**COSMol-viewer** is a high-performance molecular visualization library, written in **Rust** and powered by **WebGPU**, designed for seamless integration into **Python** workflows.  
+
+- ⚡ **High-speed rendering** — GPU-accelerated performance at native speed  
+- 🧬 **Flexible input** — Load structures from `.sdf`, `.pdb`, or dynamically generated coordinates  
+- 📓 **Notebook-ready** — Fully compatible with Jupyter and Google Colab, ideal for teaching, research, and interactive demos  
+- 🔁 **Dynamic visualization** — Update molecular structures on-the-fly or play smooth preloaded animations  
+- 🎨 **Customizable** — Fine-grained control of rendering styles, camera, and scene parameters  
+
+---
+
+## Installation
+
+```sh
+pip install cosmol-viewer
+```
+
+---
+
+## Quick Start
+
+```python
+from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules
+
+# === Step 1: Load and render a molecule ===
+with open("molecule.sdf", "r") as f:
+    sdf = f.read()
+    mol = Molecules(parse_sdf(sdf)).centered()
+
+scene = Scene()
+scene.scale(0.1)
+scene.add_shape(mol, "mol")
+
+viewer = Viewer.render(scene, width=600, height=400)  # Launch viewer
+
+print("Press Any Key to exit...", end='', flush=True)
+_ = input()  # Keep the viewer open until you decide to close
+```
+
+---
+
+## Animation Modes
+
+COSMol-viewer supports **two complementary animation workflows**, depending on whether you prefer **real-time updates** or **preloaded playback**.
+
+### 1. Real-Time Updates (Frame-by-Frame Streaming)
+
+Update the molecule directly inside an existing scene:
+
+```python
+import time
+from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules
+
+scene = Scene()
+scene.scale(0.1)
+
+# Initial load
+with open("frames/frame_1.sdf", "r") as f:
+    sdf = f.read()
+    mol = Molecules(parse_sdf(sdf)).centered()
+scene.add_shape(mol, "mol")
+
+viewer = Viewer.render(scene, width=600, height=400)
+
+# Update in real time
+for i in range(2, 10):
+    with open(f"frames/frame_{i}.sdf", "r") as f:
+        sdf = f.read()
+        updated_mol = Molecules(parse_sdf(sdf)).centered()
+
+    scene.update_shape("mol", updated_mol)
+    viewer.update(scene)
+
+    time.sleep(0.033)  # ~30 FPS
+
+print("Press Any Key to exit...", end='', flush=True)
+_ = input()
+```
+
+**Use cases:**  
+- Visualizing the *progress* of a simulation step-by-step  
+- Interactive experiments or streaming scenarios where frames are not known in advance  
+
+**Trade-offs:**  
+- ✅ Low memory usage — no need to preload frames  
+- ⚠️ Playback smoothness depends on computation / I/O speed → may stutter if frame generation is slow  
+
+---
+
+### 2. Preloaded Playback (One-Shot Animation) (Start from 0.1.3)
+
+Load all frames into memory first, then play them back smoothly:
+
+```python
+from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules
+
+frames = []
+interval = 0.033  # ~30 FPS
+
+# Preload all 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.scale(0.1)
+    scene.add_shape(mol, "mol")
+    frames.append(scene)
+
+# Playback once
+Viewer.play(frames, interval=interval, loops=1, width=600, height=400)
+
+print("Press Any Key to exit...", end='', flush=True)
+_ = input()
+```
+
+**Use cases:**  
+- Smooth, stable playback for presentations or teaching  
+- Demonstrating precomputed trajectories (e.g., molecular dynamics snapshots)  
+
+**Trade-offs:**  
+- ✅ Very smooth playback, independent of computation speed  
+- ⚠️ Requires preloading all frames → higher memory usage  
+- ⚠️ Longer initial load time for large trajectories  
+
+---
+
+## Choosing the Right Mode
+
+- ✅ Use **real-time updates** if your frames are generated on-the-fly or memory is limited  
+- ✅ Use **preloaded playback** if you want guaranteed smooth animations and can preload your trajectory  
+
+---
+
+## Exiting the Viewer
+
+> **Important:** The viewer is bound to the Python process.  
+> When your script finishes, the rendering window will close automatically.
+
+To keep the visualization alive until you are ready to exit, always add:
+
+```python
+print("Press Any Key to exit...", end='', flush=True)
+_ = input()
+```
+
+This ensures:  
+- The window stays open for inspection  
+- The user decides when to end visualization  
+- Prevents premature termination at the end of the script  
+
+---
+
+## Documentation
+
+For API reference and advanced usage, please see the [latest documentation](https://cosmol-repl.github.io/COSMol-viewer).  

{cosmol_viewer-0.1.3.dev1 → cosmol_viewer-0.1.3.dev3}/crates/core/src/lib.rs

@@ -192,6 +192,7 @@ impl NativeGuiViewer {
             let native_options = NativeOptions {
                 viewport: ViewportBuilder::default().with_inner_size(Vec2::new(width, height)),
                 depth_buffer: 24,
+                multisampling: 4,
                 event_loop_builder,
                 ..Default::default()
             };

{cosmol_viewer-0.1.3.dev1 → cosmol_viewer-0.1.3.dev3}/crates/core/src/shader/canvas.rs

@@ -329,9 +329,10 @@ impl Shader {
             gl.enable(glow::CULL_FACE);
             gl.cull_face(glow::BACK);
             gl.front_face(glow::CCW);
-
+            
             gl.enable(glow::DEPTH_TEST);
             gl.depth_func(glow::LEQUAL);
+            gl.enable(glow::MULTISAMPLE); // 开启多重采样
 
             gl.clear(glow::COLOR_BUFFER_BIT | glow::DEPTH_BUFFER_BIT);
 

{cosmol_viewer-0.1.3.dev1 → cosmol_viewer-0.1.3.dev3}/crates/core/src/shapes/sphere.rs

@@ -120,11 +120,6 @@ impl Sphere {
         self
     }
 
-    // pub fn clickable(mut self, val: bool) -> Self {
-    //     self.interaction.clickable = val;
-    //     self
-    // }
-
     pub fn to_mesh(&self, scale: f32) -> MeshData {
         let template = get_or_generate_sphere_mesh_template(self.quality);
 

cosmol_viewer-0.1.3.dev3/crates/python/README.md

@@ -0,0 +1,170 @@
+# COSMol-viewer
+
+<div align="center">
+  <a href="https://crates.io/crates/cosmol_viewer">
+    <img src="https://img.shields.io/crates/v/cosmol_viewer.svg" alt="crates.io Latest Release"/>
+  </a>
+  <a href="https://pypi.org/project/cosmol_viewer/">
+    <img src="https://img.shields.io/pypi/v/cosmol_viewer.svg" alt="PyPi Latest Release"/>
+  </a>
+  <a href="https://cosmol-repl.github.io/COSMol-viewer">
+    <img src="https://img.shields.io/badge/docs-latest-blue.svg" alt="Documentation Status"/>
+  </a>
+</div>
+
+**COSMol-viewer** is a high-performance molecular visualization library, written in **Rust** and powered by **WebGPU**, designed for seamless integration into **Python** workflows.  
+
+- ⚡ **High-speed rendering** — GPU-accelerated performance at native speed  
+- 🧬 **Flexible input** — Load structures from `.sdf`, `.pdb`, or dynamically generated coordinates  
+- 📓 **Notebook-ready** — Fully compatible with Jupyter and Google Colab, ideal for teaching, research, and interactive demos  
+- 🔁 **Dynamic visualization** — Update molecular structures on-the-fly or play smooth preloaded animations  
+- 🎨 **Customizable** — Fine-grained control of rendering styles, camera, and scene parameters  
+
+---
+
+## Installation
+
+```sh
+pip install cosmol-viewer
+```
+
+---
+
+## Quick Start
+
+```python
+from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules
+
+# === Step 1: Load and render a molecule ===
+with open("molecule.sdf", "r") as f:
+    sdf = f.read()
+    mol = Molecules(parse_sdf(sdf)).centered()
+
+scene = Scene()
+scene.scale(0.1)
+scene.add_shape(mol, "mol")
+
+viewer = Viewer.render(scene, width=600, height=400)  # Launch viewer
+
+print("Press Any Key to exit...", end='', flush=True)
+_ = input()  # Keep the viewer open until you decide to close
+```
+
+---
+
+## Animation Modes
+
+COSMol-viewer supports **two complementary animation workflows**, depending on whether you prefer **real-time updates** or **preloaded playback**.
+
+### 1. Real-Time Updates (Frame-by-Frame Streaming)
+
+Update the molecule directly inside an existing scene:
+
+```python
+import time
+from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules
+
+scene = Scene()
+scene.scale(0.1)
+
+# Initial load
+with open("frames/frame_1.sdf", "r") as f:
+    sdf = f.read()
+    mol = Molecules(parse_sdf(sdf)).centered()
+scene.add_shape(mol, "mol")
+
+viewer = Viewer.render(scene, width=600, height=400)
+
+# Update in real time
+for i in range(2, 10):
+    with open(f"frames/frame_{i}.sdf", "r") as f:
+        sdf = f.read()
+        updated_mol = Molecules(parse_sdf(sdf)).centered()
+
+    scene.update_shape("mol", updated_mol)
+    viewer.update(scene)
+
+    time.sleep(0.033)  # ~30 FPS
+
+print("Press Any Key to exit...", end='', flush=True)
+_ = input()
+```
+
+**Use cases:**  
+- Visualizing the *progress* of a simulation step-by-step  
+- Interactive experiments or streaming scenarios where frames are not known in advance  
+
+**Trade-offs:**  
+- ✅ Low memory usage — no need to preload frames  
+- ⚠️ Playback smoothness depends on computation / I/O speed → may stutter if frame generation is slow  
+
+---
+
+### 2. Preloaded Playback (One-Shot Animation) (Start from 0.1.3)
+
+Load all frames into memory first, then play them back smoothly:
+
+```python
+from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules
+
+frames = []
+interval = 0.033  # ~30 FPS
+
+# Preload all 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.scale(0.1)
+    scene.add_shape(mol, "mol")
+    frames.append(scene)
+
+# Playback once
+Viewer.play(frames, interval=interval, loops=1, width=600, height=400)
+
+print("Press Any Key to exit...", end='', flush=True)
+_ = input()
+```
+
+**Use cases:**  
+- Smooth, stable playback for presentations or teaching  
+- Demonstrating precomputed trajectories (e.g., molecular dynamics snapshots)  
+
+**Trade-offs:**  
+- ✅ Very smooth playback, independent of computation speed  
+- ⚠️ Requires preloading all frames → higher memory usage  
+- ⚠️ Longer initial load time for large trajectories  
+
+---
+
+## Choosing the Right Mode
+
+- ✅ Use **real-time updates** if your frames are generated on-the-fly or memory is limited  
+- ✅ Use **preloaded playback** if you want guaranteed smooth animations and can preload your trajectory  
+
+---
+
+## Exiting the Viewer
+
+> **Important:** The viewer is bound to the Python process.  
+> When your script finishes, the rendering window will close automatically.
+
+To keep the visualization alive until you are ready to exit, always add:
+
+```python
+print("Press Any Key to exit...", end='', flush=True)
+_ = input()
+```
+
+This ensures:  
+- The window stays open for inspection  
+- The user decides when to end visualization  
+- Prevents premature termination at the end of the script  
+
+---
+
+## Documentation
+
+For API reference and advanced usage, please see the [latest documentation](https://cosmol-repl.github.io/COSMol-viewer).