feat: Support globe view (#908)

### Change list

- Ensure that the default value of `Map.basemap` is `MaplibreBasemap` if
no value of `basemap` was passed. Add a test for this.
- Define various View classes to map to deck.gl views.
- Define View models on the TS side.
- When a GlobeView is passed, pass `projection="globe"` to Maplibre
- Render a dark background on the canvas when in globe view 
- Add `views` parameter to `Map`. For now this only supports a single
view instance, but hopefully in the future it'll support more.

This PR also sets the stage for non-geospatial map rendering and for
multi-view support.

### todo:

- [ ] Should we name the Map attribute `view` instead of `views`?
Hopefully soon we'll support multi-views, though maybe not with a
maplibre basemap. (#965 )
- [ ] View state validation
(#948)
- [ ] add something like `projection="globe"` to `viz`
(#949)


With this PR, to generate a map with globe view, someone would call

```py
from lonboard import Map
from lonboard.view import GlobeView
from lonboard.basemap import MaplibreBasemap

lonboard.Map(
	layer,
	views=GlobeView(),
	basemap=MaplibreBasemap(mode="interleaved"),
)
```

## Globe view:

<img width="787" height="685" alt="image"
src="https://github.com/user-attachments/assets/7a22fafd-d48c-4cc3-b5f0-8d4393dcb035"
/>

Closes #886 (globe
view), closes #375
(orthographic view) (though might need more work to allow non-spatial
data)

Relates to 

- #905 (multi-views), 
- #718 (multi-view), 
- #658 (repeating map
view),
- #637 (multiple
linked plots),
- #494 (basemap
refactor),
- #404 (swipe between
two maps),
- #375 (orthographic
view)

Author: kylebarron

eslint.config.js

@@ -1,9 +1,9 @@
-import globals from "globals";
 import pluginJs from "@eslint/js";
-import tseslint from "typescript-eslint";
-import pluginReact from "eslint-plugin-react";
 import eslintConfigPrettier from "eslint-config-prettier";
 import pluginImport from "eslint-plugin-import";
+import pluginReact from "eslint-plugin-react";
+import globals from "globals";
+import tseslint from "typescript-eslint";
 
 export default [
   { files: ["**/*.{js,mjs,cjs,ts,jsx,tsx}"] },

lonboard/_map.py

@@ -20,6 +20,7 @@
     VariableLengthTuple,
     ViewStateTrait,
 )
+from lonboard.view import BaseView
 
 if TYPE_CHECKING:
     import sys
@@ -151,6 +152,8 @@ def on_click(self, callback: Callable, *, remove: bool = False) -> None:
     _esm = bundler_output_dir / "index.js"
     _css = bundler_output_dir / "index.css"
 
+    # TODO: change this view state to allow non-map view states if we have non-map views
+    # Also allow a list/tuple of view states for multiple views
     view_state = ViewStateTrait()
     """
     The view state of the map.
@@ -174,6 +177,7 @@ def on_click(self, callback: Callable, *, remove: bool = False) -> None:
         once it's been initially rendered.
 
     """
+
     _has_click_handlers = t.Bool(default_value=False, allow_none=False).tag(sync=True)
     """
     Indicates if a click handler has been registered.
@@ -192,6 +196,15 @@ def on_click(self, callback: Callable, *, remove: bool = False) -> None:
     """One or more `Layer` objects to display on this map.
     """
 
+    views: t.Instance[BaseView | None] = t.Instance(BaseView, allow_none=True).tag(
+        sync=True,
+        **ipywidgets.widget_serialization,
+    )
+    """A View instance.
+
+    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.
+    """
+
     show_tooltip = t.Bool(default_value=False).tag(sync=True)
     """
     Whether to render a tooltip on hover on the map.

lonboard/traits.py

@@ -47,6 +47,7 @@
     from traitlets.utils.sentinel import Sentinel
 
     from lonboard._layer import BaseArrowLayer
