Add various carto basemaps as options (#268)

* Add various carto basemaps as option

* rename to no labels

* fmt

* fix extensions

* fix lint

README.md

@@ -13,7 +13,7 @@
 
 A Python library for fast, interactive geospatial vector data visualization in Jupyter.
 
-By utilizing new technologies like [GeoArrow](https://github.com/geoarrow/geoarrow) and [GeoParquet](https://github.com/opengeospatial/geoparquet) in conjunction with [GPU-based map rendering](https://deck.gl/), lonboard aims to enable visualizing large geospatial datasets interactively through a simple interface.
+Building on cutting-edge technologies like [GeoArrow](https://github.com/geoarrow/geoarrow) and [GeoParquet](https://github.com/opengeospatial/geoparquet) in conjunction with [GPU-based map rendering](https://deck.gl/), lonboard aims to enable visualizing large geospatial datasets interactively through a simple interface.
 
 ![](assets/hero-image.jpg)
 

build.mjs

@@ -12,4 +12,7 @@ esbuild.build({
   define: {
     "define.amd": "false",
   },
+  // Code splitting didn't work initially because it tried to load from a local
+  // relative path ./chunk.js
+  // splitting: true,
 });

docs/api/basemap.md

@@ -0,0 +1,3 @@
+# lonboard.basemap
+
+::: lonboard.basemap.CartoBasemap

lonboard/_map.py

@@ -11,6 +11,7 @@
 from lonboard._environment import DEFAULT_HEIGHT
 from lonboard._layer import BaseLayer
 from lonboard._viewport import compute_view
+from lonboard.basemap import CartoBasemap
 
 # bundler yields lonboard/static/{index.js,styles.css}
 bundler_output_dir = Path(__file__).parent / "static"
@@ -108,6 +109,17 @@ class Map(BaseAnyWidget):
     - Default: `5`
     """
 
+    basemap_style = traitlets.Unicode(CartoBasemap.PositronNoLabels).tag(sync=True)
+    """
+    A MapLibre-compatible basemap style.
+
+    Various styles are provided in [`lonboard.basemap`][lonboard.basemap].
+
+    - Type: `str`
+    - Default
+      [`lonboard.basemap.CartoBasemap.PositronNoLabels`][lonboard.basemap.CartoBasemap.PositronNoLabels]
+    """
+
     def to_html(self, filename: Union[str, Path]) -> None:
         """Save the current map as a standalone HTML file.
 

lonboard/basemap.py

@@ -0,0 +1,43 @@
+from enum import Enum
+
+
+class CartoBasemap(str, Enum):
+    """Basemap styles provided by Carto.
+
+    Refer to [Carto
+    documentation](https://docs.carto.com/carto-for-developers/carto-for-react/guides/basemaps)
+    for information on styles.
+    """
+
+    DarkMatter = "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json"
+    """A dark map style with labels.
+
+    ![](https://carto.com/help/images/building-maps/basemaps/dark_labels.png)
+    """
+
+    DarkMatterNoLabels = (
+        "https://basemaps.cartocdn.com/gl/dark-matter-nolabels-gl-style/style.json"
+    )
+    """A dark map style without labels."""
+
+    Positron = "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json"
+    """A light map style with labels.
+
+    ![](https://carto.com/help/images/building-maps/basemaps/positron_labels.png)
+    """
+
+    PositronNoLabels = (
+        "https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json"
+    )
+    """A light map style without labels."""
+
+    Voyager = "https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json"
+    """A light, colored map style with labels.
+
+    ![](https://carto.com/help/images/building-maps/basemaps/voyager_labels.png)
+    """
+
+    VoyagerNoLabels = (
+        "https://basemaps.cartocdn.com/gl/voyager-nolabels-gl-style/style.json"
+    )
+    """A light, colored map style without labels."""

mkdocs.yml

@@ -39,6 +39,7 @@ nav:
           - api/layers/path-layer.md
           - api/layers/scatterplot-layer.md
           - api/layers/solid-polygon-layer.md
+      - api/basemap.md
       - api/colormap.md
       - api/traits.md
       - Experimental:

package.json

@@ -15,9 +15,11 @@
     "react-map-gl": "^7.1.5",
     "uuid": "^9.0.1"
   },
+  "type": "module",
   "devDependencies": {
     "@jupyter-widgets/base": "^6.0.6",
     "@types/react": "^18.2.35",
+    "@types/uuid": "^9.0.7",
     "esbuild": "^0.19.5",
     "nodemon": "^3.0.1",
     "prettier": "^3.1.0",

src/accessor.ts

@@ -1,5 +1,5 @@
 import * as arrow from "apache-arrow";
-import { parseParquetBuffers } from "./parquet";
+import { parseParquetBuffers } from "./parquet.js";
 import { useState, useEffect } from "react";
 
 export function useTableBufferState(

src/index.tsx

@@ -4,11 +4,11 @@ import { createRender, useModelState, useModel } from "@anywidget/react";
 import Map from "react-map-gl/maplibre";
 import DeckGL from "@deck.gl/react/typed";
 import type { Layer } from "@deck.gl/core/typed";
-import { BaseLayerModel, initializeLayer } from "./model";
+import { BaseLayerModel, initializeLayer } from "./model/index.js";
 import type { WidgetModel } from "@jupyter-widgets/base";
-import { useParquetWasm } from "./parquet";
-import { getTooltip } from "./tooltip";
-import { loadChildModels } from "./util";
+import { useParquetWasm } from "./parquet.js";
+import { getTooltip } from "./tooltip/index.js";
+import { loadChildModels } from "./util.js";
 import { v4 as uuidv4 } from "uuid";
 
 const DEFAULT_INITIAL_VIEW_STATE = {
@@ -19,7 +19,7 @@ const DEFAULT_INITIAL_VIEW_STATE = {
   pitch: 0,
 };
 
-const MAP_STYLE =
+const DEFAULT_MAP_STYLE =
   "https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json";
 
 async function getChildModelState(
@@ -59,6 +59,7 @@ async function getChildModelState(
 function App() {
   let [parquetWasmReady] = useParquetWasm();
   let [initialViewState] = useModelState<DataView>("_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");
@@ -139,7 +140,7 @@ function App() {
         getTooltip={showTooltip && getTooltip}
         pickingRadius={pickingRadius}
       >
-        <Map mapStyle={MAP_STYLE} />
+        <Map mapStyle={mapStyle || DEFAULT_MAP_STYLE} />
       </DeckGL>
     </div>
   );

src/model/base.ts

@@ -1,5 +1,5 @@
 import type { WidgetModel } from "@jupyter-widgets/base";
-import { parseAccessor } from "../accessor";
+import { parseAccessor } from "../accessor.js";
 
 export abstract class BaseModel {
   protected model: WidgetModel;

src/model/extension.ts

@@ -6,7 +6,7 @@ import {
   CollisionFilterExtension as _CollisionFilterExtension,
 } from "@deck.gl/extensions/typed";
 import type { WidgetModel } from "@jupyter-widgets/base";
-import { BaseModel } from "./base";
+import { BaseModel } from "./base.js";
 
 export abstract class BaseExtensionModel extends BaseModel {
   static extensionType: string;

src/model/index.ts

@@ -1,14 +1,14 @@
-export { BaseModel } from "./base";
+export { BaseModel } from "./base.js";
 export {
   BaseLayerModel,
   PathModel,
   ScatterplotModel,
   SolidPolygonModel,
   initializeLayer,
-} from "./layer";
+} from "./layer.js";
 export {
   BaseExtensionModel,
   BrushingExtension,
   CollisionFilterExtension,
   initializeExtension,
-} from "./extension";
+} from "./extension.js";

src/model/layer.ts

@@ -17,10 +17,10 @@ import {
 } from "@geoarrow/deck.gl-layers";
 import type { WidgetModel } from "@jupyter-widgets/base";
 import * as arrow from "apache-arrow";
-import { parseParquetBuffers } from "../parquet";
-import { loadChildModels } from "../util";
-import { BaseModel } from "./base";
-import { BaseExtensionModel, initializeExtension } from "./extension";
+import { parseParquetBuffers } from "../parquet.js";
+import { loadChildModels } from "../util.js";
+import { BaseModel } from "./base.js";
+import { BaseExtensionModel, initializeExtension } from "./extension.js";
 
 export abstract class BaseLayerModel extends BaseModel {
   protected table: arrow.Table;

src/tooltip/index.ts

@@ -1,5 +1,5 @@
-import { TooltipContent } from "@deck.gl/core/typed/lib/tooltip";
-import { GeoArrowPickingInfo } from "@geoarrow/deck.gl-layers/dist/types";
+import { TooltipContent } from "@deck.gl/core/typed/lib/tooltip.js";
+import type { GeoArrowPickingInfo } from "@geoarrow/deck.gl-layers";
 
 import "./index.css";
 

tsconfig.json

@@ -2,7 +2,9 @@
   "include": ["src/**/*"],
   "exclude": ["node_modules"],
   "compilerOptions": {
+    // Note: setting these two to NodeNext this breaks typing for apache-arrow
     "moduleResolution": "node",
+    // "module": "NodeNext",
     "outDir": "./dist",
     "allowJs": true,
     "target": "ES2020",