Skip to content

Add pane option to HeatMapWithTime - #2349

Open
KhadeerBasha1232 wants to merge 1 commit into
python-visualization:mainfrom
KhadeerBasha1232:heatmapwithtime-pane
Open

KhadeerBasha1232 wants to merge 1 commit into
python-visualization:mainfrom
KhadeerBasha1232:heatmapwithtime-pane

Conversation

@KhadeerBasha1232

@KhadeerBasha1232 KhadeerBasha1232 commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Add pane option to HeatMapWithTime

Closes #1400

The problem

HeatMapWithTime is drawn underneath an ImageOverlay, even when the heatmap is added to the map after the image.

The heatmap library (pa7_leaflet_hm) always appends its <div> to Leaflet's overlayPane with z-index: auto. Leaflet gives every ImageOverlay a numeric zIndex, so inside that pane the image always stacks above the heatmap. The CSS workaround from #1201 (.leaflet-heatmap-layer { z-index: 300 }) doesn't help here, because that class comes from leaflet.heat, which the plain HeatMap plugin uses. The library behind HeatMapWithTime never sets it.

The fix

HeatMapWithTime now takes a pane argument, like other Leaflet layers. To draw the heatmap on top, give it a custom pane with a higher z-index:

folium.map.CustomPane("heatmap", z_index=450).add_to(m)
HeatMapWithTime(data, pane="heatmap").add_to(m)
  • The default is "overlayPane", so existing maps render as before.
  • The pane handling lives in folium's template: a small PanedHeatmapOverlay subclass moves the heatmap element into the chosen pane on onAdd and removes it from there on onRemove. I didn't edit the bundled pa7_leaflet_hm.min.js, because folium loads that file from jsDelivr.
  • A short section on the plugin's docs page shows the pattern.

Tests

  • New parametrized test: the rendered script passes the pane through for both the default and a custom pane.
  • The existing template test is updated for the new option.
  • Checked in a browser with an ImageOverlay plus HeatMapWithTime:
    • Default pane: the heatmap stays in overlayPane, as before.
    • Custom pane: the heatmap is drawn above the image.
    • Toggling it in LayerControl, stepping the time slider, zooming and panning all work with no console errors.
    • After zooming and panning, the heatmap stays aligned to its coordinates, within 1px.

CI note

The pre-commit.ci failure isn't from this change. Black wants two blank lines between two tests in tests/test_features.py, which also fails on main since #2307 and #2346 were merged. #2350 fixes it, and I'll rebase this PR once that's merged. All the test runs (Ubuntu, macOS, Windows × Python 3.11/3.14) pass.

The heatmap library always appended its element to the overlay pane
with no z-index, so any ImageOverlay (Leaflet gives it a z-index)
covered the heatmap no matter the order the layers were added.

HeatMapWithTime now takes a `pane` argument. Combined with a
CustomPane that has a higher z_index, the heatmap can be drawn on top
of image overlays. The default stays "overlayPane", so existing maps
render as before.

Closes python-visualization#1400

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was previously deployed

1 inactive deployment
pypi — 75ce7e33 Deployed Nov 16, 2026 by KhadeerBasha1232 via packages #2096
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

HeatmapWithTime is visualized in the back of overlay image

1 participant