Documentation
¶
Overview ¶
Package worldmap renders a schematic world choropleth: countries from the embedded Natural Earth 110m admin-0 asset, filled by a per-country value through a colormap, drawn Go-side into a content-versioned texture (ADR-0114). Fixed camera — the whole world at once; deliberately no pan, no zoom, no tiles.
The widget is data-agnostic: callers resolve their own strings via Atlas.Resolve and hand a map[CountryIdx]float64 to SetValues.
Map and interaction live in one paintCanvas (ADR-0114 Update 2026-08-01): the choropleth ships as a paintImage — still one rasterization per data change, not per frame — and the hovered country is outlined over it with the concave painter fill. Hover hit-testing maps the canvas-relative pointer (R24) onto the per-pixel country index buffer the same rasterization pass produces: O(1), no geometry math at frame time.
Index ¶
- Variables
- func ProjectionAspect() float64
- type Atlas
- type Country
- type CountryIdx
- type Widget
- func (inst *Widget) Atlas() *Atlas
- func (inst *Widget) ClearValues()
- func (inst *Widget) Hovered() (idx CountryIdx, value float64, ok bool)
- func (inst *Widget) PixelWidth() float64
- func (inst *Widget) Render() (clicked CountryIdx, clickedOk bool)
- func (inst *Widget) SetDisplayHeight(px float64)
- func (inst *Widget) SetDisplayWidth(px float64)
- func (inst *Widget) SetPixelWidth(px float64)
- func (inst *Widget) SetPresence(present map[CountryIdx]bool)
- func (inst *Widget) SetValues(vals map[CountryIdx]float64)
Constants ¶
This section is empty.
Variables ¶
var PackageProps = packageprops.Props{ WASMWASI: packageprops.WASMCompiles, WASMJS: packageprops.WASMCompiles, WASMFreestanding: packageprops.WASMCompiles, }
PackageProps records this package's curated properties (ADR-0080). Seeded by `boxer code analysis golang wasmsurvey props generate`; curate by hand. The same group's `props verify` reconciles it.
Functions ¶
func ProjectionAspect ¶
func ProjectionAspect() float64
ProjectionAspect is the width:height ratio of the projected world extent — the raster is sized to this so the map never stretches.
Types ¶
type Atlas ¶
type Atlas struct {
Countries []Country
// contains filtered or unexported fields
}
Atlas is the parsed country set plus the resolver's key table.
type Country ¶
type Country struct {
Admin string
Name string
A2 string // ISO 3166-1 alpha-2 (upstream ISO_A2_EH); "" when absent
A3 string // ISO 3166-1 alpha-3 (upstream ISO_A3_EH); "" when absent
// contains filtered or unexported fields
}
Country is one admin-0 feature: identity fields as shipped upstream (the `_EH` ISO variants — empty when upstream has none, e.g. Northern Cyprus) plus the projected outline rings. Rings concatenate every ring of every member polygon; the rasterizer's even-odd rule makes outer/hole/member distinctions irrelevant (members are disjoint, holes alternate parity).
type CountryIdx ¶
type CountryIdx int32
CountryIdx indexes Atlas.Countries. NoCountry marks "no country" (sea in the raster index buffer, resolver miss).
const NoCountry CountryIdx = -1
type Widget ¶
type Widget struct {
// Style knobs, settable before the first Render. Colors are 0xRRGGBBAA.
SeaRGBA uint32
NoDataRGBA uint32
StrokeRGBA uint32
PresenceRGBA uint32
Palette []uint32
// HighlightFillRGBA / HighlightStrokeRGBA style the hovered country's
// painter overlay: a translucent wash so microstates still register, and
// an opaque outline. The wash is what makes the highlight legible on the
// dark end of a palette, the outline what makes it legible on the light
// end.
HighlightFillRGBA uint32
HighlightStrokeRGBA uint32
// contains filtered or unexported fields
}
Widget is the schematic world choropleth. Construct via New; all methods are render-thread-only (the imzero2 single-goroutine contract).
func New ¶
func New(ids *c.WidgetIdStack, scopeKey string) *Widget
New constructs the widget. scopeKey seeds the widget ids and the texture cache key — unique per instance within the caller's id scope. The embedded atlas is parsed on first construction (process-wide once); a parse failure is held and rendered as an error label rather than returned, so a broken asset degrades to a dead pane instead of failing app construction.
func (*Widget) Atlas ¶
Atlas exposes the shared country atlas (nil when loading failed) so the caller can resolve its identifiers to CountryIdx values.
func (*Widget) ClearValues ¶
func (inst *Widget) ClearValues()
ClearValues drops the data: every country renders as no-data.
func (*Widget) Hovered ¶
func (inst *Widget) Hovered() (idx CountryIdx, value float64, ok bool)
Hovered returns the country under the pointer (last frame's readout) and its value (NaN when the country has no data).
func (*Widget) PixelWidth ¶
PixelWidth returns the current target raster width (for binding a control).
func (*Widget) Render ¶
func (inst *Widget) Render() (clicked CountryIdx, clickedOk bool)
Render draws the map, the legend and the hover readout, and reports a country click (primary button over a country) — immediate-mode style, so the caller reacts in the same frame. Layout: the map spans the pane width at the projection's aspect, or renders at exactly SetDisplayWidth when the caller set one.
Hover and click come from last frame's canvas registers, so both lag one frame — the same lag the readout and the highlight are drawn under.
func (*Widget) SetDisplayHeight ¶ added in v0.0.14
SetDisplayHeight caps the map's on-screen height in points; the width then follows the projection aspect. Pass 0 (the default) to let the height follow the pane width instead. Display size is independent of the raster resolution set by SetPixelWidth.
func (*Widget) SetDisplayWidth ¶ added in v0.0.15
SetDisplayWidth sets the map's on-screen width in points; the height then follows the projection aspect. Pass 0 (the default) to size from the pane width instead. A finite width takes precedence over SetDisplayHeight and needs no probe, so it is the way to make an on-screen width control actually resize the map. Display size is independent of the raster resolution set by SetPixelWidth.
func (*Widget) SetPixelWidth ¶
SetPixelWidth pins the raster width (quantized to a multiple of 8, clamped to [128, 2048]; height follows the projection aspect) and stops it tracking the canvas. Callers that drive their own resolution control want this; the default is to follow the canvas so the texture is rasterized at the size it is displayed at. Re-rasterization is debounced either way, so a drag re-rasters once at rest.
func (*Widget) SetPresence ¶
func (inst *Widget) SetPresence(present map[CountryIdx]bool)
SetPresence replaces the data with membership only: the given countries fill uniformly in PresenceRGBA, everything else is no-data, and no legend renders. Used when the caller's result names countries but carries no numeric value to grade them by.
func (*Widget) SetValues ¶
func (inst *Widget) SetValues(vals map[CountryIdx]float64)
SetValues replaces the choropleth data. Missing countries render in NoDataRGBA. The colormap range is the data min/max; a single-valued or empty range widens symmetrically so the palette midpoint is used.
Source Files