canvas.geo

#The geographic environment

canvas.geo is a map surface. Its implicit attribute is in, the boundary pack the environment is drawn over, so canvas.geo:world{ } is already a world map with nothing inside it. The committed packs are world (Natural Earth 110m countries) and six admin-1 sets — us-states, canada-provinces, australia-states, uk-counties, nz-regions and europe-admin1. Every overlay in the body inherits that pack unless it names its own. title captions the environment, projection chooses how the sphere is laid flat, and show-scale (on by default) says what a length on screen is worth on the ground.

canvas.geo:world{
    marker(at: 48.85, 2.35; label: Paris)
}(
    title: Where the survey ran
    projection: equal-earth
)

Boundaries a pack does not carry — electorates, catchments, council wards — arrive as an attached .geojson file, and in names it the same way it names a pack: in: #wards, pointing at an @data declaration. Either way the geometry is drawn as SVG, exactly as a graph mark is, and nothing is fetched from a tile server — which is what lets a map render offline, under both themes, and identically in ten years.

#centre, zoom and the fly-to

A geographic environment is framed by a camera rather than by a pair of domains: centre — latitude first — and zoom, in web-map doubling levels, where 1 fits the world's width and each level halves the span. Omit them both and the environment fits its own contents across the whole choreography, so a marker that travels stays framed at every point of its journey.

Both are animatable, and a !cue.to on each with the same anchor is the fly-to. A centre may also be written as #id naming a marker the environment already draws, so a map framed on Tokyo that also pins Tokyo states the place once; a keyframe onto a reference snaps rather than gliding, because a reference has no midpoint to interpolate through.

canvas.geo#tour:world{
    region(in: world; only: France, Germany; fill: teal)
}(
    centre: 20, 0 !cue.to{50.5, 15}(at: 1; over: 900ms)
    zoom: 1 !cue.to{4}(at: 1; over: 900ms)
)

interactive: true hands the camera to the reader — scroll to zoom, drag to pan, double-click to reset. Exploration stays on the environment's subject: the zoom floor is the frame that fits its packs, markers and arcs, so a reader cannot lose the map. Their camera then overrides the authored one for the session, and continue: #that-environment carries it into a later environment along with their parameter values.

#Overlays

Everything drawn over the basemap is an overlay, and the four share opacity and hidden (declared but not drawn, and animatable, so hidden: true !cue.to{false}(at: 2) is a reveal). Cues wrap overlays exactly as they wrap graph marks. The attention cues do not reach this environment: a highlight ring and a spotlight are plot machinery, and a geographic environment admits only cue and cue.draw.

#Boundary layers

The environment's in: already draws its pack, so a region is for what a basemap cannot say: a subset in its own colours, a second pack layered over the first, an attached.geojson over a committed pack, or boundaries that arrive on a cue. only and except narrow it by name or ISO alpha-3 code, matched case-insensitively — France, DEU and Ivory Coast all read — and fill, stroke and width paint what is left.

canvas.geo:world{
    region(in: world; except: Antarctica)
    region(in: world; only: France, Germany, Italy; fill: teal)
}

#Joining a dataset to regions

choropleth joins a @data column onto the pack's regions — the geographic sibling of the graph's heatmap. regions names the column of region names and values the column to shade by; join keys match pack names and short codes case-insensitively, and a region the join does not cover keeps the neutral land fill rather than disappearing.

What values holds decides the reading. A numeric column shades through a ramp — multicolour, temperature, or a single hue's own intensity — with range pinning the window. A text column enumerates instead: each distinct value becomes a category with its own flat hue, named by key, and intensity gives depth within that hue. That pair is the electoral map's own grammar — the winner names the colour, the margin names how solid it is.

canvas.geo:australia-states{
    choropleth(
        regions: #vote.state
        values: #vote.party
        intensity: #vote.margin
        key: Labor red, Coalition blue, Greens green
    )
}(
    title: Who led each state
)

#Places

marker is a point on the earth, in two forms. Singly, at takes a coordinate, latitude first, with an optional label; either half may be a parameter expression, so a marker rides a slider or a keyframe. Data-bound, lat and lon name columns and the one node draws every row — add size-by and symbol area scales with that column, which is the proportional-symbol map.

canvas.geo:world{
    marker(lat: #quakes.lat; lon: #quakes.lon; size-by: #quakes.magnitude; colour: red; opacity: 0.6)
}

#Great-circle routes

arc draws the great-circle path between two places — the shortest route over the earth, drawn the way the earth actually is. On a mercator environment the London–Tokyo arc bends far north of the straight line between them, and that one element is the whole projection-distortion lesson. Either end may be #id naming a marker in the same environment, and an anchored end follows its marker. An arc publishes derived distance in kilometres — the number the arc is.

canvas.geo:world{
    marker#london(at: 51.47, -0.46; label: London)
    marker#tokyo(at: 35.55, 139.78; label: Tokyo)
    cue.draw{
        arc#route(from: #london; to: #tokyo; label: {{round(#route.distance, 0)}} km)
    }(
        in: 1
        in-duration: 1200ms
    )
}(
    projection: mercator
)

#Moving a map through time

A map moves through time in one of two ways, and which one is a fact about the data. For a handful of periods, chain the columns: values is animatable, so #y1990.rate !cue.to{#y2000.rate}(at: 1) eases every region between its own two readings. Pin range when you do, or the ramp re-normalises each frame and the change erases itself.

For long-format data — one row per region per period — parameter.time is the better tool. It is an ordinary parameter under the skin, but it takes its range from the data rather than being told one, reads as a period, and can play. Name the period column and the environment gains a scrubber over exactly that span; marks carrying a period slice themselves against it, interpolating between the two periods that bracket wherever the reader is standing.

canvas.geo:world{
    parameter.time#years(period: #rates.year; name: Year; duration: 12s)
    choropleth(regions: #rates.country; values: #rates.rate; period: #rates.year; range: [0, 220])
}

Parameters and cues gives the rule the choice actually turns on: a change belongs to a scrubber when one sentence holds across its whole range, and to a cue otherwise.

#Derived attributes

Two overlays compute something and publish it for reading: a choropleth's min, max, mean and count, and an arc's distance. A parameter.time publishes value, the period the reader is standing on. Reach one by member access on the node's id — #route.distance in an attribute, {{#route.distance}} in prose. Derived attributes covers how they behave.