chore: Make GlobeView experimental (#1038)

There are just too many upstream bugs with `GlobeView` to call it
stable, such as #1037.

For now we'll cut the release with globe view as experimental.

Author: kylebarron

docs/api/controls.md

@@ -1,8 +1,3 @@
 # lonboard.controls
 
-::: lonboard.controls.BaseControl
-::: lonboard.controls.FullscreenControl
-::: lonboard.controls.NavigationControl
-::: lonboard.controls.ScaleControl
-
-::: lonboard.controls.MultiRangeSlider
+::: lonboard.controls

docs/api/view.md

@@ -1,5 +1,5 @@
-# lonboard.view
+# lonboard.experimental.view
 
-::: lonboard.view
+::: lonboard.experimental.view
     options:
         members_order: source

lonboard/_map.py

@@ -19,9 +19,9 @@
     NavigationControl,
     ScaleControl,
 )
+from lonboard.experimental.view import BaseView, GlobeView, MapView
 from lonboard.layer import BaseLayer
 from lonboard.traits import MapHeightTrait, VariableLengthTuple, ViewStateTrait
-from lonboard.view import BaseView, GlobeView, MapView
 from lonboard.view_state import BaseViewState, GlobeViewState, MapViewState
 
 if TYPE_CHECKING:
@@ -73,17 +73,6 @@ class Map(BaseAnyWidget):
 
     m = Map([point_layer, polygon_layer])
     ```
-
-    **Example:** Creating a Map with GlobeView:
-
-    ```py
-    import geopandas as gpd
-    from lonboard import Map
-    from lonboard.view import GlobeView
-
-    # Continuing from above example
-    m = Map([point_layer, polygon_layer], view=GlobeView())
-    ```
     """
 
     def __init__(
@@ -229,7 +218,10 @@ def on_click(self, callback: Callable, *, remove: bool = False) -> None:
         sync=True,
         **ipywidgets.widget_serialization,
     )
-    """One or more map controls to display on this map."""
+    """One or more map controls to display on this map.
+
+    See [`lonboard.controls`][] for available controls.
+    """
 
     view: t.Instance[BaseView | None] = t.Instance(BaseView, allow_none=True).tag(
         sync=True,
@@ -239,7 +231,7 @@ def on_click(self, callback: Callable, *, remove: bool = False) -> None:
 
     Views represent the "camera(s)" (essentially viewport dimensions and projection matrices) that you look at your data with. deck.gl offers multiple view types for both geospatial and non-geospatial use cases. Read the [Views and Projections](https://deck.gl/docs/developer-guide/views) guide for the concept and examples.
 
-    See [`lonboard.view`][lonboard.view] for available view types.
+    See [`lonboard.experimental.view`][] for available view types.
     """
 
     @t.validate("view")

lonboard/_viz.py

@@ -6,7 +6,7 @@
 
 import json
 from textwrap import dedent
-from typing import TYPE_CHECKING, Any, Literal, Protocol, TypeAlias, cast
+from typing import TYPE_CHECKING, Any, Protocol, TypeAlias, cast
 
 import numpy as np
 from arro3.core import Array, ChunkedArray, Schema, Table, struct_field
@@ -26,7 +26,6 @@
 )
 from lonboard.basemap import CartoStyle, MaplibreBasemap
 from lonboard.layer import PathLayer, PolygonLayer, ScatterplotLayer
-from lonboard.view import BaseView, GlobeView
 
 if TYPE_CHECKING:
     import duckdb
@@ -82,14 +81,13 @@ def __geo_interface__(self) -> dict: ...
 DEFAULT_POLYGON_LINE_COLOR = [0, 0, 0, 200]
 
 
-def viz(  # noqa: PLR0913
+def viz(
     data: VizDataInput | list[VizDataInput] | tuple[VizDataInput, ...],
     *,
     scatterplot_kwargs: ScatterplotLayerKwargs | None = None,
     path_kwargs: PathLayerKwargs | None = None,
     polygon_kwargs: PolygonLayerKwargs | None = None,
     map_kwargs: MapKwargs | None = None,
-    view: BaseView | Literal["globe"] | None = None,
 ) -> Map:
     """Plot your data easily.
 
@@ -168,7 +166,6 @@ def viz(  # noqa: PLR0913
             [`PolygonLayer`][lonboard.PolygonLayer]s.
         map_kwargs: a `dict` of parameters to pass down to the generated
             [`Map`][lonboard.Map].
-        view: a [view instance][lonboard.view.BaseView] to use for the map view, or the string "globe".
 
     For more control over rendering, construct [`Map`][lonboard.Map] and `Layer` objects
     directly.
@@ -204,12 +201,6 @@ def viz(  # noqa: PLR0913
 
     map_kwargs = map_kwargs if map_kwargs else {}
 
-    if "view" not in map_kwargs and view is not None:
-        if view == "globe":
-            map_kwargs["view"] = GlobeView()
-        else:
-            map_kwargs["view"] = view
-
     if "basemap_style" not in map_kwargs and "basemap" not in map_kwargs:
         map_kwargs["basemap"] = MaplibreBasemap(
             mode="interleaved",

lonboard/view.py lonboard/experimental/view.pylonboard/view.py renamed to lonboard/experimental/view.py

@@ -9,7 +9,7 @@ class BaseViewState:
 
 @dataclass(frozen=True)
 class MapViewState(BaseViewState):
-    """State of a [MapView][lonboard.view.MapView]."""
+    """State of a [MapView][lonboard.experimental.view.MapView]."""
 
     longitude: float = 0
     """longitude at the map center"""
@@ -41,7 +41,7 @@ class MapViewState(BaseViewState):
 
 @dataclass(frozen=True)
 class GlobeViewState(BaseViewState):
-    """State of a [GlobeView][lonboard.view.GlobeView]."""
+    """State of a [GlobeView][lonboard.experimental.view.GlobeView]."""
 
     longitude: float
     """longitude at the viewport center."""
@@ -61,7 +61,7 @@ class GlobeViewState(BaseViewState):
 
 @dataclass(frozen=True)
 class FirstPersonViewState(BaseViewState):
-    """State of a [FirstPersonView][lonboard.view.FirstPersonView]."""
+    """State of a [FirstPersonView][lonboard.experimental.view.FirstPersonView]."""
 
     longitude: float
     """longitude of the camera position."""
@@ -87,7 +87,7 @@ class FirstPersonViewState(BaseViewState):
 
 @dataclass(frozen=True)
 class OrthographicViewState(BaseViewState):
-    """State of an [OrthographicView][lonboard.view.OrthographicView]."""
+    """State of an [OrthographicView][lonboard.experimental.view.OrthographicView]."""
 
     target: tuple[float, float, float] = (0.0, 0.0, 0.0)
     """The world position at the center of the viewport."""
@@ -111,7 +111,7 @@ class OrthographicViewState(BaseViewState):
 
 @dataclass(frozen=True)
 class OrbitViewState(BaseViewState):
-    """State of an [OrbitView][lonboard.view.OrbitView]."""
+    """State of an [OrbitView][lonboard.experimental.view.OrbitView]."""
 
     target: tuple[float, float, float] = (0.0, 0.0, 0.0)
     """The world position at the center of the viewport."""

lonboard/view_state.py

@@ -87,9 +87,9 @@ nav:
       - api/colormap.md
       - api/controls.md
       - api/traits.md
-      - api/view.md
       - api/view_state.md
       - Experimental:
+          - api/view.md
           - Layers:
               - api/layers/text-layer.md
   - cli.md

mkdocs.yml

@@ -5,7 +5,7 @@
 
 from lonboard import Map, ScatterplotLayer, SolidPolygonLayer, viz
 from lonboard.basemap import MaplibreBasemap
-from lonboard.view import FirstPersonView, GlobeView, OrthographicView
+from lonboard.experimental.view import FirstPersonView, GlobeView, OrthographicView
 from lonboard.view_state import (
     FirstPersonViewState,
     GlobeViewState,