+    from lonboard._map import Map
 
 DEFAULT_INITIAL_VIEW_STATE = {
     "latitude": 10,
@@ -943,7 +944,7 @@ def __init__(
 
         self.tag(sync=True, to_json=serialize_view_state)
 
-    def validate(self, obj: Any, value: Any) -> None | ViewState:
+    def validate(self, obj: Map, value: Any) -> None | ViewState:
         if value is None:
             return None
 

lonboard/types/map.py

@@ -10,6 +10,7 @@
 
 if TYPE_CHECKING:
     from lonboard.basemap import MaplibreBasemap
+    from lonboard.view import BaseView
 
 
 class MapKwargs(TypedDict, total=False):
@@ -22,4 +23,5 @@ class MapKwargs(TypedDict, total=False):
     show_tooltip: bool
     show_side_panel: bool
     use_device_pixels: int | float | bool
+    views: BaseView | list[BaseView] | tuple[BaseView, ...]
     view_state: dict[str, Any]

lonboard/view.py

@@ -0,0 +1,253 @@
+import traitlets as t
+
+from lonboard._base import BaseWidget
+
+
+class BaseView(BaseWidget):
+    """A deck.gl View.
+
+    The `View` class and its subclasses are used to specify where and how your deck.gl layers should be rendered. Applications typically instantiate at least one `View` subclass.
+
+    """
+
+    x = t.Union([t.Int(), t.Unicode()], allow_none=True, default_value=None).tag(
+        sync=True,
+    )
+    """The x position of the view.
+
+    A relative (e.g. `'50%'`) or absolute position. Default `0`.
+    """
+
+    y = t.Union([t.Int(), t.Unicode()], allow_none=True, default_value=None).tag(
+        sync=True,
+    )
+    """The y position of the view.
+
+    A relative (e.g. `'50%'`) or absolute position. Default `0`.
+    """
+
+    width = t.Union([t.Int(), t.Unicode()], allow_none=True, default_value=None).tag(
+        sync=True,
+    )
+    """The width of the view.
+
+    A relative (e.g. `'50%'`) or absolute extent. Default `'100%'`.
+    """
+
+    height = t.Union([t.Int(), t.Unicode()], allow_none=True, default_value=None).tag(
+        sync=True,
+    )
+    """The height of the view.
+
+    A relative (e.g. `'50%'`) or absolute extent. Default `'100%'`.
+    """
+
+
+class FirstPersonView(BaseView):
+    """A deck.gl FirstPersonView.
+
+    The `FirstPersonView` class is a subclass of `View` that describes a camera placed at a provided location, looking towards the direction and orientation specified by viewState. The behavior is similar to that of a first-person game.
+    """
+
+    _view_type = t.Unicode("first-person-view").tag(sync=True)
+
+    projection_matrix = t.List(
+        t.Float(),
+        allow_none=True,
+        default_value=None,
+        minlen=16,
+        maxlen=16,
+    ).tag(
+        sync=True,
+    )
+    """Projection matrix.
+
+    If `projectionMatrix` is not supplied, the `View` class will build a projection matrix from the following parameters:
+    """
+
+    fovy = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Field of view covered by camera, in the perspective case. In degrees.
+
+    Default `50`.
+    """
+
+    near = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Distance of near clipping plane.
+
+    Default `0.1`.
+    """
+
+    far = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Distance of far clipping plane.
+
+    Default `1000`.
+    """
+
+    focal_distance = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Modifier of viewport scale.
+
+    Corresponds to the number of pixels per meter. Default `1`.
+    """
+
+
+class GlobeView(BaseView):
+    """A deck.gl GlobeView.
+
+    The `GlobeView` class is a subclass of `View`. This view projects the earth into a 3D globe.
+    """
+
+    _view_type = t.Unicode("globe-view").tag(sync=True)
+
+    resolution = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """The resolution at which to turn flat features into 3D meshes, in degrees.
+
+    Smaller numbers will generate more detailed mesh. Default `10`.
+    """
+
+    near_z_multiplier = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Scaler for the near plane, 1 unit equals to the height of the viewport.
+
+    Default to `0.1`. Overwrites the `near` parameter.
+    """
+
+    far_z_multiplier = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Scaler for the far plane, 1 unit equals to the distance from the camera to the top edge of the screen.
+
+    Default to `2`. Overwrites the `far` parameter.
+    """
+
+
+class MapView(BaseView):
+    """A deck.gl MapView.
+
+    The `MapView` class is a subclass of `View`. This viewport creates a camera that looks at a geospatial location on a map from a certain direction. The behavior of `MapView` is generally modeled after that of Mapbox GL JS.
+    """
+
+    _view_type = t.Unicode("map-view").tag(sync=True)
+
+    repeat = t.Bool(allow_none=True, default_value=None).tag(sync=True)
+    """
+    Whether to render multiple copies of the map at low zoom levels. Default `false`.
+    """
+
+    near_z_multiplier = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Scaler for the near plane, 1 unit equals to the height of the viewport.
+
+    Default to `0.1`. Overwrites the `near` parameter.
+    """
+
+    far_z_multiplier = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Scaler for the far plane, 1 unit equals to the distance from the camera to the top edge of the screen.
+
+    Default to `1.01`. Overwrites the `far` parameter.
+    """
+
+    projection_matrix = t.List(
+        t.Float(),
+        allow_none=True,
+        default_value=None,
+        minlen=16,
+        maxlen=16,
+    ).tag(
+        sync=True,
+    )
+    """Projection matrix.
+
+    If `projectionMatrix` is not supplied, the `View` class will build a projection matrix from the following parameters:
+    """
+
+    fovy = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Field of view covered by camera, in the perspective case. In degrees.
+
+    If not supplied, will be calculated from `altitude`.
+    """
+
+    altitude = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Distance of the camera relative to viewport height.
+
+    Default `1.5`.
+    """
+
+    orthographic = t.Bool(allow_none=True, default_value=None).tag(sync=True)
+    """Whether to create an orthographic or perspective projection matrix.
+
+    Default is `false` (perspective projection).
+    """
+
+
+class OrbitView(BaseView):
+    """A deck.gl OrbitView.
+
+    The `OrbitView` class is a subclass of `View` that creates a 3D camera that rotates around a target position. It is usually used for the examination of a 3D scene in non-geospatial use cases.
+    """
+
+    _view_type = t.Unicode("orbit-view").tag(sync=True)
+
+    orbit_axis = t.Unicode(allow_none=True, default_value=None).tag(sync=True)
+    """Axis with 360 degrees rotating freedom, either `'Y'` or `'Z'`, default to `'Z'`."""
+
+    projection_matrix = t.List(
+        t.Float(),
+        allow_none=True,
+        default_value=None,
+        minlen=16,
+        maxlen=16,
+    ).tag(
+        sync=True,
+    )
+    """Projection matrix.
+
+    If `projectionMatrix` is not supplied, the `View` class will build a projection matrix from the following parameters:
+    """
+
+    fovy = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Field of view covered by camera, in the perspective case. In degrees.
+
+    Default `50`.
+    """
+
+    near = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Distance of near clipping plane.
+
+    Default `0.1`.
+    """
+
+    far = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Distance of far clipping plane.
+
+    Default `1000`.
+    """
+
+    orthographic = t.Bool(allow_none=True, default_value=None).tag(sync=True)
+    """Whether to create an orthographic or perspective projection matrix.
+
+    Default is `false` (perspective projection).
+    """
+
+
+class OrthographicView(BaseView):
+    """A deck.gl OrthographicView.
+
+    The `OrthographicView` class is a subclass of `View` that creates a top-down view of the XY plane. It is usually used for rendering 2D charts in non-geospatial use cases.
+    """
+
+    _view_type = t.Unicode("orthographic-view").tag(sync=True)
+
+    flip_y = t.Bool(allow_none=True, default_value=None).tag(sync=True)
+    """
+    Whether to use top-left coordinates (`true`) or bottom-left coordinates (`false`).
+
+    Default `true`.
+    """
+
+    near = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Distance of near clipping plane.
+
+    Default `0.1`.
+    """
+
+    far = t.Float(allow_none=True, default_value=None).tag(sync=True)
+    """Distance of far clipping plane.
+
+    Default `1000`.
+    """