cloudglancer 0.1.6__tar.gz → 0.1.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudglancer
-Version: 0.1.6
+Version: 0.1.7
 Summary: Simple interactive visualization of 3D point clouds
 Author-email: Your Name <your.email@example.com>
 License: MIT
@@ -45,9 +45,8 @@ Simple interactive visualization of 3D point clouds using Plotly.
 - Interactive 3D scatter plots with pan, zoom, and rotation
 - Support for categorical and continuous color mapping
 - Combine multiple plots into subplot grids
-- Easy-to-use API with sensible defaults
-- Type hints for better IDE support
 - Plot batched point clouds (B, N, 3)
+- Render a (B, N, 3) batch as a grid of subplots (one cloud per cell)
 - Export a rotating turntable GIF of any figure
 
 ## Installation
@@ -76,6 +75,31 @@ fig = cg.plot(points, size=2.0)
 cg.animate(fig, "rotation.gif", axis="z", n_frames=60)
 ```
 
+Render a batch of point clouds as a grid of subplots (one cloud per cell):
+
+```python
+batch = np.random.randn(6, 500, 3)  # (B, N, 3)
+
+# Auto near-square grid, single color for every cloud
+fig = cg.plot_grid(batch, colors="#1f77b4", size=1.5)
+
+# Or explicit grid + per-cell colors
+fig = cg.plot_grid(batch, rows=2, cols=3,
+                   colors=["red", "green", "blue", "orange", "purple", "teal"])
+
+# Combine with animate() for a rotating GIF of the whole grid
+cg.animate(fig, "grid.gif", n_frames=60, width=1600, height=1200)
+```
+
+Apply a clean, GIF-friendly style (white backgrounds, hidden tick labels,
+light gray axis grid) to every 3D scene in a figure — works for both
+single plots and grids:
+
+```python
+fig = cg.beautify(cg.plot_grid(batch, colors="#1f77b4"))
+cg.animate(fig, "grid.gif", n_frames=60)
+```
+
 More examples are in the `examples` folder.
 
 ### Development Installation

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

@@ -10,9 +10,8 @@ Simple interactive visualization of 3D point clouds using Plotly.
 - Interactive 3D scatter plots with pan, zoom, and rotation
 - Support for categorical and continuous color mapping
 - Combine multiple plots into subplot grids
-- Easy-to-use API with sensible defaults
-- Type hints for better IDE support
 - Plot batched point clouds (B, N, 3)
+- Render a (B, N, 3) batch as a grid of subplots (one cloud per cell)
 - Export a rotating turntable GIF of any figure
 
 ## Installation
@@ -41,6 +40,31 @@ fig = cg.plot(points, size=2.0)
 cg.animate(fig, "rotation.gif", axis="z", n_frames=60)
 ```
 
+Render a batch of point clouds as a grid of subplots (one cloud per cell):
+
+```python
+batch = np.random.randn(6, 500, 3)  # (B, N, 3)
+
+# Auto near-square grid, single color for every cloud
+fig = cg.plot_grid(batch, colors="#1f77b4", size=1.5)
+
+# Or explicit grid + per-cell colors
+fig = cg.plot_grid(batch, rows=2, cols=3,
+                   colors=["red", "green", "blue", "orange", "purple", "teal"])
+
+# Combine with animate() for a rotating GIF of the whole grid
+cg.animate(fig, "grid.gif", n_frames=60, width=1600, height=1200)
+```
+
+Apply a clean, GIF-friendly style (white backgrounds, hidden tick labels,
+light gray axis grid) to every 3D scene in a figure — works for both
+single plots and grids:
+
+```python
+fig = cg.beautify(cg.plot_grid(batch, colors="#1f77b4"))
+cg.animate(fig, "grid.gif", n_frames=60)
+```
+
 More examples are in the `examples` folder.
 
 ### Development Installation

cloudglancer-0.1.7/cloudglancer/__init__.py

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

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

@@ -1,6 +1,7 @@
 """Core scatter plotting functionality for 3D point clouds."""
 
-from typing import Optional, List, Dict, Union
+import math
+from typing import Optional, List, Dict, Tuple, Union
 import plotly.express as px
 import pandas as pd
 import numpy as np
@@ -179,3 +180,164 @@ def combine_plots(figs: List[Figure], rows: int = 1, cols: int = 2, aspectmode:
     )
 
     return combined_fig
