Gint — Guide and Architecture

Geographic Interleaved Binary Format
interleave (Morton bit-interleaving) · integer (64-bit integer vertex codes) · intended (level of detail designed in)
A whole dataset on the GPU — drawn at any zoom, and able to answer questions

1. Why Gint — Tiles Draw, Gint Knows

The ortho-earth engine has two kinds of vector layers. The basemap is drawn from vector tiles (MVT): the server cuts the world into 4^z tiles per zoom level, each zoom fetches a new set, and each tile is triangulated once on the CPU. That is right for a background picture. It is wrong for data you want to ask about — every feature is chopped at tile edges, simplified differently at each zoom, and exists only as triangles.

A Gint layer keeps the whole geometry of a GeoPBF dataset on the GPU, once:

	Vector tiles	Gint
Files	one per tile per zoom	one file
Bytes when you zoom	new tiles	+0 — level of detail is chosen on the GPU
Polygon fill	CPU triangulation per tile	winding count — no triangulation
Features	cut at tile edges	whole, shared borders exact
Restyle	re-run the style per tile	one texture update — every feature can have its own colour
Questions	—	pick, identify, highlight, join to a table

2. Your First Gint Layer

Five steps: load, add, paint, filter, ask. The words come from MapLibre GL JS — paint properties, expressions, setPaint, setFilter — so what you already know works here. It is not a copy of MapLibre. The vocabulary is borrowed to make the first step short; the layer underneath is Gint.

import { createGlobe, geopbf } from "@ortho-earth/globe";

const map = await createGlobe({ target: "#map" });

// 1. Load — any format geopbf reads. { gint: true } also builds the GPU form (kept in IndexedDB).
const pbf = await geopbf("https://example.com/municipalities.geojson", { gint: true });

// 2. Add — a new layer on top. Nothing is replaced.
const layer = map.addGint(pbf, { tip: true });
await layer.ready;                                 // true when the layer is on the GPU

// 3. Paint — MapLibre paint properties and expressions, evaluated once per feature.
await layer.setPaint({
  "fill-color": ["interpolate", ["linear"], ["get", "pop"], 0, "#fff5eb", 1000000, "#7f2704"],
  "fill-opacity": 0.85,
  "line-color": "#ffffff",
  "line-width": 0.5,
});

// 4. Filter — hide features. Nothing is rebuilt.
await layer.setFilter([">=", ["get", "pop"], 10000]);

// 5. Ask.
layer.on("click", e => console.log(e.fid, e.properties, e.lngLat));
const hit  = layer.query([139.767, 35.681]);  // { fid, properties } or null
const hits = map.queryAll([139.767, 35.681]); // [{ layer, fid, feature }], top layer first

2.1 Load

geopbf(input, { gint: true }) takes a URL, a File, an ArrayBuffer or a GeoJSON object, in any format GeoPBF reads — GeoJSON, Shapefile, GeoPackage, FlatGeobuf, GeoParquet, KML, GPX and more. gint: true also builds the form the GPU draws: the topology encoder (WebAssembly, in a worker) turns every shared border into one shared arc. The result is kept in IndexedDB, so the next visit skips the encoder. geopbf is re-exported by @ortho-earth/globe; you do not need a second package.

Features whose properties are exactly the same become one feature — a multi-part feature with one fid. They are coloured, highlighted and answered together. If you need them apart, give each one its own property, such as an id.

2.2 Add

map.addGint(pbf, options) adds a layer and returns its handle at once. The baking — edge tables, the level-of-detail ladder, a box per feature — runs in a worker, so the map keeps drawing. await layer.ready gives true when the layer is on the GPU (false if it failed). addGint does not move the camera.

