README
¶
flatsphere
A Go library for converting between spherical and planar coordinates.
Prerequisites
Install
go get github.com/owlpinetech/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.PlanarBounds()
for x := bounds.XMin; x <= bounds.XMax; x += bounds.Width() / xSteps {
for y := bounds.YMin; y <= bounds.YMax; y += bounds.Height() / ySteps {
lat, lon := mercator.Inverse(x, y)
}
}
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 of 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 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 | ✅ |
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 DistortionAt(proj Projection, latitude float64, longitude float64) (area float64, angular float64)
- type Aitoff
- type Behrmann
- type Bounds
- type Cassini
- type Central
- type CylindricalEqualArea
- type EckertIV
- 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 Orthographic
- type PlateCarree
- type Polar
- type Projection
- type Sinusoidal
- type Stereographic
- type TabularProjection
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AngularDistortionAt ¶ added in v0.0.3
func AngularDistortionAt(proj Projection, latitude float64, longitude float64) float64
Compute the angular distortion of a projection at a particular location.
func AreaDistortionAt ¶ added in v0.0.3
func AreaDistortionAt(proj Projection, latitude float64, longitude float64) float64
Compute the area distortion of a projection at a particular location.
func DistortionAt ¶ added in v0.0.3
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 ¶ added in v0.1.1
type Aitoff struct{}
A compromise azimuthal projection stretched into an elliptical shape. https://en.wikipedia.org/wiki/Aitoff_projection
func (Aitoff) PlanarBounds ¶ added in v0.1.1
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 ¶
Represents a rectangular region in arbitrary units, where spherical positions are mapped to the plane.
func NewBounds ¶ added in v0.1.1
Construct a new bounding area from the minimum and maximum along each of the two axes. The center point will be a position halfway between the minimum and maximum.
func NewCircleBounds ¶
Construct a bounding area containing the circle described by the given radius, centered on the origin.
func NewEllipseBounds ¶
Construct a bounding area containing the ellipse described by the given semiaxes, centered on the origin.
func NewRectangleBounds ¶
Construct a bounding area of the given width and height centered on the origin.
func (Bounds) AspectRatio ¶
The aspect ratio of the bounds (Width / Height)
type Cassini ¶ added in v0.1.0
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 ¶ added in v0.1.0
func NewCassini() Cassini
func (Cassini) PlanarBounds ¶ added in v0.1.0
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
func (Central) PlanarBounds ¶
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) 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.
func (CylindricalEqualArea) PlanarBounds ¶
func (l CylindricalEqualArea) PlanarBounds() Bounds
type EckertIV ¶ added in v0.0.4
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 ¶ added in v0.0.4
func NewEckertIV() EckertIV
func (EckertIV) PlanarBounds ¶ added in v0.0.4
type EqualEarth ¶ added in v0.1.0
type EqualEarth struct{}
An equal-area pseudocylindrical projection. https://en.wikipedia.org/wiki/Equal_Earth_projection
func NewEqualEarth ¶ added in v0.1.0
func NewEqualEarth() EqualEarth
func (EqualEarth) Inverse ¶ added in v0.1.0
func (e EqualEarth) Inverse(x float64, y float64) (float64, float64)
func (EqualEarth) PlanarBounds ¶ added in v0.1.0
func (e EqualEarth) PlanarBounds() 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) Inverse ¶
func (e Equirectangular) Inverse(x float64, y float64) (lat float64, lon float64)
func (Equirectangular) PlanarBounds ¶
func (e Equirectangular) PlanarBounds() 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) Inverse ¶
func (g GallStereographic) Inverse(x float64, y float64) (lat float64, lon float64)
func (GallStereographic) PlanarBounds ¶
func (g GallStereographic) PlanarBounds() Bounds
type Gnomonic ¶ added in v0.0.3
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 ¶ added in v0.0.3
func NewGnomonic() Gnomonic
func (Gnomonic) PlanarBounds ¶ added in v0.0.3
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) Inverse ¶
func (h HEALPixStandard) Inverse(x float64, y float64) (float64, float64)
func (HEALPixStandard) PlanarBounds ¶
func (h HEALPixStandard) PlanarBounds() Bounds
type Hammer ¶ added in v0.1.1
type Hammer struct{}
An elliptical equal-area projection. https://en.wikipedia.org/wiki/Hammer_projection
func (Hammer) PlanarBounds ¶ added in v0.1.1
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) Inverse ¶
func (h Homolosine) Inverse(x float64, y float64) (lat float64, lon float64)
func (Homolosine) PlanarBounds ¶
func (h Homolosine) PlanarBounds() Bounds
type Lagrange ¶ added in v0.1.1
type Lagrange struct{}
A circular conformal projection of the whole earth.
func NewLagrange ¶ added in v0.1.1
func NewLagrange() Lagrange
func (Lagrange) PlanarBounds ¶ added in v0.1.1
type LambertAzimuthal ¶ added in v0.0.2
type LambertAzimuthal struct{}
An equal-area azimuthal projection. https://en.wikipedia.org/wiki/Lambert_azimuthal_equal-area_projection
func NewLambertAzimuthal ¶ added in v0.0.2
func NewLambertAzimuthal() LambertAzimuthal
func (LambertAzimuthal) Inverse ¶ added in v0.0.2
func (p LambertAzimuthal) Inverse(x float64, y float64) (float64, float64)
func (LambertAzimuthal) PlanarBounds ¶ added in v0.0.2
func (l LambertAzimuthal) PlanarBounds() 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
func (Mercator) PlanarBounds ¶
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
func (Miller) PlanarBounds ¶
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
func (Mollweide) PlanarBounds ¶
type ObliqueAspect ¶ added in v0.1.1
type ObliqueAspect struct {
// contains filtered or unexported fields
}
func NewObliqueAspect ¶ added in v0.1.1
func NewObliqueAspect(poleLat float64, poleLon float64, poleTheta float64) ObliqueAspect
func (ObliqueAspect) TransformFromOblique ¶ added in v0.1.1
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 ¶ added in v0.1.1
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 ¶ added in v0.0.3
type ObliqueProjection struct {
ObliqueAspect
// contains filtered or unexported fields
}
func NewObliqueProjection ¶ added in v0.0.3
func NewObliqueProjection(original Projection, poleLat float64, poleLon float64, poleTheta float64) ObliqueProjection
func (ObliqueProjection) Inverse ¶ added in v0.0.3
func (o ObliqueProjection) Inverse(x float64, y float64) (float64, float64)
func (ObliqueProjection) PlanarBounds ¶ added in v0.0.3
func (o ObliqueProjection) PlanarBounds() Bounds
type Orthographic ¶ added in v0.0.3
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 ¶ added in v0.0.3
func NewOrthographic() Orthographic
func (Orthographic) Inverse ¶ added in v0.0.3
func (o Orthographic) Inverse(x float64, y float64) (float64, float64)
func (Orthographic) PlanarBounds ¶ added in v0.0.3
func (o Orthographic) PlanarBounds() 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) Inverse ¶
func (p PlateCarree) Inverse(x float64, y float64) (lat float64, lon float64)
func (PlateCarree) PlanarBounds ¶
func (p PlateCarree) PlanarBounds() Bounds
type Polar ¶ added in v0.0.2
type Polar struct{}
An ancient equidistant azimuthal projection. https://en.wikipedia.org/wiki/Azimuthal_equidistant_projection
func (Polar) PlanarBounds ¶ added in v0.0.2
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 planar bounds of the projection.
PlanarBounds() 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 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) Inverse ¶
func (s Sinusoidal) Inverse(x float64, y float64) (lat float64, lon float64)
func (Sinusoidal) PlanarBounds ¶
func (s Sinusoidal) PlanarBounds() Bounds
type Stereographic ¶ added in v0.0.2
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 ¶ added in v0.0.2
func NewStereographic() Stereographic
func (Stereographic) Inverse ¶ added in v0.0.2
func (s Stereographic) Inverse(x float64, y float64) (float64, float64)
func (Stereographic) PlanarBounds ¶ added in v0.0.2
func (s Stereographic) PlanarBounds() Bounds
type TabularProjection ¶ added in v0.0.5
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 ¶ added in v0.1.0
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 ¶ added in v0.1.0
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 ¶ added in v0.0.5
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) Inverse ¶ added in v0.0.5
func (t TabularProjection) Inverse(x float64, y float64) (float64, float64)
func (TabularProjection) PlanarBounds ¶ added in v0.0.5
func (t TabularProjection) PlanarBounds() Bounds
Source Files