Projections

Map plots support a variety of projections, which are methods for flattening the curved, three-dimensional surface of a sphere (in Starplot, that's the sky) onto a two-dimensional flat surface like paper or a computer screen. Every projection is imperfect in some way because something will always be distorted.

Projections in Starplot are ultimately handled by PROJ (via pyproj), but Starplot has thin wrappers for each projection that let you customize a few properties (e.g. central RA/DEC).

Below is a list of all projections supported by map plots, along with a Tissot's indicatrix for each projection to illustrate how it distorts objects:

Basic Usage

from starplot import MapPlot, Stereographic

p = MapPlot(
    dec_min=-20,
    dec_max=90,
    # create a Stereographic projection 
    # with a custom center RA/DEC 
    projection=Stereographic(
        center_ra=250, 
        center_dec=35,
    )
)

Equidistant

Shows accurate distances from the center position. Often used for planispheres.

Properties

center_ra
center_dec

References

PROJ Wikipedia

Gnomonic

Gnomonic projection

Properties

center_ra
center_dec

References

PROJ Wikipedia

LambertAzEqArea

Lambert Azimuthal Equal-Area projection - accurately shows area, but distorts angles.

Properties

center_ra
center_dec

References

PROJ Wikipedia

Mercator

Good for declinations between -70 and 70, but distorts objects near the poles

Properties

center_ra

References

PROJ Wikipedia

Miller

Similar to Mercator: good for declinations between -70 and 70, but distorts objects near the poles

Properties

center_ra

References

PROJ Wikipedia

Mollweide

Good for showing the entire celestial sphere in one plot

Properties

center_ra

References

PROJ Wikipedia

ObliqueMercator

A cylindrical projection like Mercator, but the "cylinder" is wrapped around a specified great circle instead of the equator — you set that circle with center_ra/center_dec (a point on it) and azimuth (its direction there). This makes it useful for framing a narrow band of sky that runs at an angle to the RA/DEC grid — e.g. tracing the Milky Way's galactic plane, an eclipse path, or a satellite ground track — with low, Mercator-like distortion right along that line and shapes/angles preserved locally (it's conformal).

Properties