Before any paint, a layer draws in its default style: polygon outlines in orange (#FF6B35), lines in cyan (#00B4D8). When the polygons shrink below a few pixels, the layer shows them as a solid fill instead of a mesh of lines, and switches back as you zoom in. Layers stack in the order you add them; the order option (smaller is lower) fixes the order whatever the sequence of calls. Any number of layers can be on the map at once, on both backends (WebGPU and WebGL2).

2.3 Paint

setPaint(paint, filter?) takes MapLibre paint properties. Each value is a constant or an expression (§4). The expressions are evaluated once, in JavaScript, for every feature, and the results are written into a style table — one texel per feature. The GPU reads that table while it draws; no expression runs per frame. A restyle is one pass over the features plus one texture update. The geometry is never rebuilt. For the 1,919 municipalities of Japan the table is 31 KB.

Property	Applies to	Value
fill-color	polygons	colour
fill-opacity	polygons	0–1, multiplies the colour's alpha
line-color	lines and polygon outlines	colour
line-width	lines and polygon outlines	CSS pixels, in steps of 1/8, up to 31.875 · 0 = no line
circle-color	points	colour
circle-radius	points	CSS pixels, in steps of 1/4, up to 63.75 · 0 = no point
line-opacity	lines, outlines and points	0–1, multiplies the line or circle colour's alpha

Every property can be data-driven. Colours are CSS colours: #rgb, #rgba, #rrggbb, #rrggbbaa, rgb()/rgba() with commas, hsl()/hsla() and the CSS colour names. Lines and points share one colour slot per feature, so line-opacity also fades points.

• Once a layer has a paint, only fill-color fills its polygons. Leave it out and they are outlines at every zoom.
• To hide a line, set its width to 0 — and a point, its radius. A fully transparent line or circle colour falls back to the default colour.
• setPaint replaces the whole paint: pass every property you want, each time. setPaint(null) returns to the default style. To change one property at a time, use the MapLibre-shaped entrance (§6.5).

2.4 Filter

setFilter(expression) hides every feature for which the expression is false; setFilter(null) shows them all again. Like paint, the filter is evaluated once and written into the same table — nothing is rebuilt. A hidden feature is not drawn, and it takes no part in the fill, so it cannot spoil the fill of what lies under it (§5). It also drops out of hover and of questions: the answer is the next feature under the pointer, as if the hidden one were not there.

The filter lives in the same table as the paint. A filter given before the first setPaint is kept and applied with it; setPaint(paint, filter) sets both in one call.

2.5 Ask

One layer holds the cursor at a time: hover, the tip, the highlight and layer.on("click") belong to it. Adding an interactive layer gives it the cursor, layer.activate() moves it, and a layer added with interactive: false never takes it — the layer that held the cursor keeps it. Hover is continuous — a pick every 32 ms — so it stays on one layer and costs one pick. A click is rare, so it can afford to ask every layer. A layer of lines only (no polygons, no points) does not answer hover yet; ask it through map.on("click") or query.

layer.on("hover", f => …);        // { fid, properties } or null
layer.on("mouseenter", f => …);   // entering a feature: { fid, properties }
layer.on("mouseleave", e => …);   // leaving it: { fid }
layer.on("click", e => …);        // { fid, properties, lngLat: [lng, lat] }

map.on("click", ({ lngLat, hits }) => {   // every Gint layer under the point, top first
  for (const { layer, fid, feature } of hits) …
});

A fid is the index of a feature inside its own layer — two layers both have a feature 7 — so keep it together with its layer.

layer.query(lngLat) and map.queryAll(lngLat) answer at once, in JavaScript, with no round trip to the GPU. They look for a point within 50 m, then a line within 30 m, then the smallest polygon that contains the position — a click on a ward inside a city returns the ward. Features hidden by the filter are skipped.

• map.queryAll and map.on("click") answer what is shown now. A layer switched off with setVisible(false), or outside its zoom range, is left out. Layers added with interactive: false are included — a click can tell you that a parcel is also inside a hazard zone. The layers the globe draws for itself, such as the country outlines, never appear.
• layer.query asks one layer on purpose. It answers even when the layer is switched off or outside its zoom range.

2.6 More on the handle

• Labels. label: { field: ["get", "name"], size: 13, color: "#fff", halo: "#000" } in the options, or setLabel(…) later. The labels share the collision and fading of the basemap's own labels, and follow the filter. field is an expression (or a function of the properties); a plain string is shown as it is, on every feature.
• Feature state. setFeatureState(fid, { selected: true }), read in paint with ["feature-state", "selected"]. Many calls in one task are drawn in one frame.
• Zoom. ["zoom"] in a paint or a filter is read when you set it. When the camera stops after moving a quarter of a zoom level or more, the layer evaluates again by itself. The change comes at rest, not during the zoom.
• Data. setData(pbf) swaps the data; the handle, its events, the paint and the filter stay.
• The rest. setOrder(n), setVisible(bool), remove() — §6.

3. Choropleths — Three Examples

3.1 Municipalities, coloured from your own table

The values often live in a table — a census CSV, a spreadsheet — and not in the boundary file. There is no need to edit the data: build a match from the table. Two thousand labels are fine, because the expression runs once, not per frame.

// Your table: municipality code → value (for example population from a census CSV)
const values = { "13101": 66680, "13102": 169179, /* … */ };
const breaks = [10000, 50000, 100000, 300000, 1000000];
const colors = ["#f7fbff", "#c6dbef", "#6baed6", "#3182bd", "#08519c", "#08306b"];
const classOf = v => breaks.filter(b => v >= b).length;

// "N03_007" = the code field of Japan's national boundary data; use your own field name
const fill = ["match", ["to-string", ["get", "N03_007"]]];
for (const [code, v] of Object.entries(values)) fill.push(code, colors[classOf(v)]);
fill.push("rgba(0,0,0,0)");                       // not in the table: no fill

await layer.setPaint({ "fill-color": fill, "fill-opacity": 0.85, "line-color": "#ffffff", "line-width": 0.3 });

match compares with ===: the text "13101" is not the number 13101, so the input is passed through to-string. The number of colours does not change the cost of drawing. Every feature may have its own colour — the fill is two passes whether there are six colours or 1,919.

3.2 Parcels, by lot number

Japan's land registry map (登記所備付地図, published by the Ministry of Justice; geopbf reads its XML directly) gives each parcel a lot number, 地番. In central Sapporo — 57,341 parcels — the same field also holds words: 道 (road), 河川 (river), 無地番 (no lot number), 筆界未定地 (boundary not settled). One expression puts public land and unsettled boundaries on the map:

await parcels.setPaint({
  "fill-color": ["match", ["get", "地番"],
    ["道", "河川", "無地番"], "#e41a1c88",  // road, river, no lot number
    "筆界未定地", "#ff7f00aa",                // boundary not settled
    "rgba(0,0,0,0)"],                           // every other parcel: no fill
  "line-color": "#ffffff66",
  "line-width": 0.5,
});

A match label can be an array: any of its values selects the output.

3.3 Two layers — a parcel inside a hazard zone

Put a hazard layer under the parcels. The parcels hold the cursor; a click reaches both.

// Landslide warning zones (Japan's National Land Numerical Information A33). A33_002 = 2: special warning zone
const zones = map.addGint(await geopbf(zonesUrl, { gint: true }), { order: -1, interactive: false });
await zones.setPaint({
  "fill-color": ["match", ["to-number", ["get", "A33_002"]], 2, "#c0392b80", "#d9a4416b"],
  "line-width": 0,                                 // fill only, no outline
});                                                   // interactive: false — the cursor stays on the parcels

map.on("click", ({ hits }) => {
  const parcel = hits.find(h => h.layer === parcels);
  const zone   = hits.find(h => h.layer === zones);
  if (parcel && zone) console.log(parcel.feature.properties["地番"], "is in a warning zone");
});

Turning a layer on and off is setVisible — nothing is baked again. The questions “which zone is this parcel in?” and “what is under this point?” are the reason Gint exists: the layers are data, not only pictures.

4. Expressions — What Is Promised

The expressions are MapLibre's. The set below is promised for Gint layers: it is the set listed in the type definitions (globe.d.ts) and it is tested. The evaluator is shared with the basemap, which reads MapLibre style files, so it accepts more operators than these; the others are not promised for Gint layers.

Group	Operators
Data	get has feature-state geometry-type zoom literal
Choice	match case step coalesce
Interpolation	interpolate — ["linear"] and ["exponential", base], numbers and colours
Comparison and logic	== != > >= < <= ! all any in
Arithmetic	+ - * / % ^ min max
Types and text	to-number to-string concat
Variables	let var

4.1 Rules

1. Once, not per frame. Expressions run when you call setPaint or setFilter (and when feature state changes). The GPU only reads the results.
2. ["zoom"] is a snapshot. It is the zoom at evaluation time; the layer re-evaluates when the camera stops (§2.6). There is no interpolation between frames.
3. No exceptions. When an expression fails or gives the wrong type for a feature, that feature keeps the default: no fill, a 1 px line, a 1.5 px point. An operator outside the evaluator gives the default too.
4. Strict equality. ==, != and match compare with ===. Convert with to-string or to-number when the types differ.
5. in is ["in", needle, haystack], where the haystack is a string or an array (["literal", […]]).
6. Colours interpolate in RGB, and may be nested — an interpolate inside a match branch works.

5. When Data Overlaps

Real data overlaps: a prefecture polygon over its municipalities, a zone registered twice, parcels drawn over each other. Gint fills by the nonzero winding rule — the even-odd rule is never used — so overlaps behave in a way you can predict:

• One colour (no paint, or the same colour for all): the union is filled. Two copies of the same parcel fill like one; a hole covered by another feature is filled.
• A colour per feature (a choropleth): where two features overlap, the later one in the data — the higher fid — wins. If that one is transparent or filtered out, the one below shows through. This is exact where two features overlap; where three or more pile up, the result is not guaranteed.
• Filtered features take no part in the fill. When a dataset mixes levels — municipalities together with the larger polygons that contain them — filter out the level you are not painting, and the rest fills cleanly.
• Questions return the smallest polygon that contains the point and is not hidden by the filter.

One limit: the per-feature fill adds feature numbers in a float target. On GPUs that cannot blend 32-bit floats, the numbers are 16-bit and a layer can colour up to 2,047 features one by one; a larger layer loses the per-feature fill and is drawn in its plain style. If you meet this limit, merge the features that share a style into multi-polygons — the fill cost is the same.

6. API Reference

7. Pipeline Overview

8. Encoding — Topology, Vertex Codes, Ranks

8.1 Shared arcs

The encoder (Rust compiled to WebAssembly, run in a worker) splits every ring and line at junctions into arcs, and stores each arc once. A polygon is a list of arc references — [fid][nRings][arcCount][±arcIdx…], where a reversed arc is written ~idx. Two neighbouring municipalities share their border arc, so it is simplified identically for both: no slivers, no gaps, at any zoom. Lines and a neighbour list are stored in separate streams.

8.2 The 64-bit vertex code

Longitude and latitude become integers — ix = (lon + 180) × 107, iy = (lat + 90) × 107 (about 1 cm) — and their bits are interleaved (Morton order) into one 64-bit code. The code also carries the vertex's level of detail:

Long arcs get an extra L1 vertex every 1° along the great circle (a degree anchor), so a long edge can never be simplified into a chord that cuts across the curve of the Earth.

8.3 Visvalingam–Whyatt rank

Each interior vertex is weighted by the Visvalingam–Whyatt effective area — the area of the triangle it forms with its neighbours, carried as a running maximum so a vertex never outranks the ones removed before it, and corrected by cos(latitude). The area becomes a 6-bit rank:

The same formula, fed the ground area of one screen pixel, gives the rank the current zoom needs (§9). Rank and zoom speak the same unit.

8.4 GintBUF

The result is one buffer: a 64-byte header (magic "Gint", version, counts, bbox, stream lengths), then the arc vertex codes, the point codes, per-arc metadata [offset, length, weight, –, bbox], and the polygon, line and neighbour streams. It is cached in IndexedDB, so a second visit skips the encoder entirely.

9. Level of Detail in the Vertex Shader

The bake step turns arcs into edges (vertex A → vertex B) in an integer texture. Each frame:

1. Required rank. The ground area of one pixel goes through the rank formula: rank = floor(1.5·log2(pxArea) + 61.524).
2. Discard. The vertex shader drops every edge whose start vertex ranks below it.
3. Forward snap. The surviving edge's end is moved forward to the next vertex that is kept. The simplified line stays connected — no gaps, no T-junctions, because the decision is made per vertex, and a shared arc makes the same decision for both polygons.

Nothing is uploaded when you zoom. What changes is one uniform.

9.1 Tiers and chunks

A national dataset can have millions of edges. Two structures keep the vertex shader from touching them all:

• Tier ladder — up to 9 pre-filtered edge lists, each at most 600,000 edges. The steps adapt to the dataset's own histogram of weights (only for datasets over 200,000 edges). A frame draws the lightest tier that still contains every vertex the current rank needs.
• Culling chunks — edges are grouped in blocks of 16,384, ordered by the Morton code of each feature's bbox centre, so features near each other sit together. Only the runs of chunks inside the view are drawn; each feature is also tested against the view on the GPU by its bbox.

10. Filling Polygons Without Triangles

Polygons are never triangulated. Each polygon's edges are drawn as a fan from a pivot — the centre of that feature's bbox — into the stencil buffer: front-facing triangles increment, back-facing triangles decrement (nonzero winding). A second pass covers every pixel whose count is not zero. Concave shapes and holes come out right with no special cases; the fan's own overlaps cancel.

• Boundary meta. An arc shared by two polygons of the same fill cancels in the winding count, so it need not be drawn in the fill at all. The bake step drops arcs whose net reference is zero, so for a dense partition — parcels, districts — a one-colour fill costs roughly the length of the outer boundary, not the number of features inside it. The fan of this fill uses one pivot for everything, because the kept arcs of many features form mixed loops. In central Sapporo (about 370,000 edges of parcels) this took a mid-zoom frame from 20–37 ms to about 2 ms.
• Low zoom. When the features are smaller than a few pixels, the layer switches to a solid fill and fades back as you zoom in; while the camera moves, that switch is held a little longer so it does not flicker.
• Choropleth. For a map coloured per feature, each fan triangle adds ±(feature id + 1) and ±1 into a float target; dividing the two recovers the id per pixel, and the style table turns it into a colour. The number of passes does not depend on the number of colours. A fourth channel keeps the largest id that touched the pixel, which decides overlaps (§5). This fill needs every edge: the cancelling of shared arcs works only when the two sides have the same colour.
• Moving camera. A frame has a budget of 250,000 edges while the camera moves. Over it, a layer draws a cheaper form — the outline, or a one-colour silhouette — and the full picture comes back when the camera stops.
• Fill switches itself off above 2 million edges (fillMaxEdges); lines still draw.

11. Lines and Styles

Each edge is drawn as a small quad (six vertices) with a capsule signed-distance function, so lines have round joins and ends at any width without extra geometry. Colour, width, point radius and flags come from a per-feature style table on the GPU, and a 256-slot style table and dash table serve shared styles — restyling a map is a texture update, not a rebuild.

12. On a Sphere — Horizon and Antimeridian

• Horizon. Vertices on the far side of the globe are projected onto the horizon circle in 3D, so a polygon that straddles the horizon keeps a closed outline and still fills correctly. Features entirely on the far side are culled by a spherical-cap test.
• Antimeridian. Features that cross ±180° are cut there when encoded; the seam edges are recognised and never drawn, so the cut is invisible.

13. In 3D — On the Terrain

• Fills are painted into the ground texture that the terrain samples — the same one that carries raster maps — so they lie exactly on the ground, whatever its shape.
• Lines and points are draped on the same elevation field. Long edges are subdivided on the GPU according to the terrain under them (instanced draws, within a budget), so a border crossing a mountain range follows the ridges instead of cutting through them.
• Parts hidden behind terrain are shown as a faint dashed line when the camera is still — you can see where a boundary goes behind a mountain.

14. Asking Questions — Picking and Identify

• Lines and points are picked on the GPU: each is drawn with its feature id into a small target, which is read back asynchronously (a pixel buffer and fence on WebGL2, copyTextureToBuffer + mapAsync on WebGPU).
• Polygons are answered in JavaScript by a point-in-polygon test with bbox rejection, smallest wins — a click inside a ward inside a city returns the ward. About 1,900 Japanese municipalities answer in 0.5–4 ms. A line or point under the pointer comes before the polygon around it.
• The pick target is built when the camera stops, for the active layer only — one target, however many layers.
• Hover highlights the feature (a thicker outline) and can darken everything outside it.

15. Design Philosophy

How geographic data is represented is also a choice about which level of detail to treat as "reality." Just as Natural Earth's physical/cultural distinction organizes phenomena on Earth from a human perspective, Gint's level-of-detail design implements the idea that what is visible changes with scale.

The Visvalingam–Whyatt weight quantifies "how much shape would be lost by removing this vertex." It is a measure of significance — a way to separate the essential structure of a coastline or boundary from detail that only matters at finer scales. Packing it into the vertex code itself means the data carries its own answer to "what should be seen at this scale."

Two quirks belong to globes, not flat maps: polygons crossing the antimeridian must be cut, and polygons crossing the horizon must be closed along it. They are the quiet surprises that separate a flat map renderer from a globe renderer.

The API follows the same idea from the other side. The data stays as it is — the paint is a view of it, computed once and kept beside it. Borrowing MapLibre's words is not about being a copy; it is about letting what people already know carry over.