leaflet.gleo v0.2.0

Leaflet.Gleo

A LeafletJS plugin to render data through the Gleo library.

This plugin fuses together a Leaflet BlanketOverlay (which covers an entire Leaflet map pane, similar to a L.Renderer) with a Gleo Platina (which can render thousands of Gleo symbols using WebGL).

I want to see this working!

There's a few public demos:

• heatmap - a two-heatpoint heatmap
• sprites - one thousand moving sprites
• montecarlo - polygons filled with random dots over their surface ("Montecarlo fill")

Usage

Leaflet.Gleo leverages javascript modules. For convenience, the first step would be to have an import map somewhere in your HTML file, like so:

<script type="importmap">
{
	"imports": {
		"leaflet": "https://unpkg.com/leaflet@1.9.3/dist/leaflet-src.esm.js",
		"gleo/": "https://unpkg.com/gleo@0.8.0/src/",
		"leaflet-gleo": "./LeafletGleo.js"
	}
}
</script>

(If you're using a build/bundling system, like Rollup/Webpack/Parcel/etc, then you most probably won't be using import maps to specify dependencies, but npm instead)

Then, in your javascript module, create a Leaflet L.Map and an instance of the Leaflet.Gleo Platina like so:

<script type="module">
	import {Map} from 'leaflet';
	import LeafletGleo from "leaflet-gleo";

	// Create a Leaflet map, assuming a <div id='leaflet-map'> somewhere else
	const map = new Map('leaflet-map');

	// Create a Gleo Platina automatically mounted in a pane in the Leaflet map:
	const platina = new LeafletGleo(map, { /* optional platina options */ });

</script>

Then, add Gleo symbols (and/or acetates and/or loaders) to the Platina, e.g.:

import HeatPoint from "gleo/symbols/HeatPoint.mjs";
import CircleFill from "gleo/symbols/CircleFill.mjs";
import AcetateHeatMap from "gleo/acetates/AcetateHeatMap.mjs";
import LatLng from 'gleo/geometry/LatLng.mjs';

new CircleFill(new LatLng([50,-100]), {colour: 'red', radius: 100}).addTo(platina);

const heatmap = new AcetateHeatMap(platina, {
	stops: {
		0: [0, 0, 128, 0],
		10: [0, 0, 128, 255],
		100: [0, 255, 128, 255],
		200: [255, 255, 0, 255],
		500: [255, 255, 255, 255],
	},
});

new HeatPoint(new LatLng([0,0]), {intensity: 100, radius: 100}).addTo(heatmap);
new HeatPoint(new LatLng([40,-3]), {intensity: 100, radius: 100}).addTo(heatmap);

You can pass options to the the Platina constructor. These include both options for the Leaflet BlanketOverlay (such as padding) and options for the Gleo Platina (such as preserveDrawingBuffer):

const map = new Map('leaflet-map');
const platina = new LeafletGleo(map, {
	padding: 0.2,
	preserveDrawingBuffer: true
});

Limitations and gotchas

No magic handling of Leaflet Markers, TileLayers, nor Paths.

It'd be possible to replace Leaflet L.Markers with Gleo Sprites (and L.TileLayers with Gleo MercatorTiles; and Leaflet L.Polylines with Gleo Strokes; and Leaflet L.Polygons with Gleo Fills). This replacement does not happen automatically, at least for now.

No automatic handling of coordinate systems for Gleo Geometrys.

Gleo is a projection-agnostic map library and, as such, allows arbitrary coordinate reference systems ("CRSs").

The output of Gleo is assumed to be a Leaflet map using L.CRS.EPSG3857 (which is the default), so Gleo uses its own epsg3857 for the job.

However, the input for the Gleo Geometrys is not defined. It's up to the implementations to ensure that Gleo Geometrys are created with the right Gleo CRS.

If (and only if!) all your inputs are arrays in latitude-longitude, then it's possible to use Gleo's DefaultGeometry functionality, like so:

import {setFactory} from "gleo/geometry/DefaultGeometry.mjs";
import {LatLng} from "gleo/geometry/LatLng.mjs";

setFactory(function latLngize(coords) {
	return new LatLng(coords);
});

// Once that's done, geometries are implicit, like:
new CircleFill([40, -3]).addTo(platina);

// the previous line would be  equivalent to:
new CircleFill(new LatLng([40, -3])).addTo(platina);

// which is equivalent to:
import Geometry from "gleo/geometry/geometry.mjs";
import epsg4326 from "gleo/crs/epsg4326.mjs";
new CircleFill(new Geometry(epsg4326,[-3, 40])).addTo(platina);

Potential confusion about LatLng

Leaflet's L.LatLng and Gleo's LatLng are NOT equivalent!!!

No support for Proj4Leaflet

Proj4Leaflet supports arbitrary CRSs, and Gleo supports arbitrary CRSs, but that does not mean that those two will play together nicely.

It'd be possible to achieve it, but that would need quite some work.

No support for L.CRS.Simple

Leaflet.Gleo assumes that Leaflet uses the default L.CRS.EPSG3857 CRS.

It'd be possible to match the Leaflet L.CRS.Simple with the Gleo cartesian CRS. It'd need some work.

Idem for the other built-in Leaflet CRSs (including L.CRS.EPSG4326).

Bad behaviour of click events on Clusterer

Whenever a Clusterer is added to the platina, its default onClusterClick still applies. It affects the scale of the Gleo Platina, and not the zoom level of the Leaflet map.

The workaround is to manually use the following function as the onClusterClick option of a Clusterer:

function onClusterClick(ev) {
	const [lng, lat] = ev.geometry.toCRS("EPSG:4326").coords;
	map.setZoomAround([lat, lng], map.getZoom() + 1);
}

devicePixelRatio incompatibility with Gleo <= 0.7.1

Gleo added support for hi-DPI screens (i.e. window.devicePixelRatio is > 1) in 0.8.0. Using Leaflet.Gleo with a version of Gleo previous to 0.8.0 will not work properly (the whole Gleo overlay will appear scaled).

Legalese

Leaflet.Gleo is licensed under a GPL-3.0 license. See the LICENSE file for details.