ipyleaflet Documentation

ipyleaflet is a Jupyter/Leaflet bridge that enables interactive maps within Jupyter notebooks. It consists of two main parts:

• jupyter-leaflet: The front-end npm package (the widget component).
• ipyleaflet: The Python package that serves as the backend for the Python Jupyter kernel.

Key features include:

• Selecting and switching between different basemaps.
• Loading and visualizing GeoJSON data.
• Using LeafletJS primitives directly.
• Implementing splitmap controls.
• Visualizing velocity data on maps.
• Creating Choropleth layers.
• Using widget controls within the map interface.

Everything in ipyleaflet—including the Map class, Layer classes, and Control classes—is an interactive widget. This means any attribute exposed by these classes can be synchronized between the JavaScript frontend and the Python backend. Common examples of interactive attributes include:

• map.zoom for controlling map magnification.
• layer.url for updating tile or data sources.
• marker.location for moving markers.
• heatmap.locations for updating heatmap data.

For a Choropleth layer to render correctly, your data must follow these structures:

GeoJSON (geo_data) structure: The GeoJSON must contain features with identifiers that match your data dictionary. These identifiers can be found in the id field or within the properties object.

{
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "id": "AL",
        "properties": {"name": "Alabama"},
        "geometry": {
            "type": "Polygon",
            "coordinates": [[[-87.359296, 35.00118]]] 
        }
    }]
}

Data Dictionary (choro_data) structure: A simple dictionary mapping the identifier (from the GeoJSON) to a float value.

{'AL': 7.1, 'AK': 6.8}

The LayersControl widget adds a layer selector to the map, allowing users to toggle the visibility of different layers.

To ensure a layer appears in the selector, you must provide a name attribute to the layer (e.g., Marker(name='my_marker')). This name is what the user sees in the control interface. You can specify the position of the control on the map using the position argument (e.g., 'topright').

from ipyleaflet import Map, Marker, LayersControl

m = Map(center=(50, 0), zoom=5)

# Layers must have a 'name' to appear in the LayersControl
marker1 = Marker(name='marker1', location=(48, -2))
marker2 = Marker(name='marker2', location=(50, 0))
marker3 = Marker(name='marker3', location=(52, 2))

m.add(marker1)
m.add(marker2)
m.add(marker3)

# Add the control to the map
control = LayersControl(position='topright')
m.add(control)

m

You can create a TileLayer instance easily using the basemap_to_tiles function. This function accepts a basemap object from the basemaps dictionary (e.g., basemaps.CartoDB.DarkMatter).

For certain providers like NASA GIBS, you can also specify a date string to load specific imagery.

from ipyleaflet import Map, basemaps, basemap_to_tiles

m = Map(center=(52.204793, 360.121558), zoom=9)

# Create a layer from a basemap
dark_matter_layer = basemap_to_tiles(basemaps.CartoDB.DarkMatter)
m.add(dark_matter_layer)

# Example with a specific date for NASA imagery
nasa_layer = basemap_to_tiles(basemaps.NASAGIBS.ModisTerraTrueColorCR, "2018-04-08")
m.add(nasa_layer)

The Map object allows you to add layers (like Marker) and controls using the .add() method. Because all layers and controls are themselves widgets, you can dynamically update their attributes from Python or through direct interaction on the map interface.

from ipyleaflet import Map, Marker, basemaps, basemap_to_tiles

m = Map(
    basemap=basemap_to_tiles(basemaps.NASAGIBS.ModisTerraTrueColorCR, "2017-04-08"),
    center=(52.204793, 360.121558),
    zoom=4
)

m.add(Marker(location=(52.204793, 360.121558)))

m

To enable built-in basemap switching using the LayersControl widget, you must:

1. Create TileLayer objects using basemap_to_tiles.
2. Set the .base attribute of each layer to True.
3. Pass these layers as a list to the layers argument of the Map constructor.
4. Add a LayersControl() instance to the map.

from ipyleaflet import Map, basemaps, basemap_to_tiles, LayersControl

mapnik = basemap_to_tiles(basemaps.OpenStreetMap.Mapnik)
mapnik.base = True

toner = basemap_to_tiles(basemaps.Stadia.StamenTerrain)
toner.base = True

# Pass the base layers to the Map constructor
m = Map(layers=[mapnik, toner], center=(52.204793, 360.121558), zoom=9)

# Add the control to allow switching
m.add(LayersControl())

You can set the background map of an ipyleaflet.Map instance using the basemap argument. The available default basemaps are provided via the basemaps module. These basemaps are sourced from the xyzservices package.

If a specific provider is not available in the basemaps module, you can use a custom TileLayer to provide your own tiles.

from ipyleaflet import Map, basemaps

center = [38.128, 2.588]
zoom = 5

# Example using OpenStreetMap Mapnik
Map(basemap=basemaps.OpenStreetMap.Mapnik, center=center, zoom=zoom)