+
+
+_DEFAULT_AXIS_STYLE = dict(
+    backgroundcolor="white",
+    gridcolor="lightgray",
+    showbackground=True,
+    showticklabels=False,
+    title="",
+    zerolinecolor="lightgray",
+)
+
+
+def beautify(
+    fig: Figure,
+    paper_bgcolor: str = "white",
+    scene_bgcolor: str = "white",
+    axis_style: Optional[Dict] = None,
+) -> Figure:
+    """
+    Apply a clean, GIF-friendly style to every 3D scene in a figure.
+
+    Hides axis tick labels and titles, gives axes a light gray grid, and
+    paints both the figure paper and each 3D scene's background. Works on
+    single-scene figures (from :func:`plot`) and multi-scene figures (from
+    :func:`plot_grid` / :func:`combine_plots`), which use layout keys
+    ``scene``, ``scene2``, ``scene3``, .... Mutates and returns ``fig``.
+
+    Args:
+        fig (plotly.graph_objects.Figure): Figure to style in place.
+        paper_bgcolor (str, optional): Color of the area outside the 3D
+            scenes. Default ``"white"``.
+        scene_bgcolor (str, optional): Color of the area inside each 3D
+            scene's box. Default ``"white"``.
+        axis_style (dict, optional): Override the per-axis style applied
+            to ``xaxis``/``yaxis``/``zaxis`` of every scene. When ``None``
+            a clean default (light gray grid, hidden tick labels and
+            titles) is used.
+
+    Returns:
+        plotly.graph_objects.Figure: The same ``fig``, restyled.
+
+    Examples:
+        >>> import numpy as np
+        >>> import cloudglancer as cg
+        >>> pts = np.random.randn(6, 200, 3)
+        >>> fig = cg.beautify(cg.plot_grid(pts, colors="#1f77b4"))
+        >>> cg.animate(fig, "grid.gif", n_frames=60)
+    """
+    style = dict(_DEFAULT_AXIS_STYLE if axis_style is None else axis_style)
+
+    fig.update_layout(paper_bgcolor=paper_bgcolor)
+
+    for key in fig.layout:
+        if key == "scene" or (key.startswith("scene") and key[len("scene"):].isdigit()):
+            fig.layout[key].update(
+                bgcolor=scene_bgcolor,
+                xaxis=style,
+                yaxis=style,
+                zaxis=style,
+            )
+
+    return fig
+
+
+def _resolve_grid_shape(n: int, rows: Optional[int], cols: Optional[int]) -> Tuple[int, int]:
+    if rows is None and cols is None:
+        cols = int(math.ceil(math.sqrt(n)))
+        rows = int(math.ceil(n / cols))
+    elif rows is None:
+        rows = int(math.ceil(n / cols))
+    elif cols is None:
+        cols = int(math.ceil(n / rows))
+    if rows * cols < n:
+        raise ValueError(f"rows*cols={rows * cols} < B={n}")
+    return rows, cols
+
+
+def plot_grid(
+    points: np.ndarray,
+    rows: Optional[int] = None,
+    cols: Optional[int] = None,
+    colors: Optional[Union[str, List[str]]] = None,
+    size: float = 1.5,
+    aspectmode: Optional[str] = 'data',
+    showlegend: bool = False,
+) -> Figure:
+    """
+    Render a batch of 3D point clouds as a grid of subplots, one cloud per cell.
+
+    Args:
+        points (np.ndarray): Array of shape (B, N, 3). Each batch element is
+            rendered into its own subplot.
+        rows (int, optional): Number of grid rows. If both ``rows`` and ``cols``
+            are ``None``, a near-square grid is chosen automatically. If only
+            one is given, the other is derived from ``B``.
+        cols (int, optional): Number of grid columns. See ``rows``.
+        colors (str or list of str, optional): Color for each subplot. Pass a
+            single color string to use it for every cloud, or a list of length
+            ``B`` to color each cloud individually. Defaults to Plotly's
+            qualitative palette.
+        size (float, optional): Marker size. Default is 1.5.
+        aspectmode (str, optional): Aspect mode for each 3D scene. Default
+            ``'data'``.
+        showlegend (bool, optional): Whether to show the figure legend.
+            Default ``False`` (legends are noisy in grids).
+
+    Returns:
+        plotly.graph_objects.Figure: A combined figure with the grid of
+        subplots, ready for ``.show()`` or for passing to
+        :func:`cloudglancer.animate`.
+
+    Raises:
+        ValueError: If ``points`` is not (B, N, 3), if ``colors`` is a list
+            whose length does not match ``B``, or if ``rows*cols < B``.
+
+    Examples:
+        >>> import numpy as np
+        >>> import cloudglancer as cg
+        >>> pts = np.random.randn(6, 200, 3)
+        >>> fig = cg.plot_grid(pts, colors="#1f77b4", size=1.5)
+        >>> cg.animate(fig, "grid.gif", n_frames=60)
+    """
+    if points.ndim != 3 or points.shape[-1] != 3:
+        raise ValueError(f"points must be of shape (B, N, 3); got {points.shape}")
+
+    B = points.shape[0]
+    rows, cols = _resolve_grid_shape(B, rows, cols)
+
+    if colors is None:
+        palette = px.colors.qualitative.Plotly
+        cell_colors = [palette[i % len(palette)] for i in range(B)]
+    elif isinstance(colors, str):
+        cell_colors = [colors] * B
+    else:
+        if len(colors) != B:
+            raise ValueError(
+                f"colors must have length B={B}; got {len(colors)}"
+            )
+        cell_colors = list(colors)
+
+    figs = []
+    for i in range(rows * cols):
+        if i < B:
+            sub = plot(
+                points[i:i + 1],
+                batch_colors=[cell_colors[i]],
+                size=size,
+                aspectmode=aspectmode,
+            )
+        else:
+            sub = plot(
+                np.zeros((1, 1, 3), dtype=points.dtype),
+                batch_colors=["rgba(0,0,0,0)"],
+                size=size,
+                aspectmode=aspectmode,
+            )
+        figs.append(sub)
+
+    combined = combine_plots(figs, rows=rows, cols=cols, aspectmode=aspectmode)
+    combined.update_layout(showlegend=showlegend)
+    return combined

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudglancer
-Version: 0.1.6
+Version: 0.1.7
 Summary: Simple interactive visualization of 3D point clouds
 Author-email: Your Name <your.email@example.com>
 License: MIT
