README
¶
flatsphere
A Go library for converting between spherical and planar coordinates.
Prerequisites
Install
go get github.com/gracefulearth/flatsphere
Usage
Projecting/Inverse
Go from latitude/longitude pairs to points on the x/y plane, or the reverse.
mercator := flatsphere.NewMercator() // or some other projection
x, y := mercator.Project(lat, lon)
rlat, rlon := mercator.Inverse(sampleX, sampleY)
Bounds of Projection Plane
Determine the domain of the projection inverse function, to know which valid x/y values can be supplied. Helpful when iterating over the projected space.
mercator := flatsphere.NewMercator()
bounds := mercator.Bounds()
for _, xy := range flatsphere.BoundsIterate(bounds, xSteps, ySteps) {
lat, lon := mercator.Inverse(xy.x, xy.y)
// do stuff with lat, lon here ...
}
Reprojecting
Convert planar points in one projection into another projection.
origProj := flatsphere.NewMercator()
newProj := flatsphere.NewLambert()
lat, lon := origProj.Inverse(origX, origY)
newX, newY := newProj.Project(lat, lon)
Oblique Projections
Easily create variants of existing projections with different center points and rotations around the center point.
mercator := flatsphere.NewMercator() // or some other projection
transverseMercator := flatsphere.NewOblique(mercator, 0, math.Pi/2, -math.Pi/2)
x, y := transverseMercator.Project(lat, lon)
Distortion
Determine how representative of reality a projection is at a point on the sphere.
mercator := flatsphere.NewMercator() // or some other projection
areaDistortion, angularDistortion = proj.DistortionAt(lat, lon)
Projections
A list of the predefined projections supported by the package.
Invertability: all projections in this library have a well defined inverse function. However, only some of them reasonably satisfy the invertability property x = f_1(f(x)) due to floating-point error in computations, edge-cases resulting in infinities or NaNs, or ambiguity at some type of critical point (commonly the poles or prime meridian). The table below checks off invertible for all projections which satisfy the x = f_1(f(x)) property for all valid spherical locations except the poles to a reasonably fine degree of precision, referred to here as almost everywhere floating-point invertible. Oblique transforms of floating-point invertible standard projections do not necessarily share that property.
Efforts are ongoing to improve the coverage of this property to more projections where possible.
| Projection | Everywhere Floating-point Invertible |
|---|---|
| Mercator | ✅ |
| Plate carrée | ✅ |
| Equirectangular | ✅ |
| Lambert cylindrical | ✅ |
| Behrmann | ✅ |
| Gall orthographic | ✅ |
| Hobo-Dyer | ✅ |
| Gall stereographic | ✅ |
| Miller | ✅ |
| Central | ✅ |
| Sinusoidal | ✅ |
| HEALPix | ✅ |
| Mollweide | |
| Homolosine | |
| Eckert IV | |
| Stereographic | |
| Polar | |
| Lambert azimuthal | |
| Gnomonic | |
| Orthographic | |
| Robinson | ✅ |
| Natural Earth | ✅ |
| Cassini | ✅ |
| Aitoff | |
| Hammer | |
| Lagrange | ✅ |
| Vertical Perspective | |
| Oblique Vertical Perspective |
Credits
Inspired by the Map-Projections library made by @jkunimune. Right now this library is essentially a Go-flavored port of his original Java, minus a few things to keep it focused on library use cases.
Documentation
¶
Overview ¶
Example (Reproject) ¶
Example_Reproject demonstrates taking a position in one projected plane and converting it into the analogous position in a different projection.
// determine the original projection of the data
original := NewMercator()
// decide on a new desired projection of the data
target := NewCassini()
// take a point within the PlanarBounds() of the original projection
ox, oy := math.Pi, math.Pi
// get a latitude and longitude on the sphere from the original projected point
lat, lon := original.Inverse(ox, oy)
// get a projected point in the desired projection
cx, cy := target.Project(lat, lon)
fmt.Printf("original x, y: %f, %f\n", ox, oy)
fmt.Printf("target x, y: %f, %f\n", cx, cy)
Output: original x, y: 3.141593, 3.141593 target x, y: 0.000000, 1.657170
Index ¶
- func AngularDistortionAt(proj Projection, latitude float64, longitude float64) float64
- func AreaDistortionAt(proj Projection, latitude float64, longitude float64) float64
- func BoundsAspectRatio(b Bounds) float64
- func BoundsHeight(b Bounds) float64
- func BoundsIterate(b Bounds, stepsX, stepsY int) iter.Seq2[struct{ xstep, ystep int }, struct{ x, y float64 }]
- func BoundsWidth(b Bounds) float64
- func DistortionAt(proj Projection, latitude float64, longitude float64) (area float64, angular float64)
- type Aitoff
- type Behrmann
- type Bounds
- type Cassini
- type Central
- type CircleBounds
- type CylindricalEqualArea
- type EckertIV
- type EllipseBounds
- type EqualEarth
- type Equirectangular
- type GallOrthographic
- type GallStereographic
- type Gnomonic
- type HEALPixStandard
- type Hammer
- type HoboDyer
- type Homolosine
- type Lagrange
- type LambertAzimuthal
- type LambertCylindrical
- type Mercator
- type Miller
- type Mollweide
- type ObliqueAspect
- type ObliqueProjection
- type ObliqueVerticalPerspective
- type Orthographic
- type PlateCarree
- type Polar
- type Projection
- type RectangleBounds
- type Sinusoidal
- type Stereographic
- type TabularProjection
- type VerticalPerspective
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AngularDistortionAt ¶
func AngularDistortionAt(proj Projection, latitude float64, longitude float64) float64
Compute the angular distortion of a projection at a particular location.
func AreaDistortionAt ¶
func AreaDistortionAt(proj Projection, latitude float64, longitude float64) float64
Compute the area distortion of a projection at a particular location.
func BoundsAspectRatio ¶
BoundsAspectRatio returns the aspect ratio of the bounds (width / height).
func BoundsHeight ¶
BoundsHeight returns the maximum height of the bounds (YMax - YMin).
func BoundsIterate ¶
func BoundsIterate(b Bounds, stepsX, stepsY int) iter.Seq2[struct{ xstep, ystep int }, struct{ x, y float64 }]
Convenience function to iterate over points within the given bounds, dividing the area into the specified number of steps at each axis. Points returned are guaranteed to be within the bounds, but the number of points yielded may be less than (stepsX+1)*(stepsY+1) if the bounds do not cover a rectangular area.
func BoundsWidth ¶
BoundsWidth returns the maximum width of the bounds (XMax - XMin).
func DistortionAt ¶
func DistortionAt(proj Projection, latitude float64, longitude float64) (area float64, angular float64)
Compute both area distortion and angular distortion at a particular location on the sphere, for the given projection.
Types ¶
type Aitoff ¶
type Aitoff struct{}
A compromise azimuthal projection stretched into an elliptical shape. https://en.wikipedia.org/wiki/Aitoff_projection
type Behrmann ¶
type Behrmann struct {
CylindricalEqualArea
}
An equal area projection with least distortion at 30 degrees latitude. https://en.wikipedia.org/wiki/Behrmann_projection
func NewBehrmann ¶
func NewBehrmann() Behrmann
type Bounds ¶
type Bounds interface {
Min() (x float64, y float64) // Minimum X and Y coordinates of the bounding area
Max() (x float64, y float64) // Maximum X and Y coordinates of the bounding area
Within(x float64, y float64) bool // Determines whether the given point is inside the bounding area
}
Bounds represents a planar bounding area in arbitrary units, where spherical positions are mapped to the plane. The total rectangular area covered by the bounds is defined by the minimum and maximum X and Y coordinates, but the actual valid area may be a different shape (for example, a circle or an ellipse) contained within that rectangle. The Within() method can be used to determine whether a particular point is inside the valid area.
type Cassini ¶
type Cassini struct{}
A transverse version of the Plate–Carée projection, implemented directly for efficiency. https://en.wikipedia.org/wiki/Cassini_projection
func NewCassini ¶
func NewCassini() Cassini
type Central ¶
type Central struct{}
A compromise cylindrical projection with prominent use in panoramic photography, but very distorted for mapping purposes. https://en.wikipedia.org/wiki/Central_cylindrical_projection
func NewCentral ¶
func NewCentral() Central
type CircleBounds ¶
type CircleBounds struct {
Radius float64
}
Represents a circular region in arbitrary units, where spherical positions are mapped to the plane. Valid planar coordinates are within the circle of the given radius centered on the origin.
func NewCircleBounds ¶
func NewCircleBounds(radius float64) CircleBounds
Construct a bounding area containing the circle described by the given radius, centered on the origin.
func (CircleBounds) Max ¶
func (c CircleBounds) Max() (x float64, y float64)
func (CircleBounds) Min ¶
func (c CircleBounds) Min() (x float64, y float64)
type CylindricalEqualArea ¶
type CylindricalEqualArea struct {
// The stretch factor of the resulting projection based on the desired parallel of least distortion.
// If Stretch == 1, then the parallel of least distortion is the equator. If Stretch > 1, then there
// are no parallels where the horizontal scale matches the vertical scale.
Stretch float64
}
A generalized form of equal-area cylindrical projection. https://en.wikipedia.org/wiki/Cylindrical_equal-area_projection
func NewCylindricalEqualArea ¶
func NewCylindricalEqualArea(parallel float64) CylindricalEqualArea
Construct a new cylindrical equal-area projection with least distortion around the given latitude in radians.
func (CylindricalEqualArea) Bounds ¶
func (l CylindricalEqualArea) Bounds() Bounds
func (CylindricalEqualArea) Inverse ¶
func (l CylindricalEqualArea) Inverse(x float64, y float64) (lat float64, lon float64)
func (CylindricalEqualArea) Parallel ¶
func (l CylindricalEqualArea) Parallel() float64
The northern latitude (in radians) at which the map has the least distortion.
type EckertIV ¶
type EckertIV struct{}
An equal-area pseudocylindrical projection, in which the polar lines are half the size of the equator. https://en.wikipedia.org/wiki/Eckert_IV_projection
func NewEckertIV ¶
func NewEckertIV() EckertIV
func (EckertIV) PlanarBounds ¶
type EllipseBounds ¶
Represents an elliptical region in arbitrary units, where spherical positions are mapped to the plane. Valid planar coordinates are within the ellipse defined by the given semiaxes, centered on the origin.
func NewEllipseBounds ¶
func NewEllipseBounds(semiaxisX float64, semiaxisY float64) EllipseBounds
Construct a bounding area containing the ellipse described by the given semiaxes, centered on the origin.
func (EllipseBounds) Max ¶
func (e EllipseBounds) Max() (x float64, y float64)
func (EllipseBounds) Min ¶
func (e EllipseBounds) Min() (x float64, y float64)
type EqualEarth ¶
type EqualEarth struct{}
An equal-area pseudocylindrical projection. https://en.wikipedia.org/wiki/Equal_Earth_projection
func NewEqualEarth ¶
func NewEqualEarth() EqualEarth
func (EqualEarth) Bounds ¶
func (e EqualEarth) Bounds() Bounds
type Equirectangular ¶
type Equirectangular struct {
// The latitude (in radians) at which the scale is true (undistorted) for this projection.
Parallel float64
}
A linear mapping of latitude and longitude to x and y, with the given latitude of focus where results will be undistorted. https://en.wikipedia.org/wiki/Equirectangular_projection
func NewEquirectangular ¶
func NewEquirectangular(parallel float64) Equirectangular
Construct a new equirectangular projection with less distortion at the given parellel (in radians).
func (Equirectangular) Bounds ¶
func (e Equirectangular) Bounds() Bounds
type GallOrthographic ¶
type GallOrthographic struct {
CylindricalEqualArea
}
An equal area projection with least distortion at 45 degrees latitude. https://en.wikipedia.org/wiki/Gall%E2%80%93Peters_projection
func NewGallOrthographic ¶
func NewGallOrthographic() GallOrthographic
type GallStereographic ¶
type GallStereographic struct{}
A compromise cylindrical projection that tries to minimize distortion as much as possible. https://en.wikipedia.org/wiki/Gall_stereographic_projection
func NewGallStereographic ¶
func NewGallStereographic() GallStereographic
func (GallStereographic) Bounds ¶
func (g GallStereographic) Bounds() Bounds
type Gnomonic ¶
type Gnomonic struct{}
An ancient projection in which all great cirlces are straight lines. Many use cases but rapidly distorts the further away from the center of the projection. https://en.wikipedia.org/wiki/Gnomonic_projection
func NewGnomonic ¶
func NewGnomonic() Gnomonic
func (Gnomonic) PlanarBounds ¶
type HEALPixStandard ¶
type HEALPixStandard struct{}
An equal area projection combining Lambert cylindrical with interrupted Collignon for the polar regions. https://en.wikipedia.org/wiki/HEALPix See also: "Mapping on the HEALPix Grid", https://arxiv.org/pdf/astro-ph/0412607.pdf
func NewHEALPixStandard ¶
func NewHEALPixStandard() HEALPixStandard
func (HEALPixStandard) Bounds ¶
func (h HEALPixStandard) Bounds() Bounds
type Hammer ¶
type Hammer struct{}
An elliptical equal-area projection. https://en.wikipedia.org/wiki/Hammer_projection
type HoboDyer ¶
type HoboDyer struct {
CylindricalEqualArea
}
An equal area projection with least distortion at 37.5 degrees latitude. https://en.wikipedia.org/wiki/Hobo%E2%80%93Dyer_projection
func NewHoboDyer ¶
func NewHoboDyer() HoboDyer
type Homolosine ¶
type Homolosine struct {
// contains filtered or unexported fields
}
An equal-area projection combining Sinusoidal and Mollweide at different hemispheres. While most presentations of this projection use an interrupted form, this type is an uninterrupted version of Homolosine. https://en.wikipedia.org/wiki/Goode_homolosine_projection
func NewHomolosine ¶
func NewHomolosine() Homolosine
func (Homolosine) Bounds ¶
func (h Homolosine) Bounds() Bounds
type Lagrange ¶
type Lagrange struct{}
A circular conformal projection of the whole earth.
func NewLagrange ¶
func NewLagrange() Lagrange
type LambertAzimuthal ¶
type LambertAzimuthal struct{}
An equal-area azimuthal projection. https://en.wikipedia.org/wiki/Lambert_azimuthal_equal-area_projection
func NewLambertAzimuthal ¶
func NewLambertAzimuthal() LambertAzimuthal
func (LambertAzimuthal) Bounds ¶
func (l LambertAzimuthal) Bounds() Bounds
type LambertCylindrical ¶
type LambertCylindrical struct {
CylindricalEqualArea
}
An equal area projection with least distortion near the equator. https://en.wikipedia.org/wiki/Lambert_cylindrical_equal-area_projection
func NewLambertCylindrical ¶
func NewLambertCylindrical() LambertCylindrical
type Mercator ¶
type Mercator struct{}
An early standard cylindrical projection useful for navigation. https://en.wikipedia.org/wiki/Mercator_projection
func NewMercator ¶
func NewMercator() Mercator
type Miller ¶
type Miller struct{}
A compromise cylindrical projection intended to resemble Mercator with less distortion at the poles. https://en.wikipedia.org/wiki/Miller_cylindrical_projection
type Mollweide ¶
type Mollweide struct{}
An equal-area pseudocylindrical map commonly used for maps of the celestial sphere. https://en.wikipedia.org/wiki/Mollweide_projection
func NewMollweide ¶
func NewMollweide() Mollweide
type ObliqueAspect ¶
type ObliqueAspect struct {
// contains filtered or unexported fields
}
func NewObliqueAspect ¶
func NewObliqueAspect(poleLat float64, poleLon float64, poleTheta float64) ObliqueAspect
func (ObliqueAspect) TransformFromOblique ¶
func (o ObliqueAspect) TransformFromOblique(latitude float64, longitude float64) (float64, float64)
Applies the pole shift and rotation of the Oblique projection transform to the given input latitude and longitude points, so that the returned latitude/longitude are able to be used for the non-transformed 'original' projection.
func (ObliqueAspect) TransformToOblique ¶
func (o ObliqueAspect) TransformToOblique(latitude float64, longitude float64) (float64, float64)
Given a latitude/longitude in the non-transformed 'original' projection space, applies the pole shift and rotation of the Oblique projection so that the returned latitude/longitude are in the Oblique projection space.
type ObliqueProjection ¶
type ObliqueProjection struct {
ObliqueAspect
// contains filtered or unexported fields
}
func NewObliqueProjection ¶
func NewObliqueProjection(original Projection, poleLat float64, poleLon float64, poleTheta float64) ObliqueProjection
func (ObliqueProjection) Bounds ¶
func (o ObliqueProjection) Bounds() Bounds
type ObliqueVerticalPerspective ¶
A projection of that mimics the actual appearance of the sphere from a fixed viewing distance, centered at the given latitude and longitude. Could be equivalently represented using an oblique transform of VerticalPerspective, but this is more efficient.
func NewObliqueVerticalPerspective ¶
func NewObliqueVerticalPerspective(camLat float64, camLon float64, d float64) ObliqueVerticalPerspective
func (ObliqueVerticalPerspective) Bounds ¶
func (p ObliqueVerticalPerspective) Bounds() Bounds
type Orthographic ¶
type Orthographic struct{}
A projection of a hemisphere of a sphere as if viewed from an infinite distance away. https://en.wikipedia.org/wiki/Orthographic_map_projection
func NewOrthographic ¶
func NewOrthographic() Orthographic
func (Orthographic) Bounds ¶
func (o Orthographic) Bounds() Bounds
type PlateCarree ¶
type PlateCarree struct{}
A special case of the equirectangular projection which allows for easy conversion between pixel coordinates and locations on the sphere. The scale is less distorted the closer toward the equator a spherical position is. https://en.wikipedia.org/wiki/Equirectangular_projection
func NewPlateCarree ¶
func NewPlateCarree() PlateCarree
func (PlateCarree) Bounds ¶
func (p PlateCarree) Bounds() Bounds
type Polar ¶
type Polar struct{}
An ancient equidistant azimuthal projection. https://en.wikipedia.org/wiki/Azimuthal_equidistant_projection
type Projection ¶
type Projection interface {
// Convert a location on the sphere (in radians) to a coordinate on the plane.
Project(lat float64, lon float64) (x float64, y float64)
// Convert a coordinate on the plane to a location in radians on the sphere.
Inverse(x float64, y float64) (lat float64, lon float64)
// Retrieve the bounds of the projection in projected (planar) coordinates.
Bounds() Bounds
}
A package of functionality for converting from spherical locations to planar coordinates, or from planar coordinates into spherical locations. Contains information specifying some characteristics of the planar space mapped to by the projection functions, which can differ between projections.
type RectangleBounds ¶
Represents a rectangular region in arbitrary units, where spherical positions are mapped to the plane. Valid planar coordinates are within the rectangle defined by (XMin, YMin) and (XMax, YMax).
func NewRectangleBounds ¶
func NewRectangleBounds(width float64, height float64) RectangleBounds
Construct a bounding area of the given width and height centered on the origin.
func (RectangleBounds) Max ¶
func (b RectangleBounds) Max() (x float64, y float64)
func (RectangleBounds) Min ¶
func (b RectangleBounds) Min() (x float64, y float64)
type Sinusoidal ¶
type Sinusoidal struct{}
An equal-area projection representing the poles as points. https://en.wikipedia.org/wiki/Sinusoidal_projection
func NewSinusoidal ¶
func NewSinusoidal() Sinusoidal
func (Sinusoidal) Bounds ¶
func (s Sinusoidal) Bounds() Bounds
type Stereographic ¶
type Stereographic struct{}
An ancient azimuthal conformal projection (on spheres only, not ellipsoids) which is often used for rendering planets to maintain shape of craters. Diverges as latitude approaches Pi/2. https://en.wikipedia.org/wiki/Stereographic_map_projection
func NewStereographic ¶
func NewStereographic() Stereographic
func (Stereographic) Bounds ¶
func (s Stereographic) Bounds() Bounds
type TabularProjection ¶
type TabularProjection struct {
// contains filtered or unexported fields
}
A class of pseudocylindrical projections defined by a table of ratio values at particular latitutdes. Ratio values between the latitudes with defined entries are computed via interpolation during projection/inverse. The polynomial order parameter is use to control the interpolation expensiveness/accuracy, and should be a positive even number. The y scale parameter is used to control the scaling of latitude projection relative to width, allowing the parallel distance ratios to be input in normalized (-1, 1) range (i.e. as an actual ratio).
func NewNaturalEarth ¶
func NewNaturalEarth() TabularProjection
Create a new Natural Earth projection, a well-known instance of a pseudocylindrical projection defined by a table of values. https://en.wikipedia.org/wiki/Natural_Earth_projection
func NewRobinson ¶
func NewRobinson() TabularProjection
Create a new Robinson projection, a well-known instance of a pseudocylindrical projection defined by a table of values. https://en.wikipedia.org/wiki/Robinson_projection
func NewTabularProjection ¶
func NewTabularProjection( latitudes []float64, parallelLengthRatios []float64, parallelDistanceRatios []float64, polynomialOrder int, yScale float64, ) TabularProjection
Create a new pseudocylindrical projection from a table of values. The tables should be sorted by the latitude entry, such that the least latitude, and its corresponding ratio entries, are the first row in the table. Polynomial order should be a positive even integer, bigger = more accurate but more compute. yScale should be a positive float in the range (0,1).
func (TabularProjection) Bounds ¶
func (t TabularProjection) Bounds() Bounds
type VerticalPerspective ¶
type VerticalPerspective struct {
D float64 // Distance from the center of the sphere to the viewpoint, in multiples of the sphere radius.
}
A projection of that mimics the actual appearance of the earth from a fixed viewing distance. https://en.wikipedia.org/wiki/General_Perspective_projection
func NewVerticalPerspective ¶
func NewVerticalPerspective(d float64) VerticalPerspective
func (VerticalPerspective) Bounds ¶
func (p VerticalPerspective) Bounds() Bounds
Source Files