feat: Table of contents

examples/layer_control.ipynb

@@ -0,0 +1,240 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "a033bf32-69c9-48bc-a275-8ce1a3901365",
+   "metadata": {},
+   "source": [
+    "## Layer Control\n",
+    "\n",
+    "This notebook demonstrates the use of the lonbord map's `layer_control`, to control layer visibility and layer properties."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bb983a26-ab11-4070-91bd-c78371ca6d68",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "\n",
+    "import geopandas as gpd\n",
+    "from palettable.colorbrewer.sequential import Blues_8\n",
+    "\n",
+    "from lonboard import Map, PathLayer, PolygonLayer\n",
+    "from lonboard.colormap import apply_continuous_cmap"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3dcbf11b-6c10-46bc-a6de-1d1d37f4e8b6",
+   "metadata": {},
+   "source": [
+    "### Get data\n",
+    "\n",
+    "Download data from the web and save as geoparquet so we can show some data on our Lonboard map and create a layer control."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "56896a28-4d72-426e-9ea0-2e3854e389f8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "file_urls = [\n",
+    "    (\n",
+    "        \"ne_10m_roads_north_america.parquet\",\n",
+    "        \"https://naciscdn.org/naturalearth/10m/cultural/ne_10m_roads_north_america.zip\",\n",
+    "    ),\n",
+    "    (\n",
+    "        \"geoBoundariesCGAZ_ADM1.parquet\",\n",
+    "        \"https://github.com/wmgeolab/geoBoundaries/raw/main/releaseData/CGAZ/geoBoundariesCGAZ_ADM1.geojson\",\n",
+    "    ),\n",
+    "    (\n",
+    "        \"rivers_asia_37331.parquet\",\n",
+    "        \"https://storage.googleapis.com/fao-maps-catalog-data/geonetwork/aquamaps/rivers_asia_37331.zip\",\n",
+    "    ),\n",
+    "]\n",
+    "for filename, url in file_urls:\n",
+    "    if Path(filename).exists() is False:\n",
+    "        print(f\"Reading {filename} from web and saving as geoparquet.\")\n",
+    "        gdf = gpd.read_file(url, engine=\"pyogrio\")\n",
+    "        gdf.to_parquet(filename)\n",
+    "        del gdf\n",
+    "    else:\n",
+    "        print(f\"{filename} already downloaded.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "00e57959-6b12-4dc7-8621-6f725d928b96",
+   "metadata": {},
+   "source": [
+    "### Read geoparquet files into geopandas dataframes"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "230e851e-8bb9-4697-9143-688537c746a0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "boundary_df = gpd.read_parquet(\"geoBoundariesCGAZ_ADM1.parquet\")\n",
+    "boundary_df = boundary_df.loc[\n",
+    "    (boundary_df[\"shapeGroup\"] == \"USA\")\n",
+    "    & (~boundary_df[\"shapeName\"].isin([\"Alaska\", \"Hawaii\"]))\n",
+    "]  # parse data down to lower 48 of USA\n",
+    "\n",
+    "road_df = gpd.read_parquet(\"ne_10m_roads_north_america.parquet\")\n",
+    "road_df = road_df.loc[\n",
+    "    road_df[\"class\"] == \"Interstate\"\n",
+    "]  # parse data down to just interstates\n",
+    "\n",
+    "river_df = gpd.read_parquet(\"rivers_asia_37331.parquet\")\n",
+    "river_df = river_df.loc[river_df[\"MAJ_NAME\"] == \"Amur\"]  # parse data down to just Amur"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f98bf950-2f66-47eb-8e3a-8123aa2083d5",
+   "metadata": {},
+   "source": [
+    "### Create layers\n",
+    "\n",
+    "* Create a `PolygonLayer` from the boundary dataframe that is brown with a darker brown outline, that's 1 pixel wide.\n",
+    "\n",
+    "* Create a `PathLayer` from the road dataframe with a title and minimum width.\n",
+    "\n",
+    "* Create a `PathLayer` from the river dataframe that uses the 'Strahler' column for setting the color and width of the lines, as well as some defaults on the width to make the more prominent rivers darker and wider on the map."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e3366f15-245f-4a8f-b87d-dcb7fd993392",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "boundary_layer = PolygonLayer.from_geopandas(\n",
+    "    boundary_df,\n",
+    "    title=\"Boundaries\",\n",
+    "    get_fill_color=[137, 81, 41],\n",
+    "    get_line_color=[102, 60, 31],\n",
+    "    get_line_width=1,\n",
+    "    line_width_units=\"pixels\",\n",
+    "    stroked=True,\n",
+    ")\n",
+    "\n",
+    "road_layer = PathLayer.from_geopandas(road_df, width_min_pixels=0.8)\n",
+    "\n",
+    "river_layer = PathLayer.from_geopandas(\n",
+    "    river_df,\n",
+    "    title=\"Rivers\",\n",
+    "    get_color=apply_continuous_cmap(river_df[\"Strahler\"] / 7, Blues_8),\n",
+    "    get_width=river_df[\"Strahler\"],\n",
+    "    width_scale=3000,\n",
+    "    width_min_pixels=0.5,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9cdd3071-2dd6-4b77-b42d-7def62e3087d",
+   "metadata": {},
+   "source": [
+    "### Create the Lonboard `Map` and `layer_control`\n",
+    "\n",
+    "Create a lonboard map, and then create a `layer_control` with the `include_settings` parameter to True then display them both.\n",
+    "\n",
+    "With `include_settings=True` we will get a layer control that includes the setttings cog, which when expanded will allow us to change some of the layer properties. Note that we did not give this layer a title, so when we make the layer control, the default title will show in the layer control.\n",
+    "\n",
+    "If the user unchecks the checkbox next to the layer's name the layer's visibility will be set to False.\n",
+    "\n",
+    "!!! note\n",
+    "\n",
+    "    We're only adding the boundary and road layer at this point, not the river layer.  We'll add that later, and when we do we can see the layer control automatically react to the new layer being added to the map, and it will show up in our layer control."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ae4529e4-b656-47eb-8928-a51f02d038fb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "lonboard_map = Map([boundary_layer, road_layer])\n",
+    "lc = lonboard_map.layer_control(include_settings=True)\n",
+    "\n",
+    "display(lonboard_map)\n",
+    "display(lc)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9c291004-4d2d-4f7f-9dcb-f3f1d098114f",
+   "metadata": {},
+   "source": [
+    "### Change the title of the road layer\n",
+    "\n",
+    "By default the title of the layer is the layer's type.  When we change the title of the layer, it will automatically be changed in the layer control."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2039d785-3edb-44b8-bbb7-ab61397bdae4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "road_layer.title = \"Roads\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d475c61b-e0fd-4227-a3c1-aa2cabeec7d0",
+   "metadata": {},
+   "source": [
+    "### Add the River layer\n",
+    "\n",
+    "When we add the river layer to the map, the layer control will automatically detect the new layer, and also add it to the layer control.\n",
+    "\n",
+    "When we expand the cog for the river layer we will see that the `Color` and the `Width` properties of the layer display `Custom` instead of a color picker/float widget.  \n",
+    "\"Custom\" is displayed in the layer control currently because the layer uses the values from the rows of data to render the lines.  This may change in future releases of Lonboard."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "13a4bb69-6871-4e40-946f-27edccac9f05",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "lonboard_map.add_layer(river_layer, reset_zoom=True)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "lonboard_toc",
+   "language": "python",
+   "name": "lonboard_toc"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

lonboard/_layer.py

@@ -92,6 +92,11 @@ def __init__(
         extensions: Sequence[BaseExtension] = (),
         **kwargs: Any,
     ) -> None:
+        if self.title is None:
+            if hasattr(self, "_layer_type"):
+                self.title = self._layer_type.title() + " Layer"
+            else:
+                self.title = "Layer"
         # We allow layer extensions to dynamically inject properties onto the layer
         # widgets where the layer is defined. We wish to allow extensions and their
         # properties to be passed in the layer constructor. _However_, if
@@ -281,6 +286,12 @@ def _add_extension_traits(self, extensions: Sequence[BaseExtension]) -> None:
     for an example.
     """
 
+    title = t.CUnicode(default_value=None, allow_none=True).tag(sync=True)
+    """
+    The title of the layer.  The title of the layer is visible in the layer control
+    produced by map.layer_control().
+    """
+
 
 def default_geoarrow_viewport(
     table: Table,

lonboard/_map.py

@@ -9,11 +9,16 @@
 import traitlets as t
 from ipywidgets import CallbackDispatcher
 from ipywidgets.embed import dependency_state, embed_minimal_html
+from ipywidgets.widgets.widget_box import VBox
 
 from lonboard._base import BaseAnyWidget
 from lonboard._layer import BaseLayer
 from lonboard._viewport import compute_view
 from lonboard.basemap import CartoBasemap
+from lonboard.controls import (
+    _make_layer_control_item,
+    _make_layer_control_item_with_settings,
+)
 from lonboard.traits import (
     DEFAULT_INITIAL_VIEW_STATE,
     BasemapUrl,
@@ -626,3 +631,37 @@ def as_html(self) -> HTML:
     @traitlets.default("view_state")
     def _default_initial_view_state(self) -> dict[str, Any]:
         return compute_view(self.layers)  # type: ignore
+
+    def layer_control(self, *, include_settings: bool = False) -> VBox:
+        """Make layer control box for the layers in the Map.
+
+        Args:
+            include_settings: If `False` The controler will only contain a checkbox for each layer, which controls layer visibility in the Lonboard map. If `True` The controller will also have a settings button, which when clicked will expose properties for the layer which can be changed. If a layer's property is None when the layer is added to the control, a widget for controling that property will not be created.
+
+        !!! note
+
+            For layer properties that are set as an array of values to control the display of each feature separately (example, using a color map to vary the color of the features based on the data) the layer control will display "Custom" instead of allowing the user to change the property.  This may change in a future version of Lonboard.
+
+        !!! note
+
+            The layer control uses the [ipywidgets color picker](https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20List.html#color-picker) to set colors.  This widget does not respect alpha values, so if you are using an RGBA value to set the color and the alpha of the layer, and then you use the color picker, it will set the alpha value 255.
+
+        Returns:
+            ipywidgets VBox of the layer control.
+
+        """
+        if include_settings is False:
+            item_creation_function = _make_layer_control_item
+        else:
+            item_creation_function = _make_layer_control_item_with_settings
+
+        control_items = [item_creation_function(layer) for layer in self.layers]
+        contol = VBox(control_items)
+
+        ## Observe the map's layers trait, so additions/removals of layers will result in the control recreating itself to reflect the map's current state
+        def handle_layer_change(_: traitlets.utils.bunch.Bunch) -> None:
+            control_items = [item_creation_function(layer) for layer in self.layers]
+            contol.children = control_items
+
+        self.observe(handle_layer_change, "layers", "change")
+        return contol