cloudglancer 0.1.4__tar.gz → 0.1.6__tar.gz

{cloudglancer-0.1.4/cloudglancer.egg-info → cloudglancer-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudglancer
-Version: 0.1.4
+Version: 0.1.6
 Summary: Simple interactive visualization of 3D point clouds
 Author-email: Your Name <your.email@example.com>
 License: MIT
@@ -24,6 +24,9 @@ Requires-Dist: plotly>=5.0.0
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: numpy>=1.24.0
 Requires-Dist: nbformat>=4.2.0
+Requires-Dist: kaleido<1.0,>=0.2.1
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: tqdm>=4.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
@@ -45,6 +48,7 @@ Simple interactive visualization of 3D point clouds using Plotly.
 - Easy-to-use API with sensible defaults
 - Type hints for better IDE support
 - Plot batched point clouds (B, N, 3)
+- Export a rotating turntable GIF of any figure
 
 ## Installation
 
@@ -64,6 +68,14 @@ points = np.random.randn(500, 3)
 # Create and display the plot
 cg.plot(points, title="My Point Cloud", size=2.0).show()
 ```
+
+Export a rotating GIF of the same figure:
+
+```python
+fig = cg.plot(points, size=2.0)
+cg.animate(fig, "rotation.gif", axis="z", n_frames=60)
+```
+
 More examples are in the `examples` folder.
 
 ### Development Installation

{cloudglancer-0.1.4 → cloudglancer-0.1.6}/README.md

@@ -13,6 +13,7 @@ Simple interactive visualization of 3D point clouds using Plotly.
 - Easy-to-use API with sensible defaults
 - Type hints for better IDE support
 - Plot batched point clouds (B, N, 3)
+- Export a rotating turntable GIF of any figure
 
 ## Installation
 
@@ -32,6 +33,14 @@ points = np.random.randn(500, 3)
 # Create and display the plot
 cg.plot(points, title="My Point Cloud", size=2.0).show()
 ```
+
+Export a rotating GIF of the same figure:
+
+```python
+fig = cg.plot(points, size=2.0)
+cg.animate(fig, "rotation.gif", axis="z", n_frames=60)
+```
+
 More examples are in the `examples` folder.
 
 ### Development Installation

{cloudglancer-0.1.4 → cloudglancer-0.1.6}/cloudglancer/__init__.py

@@ -1,6 +1,7 @@
 """cloudglancer: Simple interactive visualization of 3D point clouds"""
 
 from cloudglancer.scatter import plot, combine_plots
+from cloudglancer.animate import animate
 
 __version__ = "0.1.0"
-__all__ = ["plot", "combine_plots"]
+__all__ = ["plot", "combine_plots", "animate"]

cloudglancer-0.1.6/cloudglancer/animate.py

@@ -0,0 +1,184 @@
+"""Render a rotating GIF animation of a 3D Plotly figure."""
+
+import multiprocessing
+import os
+from concurrent.futures import ProcessPoolExecutor
+from io import BytesIO
+from typing import Tuple
+
+import numpy as np
+from plotly.graph_objects import Figure
+from tqdm import tqdm
+
+
+_AXIS_VECTORS = {
+    "x": np.array([1.0, 0.0, 0.0]),
+    "y": np.array([0.0, 1.0, 0.0]),
+    "z": np.array([0.0, 0.0, 1.0]),
+}
+
+
+def _rotation_matrix(axis: np.ndarray, theta: float) -> np.ndarray:
+    """Rodrigues' rotation matrix for rotation by `theta` around unit `axis`."""
+    x, y, z = axis
+    c = np.cos(theta)
+    s = np.sin(theta)
+    C = 1.0 - c
+    return np.array([
+        [c + x * x * C,     x * y * C - z * s, x * z * C + y * s],
+        [y * x * C + z * s, c + y * y * C,     y * z * C - x * s],
+        [z * x * C - y * s, z * y * C + x * s, c + z * z * C],
+    ])
+
+
+def _scene_keys(fig: Figure) -> list:
+    """Return all scene-typed layout keys on `fig` (e.g. 'scene', 'scene2', ...)."""
+    keys = []
+    for key in fig.layout:
+        if key == "scene" or (key.startswith("scene") and key[5:].isdigit()):
+            keys.append(key)
+    return keys
+
+
+def _eye_to_vec(eye) -> np.ndarray:
+    if eye is None or eye.x is None:
+        return np.array([1.25, 1.25, 1.25])
+    return np.array([eye.x, eye.y, eye.z])
+
+
+_WORKER_FIG = None
+
+
+def _init_worker(fig_dict: dict) -> None:
+    global _WORKER_FIG
+    from plotly.graph_objects import Figure as _Figure
+    _WORKER_FIG = _Figure(fig_dict)
+
+
+def _render_frame(args: Tuple[dict, int, int]) -> bytes:
+    scene_updates, width, height = args
+    _WORKER_FIG.update_layout(**scene_updates)
+    return _WORKER_FIG.to_image(format="png", width=width, height=height)
+
+
+def animate(
+    fig: Figure,
+    output_path: str,
+    axis: str = "z",
+    n_frames: int = 60,
+    duration: int = 50,
+    width: int = 800,
+    height: int = 600,
+    loop: int = 0,
+    progress: bool = True,
+) -> str:
+    """
+    Render a rotating GIF of a 3D Plotly figure.
+
+    The camera orbits the scene around the chosen axis for one full revolution
+    over `n_frames` frames, producing a turntable-style animation. The input
+    figure is not mutated.
+
+    Args:
+        fig: A Plotly Figure (e.g. the output of :func:`cloudglancer.plot` or
+            :func:`cloudglancer.combine_plots`).
+        output_path: Path where the GIF is written.
+        axis: Rotation axis, one of ``'x'``, ``'y'``, ``'z'``. Defaults to ``'z'``.
+        n_frames: Number of frames in one full revolution. Defaults to 60.
+        duration: Per-frame display time in milliseconds. Defaults to 50.
+        width: Frame width in pixels. Defaults to 800.
+        height: Frame height in pixels. Defaults to 600.
+        loop: Number of times the GIF should loop (0 = infinite). Defaults to 0.
+        progress: Show a tqdm progress bar while rendering frames. Defaults to True.
+
+    Returns:
+        The ``output_path`` it wrote to.
+
+    Raises:
+        ValueError: If `axis` is not one of ``'x'``, ``'y'``, ``'z'``.
+        ImportError: If ``kaleido`` or ``Pillow`` is not installed.
+
+    Examples:
+        >>> import numpy as np
+        >>> import cloudglancer as cg
+        >>> pts = np.random.randn(500, 3)
+        >>> fig = cg.plot(pts, size=2.0)
+        >>> cg.animate(fig, "rotation.gif", axis="z", n_frames=60)
+        'rotation.gif'
+    """
+    if axis not in _AXIS_VECTORS:
+        raise ValueError(f"axis must be one of 'x', 'y', 'z' (got {axis!r})")
+
+    try:
+        from PIL import Image
+    except ImportError as e:
+        raise ImportError(
+            "animate() requires Pillow. Install it with `pip install Pillow`."
+        ) from e
+
+    axis_vec = _AXIS_VECTORS[axis]
+    up_vec = {"x": dict(x=1, y=0, z=0),
+              "y": dict(x=0, y=1, z=0),
+              "z": dict(x=0, y=0, z=1)}[axis]
+
+    scene_keys = _scene_keys(fig)
+    if not scene_keys:
+        raise ValueError("figure has no 3D scene to animate")
+
+    initial_eyes = {k: _eye_to_vec(fig.layout[k].camera.eye) for k in scene_keys}
+
+    tasks = []
+    for i in range(n_frames):
+        theta = 2.0 * np.pi * i / n_frames
+        R = _rotation_matrix(axis_vec, theta)
+        scene_updates = {}
+        for k in scene_keys:
+            eye = R @ initial_eyes[k]
+            scene_updates[k] = dict(
+                camera=dict(
+                    eye=dict(x=float(eye[0]), y=float(eye[1]), z=float(eye[2])),
+                    up=up_vec,
+                )
+            )
+        tasks.append((scene_updates, width, height))
+
+    fig_dict = fig.to_dict()
+    n_workers = min(4, os.cpu_count() or 2, n_frames)
+
+    pngs: list = [None] * n_frames
+    try:
+        with ProcessPoolExecutor(
+            max_workers=n_workers,
+            mp_context=multiprocessing.get_context("spawn"),
+            initializer=_init_worker,
+            initargs=(fig_dict,),
+        ) as executor:
+            iterator = executor.map(_render_frame, tasks, chunksize=1)
+            for i, png in enumerate(
+                tqdm(iterator, total=n_frames, desc="Rendering frames",
+                     unit="frame", disable=not progress)
+            ):
+                pngs[i] = png
+    except ValueError as e:
+        raise ImportError(
+            "animate() requires kaleido for PNG export. "
+            "Install it with `pip install 'kaleido<1.0'`."
+        ) from e
+
+    ref_palette = Image.open(BytesIO(pngs[0])).convert("P", palette=Image.ADAPTIVE)
+
+    frames = [ref_palette]
+    for png in pngs[1:]:
+        rgb = Image.open(BytesIO(png)).convert("RGB")
+        frames.append(rgb.quantize(palette=ref_palette, dither=Image.NONE))
+
+    frames[0].save(
+        output_path,
+        save_all=True,
+        append_images=frames[1:],
+        duration=duration,
+        loop=loop,
+        disposal=2,
+    )
+
+    return output_path

{cloudglancer-0.1.4 → cloudglancer-0.1.6}/cloudglancer/scatter.py

@@ -11,7 +11,7 @@ def plot(
     points: np.ndarray,
     labels: Optional[np.ndarray] = None,
     label_map: Optional[Dict] = None,
-    color_map: Optional[Union[List[str], float]] = None,
+    color_map: Optional[Union[List[str], Dict[str, str], float]] = None,
     batch_colors: Optional[List[str]] = None,
     size: float = 1.5,
     title: Optional[str] = None,
@@ -29,8 +29,9 @@ def plot(
             a continuous color scale. Not supported for batched input.
         label_map (dict, optional): Maps label values to display names. When provided,
             enables discrete color mapping.
-        color_map (list or float, optional): When label_map is provided, this should be
-            a list of color strings for discrete coloring. Without label_map, this can be
+        color_map (list, dict, or float, optional): When label_map is provided, a
+            {display_name: color} dict (preferred) or a list of color strings aligned
+            with label_map values for discrete coloring. Without label_map, this can be
             a float specifying the continuous color scale midpoint.
         batch_colors (list, optional): List of color strings, one per batch element.
             Only used when points is 3D. Defaults to Plotly's qualitative palette.
@@ -91,8 +92,18 @@ def plot(
             df["label"] = labels
             if label_map:
                 df["label"] = df["label"].map(label_map).fillna(df["label"])
-                fig = px.scatter_3d(df, x="x", y="y", z="z", color="label",
-                                  color_discrete_sequence=color_map)
+                category_orders = {"label": list(label_map.values())}
+                if isinstance(color_map, dict):
+                    discrete_map = color_map
+                elif isinstance(color_map, list):
+                    discrete_map = dict(zip(label_map.values(), color_map))
+                else:
+                    discrete_map = None
+                fig = px.scatter_3d(
+                    df, x="x", y="y", z="z", color="label",
+                    color_discrete_map=discrete_map,
+                    category_orders=category_orders,
+                )
             else:
                 fig = px.scatter_3d(df, x="x", y="y", z="z", color="label",
                                   color_continuous_midpoint=color_map, range_color=[0, 1])

{cloudglancer-0.1.4 → cloudglancer-0.1.6/cloudglancer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudglancer
-Version: 0.1.4
+Version: 0.1.6
 Summary: Simple interactive visualization of 3D point clouds
 Author-email: Your Name <your.email@example.com>
 License: MIT
@@ -24,6 +24,9 @@ Requires-Dist: plotly>=5.0.0
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: numpy>=1.24.0
 Requires-Dist: nbformat>=4.2.0
+Requires-Dist: kaleido<1.0,>=0.2.1
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: tqdm>=4.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
@@ -45,6 +48,7 @@ Simple interactive visualization of 3D point clouds using Plotly.
 - Easy-to-use API with sensible defaults
 - Type hints for better IDE support
 - Plot batched point clouds (B, N, 3)
+- Export a rotating turntable GIF of any figure
 
 ## Installation
 
@@ -64,6 +68,14 @@ points = np.random.randn(500, 3)
 # Create and display the plot
 cg.plot(points, title="My Point Cloud", size=2.0).show()
 ```
+
+Export a rotating GIF of the same figure:
+
+```python
+fig = cg.plot(points, size=2.0)
+cg.animate(fig, "rotation.gif", axis="z", n_frames=60)
+```
+
 More examples are in the `examples` folder.
 
 ### Development Installation

{cloudglancer-0.1.4 → cloudglancer-0.1.6}/cloudglancer.egg-info/SOURCES.txt

@@ -3,10 +3,12 @@ MANIFEST.in
 README.md
 pyproject.toml
 cloudglancer/__init__.py
+cloudglancer/animate.py
 cloudglancer/scatter.py
 cloudglancer.egg-info/PKG-INFO
 cloudglancer.egg-info/SOURCES.txt
 cloudglancer.egg-info/dependency_links.txt
 cloudglancer.egg-info/requires.txt
 cloudglancer.egg-info/top_level.txt
+tests/test_animate.py
 tests/test_scatter.py

{cloudglancer-0.1.4 → cloudglancer-0.1.6}/cloudglancer.egg-info/requires.txt

@@ -2,6 +2,9 @@ plotly>=5.0.0
 pandas>=2.0.0
 numpy>=1.24.0
 nbformat>=4.2.0
+kaleido<1.0,>=0.2.1
+Pillow>=9.0.0
+tqdm>=4.0.0
 
 [dev]
 pytest>=7.0.0

{cloudglancer-0.1.4 → cloudglancer-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cloudglancer"
-version = "0.1.4"
+version = "0.1.6"
 description = "Simple interactive visualization of 3D point clouds"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -29,6 +29,9 @@ dependencies = [
     "pandas>=2.0.0",
     "numpy>=1.24.0",
     "nbformat>=4.2.0",
+    "kaleido>=0.2.1,<1.0",
+    "Pillow>=9.0.0",
+    "tqdm>=4.0.0",
 ]
 
 [project.optional-dependencies]

cloudglancer-0.1.6/tests/test_animate.py

@@ -0,0 +1,62 @@
+"""Unit tests for cloudglancer.animate module."""
+
+import numpy as np
+import pytest
+
+from cloudglancer import plot, combine_plots, animate
+
+
+def _is_gif(path) -> bool:
+    with open(path, "rb") as f:
+        head = f.read(6)
+    return head in (b"GIF87a", b"GIF89a")
+
+
+def test_animate_writes_file(tmp_path):
+    points = np.random.randn(50, 3)
+    fig = plot(points)
+    out = tmp_path / "out.gif"
+    result = animate(fig, str(out), n_frames=4, width=160, height=120, progress=False)
+    assert result == str(out)
+    assert out.exists() and out.stat().st_size > 0
+    assert _is_gif(out)
+
+
+def test_animate_invalid_axis(tmp_path):
+    fig = plot(np.random.randn(10, 3))
+    with pytest.raises(ValueError, match="axis must be one of"):
+        animate(fig, str(tmp_path / "x.gif"), axis="w", n_frames=2)
+
+
+def test_animate_does_not_mutate_figure(tmp_path):
+    fig = plot(np.random.randn(20, 3))
+    fig.update_layout(scene=dict(camera=dict(eye=dict(x=2.0, y=2.0, z=2.0))))
+    before = (
+        fig.layout.scene.camera.eye.x,
+        fig.layout.scene.camera.eye.y,
+        fig.layout.scene.camera.eye.z,
+    )
+    animate(fig, str(tmp_path / "x.gif"), n_frames=3, width=120, height=120, progress=False)
+    after = (
+        fig.layout.scene.camera.eye.x,
+        fig.layout.scene.camera.eye.y,
+        fig.layout.scene.camera.eye.z,
+    )
+    assert before == after
+
+
+def test_animate_combined_figure(tmp_path):
+    f1 = plot(np.random.randn(20, 3))
+    f2 = plot(np.random.randn(20, 3))
+    combined = combine_plots([f1, f2], rows=1, cols=2)
+    out = tmp_path / "combined.gif"
+    animate(combined, str(out), axis="y", n_frames=3, width=200, height=120, progress=False)
+    assert out.exists() and _is_gif(out)
+
+
+@pytest.mark.parametrize("axis", ["x", "y", "z"])
+def test_animate_each_axis(tmp_path, axis):
+    fig = plot(np.random.randn(20, 3))
+    out = tmp_path / f"{axis}.gif"
+    animate(fig, str(out), axis=axis, n_frames=3, width=120, height=120, progress=False)
+    assert _is_gif(out)

{cloudglancer-0.1.4 → cloudglancer-0.1.6}/tests/test_scatter.py

@@ -34,6 +34,40 @@ def test_plot_with_label_map():
     assert len(fig.data) > 0
 
 
+def test_plot_label_map_color_binding_is_order_independent():
+    """Colors must bind to labels via label_map, not the point order
+    (regression for issue #1)."""
+    pts = np.random.randn(200, 3)
+    labels_a = np.zeros(200, dtype=int); labels_a[:100] = 1
+    labels_b = np.zeros(200, dtype=int); labels_b[100:] = 1
+    label_map = {0: "unknown", 1: "known"}
+    color_map = ["red", "steelblue"]
+
+    fig_a = plot(pts, labels=labels_a, label_map=label_map, color_map=color_map)
+    fig_b = plot(pts, labels=labels_b, label_map=label_map, color_map=color_map)
+
+    def color_for(fig, name):
+        trace = next(t for t in fig.data if t.name == name)
+        return trace.marker.color
+
+    assert color_for(fig_a, "unknown") == color_for(fig_b, "unknown") == "red"
+    assert color_for(fig_a, "known") == color_for(fig_b, "known") == "steelblue"
+
+
+def test_plot_label_map_accepts_color_dict():
+    """color_map may be a {display_name: color} dict."""
+    pts = np.random.randn(60, 3)
+    labels = np.array([0] * 30 + [1] * 30)
+    fig = plot(
+        pts, labels=labels,
+        label_map={0: "unknown", 1: "known"},
+        color_map={"unknown": "red", "known": "steelblue"},
+    )
+    by_name = {t.name: t.marker.color for t in fig.data}
+    assert by_name["unknown"] == "red"
+    assert by_name["known"] == "steelblue"
+
+
 def test_plot_invalid_shape():
     """Test that ValueError is raised for incorrect point shape."""
     points = np.random.randn(100, 2)  # Wrong shape