geo

Geographic projection plus a project-once GeoJSON pipeline. fitProjection fits any d3 projection to a feature collection and viewport, featureGroup projects features into a core!Scene group exactly once, and viewTransform / lonLatFromScreen / referenceFromScreen map between screen, reference, and lon/lat space.

import { fitProjection, featureGroup } from "@mapequation/d3gl/geo";

const projection = fitProjection(geoNaturalEarth1(), featureCollection, width, height);
scene.group("cells", featureGroup(features, projection, { id: (f) => f.id, lineWidth: 0.5 }));

Interfaces

Interface	Description
FeatureAccessors	How to derive a drawable id (and optional stroke width) from a feature.
GeoLayerOptions	-

Type Aliases

Type Alias

Description

GeoInput

A GeoJSON object d3-geo can project + render (feature, geometry, or collection), plus the GeoJSON-adjacent GeoSphere ({ type: "Sphere" }) that d3-geo’s projections and geoPath accept natively to draw the whole-globe outline (the ocean/graticule background). GeoSphere isn’t part of the GeoJSON spec, so it has to be unioned in explicitly — without it, callers must cast a Sphere with as any / as unknown as GeoInput.

Functions

Function	Description
featureGroup	A Scene.group builder that projects each GeoJSON feature ONCE with projection (via geoPath into the drawable’s PathContext) and registers it as a drawable. After this, the GPU renders, recolors, and pans/zooms without re-projecting.
fitProjection	Fit a d3 projection so object’s bounds fill a width x height viewport. Mutates + returns it.
geoLayer	A Scene.group builder projecting any GeoJSON geometry once. Points → analytic circles.
lonLatFromScreen	Screen pixel -> lon/lat: undo the zoom transform, then the projection. Returns null if the projection cannot invert the point (e.g. outside the globe).
projectVisiblePoint	Project a Point’s [lon, lat] to screen coords, or return null when it isn’t visible. A raw projection(point) returns coordinates even for back-facing points (they fold onto the front disc). An azimuthal projection reports a positive clipAngle (e.g. orthographic ≈ 90°); others report 0 (no angular clip). When azimuthal, cull points whose great-circle distance from the view centre exceeds that angle. Shared by geoLayer and the pass-through path so both cull identically.
referenceFromScreen	Invert the d3-zoom pixel transform: screen pixel -> reference (projected) pixel. screen = k*reference + (x,y) => reference = (screen - (x,y)) / k.
viewTransform	Turn a d3-zoom transform {k,x,y} into the column-major clip-space mat3 the renderer’s setTransform expects (re-export of the GPU view matrix builder).

References

ViewTransform

Re-exports ViewTransform