folium Documentation

Folium provides a wide range of plugins to extend map functionality, including animations, specialized markers, advanced controls, and data visualizations.

Key categories of plugins include:

• Animations & Visuals: Ant Path (flux animation), Boat Marker (yachts/sailboats), Pattern (pattern fills), Polyline Textpath (text along lines), and Terminator (day/night overlays).
• Markers & Clustering: Beautify Icon (CSS-styled markers), Marker Cluster (high-performance clustering), Overlapping Marker Spiderfier (managing overlapping markers), and Semi Circle.
• Drawing & Editing: Draw (user interface for drawing shapes), Geoman (interactive editing interface), and encoded formats like Polygon Encoded and Polyline Encoded.
• Controls & UI: Fullscreen, Geocoder (geocoding/reverse geocoding), Locate Control, Measure Control, Mini Map, Mouse Position, Scroll Zoom Toggler, Search, and TreeLayerControl.
• Time & Data Visualization: Heatmap, Heatmap with Time, Timeline, Timeslider Choropleth, Timestamped GeoJSON, and WMS Time Dimension.
• Advanced Map Views: Dual Map (synchronized views), Side by Side Layers (split screen comparison), WebGL Earth (3D interactive globe), and Vector Tiles (gridded vector data).

The Timeline plugin allows you to visualize changing geospatial data by using GeoJSON features that contain start and end time properties. To control the playback of these timelines, use the TimelineSlider plugin.

Key differences from other plugins:

• vs TimestampedGeoJson: Timeline expects each Feature to have its own start and end time in its properties. TimestampedGeoJson uses an array of start times and a global duration instead of individual end times.
• vs Realtime: Timeline is designed for historical data (past events), whereas Realtime is used for live updates.

import folium
from folium.utilities import JsCode
from folium.features import GeoJsonPopup
from folium.plugins.timeline import Timeline, TimelineSlider
import requests

m = folium.Map()

data = requests.get(
    "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/historical_country_borders.json"
).json()

timeline = Timeline(
    data,
    style=JsCode("""
        function (data) {
            function getColorFor(str) {
                var hash = 0;
                for (var i = 0; i < str.length; i++) {
                    hash = str.charCodeAt(i) + ((hash << 5) - hash);
                }
                var red = (hash >> 24) & 0xff;
                var grn = (hash >> 16) & 0xff;
                var blu = (hash >> 8) & 0xff;
                return "rgb(" + red + "," + grn + "," + blu + ")";
            }
            return {
                stroke: false,
                color: getColorFor(data.properties.name),
                fillOpacity: 0.5,
            };
        }
    """)
).add_to(m)

GeoJsonPopup(fields=['name'], labels=True).add_to(timeline)

TimelineSlider(
    auto_play=False,
    show_ticks=True,
    enable_keyboard_controls=True,
    playback_duration=30000,
).add_timelines(timeline).add_to(m)

You can generate dynamic maps by passing a numpy array to ImageOverlay.

Requirements

• numpy must be installed.
• You must provide a colormap argument.

Colormap Format

The colormap must be a function (e.g., a lambda) that accepts a value x and returns an RGBA tuple: lambda x: (R, G, B, A), where R, G, B, A are floats between 0 and 1.

Handling Orientation and Projection

• origin='lower': Use this to inform Folium that the first lines of the array should be plotted at the bottom of the image (matching numpy.imshow behavior).
• mercator_project=True: Because Leaflet uses Mercator projection, raw numpy arrays may not align correctly with geographic coordinates (like Polylines). Setting mercator_project=True allows Folium to handle the projection math so the array aligns with the map's coordinate system.

import numpy as np
import folium

# Create a dummy numpy array
image = np.zeros((61, 1))
image[45, :] = 1.0

m = folium.Map([37, 0], zoom_start=3)

# Add a polyline to verify alignment
folium.PolyLine([[45, -60], [45, 60]]).add_to(m)

# Use ImageOverlay with mercator_project=True for correct alignment
folium.raster_layers.ImageOverlay(
    image=image,
    bounds=[[0, -60], [60, 60]],
    origin="lower",
    colormap=lambda x: (1, 0, 0, x),
    mercator_project=True,
).add_to(m)

Use WebGLEarthRealtime to fetch and display live data on the 3D globe. It requires a source_url for the data and an interval (in milliseconds). The on_update parameter accepts a folium.JsCode object containing a JavaScript function that defines how the data should be rendered on the globe (e.g., updating marker positions).

import folium
from folium import JsCode
from folium.plugins import WebGLEarth, WebGLEarthRealtime

m = folium.Map()

globe = WebGLEarth(center=[0, 0], zoom=1.8)
globe.add_to(m)

WebGLEarthRealtime(
    source_url="https://api.wheretheiss.at/v1/satellites/25544",
    interval=3000,
    on_update=JsCode("""
        function(data, earth) {
            if (window._issMarker) window._issMarker.removeFrom(earth);
            window._issMarker = WE.marker(
                [data.latitude, data.longitude]
            ).addTo(earth);
            window._issMarker.bindPopup(
                '<b>ISS</b><br>'
                + 'Lat: ' + data.latitude.toFixed(2)
                + '<br>Lng: ' + data.longitude.toFixed(2)
                + '<br>Alt: ' + data.altitude.toFixed(1) + ' km'
            );
        }
    """),
).add_to(globe)

m