cosmol-viewer 0.1.1__cp37-abi3-win32.whl → 0.1.5.dev5__cp37-abi3-win32.whl

cosmol_viewer/__init__.pyi

@@ -0,0 +1,389 @@
+from typing import Optional, Union, List
+
+def parse_sdf(
+    sdf: str,
+    keep_h: bool = True,
+    multimodel: bool = True,
+    onemol: bool = False
+) -> MoleculeData:
+    """
+    Parse an SDF string into molecule data.
+
+    # Args
+      - sdf: Path to an SD string containing SDF content.
+      - keep_h: Whether to keep explicit hydrogen atoms (default: True).
+      - multimodel: Whether to allow multiple models in one file (default: True).
+      - onemol: Whether to merge multiple models into one molecule (default: False).
+
+    # Returns
+      - MoleculeData: Parsed molecule data object.
+
+    # Example
+    ```python
+    from cosmol_viewer import parse_sdf
+    mol = parse_sdf(open("./molecule.sdf", "r", encoding="utf-8").read())
+    ```
+    """
+    ...
+
+def parse_mmcif(
+    mmcif: str
+) -> ProteinData:
+    """
+    Parse an MMCIF string into protein data.
+
+    # Args
+      - mmcif: Path to an MMCIF string containing MMCIF content.
+
+    # Returns
+      - ProteinData: Parsed protein data object.
+
+    # Example
+    ```python
+    from cosmol_viewer import parse_mmcif
+    prot = parse_mmcif(open("./protein.cif", "r", encoding="utf-8").read())
+    ```
+    """
+    ...
+
+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:
+      - PySphere
+      - PyStick
+      - PyMolecules
+
+    Shapes can be optionally identified with a string `id`,
+    which allows updates and deletion.
+    """
+
+    def __init__(self) -> None:
+        """
+        Creates a new empty scene.
+
+        # Example
+        ```python
+        scene = Scene()
+        ```
+        """
+        ...
+
+    def add_shape(self, shape: Union["Sphere", "Stick", "Molecules", "Protein"], id: Optional[str] = None) -> None:
+        """
+        Add a shape to the scene.
+
+        # Args
+          - shape: A shape instance (Sphere, Stick, Molecules, or Protein).
+          - id: Optional string ID to associate with the shape.
+
+        If the `id` is provided and a shape with the same ID exists,
+        the new shape will replace it.
+
+        # Example
+        ```python
+        scene.add_shape(sphere)
+        scene.add_shape(stick, id="bond1")
+        ```
+        """
+        ...
+
+    def update_shape(self, id: str, shape: Union["Sphere", "Stick", "Molecules", "Protein"]) -> None:
+        """
+        Update 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
+        ```python
+        scene.update_shape("atom1", updated_sphere)
+        ```
+        """
+        ...
+
+    def delete_shape(self, id: str) -> None:
+        """
+        Remove a shape from the scene by its ID.
+
+        # Args
+          - id: ID of the shape to remove.
+
+        # Example
+        ```python
+        scene.delete_shape("bond1")
+        ```
+        """
+        ...
+
+    def recenter(self, center: List[float]) -> None:
+        """
+        Recenter the scene at a given point.
+
+        # Args
+          - center: An XYZ array of 3 float values representing the new center.
+
+        # Example
+        ```python
+        scene.recenter([0.0, 0.0, 0.0])
+        ```
+        """
+        ...
+
+    def 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
+        ```python
+        scene.scale(1.5)
+        ```
+        """
+        ...
+
+    def set_background_color(self, background_color: List[float]) -> 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
+        ```python
+        scene.set_background_color([1.0, 1.0, 1.0])  # white background
+        ```
+        """
+        ...
+
+    def use_black_background(self) -> None:
+        """
+        Set the background color of the scene to black.
+
+        # Example
+        ```python
+        scene.use_black_background()
+        ```
+        """
+        ...
+
+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.
+    """
+
+    @staticmethod
+    def get_environment() -> str:
+        """
+        Get the current runtime environment.
+
+        # Returns
+          - str: One of "Jupyter", "Colab", "PlainScript", or "IPythonTerminal".
+
+        # Example
+        ```python
+        env = Viewer.get_environment()
+        print(env)  # e.g., "Jupyter"
+        ```
+        """
+        ...
+
+    @staticmethod
+    def render(scene: "Scene", width: float = 800.0, height: float = 600.0) -> "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
+        ```python
+        from cosmol_viewer import Viewer, Scene, Sphere
+        scene = Scene()
+        scene.add_shape(Sphere([0, 0, 0], 1.0))
+        viewer = Viewer.render(scene)
+        ```
+        """
+        ...
+
+    @staticmethod
+    def play(
+        frames: List["Scene"],
+        interval: float,
+        loops: int,
+        width: float = 800.0,
+        height: float = 600.0,
+        smooth: bool = False
+    ) -> "Viewer":
+        """
+        Play an animation of multiple frames.
+
+        # Args
+          - frames: List of Scene objects as animation frames.
+          - interval: Frame interval in seconds.
+          - loops: Number of loops to repeat (-1 for infinite).
+          - width: The viewport width in pixels.
+          - height: The viewport height in pixels.
+          - smooth: Whether to smooth the animation by
+            interpolating between frames.
+
+        # Returns
+          - Viewer: The created viewer instance.
+
+        # Example
+        ```python
+        viewer = Viewer.play([scene1, scene2], interval=0.5, loops=3)
+        ```
+        """
+        ...
+
+    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
+        ```python
+        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
+        ```python
+        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
+    ```python
+    sphere = Sphere([0, 0, 0], 1.0).color([1, 0, 0])
+    ```
+    """
+
+    def __init__(self, center: List[float], radius: float) -> None: ...
+    def set_center(self, center: List[float]) -> "Sphere": ...
+    def set_radius(self, radius: float) -> "Sphere": ...
+    def color(self, color: List[float]) -> "Sphere": ...
+    def color_rgba(self, color: List[float]) -> "Sphere": ...
+    def opacity(self, opacity: float) -> "Sphere": ...
+
+
+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
+    ```python
+    stick = Stick([0,0,0], [1,1,1], 0.1).opacity(0.5)
+    ```
+    """
+
+    def __init__(self, start: List[float], end: List[float], thickness: float) -> None: ...
+    def color(self, color: List[float]) -> "Stick": ...
+    def color_rgba(self, color: List[float]) -> "Stick": ...
+    def opacity(self, opacity: float) -> "Stick": ...
+    def set_thickness(self, thickness: float) -> "Stick": ...
+    def set_start(self, start: List[float]) -> "Stick": ...
+    def set_end(self, end: List[float]) -> "Stick": ...
+
+
+class Molecules:
+    """
+    A molecular shape object.
+
+    # Example
+    ```python
+    mol = parse_sdf(open("molecule.sdf", "r", encoding="utf-8").read())
+    molecules = Molecules(mol).centered().color([0,1,0])
+    ```
+    """
+
+    def __init__(self, molecule_data: "MoleculeData") -> None: ...
+    def get_center(self) -> List[float]: ...
+    def centered(self) -> "Molecules": ...
+    def color(self, color: List[float]) -> "Molecules": ...
+    def color_rgba(self, color: List[float]) -> "Molecules": ...
+    def opacity(self, opacity: float) -> "Molecules": ...
+    def reset_color(self) -> "Molecules": ...
+
+class MoleculeData:
+    """
+    Internal representation of molecule data returned by `parse_sdf`.
+    """
+    ...
+
+class Protein:
+    """
+    A protein shape object.
+
+    # Example
+    ```python
+    mmcif_data  = parse_mmcif(open("2AMD.cif", "r", encoding="utf-8").read())
+    prot = Protein(mmcif_data).centered().color([0,1,0])
+    ```
+    """
+
+    def __init__(self, molecule_data: "MoleculeData") -> None: ...
+    def get_center(self) -> List[float]: ...
+    def centered(self) -> "Molecules": ...
+    def color(self, color: List[float]) -> "Molecules": ...
+    def color_rgba(self, color: List[float]) -> "Molecules": ...
+    def opacity(self, opacity: float) -> "Molecules": ...
+    def reset_color(self) -> "Molecules": ...
+
+class ProteinData:
+    """
+    Internal representation of protein data returned by `parse_mmcif`.
+    """
+    ...

cosmol_viewer-0.1.5.dev5.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: cosmol-viewer
+Version: 0.1.5.dev5
+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>
+
+A high-performance molecular viewer for `Python` and `Rust`, backed by `Rust`.
+Supports both static rendering and smooth animation playback — including inside Jupyter notebooks.
+
+
+A compact, high-performance renderer for molecular and scientific shapes with two usage patterns:
+
+- **Static rendering + update** — push individual scene updates from your application or simulation.
+- **Play (recommended for demonstrations & smooth playback)** — precompute frames and hand the sequence to the viewer to play back with optional interpolation (`smooth`).
+
+---
+
+## Quick concepts
+
+- **Scene**: container for shapes (molecules, spheres, lines, 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 (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.
+
+---
+
+## Installation
+
+```sh
+pip install cosmol-viewer
+```
+
+---
+
+## Quick Start
+See examples in [Google Colab](https://colab.research.google.com/drive/1Sw72QWjQh_sbbY43jGyBOfF1AQCycmIx?usp=sharing).
+### 1. Static molecular rendering
+
+```python
+from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules
+
+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)
+
+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`
+
+```python
+from cosmol_viewer import Scene, Viewer, parse_sdf, Molecules
+import time
+
+interval = 0.033   # ~30 FPS
+
+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)
+
+Viewer.play(frames, interval=interval, loops=1, width=600, height=400, smooth=True)
+```
+
+## Documentation
+
+For API reference and advanced usage, please see the [latest documentation](https://cosmol-repl.github.io/COSMol-viewer).
+

cosmol_viewer-0.1.5.dev5.dist-info/RECORD

@@ -0,0 +1,7 @@
+cosmol_viewer-0.1.5.dev5.dist-info/METADATA,sha256=dRDKxadRG0w5bgVf9teyHcUiycCYXIahuaPNAljCakE,3677
+cosmol_viewer-0.1.5.dev5.dist-info/WHEEL,sha256=Wk5Fd_lTEzYPUyNAg_8onKUGSv_hYjos3aDyUsI9euQ,91
+cosmol_viewer/__init__.py,sha256=K33zoYpHqUVvpFdMVxmCtw4uKj9ZXrGuQD4D4DuUmjk,135
+cosmol_viewer/__init__.pyi,sha256=0wSXySnkje07Z-LqpQtrx5lqudkNa_8mAzCLm-Z2I6A,10609
+cosmol_viewer/cosmol_viewer.pyd,sha256=9Hugh5gzubhj8KjouKPWATgzWteZWk2cuxtDd-wrLqk,16866816
+cosmol_viewer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cosmol_viewer-0.1.5.dev5.dist-info/RECORD,,

{cosmol_viewer-0.1.1.dist-info → cosmol_viewer-0.1.5.dev5.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: maturin (1.9.1)
+Generator: maturin (1.10.2)
 Root-Is-Purelib: false
 Tag: cp37-abi3-win32

cosmol_viewer-0.1.1.dist-info/METADATA

@@ -1,57 +0,0 @@
-Metadata-Version: 2.4
-Name: cosmol-viewer
-Version: 0.1.1
-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
-
-A high-performance molecular visualization library built with Rust and WebGPU, designed for seamless integration into Python workflows.
-
-- ⚡ Fast: Native-speed rendering powered by Rust and GPU acceleration
-
-- 🧬 Flexible: Load molecules from .sdf, .pdb, and dynamically update 3D structures
-
-- 📓 Notebook-friendly: Fully supports Jupyter and Google Colab — ideal for education, research, and live demos
-
-- 🔁 Real-time updates: Update molecular coordinates on-the-fly for simulations or animations
-
-- 🎨 Customizable: Control styles, camera, and rendering settings programmatically
-
-# Installation
-
-```sh
-pip install cosmol-viewer==0.1.1
-```
-
-# Usage
-
-```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)  # Launch the viewer
-
-# === Step 2: Update the same molecule dynamically ===
-import time
-
-for i in range(1, 10):  # Simulate multiple frames
-    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
-```

cosmol_viewer-0.1.1.dist-info/RECORD

@@ -1,5 +0,0 @@
-cosmol_viewer-0.1.1.dist-info/METADATA,sha256=vBi1xxURedVVx8L5IHJLvkbH-FNA0kaC1jz8EVzsd6Q,1697
-cosmol_viewer-0.1.1.dist-info/WHEEL,sha256=UcECe7RMSN54PK7UjTb4XiJPfalDkexpKph-K5Oo0Os,90
-cosmol_viewer/__init__.py,sha256=K33zoYpHqUVvpFdMVxmCtw4uKj9ZXrGuQD4D4DuUmjk,135
-cosmol_viewer/cosmol_viewer.pyd,sha256=Kb9SfX6Sv8NJIQLVhLR5IQODJIoGsZFOkt04tWtPVgE,10196480
-cosmol_viewer-0.1.1.dist-info/RECORD,,