@@ -45,9 +45,8 @@ Simple interactive visualization of 3D point clouds using Plotly.
 - Interactive 3D scatter plots with pan, zoom, and rotation
 - Support for categorical and continuous color mapping
 - Combine multiple plots into subplot grids
-- Easy-to-use API with sensible defaults
-- Type hints for better IDE support
 - Plot batched point clouds (B, N, 3)
+- Render a (B, N, 3) batch as a grid of subplots (one cloud per cell)
 - Export a rotating turntable GIF of any figure
 
 ## Installation
@@ -76,6 +75,31 @@ fig = cg.plot(points, size=2.0)
 cg.animate(fig, "rotation.gif", axis="z", n_frames=60)
 ```
 
+Render a batch of point clouds as a grid of subplots (one cloud per cell):
+
+```python
+batch = np.random.randn(6, 500, 3)  # (B, N, 3)
+
+# Auto near-square grid, single color for every cloud
+fig = cg.plot_grid(batch, colors="#1f77b4", size=1.5)
+
+# Or explicit grid + per-cell colors
+fig = cg.plot_grid(batch, rows=2, cols=3,
+                   colors=["red", "green", "blue", "orange", "purple", "teal"])
+
+# Combine with animate() for a rotating GIF of the whole grid
+cg.animate(fig, "grid.gif", n_frames=60, width=1600, height=1200)
+```
+
+Apply a clean, GIF-friendly style (white backgrounds, hidden tick labels,
+light gray axis grid) to every 3D scene in a figure — works for both
+single plots and grids:
+
+```python
+fig = cg.beautify(cg.plot_grid(batch, colors="#1f77b4"))
+cg.animate(fig, "grid.gif", n_frames=60)
+```
+
 More examples are in the `examples` folder.
 
 ### Development Installation

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cloudglancer"
-version = "0.1.6"
+version = "0.1.7"
 description = "Simple interactive visualization of 3D point clouds"
 readme = "README.md"
 requires-python = ">=3.9"

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

@@ -2,7 +2,7 @@
 
 import numpy as np
 import pytest
-from cloudglancer import plot, combine_plots
+from cloudglancer import plot, combine_plots, plot_grid, beautify
 
 
 def test_plot_basic():
@@ -154,3 +154,105 @@ def test_plot_batched_with_labels_raises():
     labels = np.zeros(300)
     with pytest.raises(ValueError, match="labels are not supported"):
         plot(points, labels=labels)
+
+
+def _scene_count(fig):
+    return sum(
+        1 for k in fig.layout
+        if k == "scene" or (k.startswith("scene") and k[5:].isdigit())
+    )
+
+
+def test_plot_grid_auto_shape():
+    """Auto grid for B=5 → 3 cols x 2 rows = 6 cells."""
+    pts = np.random.randn(5, 30, 3)
+    fig = plot_grid(pts)
+    assert _scene_count(fig) == 6
+    assert fig.layout.showlegend is False
+
+
+def test_plot_grid_explicit_shape():
+    pts = np.random.randn(4, 30, 3)
+    fig = plot_grid(pts, rows=2, cols=2)
+    assert _scene_count(fig) == 4
+    assert len(fig.data) == 4
+
+
+def test_plot_grid_single_color_string():
+    pts = np.random.randn(3, 20, 3)
+    fig = plot_grid(pts, colors="#1f77b4")
+    cloud_traces = [t for t in fig.data if len(t.x) > 1]
+    assert len(cloud_traces) == 3
+    for t in cloud_traces:
+        assert t.marker.color == "#1f77b4"
+
+
+def test_plot_grid_color_list():
+    pts = np.random.randn(3, 20, 3)
+    fig = plot_grid(pts, colors=["red", "green", "blue"])
+    cloud_traces = [t for t in fig.data if len(t.x) > 1]
+    colors = [t.marker.color for t in cloud_traces]
+    assert sorted(colors) == sorted(["red", "green", "blue"])
+
+
+def test_plot_grid_invalid_shape():
+    with pytest.raises(ValueError, match="points must be of shape"):
+        plot_grid(np.random.randn(3, 20, 2))
+
+
+def test_plot_grid_grid_too_small():
+    pts = np.random.randn(5, 20, 3)
+    with pytest.raises(ValueError, match="rows\\*cols"):
+        plot_grid(pts, rows=2, cols=2)
+
+
+def test_plot_grid_color_list_length_mismatch():
+    pts = np.random.randn(3, 20, 3)
+    with pytest.raises(ValueError, match="colors must have length"):
+        plot_grid(pts, colors=["red", "green"])
+
+
+def test_plot_grid_pads_when_grid_larger_than_b():
+    """B=3 in a 2x2 grid → 4 scenes, with the last cell padded."""
+    pts = np.random.randn(3, 20, 3)
+    fig = plot_grid(pts, rows=2, cols=2)
+    assert _scene_count(fig) == 4
+    assert len(fig.data) == 4
+
+
+def test_beautify_single_scene():
+    pts = np.random.randn(50, 3)
+    fig = beautify(plot(pts))
+    assert fig.layout.paper_bgcolor == "white"
+    assert fig.layout.scene.bgcolor == "white"
+    assert fig.layout.scene.xaxis.showticklabels is False
+    assert fig.layout.scene.yaxis.gridcolor == "lightgray"
+
+
+def test_beautify_applies_to_every_grid_scene():
+    """All scenes (not just `scene`) should get the styling."""
+    pts = np.random.randn(4, 30, 3)
+    fig = beautify(plot_grid(pts, rows=2, cols=2))
+    scene_keys = [
+        k for k in fig.layout
+        if k == "scene" or (k.startswith("scene") and k[5:].isdigit())
+    ]
+    assert len(scene_keys) == 4
+    for k in scene_keys:
+        scene = fig.layout[k]
+        assert scene.bgcolor == "white"
+        assert scene.xaxis.showticklabels is False
+        assert scene.yaxis.showticklabels is False
+        assert scene.zaxis.showticklabels is False
+
+
+def test_beautify_custom_colors():
+    fig = beautify(plot(np.random.randn(20, 3)),
+                   paper_bgcolor="black", scene_bgcolor="black")
+    assert fig.layout.paper_bgcolor == "black"
+    assert fig.layout.scene.bgcolor == "black"
+
+
+def test_beautify_returns_same_figure():
+    fig = plot(np.random.randn(20, 3))
+    assert beautify(fig) is fig

cloudglancer-0.1.6/cloudglancer/__init__.py

@@ -1,7 +0,0 @@
-"""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", "animate"]