Documentation
¶
Overview ¶
Package geodata embeds vector boundary data (countries + admin-1 regions) for Prism's geoshape mark. It exposes two surfaces:
Manifest: a lightweight catalog of feature IDs, names, ISO codes, and bounding boxes. Embedded into every build (host + WASM) so validate/inspect/plan stay no-execute. ~100 KB ungzipped.
Store: feature geometries (polygon rings, projected later by encode/projection). For the host build the full TopoJSON tier archives are embedded via //go:embed (~6 MB on disk, acceptable for a CLI binary). For the WASM build the embeds are absent and the loader auto-fetches the tier from `prism static-bundle`'s geodata/ directory on first access.
Tier conventions:
world-110m — Natural Earth admin-0 at 1:110m (countries; coarse). world-50m — Natural Earth admin-0 at 1:50m (countries; standard). admin1-50m — Natural Earth admin-1 at 1:50m (states/provinces).
Feature IDs follow ISO conventions:
admin-0 features: ISO 3166-1 alpha-3 (USA, CAN, GBR, …) admin-1 features: ISO 3166-2 (US-CA, CA-ON, GB-ENG, …)
Source of truth: Natural Earth Data (public domain, naturalearthdata.com). Regenerated via `make geodata`, which runs internal/tools/build_geodata. The committed *.topo + manifest.bin are the inputs `make build` honours — no network required at build time.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EmbeddedManifestBytes ¶
func EmbeddedManifestBytes() []byte
EmbeddedManifestBytes returns the manifest.json bytes as embedded at build time. Available on both host and WASM builds because manifest.go has no platform constraint.
func EmbeddedTierBytes ¶
EmbeddedTierBytes returns the on-disk bundle bytes for the given tier as embedded into the host binary. Host-only (the wasm build does not embed; it fetches). Returns an error for unknown tiers.
Consumers (cmd/prism static-bundle) use this to copy the geodata artifacts to disk without duplicating //go:embed directives.
Types ¶
type BBox ¶
type BBox struct {
West float64 `json:"w"`
South float64 `json:"s"`
East float64 `json:"e"`
North float64 `json:"n"`
}
BBox is a longitude/latitude bounding box. West/East may straddle the antimeridian (West > East) for features that cross 180°.
type Feature ¶
Feature is the resolved geometry payload returned by Store.Lookup. Coordinates are raw longitude/latitude (degrees); projection happens in encode/projection. Rings follow the GeoJSON winding convention: outer rings counter-clockwise, holes clockwise.
type FeatureMeta ¶
type FeatureMeta struct {
ID string `json:"id"`
Name string `json:"name"`
ISOA2 string `json:"iso_a2,omitempty"`
Centroid [2]float64 `json:"c,omitempty"` // [lon, lat]
BBox BBox `json:"bb"`
Tier Tier `json:"t"`
// Parent links an admin-1 feature to its admin-0 ISO alpha-3 (e.g.
// US-CA's Parent = "USA"). Empty for admin-0 features.
Parent string `json:"p,omitempty"`
}
FeatureMeta is the manifest-resident record for one feature. Carries only what validate / inspect / plan need: ID, name, ISO codes, and the rough geographic envelope. Geometry lives in the per-tier topo archive and is loaded lazily via Store.
type Manifest ¶
type Manifest struct {
Version int `json:"version"`
Features map[string]*FeatureMeta `json:"features"`
}
Manifest is the catalog embedded in every build. Indexed by feature ID for O(1) lookup.
func LoadManifest ¶
LoadManifest returns the embedded manifest, parsing it on first call. Safe for concurrent use. Subsequent calls return the cached pointer.
func MustLoadManifest ¶
func MustLoadManifest() *Manifest
MustLoadManifest panics on failure. Intended for package init paths that cannot recover (the embedded manifest is supposed to be well-formed; if it isn't, the build is broken).
func (*Manifest) FeatureIDs ¶
FeatureIDs returns every feature ID in the manifest, sorted. Useful for validation error messages ("did you mean ...").
func (*Manifest) FeatureIDsForTier ¶
FeatureIDsForTier returns the sorted IDs that belong to the given tier. Useful for choropleth fixtures and for trimming the search space in error suggestions.
type Polygon ¶
Polygon is one outer ring plus zero or more holes. A feature with multiple disjoint pieces (e.g. an archipelago) is represented as multiple Polygon entries on Feature.
type Ring ¶
type Ring [][2]float64
Ring is a closed sequence of [lon, lat] pairs. The first and last point are NOT required to match — renderers close the ring.
type Store ¶
type Store interface {
// Lookup returns the feature for id at the requested tier. When the
// tier archive is not loaded yet the implementation loads it
// (host: decode embed; wasm: fetch + decode) and caches the result.
Lookup(tier Tier, id string) (*Feature, error)
// Preload eagerly decodes the tier. Optional; Lookup pulls in
// lazily. Useful in renderers that know they'll need many features
// from the same tier.
Preload(tier Tier) error
}
Store resolves a feature ID to its raw lon/lat geometry. The host implementation reads from embedded TopoJSON; the WASM implementation fetches from `prism static-bundle` on first use. Both are safe for concurrent use after primer initialisation.
func DefaultStore ¶
func DefaultStore() Store
DefaultStore returns the platform-default Store. On host builds it reads from embedded TopoJSON; on WASM it fetches from the static bundle origin set via SetWasmBundleURL.
Source Files