Skip to content

Map

lonboard.Map

The top-level class used to display a map in a Jupyter Widget.

Example:

import geopandas as gpd
from lonboard import Map, ScatterplotLayer, SolidPolygonLayer

# A GeoDataFrame with Point geometries
point_gdf = gpd.GeoDataFrame()
point_layer = ScatterplotLayer.from_geopandas(
    point_gdf,
    get_fill_color=[255, 0, 0],
)

# A GeoDataFrame with Polygon geometries
polygon_gdf = gpd.GeoDataFrame()
polygon_layer = SolidPolygonLayer.from_geopandas(
    gdf,
    get_fill_color=[255, 0, 0],
)

m = Map([point_layer, polygon_layer])

__init__ 

__init__(
    layers: Union[BaseLayer, Sequence[BaseLayer]], **kwargs: Unpack[MapKwargs]
) -> None

Create a new Map.

Aside from the layers argument, pass keyword arguments for any other attribute defined in this class.

Parameters:

Returns:

  • None –

    A Map object.

add_layer 

add_layer(
    layers: BaseLayer | Sequence[BaseLayer] | Map,
    *,
    focus: bool = False,
    reset_zoom: bool = False
)

Add one or more new layers to the map.

Examples:

from lonboard import viz

m = viz(some_data)
m.add_layer(viz(more_data), focus=True)

Parameters:

  • layers (BaseLayer | Sequence[BaseLayer] | Map) –

    New layers to add to the map. This can be: - a layer instance - a list or tuple of layer instances - another Map instance, in which case its layers will be added to this map. This lets you pass the result of viz into this method.

  • focus (bool, default: False ) –

    If True, set the view state of the map based on the newly-added layers. Defaults to False.

  • reset_zoom (bool, default: False ) –

    If True, set the view state of the map based on all layers. Defaults to False.

Raises:

as_html 

as_html() -> HTML

Render the current map as a static HTML file in IPython.

Warning

The primary, recommended way to display a map is by leaving it as the last line in a cell.

from lonboard import Map

m = Map(layers=[])
m

This method exists to support environments that are unable to display Jupyter Widgets. Some aspects of Lonboard are unavailable with this display method. In particular, the map is unable to send any information back to Python. So selected_index will never be populated, for example.

Returns:

  • HTML –

    IPython HTML object.

basemap_style class-attribute instance-attribute 

basemap_style = BasemapUrl(PositronNoLabels)

A URL to a MapLibre-compatible basemap style.

Various styles are provided in lonboard.basemap.

custom_attribution class-attribute instance-attribute 

custom_attribution = tag(sync=True)

Custom attribution to display on the map.

This attribute supports the same format as the attribution property in the Maplibre API.

  • Type: str or List[str]
  • Default: None

You can provide either a single string or a list of strings for custom attributions. If an attribution value is set in the map style, it will be displayed in addition to this custom attribution.

Example:

```py
m = Map(
    layers,
    custom_attribution="Development Seed"
)
```

Example:

```py
m = Map(
    layers,
    custom_attribution=["Development Seed", "OpenStreetMap"]
)
```

fly_to 

fly_to(
    *,
    longitude: Union[int, float],
    latitude: Union[int, float],
    zoom: Union[int, float],
    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.

Parameters:

  • longitude (Union[int, float]) –

    The longitude of the new viewport.

  • latitude (Union[int, float]) –

    The latitude of the new viewport.

  • zoom (Union[int, float]) –

    The zoom of the new viewport.

  • pitch (Union[int, float], default: 0 ) –

    The pitch of the new viewport. Defaults to 0.

  • bearing (Union[int, float], default: 0 ) –

    The bearing of the new viewport. Defaults to 0.

  • duration (int, default: 4000 ) –

    The number of milliseconds for the viewport transition to take. Defaults to 4000.

  • curve (Optional[Union[int, float]], default: None ) –

    The zooming "curve" that will occur along the flight path. Default 1.414.

  • speed (Optional[Union[int, float]], default: None ) –

    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 (Optional[Union[int, float]], default: None ) –

    The average speed of the animation measured in screenfuls per second. Similar to speed it linearly affects the duration, when specified speed is ignored.

layers class-attribute instance-attribute 

layers = tag(sync=True, **widget_serialization)

One or more Layer objects to display on this map.

parameters class-attribute instance-attribute 

parameters = 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, which comes from the MDN docs here.

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, 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:

{
  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 API for documentation on supported parameters and values.

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.

picking_radius class-attribute instance-attribute 

picking_radius = tag(sync=True)

Extra pixels around the pointer to include while picking (such as for a tooltip).

This is helpful when rendered objects are difficult to target, for example irregularly shaped icons, small moving circles or interaction by touch.

  • Type: int
  • Default: 5

selected_bounds class-attribute instance-attribute 

selected_bounds = tag(sync=True)

Bounds selected by the user, represented as a tuple of floats ordered as

(minx, miny, maxx, maxy)

set_view_state 

set_view_state(
    *,
    longitude: Optional[float] = None,
    latitude: Optional[float] = None,
    zoom: Optional[float] = None,
    pitch: Optional[float] = None,
    bearing: Optional[float] = None
) -> None

Set the view state of the map.

Any parameters that are unset will not be changed.

Other Parameters:

  • longitude (Optional[float]) –

    the new longitude to set on the map. Defaults to None.

  • latitude (Optional[float]) –

    the new latitude to set on the map. Defaults to None.

  • zoom (Optional[float]) –

    the new zoom to set on the map. Defaults to None.

  • pitch (Optional[float]) –

    the new pitch to set on the map. Defaults to None.

  • bearing (Optional[float]) –

    the new bearing to set on the map. Defaults to None.

show_tooltip class-attribute instance-attribute 

show_tooltip = tag(sync=True)

Whether to render a tooltip on hover on the map.

  • Type: bool
  • Default: True

to_html 

to_html(
    filename: Union[str, Path, TextIO, IO[str], None] = None,
    title: Optional[str] = None,
) -> Union[None, str]

Save the current map as a standalone HTML file.

Parameters:

Other Parameters:

  • title (Optional[str]) –

    A title for the exported map. This will show as the browser tab name.

Returns:

  • Union[None, str] –

    If filename is not passed, returns the HTML content as a str.

use_device_pixels class-attribute instance-attribute 

use_device_pixels = 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

view_state class-attribute instance-attribute 

view_state = ViewStateTrait()

The view state of the map.

  • Type: ViewState
  • Default: Automatically inferred from the data passed to the map.

You can initialize the map to a specific view state using this property:

Map(
    layers,
    view_state={"longitude": -74.0060, "latitude": 40.7128, "zoom": 7}
)

Note

The properties of the view state are immutable. Use set_view_state to modify a map's view state once it's been initially rendered.

lonboard.models.ViewState

Bases: NamedTuple

bearing instance-attribute 

bearing: float

Bearing angle in degrees. 0 is north.

latitude instance-attribute 

latitude: float

Latitude at the map center.

longitude instance-attribute 

longitude: float

Longitude at the map center

pitch instance-attribute 

pitch: float

Pitch angle in degrees. 0 is top-down.

zoom instance-attribute 

zoom: float

Zoom level.