Documentation
¶
Overview ¶
Package projection maps geographic coordinates (longitude / latitude in degrees) to plot-space pixels for the geoshape mark family.
Every implementation satisfies the Projection interface:
type Projection interface {
Project(lon, lat float64) (x, y float64, ok bool)
Configure(opts Options)
}
Coordinates outside the projection's valid domain (e.g. the poles for Mercator) return ok=false; the encoder treats them as a clip signal and drops the offending segment.
Built-in projections (P18):
mercator — Web Mercator (EPSG:3857), classic web-map default. equirectangular — Plate carrée; lon/lat → x/y linearly. naturalearth — Natural Earth pseudocylindrical (smooth, balanced). albers_usa — Composite Albers projection covering CONUS + AK + HI. orthographic — Globe view from infinity along the configured Rotate.
Pixel coordinates pass through render.FormatFloat (3-decimal pin) at SVG emission time. Projection math runs in float64; rounding lives at the renderer boundary, not here.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Available ¶
func Available() []string
Available returns the canonical projection names in stable order. Used by validate error messages.
func SizeFromBBox ¶
func SizeFromBBox(p Projection, bboxW, bboxS, bboxE, bboxN, pxW, pxH float64) (scale float64, translate [2]float64)
SizeFromBBox returns a Scale + Translate pair that fits the given lon/lat bbox into the supplied pixel rectangle for a unit-sphere projection (mercator / equirectangular / naturalearth). The encoder calls this when the spec leaves Scale/Translate unset, so charts auto-fit their data extent.
Types ¶
type AlbersUSA ¶
type AlbersUSA struct {
// contains filtered or unexported fields
}
AlbersUSA is the composite Albers equal-area projection that lays Alaska and Hawaii adjacent to CONUS in inset boxes. Matches d3-geo's geoAlbersUsa() layout (CONUS via lower48 parallels 29.5° / 45.5°, AK as a 35%-scaled inset bottom-left of CONUS, HI as a 100%-scaled inset to the right of AK).
Per-vertex dispatch follows d3's stream pattern: try each sub-projection in turn, accept the first whose projected pixel lands inside the sub-projection's pixel-space extent. Vertices outside every extent return ok=false so the encoder drops them. This stops multipart features (e.g. the Aleutian chain crossing -180°) from half-projecting through the wrong sub-projection.
type Equirectangular ¶
type Equirectangular struct {
// contains filtered or unexported fields
}
Equirectangular is the plate-carrée projection. Linear in both dimensions: x = scale * (lon - centerLon), y = -scale * (lat - centerLat). Has no domain restrictions.
func (*Equirectangular) Configure ¶
func (e *Equirectangular) Configure(o Options)
func (*Equirectangular) Name ¶
func (e *Equirectangular) Name() string
type Mercator ¶
type Mercator struct {
// contains filtered or unexported fields
}
Mercator is the conformal Web-Mercator projection. Domain is (lon ∈ [-180, 180], lat ∈ (-85.0511, 85.0511)). Latitudes outside the bounded strip map to ok=false (the encoder drops them); this matches d3-geo's behaviour and prevents the ±∞ blowup at the poles.
type NaturalEarth ¶
type NaturalEarth struct {
// contains filtered or unexported fields
}
NaturalEarth implements Tom Patterson's "Natural Earth" projection (a pseudocylindrical compromise between distortion and aesthetics). Polynomial form per Šavrič et al. 2011.
func (*NaturalEarth) Configure ¶
func (n *NaturalEarth) Configure(o Options)
func (*NaturalEarth) Name ¶
func (n *NaturalEarth) Name() string
type Options ¶
type Options struct {
// Scale is the radius the projection treats as one unit of distance
// on the plot. For a unit-sphere projection (mercator, equirect),
// Scale ≈ pixels-per-radian / (2π). The encoder sizes Scale from
// the plot rectangle when unset.
Scale float64
// Center is the [lon, lat] focal point of the projection in degrees.
// Equirectangular and Mercator translate so Center maps to the
// plot's geometric centre.
Center [2]float64
// Rotate is the [lambda, phi, gamma] rotation in degrees applied
// before projection. Used by orthographic (defaults to {0,0,0})
// and by composite Albers presets. Mercator ignores it.
Rotate [3]float64
// Translate is the [px, py] pixel-space origin the projected
// coordinates anchor on. Defaults to the plot rectangle's centre.
Translate [2]float64
// ClipExtent is the optional [[minX, minY], [maxX, maxY]] rectangle
// outputs are clipped to. Zero value disables clipping; callers
// (encoder) set it to the plot rect.
ClipExtent [2][2]float64
}
Options carries the parameters every projection accepts. Fields not applicable to a given projection are ignored (e.g. Mercator ignores Rotate's roll axis). Defaults documented per-projection in New.
type Orthographic ¶
type Orthographic struct {
// contains filtered or unexported fields
}
Orthographic projects onto a plane tangent to the rotated globe. Hemisphere clipping is enforced by ok=false for points on the far side. Rotate[0]=lambda, Rotate[1]=phi are honoured; Rotate[2] (roll) is ignored — Prism currently has no UI gesture that exposes roll.
func (*Orthographic) Configure ¶
func (o *Orthographic) Configure(opts Options)
func (*Orthographic) Name ¶
func (o *Orthographic) Name() string
type Projection ¶
type Projection interface {
// Project maps (lon, lat) degrees to (x, y) pixels. ok=false means
// the input is outside the projection's valid domain (e.g. ±90°
// latitude under Mercator) and callers should drop the segment.
Project(lon, lat float64) (x, y float64, ok bool)
// Configure replaces the projection's options.
Configure(opts Options)
// Name returns the canonical projection identifier
// ("mercator", "equirectangular", ...).
Name() string
}
Projection projects geographic coordinates into pixel space.
Source Files