Merge pull request #183 from CU-ESIIL/codex/update-default-camera-settings-in-v.plot

Default front-right, zoomed-out camera for v.plot with override and tests

Author: ttuff

docs/viz/cube_viewer.md

@@ -44,6 +44,19 @@ pipe(ndvi) | v.plot()
 - The viewer renders into a canvas inside the notebook output. The same HTML
   can be opened standalone for debugging.
 
+## Customizing the view
+
+Pass a Plotly-style camera dict to `v.plot()` to set the initial view. This is
+useful for forcing a front-right swing or zooming out when sharing links.
+
+```python
+from cubedynamics import pipe, verbs as v
+
+plot = pipe(ndvi) | v.plot(
+    camera=dict(eye=dict(x=2.0, y=1.5, z=1.2)),
+)
+```
+
 ## Saving and opening as HTML
 
 Use the returned `CubePlot` to save a standalone HTML file for easier

src/cubedynamics/__init__.py

@@ -107,6 +107,7 @@ def plot(
     time_dim: str | None = "time",
     cmap: str = "viridis",
     clim: tuple[float, float] | None = None,
+    camera: dict | None = None,
     **kwargs,
 ):
     """Plot a cube without explicitly building a pipe chain.
@@ -123,6 +124,8 @@ def plot(
     clim : tuple of float, optional
         Value limits passed through to the plotting verb for consistent color
         scaling.
+    camera : dict, optional
+        Plotly-style camera configuration for the initial cube view.
     **kwargs : Any
         Forwarded to :func:`cubedynamics.verbs.plot.plot` for advanced layout
         control.
@@ -159,6 +162,7 @@ def plot(
         time_dim=time_dim,
         cmap=cmap,
         clim=clim,
+        camera=camera,
         **kwargs,
     )
 

src/cubedynamics/plotting/cube_plot.py

@@ -16,6 +16,7 @@
 
 import logging
 import html
+import math
 import os
 import string
 
@@ -258,6 +259,53 @@ class CoordCube:
     time_format: str = "%Y-%m-%d"
 
 
+DEFAULT_CAMERA: Dict[str, Dict[str, float]] = {
+    "eye": {"x": 1.8, "y": 1.35, "z": 1.15},
+    "up": {"x": 0.0, "y": 0.0, "z": 1.0},
+    "center": {"x": 0.0, "y": 0.0, "z": 0.0},
+}
+_PLOTLY_DEFAULT_EYE = {"x": 1.25, "y": 1.25, "z": 1.25}
+
+
+def resolve_camera(camera: Optional[Dict[str, Any]]) -> Dict[str, Dict[str, float]]:
+    merged = {
+        "eye": dict(DEFAULT_CAMERA["eye"]),
+        "up": dict(DEFAULT_CAMERA["up"]),
+        "center": dict(DEFAULT_CAMERA["center"]),
+    }
+    if not camera:
+        return merged
+    for key in ("eye", "up", "center"):
+        values = camera.get(key)
+        if isinstance(values, dict):
+            for axis in ("x", "y", "z"):
+                if axis in values:
+                    merged[key][axis] = float(values[axis])
+    return merged
+
+
+def plotly_camera_to_coord(camera: Optional[Dict[str, Any]]) -> CoordCube:
+    resolved = resolve_camera(camera)
+    eye = resolved["eye"]
+    x = float(eye.get("x", 0.0))
+    y = float(eye.get("y", 0.0))
+    z = float(eye.get("z", 0.0))
+
+    azim = math.degrees(math.atan2(y, x)) if (x or y) else 0.0
+    horiz = math.hypot(x, y)
+    elev = math.degrees(math.atan2(z, horiz)) if (horiz or z) else 0.0
+
+    ref = math.sqrt(
+        _PLOTLY_DEFAULT_EYE["x"] ** 2
+        + _PLOTLY_DEFAULT_EYE["y"] ** 2
+        + _PLOTLY_DEFAULT_EYE["z"] ** 2
+    )
+    mag = math.sqrt(x**2 + y**2 + z**2) or ref
+    zoom = mag / ref if ref else 1.0
+
+    return CoordCube(elev=elev, azim=azim, zoom=zoom)
+
+
 @dataclass
 class CubeAnnotation:
     """Simple annotation container for planes/text anchored to cube axes."""
@@ -453,6 +501,7 @@ class CubePlot(metaclass=_CubePlotMeta):
     show_progress: bool = True
     progress_style: str = "bar"
     coord: CoordCube = field(default_factory=CoordCube)
+    camera: Optional[Dict[str, Any]] = None
     annotations: List[CubeAnnotation] = field(default_factory=list)
     out_html: str = "cube_da.html"
     facet: Optional[CubeFacet] = None
@@ -486,6 +535,8 @@ def __post_init__(self) -> None:
             self.alpha_scale = ScaleAlphaContinuous()
         if self.caption is None and self.fig_title is not None:
             self.caption = {"title": self.fig_title}
+        if self.camera is not None:
+            self.coord = plotly_camera_to_coord(self.camera)
         if isinstance(self.data, xr.DataArray):
             self.axis_meta = self.axis_meta or self._build_axis_meta(self.data)
 

src/cubedynamics/verbs/plot.py

@@ -19,7 +19,13 @@
 
 import xarray as xr
 
-from cubedynamics.plotting.cube_plot import CubePlot, ScaleFillContinuous
+from cubedynamics.plotting.cube_plot import (
+    DEFAULT_CAMERA,
+    CubePlot,
+    ScaleFillContinuous,
+    plotly_camera_to_coord,
+    resolve_camera,
+)
 from cubedynamics.streaming import VirtualCube
 from cubedynamics.utils import _infer_time_y_x_dims
 from ..piping import Verb
@@ -39,6 +45,7 @@ class PlotOptions:
     thin_time_factor: int = 4
     time_dim: str | None = None
     clim: tuple[float, float] | None = None
+    camera: dict | None = None
     fig_id: int | None = None
     fig_title: str | None = None
     fig_text: str | None = None
@@ -54,6 +61,7 @@ def plot(
     thin_time_factor: int = 4,
     time_dim: str | None = None,
     clim: tuple[float, float] | None = None,
+    camera: dict | None = None,
     fig_id: int | None = None,
     fig_title: str | None = None,
     fig_text: str | None = None,
@@ -70,6 +78,7 @@ def plot(
     thin_time_factor: int = 4,
     time_dim: str | None = None,
     clim: tuple[float, float] | None = None,
+    camera: dict | None = None,
     fig_id: int | None = None,
     fig_title: str | None = None,
     fig_text: str | None = None,
@@ -86,6 +95,7 @@ def plot(
     thin_time_factor: int = 4,
     time_dim: str | None = None,
     clim: tuple[float, float] | None = None,
+    camera: dict | None = None,
     fig_id: int | None = None,
     fig_title: str | None = None,
     fig_text: str | None = None,
@@ -116,6 +126,9 @@ def plot(
         Name of the temporal dimension. Inferred when not provided.
     clim : tuple of float, optional
         Color limits for the continuous scale.
+    camera : dict, optional
+        Plotly-style camera configuration used to set the initial cube view.
+        When omitted, a front-right, zoomed-out default is applied.
     fig_id, fig_title, fig_text : optional
         Caption metadata used by the viewer export helpers.
 
@@ -158,6 +171,7 @@ def plot(
         thin_time_factor=thin_time_factor,
         time_dim=time_dim,
         clim=clim,
+        camera=camera,
         fig_id=fig_id,
         fig_title=fig_title,
         fig_text=fig_text,
@@ -183,6 +197,9 @@ def _plot(value: xr.DataArray | VirtualCube):
         if opts.fig_id is not None or opts.fig_title is not None or opts.fig_text is not None:
             caption_payload = {"id": opts.fig_id, "title": opts.fig_title, "text": opts.fig_text}
 
+        camera_to_use = resolve_camera(opts.camera or DEFAULT_CAMERA)
+        coord = plotly_camera_to_coord(camera_to_use)
+
         # 1. Build CubePlot for this cube
         cube = CubePlot(
             da_value,
@@ -194,6 +211,8 @@ def _plot(value: xr.DataArray | VirtualCube):
             time_dim=resolved_time,
             fill_scale=ScaleFillContinuous(cmap=opts.cmap, limits=opts.clim),
             fig_title=opts.fig_title,
+            coord=coord,
+            camera=camera_to_use,
         )
 
         # 2. Draw cube

tests/test_plot_verb.py

@@ -4,6 +4,7 @@
 from cubedynamics import verbs as v
 from cubedynamics.piping import pipe
 from cubedynamics.plotting import CubePlot
+from cubedynamics.plotting.cube_plot import DEFAULT_CAMERA
 
 
 def _make_tiny_cube():
@@ -30,3 +31,17 @@ def test_plot_does_not_materialize_dask():
     result = (pipe(cube) | v.plot()).unwrap()
     assert isinstance(result, CubePlot)
     assert cube.data.__class__.__name__.lower().startswith("array")
+
+
+def test_plot_default_camera():
+    cube = _make_tiny_cube()
+    result = (pipe(cube) | v.plot()).unwrap()
+    assert result.camera == DEFAULT_CAMERA
+    assert result.camera["eye"]["x"] > 0
+
+
+def test_plot_camera_override():
+    cube = _make_tiny_cube()
+    custom_camera = {"eye": {"x": 2.0, "y": 1.5, "z": 1.2}}
+    result = (pipe(cube) | v.plot(camera=custom_camera)).unwrap()
+    assert result.camera["eye"] == custom_camera["eye"]