diff --git a/assets/table-of-contents.jpeg b/assets/table-of-contents.jpeg new file mode 100644 index 00000000..bda1c03c Binary files /dev/null and b/assets/table-of-contents.jpeg differ diff --git a/examples/index.md b/examples/index.md index 17288423..46826a9f 100644 --- a/examples/index.md +++ b/examples/index.md @@ -13,7 +13,7 @@ - [Rivers in Asia ![](../assets/rivers-asia.jpg)](../examples/map_challenge/6-asia/) using [`PathLayer`](../api/layers/path-layer) - [Inflation Reduction Act Projects ![](../assets/column-layer.jpg)](../examples/column-layer/) using [`ColumnLayer`](../api/layers/column-layer) - [Linked Maps ![](../assets/linked-maps.gif)](../examples/linked-maps/) - +- [Table of contents ![](../assets/table-of-contents.jpeg)](../examples/lonboard-table-of-contents/) ## Integrations diff --git a/examples/lonboard-table-of-contents.ipynb b/examples/lonboard-table-of-contents.ipynb new file mode 100644 index 00000000..340e6a74 --- /dev/null +++ b/examples/lonboard-table-of-contents.ipynb @@ -0,0 +1,190 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "a9528b4f-0597-4eba-a618-35cdb738a685", + "metadata": {}, + "source": [ + "# Lonboard Table of Contents\n", + "\n", + "This notebook demonstrates using the Lonboard controls to make a table of contents from a Lonboard map." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "2c1be9b5-feea-4072-b356-228dfdb86331", + "metadata": {}, + "outputs": [], + "source": [ + "import shapely\n", + "import geopandas as gpd\n", + "\n", + "import lonboard" + ] + }, + { + "cell_type": "markdown", + "id": "8d9af9fa-5e4c-48cf-88fa-031dd0b3f78e", + "metadata": {}, + "source": [ + "#### Make some simple dataframes and layers\n", + "\n", + "This notebook is not to demonstrate the speed of Lonboard, rather, it is simply to show the table of contents. Some simple geodataframes with one row each will be sufficient to make layers to add to a map." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "00ae8b4b-ea2d-42d2-8ce0-c17372b08fd1", + "metadata": {}, + "outputs": [], + "source": [ + "point = shapely.Point(-90, 38.8)\n", + "point_df = gpd.GeoDataFrame(\n", + " [point],\n", + " columns=[\"geometry\"],\n", + " geometry=\"geometry\",\n", + " crs=4326\n", + ")\n", + "point_layer = lonboard.ScatterplotLayer.from_geopandas(\n", + " point_df,\n", + " title=\"Point Layer\",\n", + " radius_min_pixels=10,\n", + " get_fill_color=[255, 255, 0]\n", + ")\n", + "\n", + "line = shapely.LineString([[-91, 38], [-90, 39]])\n", + "line_df = gpd.GeoDataFrame(\n", + " [line],\n", + " columns=[\"geometry\"],\n", + " geometry=\"geometry\",\n", + " crs=4326,\n", + ")\n", + "line_layer = lonboard.PathLayer.from_geopandas(\n", + " line_df,\n", + " title=\"Line Layer\",\n", + " width_min_pixels=10,\n", + " get_color=[124, 124, 124]\n", + ")\n", + "\n", + "polygon = shapely.Polygon([[-91, 38], [-90, 39], [-89, 38.5]])\n", + "polygon_df = gpd.GeoDataFrame(\n", + " [polygon],\n", + " columns=[\"geometry\"],\n", + " geometry=\"geometry\",\n", + " crs=4326\n", + ")\n", + "polygon_layer = lonboard.PolygonLayer.from_geopandas(\n", + " polygon_df,\n", + " title=\"Polygon Layer\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "f2c7c703-fbd1-4084-98fc-b755ece60f72", + "metadata": {}, + "source": [ + "#### Make the map with the polygon and line layers and then make a table of contents from the map\n", + "\n", + "The checkboxes in the table of contents toggle the layer's visibility.\n", + "\n", + "If you click the settings gear for a layer in the TOC, the layer's traits are exposed and can be changed by the user" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "345b2305-4a00-4adb-9117-bf2f3efb60eb", + "metadata": {}, + "outputs": [ + { + "data": { + "application/vnd.jupyter.widget-view+json": { + "model_id": "2bcf1687e5854cd1837da4e277da38b1", + "version_major": 2, + "version_minor": 1 + }, + "text/plain": [ + "Map(custom_attribution='', layers=(PolygonLayer(table=arro3.core.Table\n", + "-----------\n", + "geometry: List(Field { name…" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "application/vnd.jupyter.widget-view+json": { + "model_id": "fa1470fcc4a54257bc6e5282aac72a23", + "version_major": 2, + "version_minor": 0 + }, + "text/plain": [ + "VBox(children=(VBox(children=(HBox(children=(Checkbox(value=True, description='Polygon Layer', indent=False, l…" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "lonboard_map = lonboard.Map([polygon_layer, line_layer])\n", + "lonboard_toc = lonboard.controls.make_TOC(lonboard_map)\n", + "display(lonboard_map)\n", + "display(lonboard_toc)" + ] + }, + { + "cell_type": "markdown", + "id": "8ebcad27-da7d-44be-bf91-c1f6dadf24e2", + "metadata": {}, + "source": [ + "### Table of contents is reactive to changes\n", + "\n", + "If you add a layer to the map after it is created, the table of content will dynamically refresh itself and show the new layer" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "a82f2fb5-305b-47e8-9db9-30ed78d6a722", + "metadata": {}, + "outputs": [], + "source": [ + "lonboard_map.add_layer(point_layer)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "cce264ba-0426-4db2-81eb-c33cf01556dc", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "lonboard", + "language": "python", + "name": "lonboard" + }, + "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.4" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/lonboard/_layer.py b/lonboard/_layer.py index 3b4d35f3..a5ec24c3 100644 --- a/lonboard/_layer.py +++ b/lonboard/_layer.py @@ -271,6 +271,12 @@ def _add_extension_traits(self, extensions: Sequence[BaseExtension]): for an example. """ + title = t.CUnicode("Layer", allow_none=False).tag(sync=True) + """ + The title of the layer. The title of the layer is visible in the table of + contents produced by the lonboard.controls.make_TOC() function. + """ + def default_geoarrow_viewport( table: Table, diff --git a/lonboard/controls.py b/lonboard/controls.py index bec97922..2eed1a86 100644 --- a/lonboard/controls.py +++ b/lonboard/controls.py @@ -1,12 +1,18 @@ from functools import partial -from typing import Sequence +from typing import List, Sequence +import ipywidgets import traitlets from ipywidgets import FloatRangeSlider from ipywidgets.widgets.trait_types import TypedTuple # Import from source to allow mkdocstrings to link to base class -from ipywidgets.widgets.widget_box import VBox +from ipywidgets.widgets.widget_box import HBox, VBox + +from lonboard.traits import ( + ColorAccessor, + FloatAccessor, +) class MultiRangeSlider(VBox): @@ -86,3 +92,236 @@ def callback(change, *, i: int): initial_values.append(child.value) super().__init__(children, value=initial_values, **kwargs) + + +def _rgb2hex(r: int, g: int, b: int) -> str: + """Converts an RGB color code values to hex.""" + return "#{:02x}{:02x}{:02x}".format(r, g, b) + + +def _hex2rgb(hex_color: str) -> List[int]: + """Converts a hex color code to RGB.""" + hex_color = hex_color.lstrip("#") + return list(int(hex_color[i : i + 2], 16) for i in (0, 2, 4)) + + +def _link_rgb_and_hex_traits( + rgb_object, rgb_trait_name, hex_object, hex_trait_name +) -> None: + """Makes links between two objects/traits that hold RBG and hex color codes.""" + + def handle_RGB_color_change(change: traitlets.utils.bunch.Bunch) -> None: + new_color_RGB = change.get("new")[0:3] + new_color_hex = _rgb2hex(*new_color_RGB) + hex_object.set_trait(hex_trait_name, new_color_hex) + + rgb_object.observe(handle_RGB_color_change, rgb_trait_name, "change") + + def handle_hex_color_change(change: traitlets.utils.bunch.Bunch) -> None: + new_color_hex = change.get("new") + new_color_rgb = _hex2rgb(new_color_hex) + rgb_object.set_trait(rgb_trait_name, new_color_rgb) + + hex_object.observe(handle_hex_color_change, hex_trait_name, "change") + + +def _make_TOC_item(layer, with_layer_controls: bool = True) -> VBox: + """ + Returns an ipywidgets VBox to be used by a table of contents based on the input + Lonboard layer. + + If with_layer_controls is True, the VBox will contain a toggle for the layer's + visibility and a button that when clicked will display widgets linked to the layers + traits so they can be modified. + + If with_layer_controls is False, the VBox will only contain a toggle for the layer's + visibility. + """ + visibility_w = ipywidgets.Checkbox( + value=True, description="", disabled=False, indent=False + ) + visibility_w.layout = ipywidgets.Layout(width="196px") + ipywidgets.dlink((layer, "title"), (visibility_w, "description")) + ipywidgets.link((layer, "visible"), (visibility_w, "value")) + + if with_layer_controls is False: + # with_layer_controls is False return the visibility widget within a VBox + # within a HBox to maintain consistency with the TOC item that would be returned + # if with_layer_controls were True + TOC_item = VBox([HBox([visibility_w])]) + else: + # with_layer_controls is True, make a button that will display the layer props, + # and widgets for the layer properties. Instead of making the trait controlling + # widgets in a random order, make lists so we can make the color widgets at the + # top, followed by the boolean widgets and the number widgets so the layer props + # display has some sort of order + color_widgets = [] + bool_widgets = [] + number_widgets = [] + + ## style and layout to keep property wigets consistent + prop_style = {"description_width": "initial"} + prop_layout = ipywidgets.Layout(width="224px") + for trait_name, trait in layer.traits().items(): + ## Guard against making widgets for protected traits + if trait_name.startswith("_"): + continue + # Guard against making widgets for things we've determined we should not + # make widgets to change + if trait_name in ["visible", "selected_index", "title"]: + continue + + ## Make a human readable name from the trait + trait_description = trait_name.replace("get_", "").replace("_", " ").title() + + if isinstance(trait, ColorAccessor): + if getattr(layer, trait_name) is not None: + hex_color = _rgb2hex(*getattr(layer, trait_name)) + else: + hex_color = "#000000" + color_picker_w = ipywidgets.ColorPicker( + description=trait_description, layout=prop_layout, value=hex_color + ) + _link_rgb_and_hex_traits(layer, trait_name, color_picker_w, "value") + color_widgets.append(color_picker_w) + + if ( + isinstance(trait, traitlets.traitlets.Bool) + and getattr(layer, trait_name) is not None + ): + bool_w = ipywidgets.Checkbox( + value=True, + description=trait_description, + disabled=False, + style=prop_style, + layout=prop_layout, + ) + ipywidgets.link((layer, trait_name), (bool_w, "value")) + bool_widgets.append(bool_w) + + if ( + isinstance(trait, (FloatAccessor, traitlets.traitlets.Float)) + and getattr(layer, trait_name) is not None + ): + min_val = None + if hasattr(trait, "min"): + min_val = trait.min + + max_val = None + if hasattr(trait, "max"): + max_val = trait.max + if max_val == float("inf"): + max_val = 999999999999 + + if max_val is not None and max_val is not None: + ## min/max are not None, make a bounded float + float_w = ipywidgets.BoundedFloatText( + value=True, + description=trait_description, + disabled=False, + indent=True, + min=min_val, + max=max_val, + style=prop_style, + layout=prop_layout, + ) + else: + ## min/max are None, use normal flaot, not bounded. + float_w = ipywidgets.FloatText( + value=True, + description=trait_description, + disabled=False, + indent=True, + layout=prop_layout, + ) + ipywidgets.link((layer, trait_name), (float_w, "value")) + number_widgets.append(float_w) + + if ( + isinstance(trait, (traitlets.traitlets.Int)) + and getattr(layer, trait_name) is not None + ): + min_val = None + if hasattr(trait, "min"): + min_val = trait.min + + max_val = None + if hasattr(trait, "max"): + max_val = trait.max + if max_val == float("inf"): + max_val = 999999999999 + + if max_val is not None and max_val is not None: + ## min/max are not None, make a bounded int + float_w = ipywidgets.BoundedIntText( + value=True, + description=trait_description, + disabled=False, + indent=True, + min=min_val, + max=max_val, + style=prop_style, + layout=prop_layout, + ) + else: + ## min/max are None, use normal int, not bounded. + float_w = ipywidgets.IntText( + value=True, + description=trait_description, + disabled=False, + indent=True, + style=prop_style, + layout=prop_layout, + ) + ipywidgets.link((layer, trait_name), (float_w, "value")) + number_widgets.append(float_w) + + layer_props_title = ipywidgets.HTML(value=f"{layer.title} Properties") + props_box_layout = ipywidgets.Layout( + border="solid 3px #EEEEEE", width="240px", display="none" + ) + props_widgets = ( + [layer_props_title] + color_widgets + bool_widgets + number_widgets + ) + layer_props_box = VBox(props_widgets, layout=props_box_layout) + + props_button = ipywidgets.Button(description="", icon="gear") + props_button.layout.width = "36px" + + def on_props_button_click(_: ipywidgets.widgets.widget_button.Button) -> None: + if layer_props_box.layout.display != "none": + layer_props_box.layout.display = "none" + else: + layer_props_box.layout.display = "flex" + + props_button.on_click(on_props_button_click) + TOC_item = VBox([HBox([visibility_w, props_button]), layer_props_box]) + return TOC_item + + +def make_TOC(lonboard_map, with_layer_controls: bool = True) -> VBox: + """Function to make create a table of contents (TOC) based on a Lonboard Map. + + The TOC will contain a checkbox for each layer, which controls layer visibility in + the Lonboard map. + + If `with_layer_controls` is True, each layer in the TOC 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 TOC is created, a widget controling that + property will not be created. + """ + toc_items = [ + _make_TOC_item(layer, with_layer_controls) for layer in lonboard_map.layers + ] + toc = VBox(toc_items) + + # Observe the map's layers trait, so additions/removals of layers will result in + # the TOC recreating itself to reflect the map's current state + def handle_layer_change(change: traitlets.utils.bunch.Bunch) -> None: + toc_items = [_make_TOC_item(layer) for layer in lonboard_map.layers] + toc.children = toc_items + + lonboard_map.observe(handle_layer_change, "layers", "change") + return diff --git a/lonboard/types/layer.py b/lonboard/types/layer.py index f30f88d1..1454aeb0 100644 --- a/lonboard/types/layer.py +++ b/lonboard/types/layer.py @@ -78,6 +78,7 @@ class BaseLayerKwargs(TypedDict, total=False): visible: bool opacity: IntFloat auto_highlight: bool + title: str class BitmapLayerKwargs(BaseLayerKwargs, total=False):