ImageOverlay
Quick answer
L.imageOverlay places a single image across a geographic bounds rectangle so it scales and translates with the map. It suits radar frames, scanned site plans, hillshade exports and any raster that has no tile pyramid behind it. Opacity, zIndex and an error replacement URL are all available as options.
L.imageOverlay( imageUrl , bounds , options ) → ImageOverlay
Key points
- setUrl swaps the image while preserving bounds, avoiding flicker when animating frames.
- crossOrigin true is required before reading pixels or compositing into a canvas.
- bounds accepts nested arrays in south west, north east corner order.
Example
var bounds = [[39.880, 116.360], [39.940, 116.450]];
var overlay = L.imageOverlay(
'https://example.com/radar/2026-10-28-08.png',
bounds,
{ opacity: 0.55, crossOrigin: true, zIndex: 2 }
).addTo(map);
/* 逐帧切换,用 setUrl 而不是重建图层,避免闪烁 */
var frames = ['08.png', '09.png', '10.png'];
var i = 0;
setInterval(function () {
i = (i + 1) % frames.length;
overlay.setUrl('/radar/' + frames[i]);
}, 1200);
/* 放在 canvas 里合成导出时,范围要从图片自身尺寸推算 */
var b = overlay.getBounds();
console.log(b.getSouth(), b.getWest(), b.getNorth(), b.getEast());
Notes
- The image must be a rectangular grid; Leaflet applies no perspective correction or clipping.
- Cross-origin images without proper headers stay invisible once crossOrigin is enabled.
English edition written for Atlaslog. Code is taken from the original Chinese page and runs unchanged.
Atlaslog (2026). ImageOverlay. https://www.jingweizhi.com/en/leaflet/api/image-overlay.html (accessed 2026-11-03).