Add fly-to map action (#408)

### Change list

- Add `Map.fly_to` which "flies" map to desired view state location

Author: kylebarron

lonboard/_map.py

@@ -167,6 +167,153 @@ def __init__(
       [`lonboard.basemap.CartoBasemap.PositronNoLabels`][lonboard.basemap.CartoBasemap.PositronNoLabels]
     """
 
+    # TODO: We'd prefer a "Strict union of bool and float" but that doesn't
+    # work here because `Union[bool, float]` would coerce `1` to `True`, which we don't
+    # want, and `Union[float, bool]` would coerce `True` to `1`, which we also don't
+    # want.
+    # In the future we could create a custom trait for this if asked for.
+    use_device_pixels = traitlets.Any(allow_none=True, default_value=None).tag(
+        sync=True
+    )
+    """Controls the resolution of the drawing buffer used for rendering.
+
+    Setting this to `false` or a number <= 1 will improve performance on high resolution
+    displays.
+
+    **Note**: This parameter must be passed to the `Map()` constructor. It cannot be
+    changed once the map has been created.
+
+    The available options are:
+
+    - `true`: Device (physical) pixels resolution is used for rendering, this resolution
+      is defined by `window.devicePixelRatio`. On Retina/HD systems this resolution is
+      usually twice as big as CSS pixels resolution.
+    - `false`: CSS pixels resolution (equal to the canvas size) is used for rendering.
+    - `Number` (Experimental): Specified Number is used as a custom ratio (drawing
+      buffer resolution to CSS pixel resolution) to determine drawing buffer size, a
+      value less than one uses resolution smaller than CSS pixels, gives better
+      performance but produces blurry images, a value greater than one uses resolution
+      bigger than CSS pixels resolution (canvas size), produces sharp images but at a
+      lower performance.
+
+    - Type: `float`, `int` or `bool`
+    - Default: `true`
+    """
+
+    parameters = traitlets.Any(allow_none=True, default_value=None).tag(sync=True)
+    """GPU parameters to pass to deck.gl.
+
+    **This is an advanced API. The vast majority of users should not need to touch this
+    setting.**
+
+    !!! Note
+
+        The docstring below is copied from upstream deck.gl documentation. Any usage of
+        `GL` refers to the constants defined in [`@luma.gl/constants`
+        here](https://github.com/visgl/luma.gl/blob/master/modules/constants/src/webgl-constants.ts),
+        which comes from the [MDN docs
+        here](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Constants).
+
+        In place of any `GL` constant, you can use the underlying integer it represents.
+        For example, instead of the JS
+
+        ```
+        depthFunc: GL.LEQUAL
+        ```
+
+        referring to the [MDN
+        docs](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Constants#depth_or_stencil_tests),
+        you should use
+
+        ```
+        depthFunc: 0x0203
+        ```
+
+        Note that these parameters do not yet work with integer keys. If you would like
+        to use integer keys, open an issue.
+
+    Expects an object with GPU parameters. Before each frame is rendered, this object
+    will be passed to luma.gl's `setParameters` function to reset the GPU context
+    parameters, e.g. to disable depth testing, change blending modes etc. The default
+    parameters set by `Deck` on initialization are the following:
+
+    ```js
+    {
+      blend: true,
+      blendFunc: [GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA, GL.ONE, GL.ONE_MINUS_SRC_ALPHA],
+      polygonOffsetFill: true,
+      depthTest: true,
+      depthFunc: GL.LEQUAL
+    }
+    ```
+
+    Refer to the luma.gl
+    [setParameters](https://github.com/visgl/luma.gl/blob/8.5-release/modules/gltools/docs/api-reference/parameter-setting.md)
+    API for documentation on supported parameters and values.
+
+    ```js
+    import GL from '@luma.gl/constants';
+    new Deck({
+      // ...
+      parameters: {
+        blendFunc: [GL.ONE, GL.ONE, GL.ONE, GL.ONE],
+        depthTest: false
+      }
+    });
+    ```
+
+    Notes:
+
+    - Any GPU `parameters` prop supplied to individual layers will still override the
+      global `parameters` when that layer is rendered.
+    """
+
+    def fly_to(
+        self,
+        *,
+        longitude: Union[int, float],
+        latitude: Union[int, float],
+        zoom: int,
+        duration: int = 4000,
+        pitch: Union[int, float] = 0,
+        bearing: Union[int, float] = 0,
+        curve: Optional[Union[int, float]] = None,
+        speed: Optional[Union[int, float]] = None,
+        screen_speed: Optional[Union[int, float]] = None,
+    ):
+        """ "Fly" the map to a new location.
+
+        Args:
+            longitude: The longitude of the new viewport.
+            latitude: The latitude of the new viewport.
+            zoom: The zoom of the new viewport.
+            pitch: The pitch of the new viewport. Defaults to 0.
+            bearing: The bearing of the new viewport. Defaults to 0.
+            duration: The number of milliseconds for the viewport transition to take.
+                Defaults to 4000.
+            curve: The zooming "curve" that will occur along the flight path. Default
+                `1.414`.
+            speed: The average speed of the animation defined in relation to
+                `curve`, it linearly affects the duration, higher speed returns smaller
+                durations and vice versa. Default `1.2`.
+            screen_speed: The average speed of the animation measured in screenfuls per
+                second. Similar to speed it linearly affects the duration, when
+                specified speed is ignored.
+        """
+        data = {
+            "type": "fly-to",
+            "longitude": longitude,
+            "latitude": latitude,
+            "zoom": zoom,
+            "pitch": pitch,
+            "bearing": bearing,
+            "transitionDuration": duration,
+            "curve": curve,
+            "speed": speed,
+            "screenSpeed": screen_speed,
+        }
+        self.send(data)
+
     def to_html(
         self, filename: Union[str, Path, TextIO, IO[str]], title: Optional[str] = None
     ) -> None:

lonboard/types/map.py

@@ -15,3 +15,5 @@ class MapKwargs(TypedDict, total=False):
     show_tooltip: bool
     picking_radius: int
     basemap_style: Union[str, CartoBasemap]
+    use_device_pixels: Union[int, float, bool]
+    parameters: Dict[str, Any]

src/actions/fly-to.ts

@@ -0,0 +1,35 @@
+import { SetStateAction } from "react";
+import { FlyToMessage } from "../types";
+import { FlyToInterpolator, MapViewState } from "@deck.gl/core/typed";
+import { isDefined } from "../util";
+
+export function flyTo(
+  msg: FlyToMessage,
+  setInitialViewState: (value: SetStateAction<MapViewState>) => void,
+) {
+  const {
+    longitude,
+    latitude,
+    zoom,
+    pitch,
+    bearing,
+    transitionDuration,
+    curve,
+    speed,
+    screenSpeed,
+  } = msg;
+  const transitionInterpolator = new FlyToInterpolator({
+    ...(isDefined(curve) && { curve }),
+    ...(isDefined(speed) && { speed }),
+    ...(isDefined(screenSpeed) && { screenSpeed }),
+  });
+  setInitialViewState({
+    longitude,
+    latitude,
+    zoom,
+    pitch,
+    bearing,
+    transitionDuration,
+    transitionInterpolator,
+  });
+}

src/index.tsx

@@ -4,13 +4,15 @@ import { createRender, useModelState, useModel } from "@anywidget/react";
 import type { Initialize, Render } from "@anywidget/types";
 import Map from "react-map-gl/maplibre";
 import DeckGL from "@deck.gl/react/typed";
-import type { Layer } from "@deck.gl/core/typed";
+import { MapViewState, type Layer } from "@deck.gl/core/typed";
 import { BaseLayerModel, initializeLayer } from "./model/index.js";
 import type { WidgetModel } from "@jupyter-widgets/base";
 import { initParquetWasm } from "./parquet.js";
 import { getTooltip } from "./tooltip/index.js";
-import { loadChildModels } from "./util.js";
+import { isDefined, loadChildModels } from "./util.js";
 import { v4 as uuidv4 } from "uuid";
+import { Message } from "./types.js";
+import { flyTo } from "./actions/fly-to.js";
 
 await initParquetWasm();
 
@@ -60,17 +62,40 @@ async function getChildModelState(
 }
 
 function App() {
-  let [initialViewState] = useModelState<DataView>("_initial_view_state");
+  let model = useModel();
+
+  let [pythonInitialViewState] = useModelState<MapViewState>(
+    "_initial_view_state",
+  );
   let [mapStyle] = useModelState<string>("basemap_style");
   let [mapHeight] = useModelState<number>("_height");
   let [showTooltip] = useModelState<boolean>("show_tooltip");
   let [pickingRadius] = useModelState<number>("picking_radius");
+  let [useDevicePixels] = useModelState<number | boolean>("use_device_pixels");
+  let [parameters] = useModelState<object>("parameters");
+
+  let [initialViewState, setInitialViewState] = useState(
+    pythonInitialViewState,
+  );
+
+  // Handle custom messages
+  model.on("msg:custom", (msg: Message, buffers) => {
+    switch (msg.type) {
+      case "fly-to":
+        flyTo(msg, setInitialViewState);
+        break;
+
+      default:
+        break;
+    }
+  });
+
   const [mapId] = useState(uuidv4());
 
   let [subModelState, setSubModelState] = useState<
     Record<string, BaseLayerModel>
   >({});
-  let model = useModel();
+
   let [childLayerIds] = useModelState<string[]>("layers");
 
   // Fake state just to get react to re-render when a model callback is called
@@ -134,6 +159,13 @@ function App() {
         // @ts-expect-error
         getTooltip={showTooltip && getTooltip}
         pickingRadius={pickingRadius}
+        useDevicePixels={isDefined(useDevicePixels) ? useDevicePixels : true}
+        // https://deck.gl/docs/api-reference/core/deck#_typedarraymanagerprops
+        _typedArrayManagerProps={{
+          overAlloc: 1,
+          poolSize: 0,
+        }}
+        parameters={parameters || {}}
       >
         <Map mapStyle={mapStyle || DEFAULT_MAP_STYLE} />
       </DeckGL>

src/types.ts

@@ -0,0 +1,14 @@
+export type FlyToMessage = {
+  type: "fly-to";
+  longitude: number;
+  latitude: number;
+  zoom: number;
+  pitch?: number | undefined;
+  bearing?: number | undefined;
+  transitionDuration?: number | "auto" | undefined;
+  curve?: number | undefined;
+  speed?: number | undefined;
+  screenSpeed?: number | undefined;
+};
+
+export type Message = FlyToMessage;