Coordinates (sunpy.coordinates)#

This sub-package contains:

  • A robust framework for working with solar-physics coordinate systems

  • Functions to obtain the locations of solar-system bodies (sunpy.coordinates.ephemeris)

  • Functions to calculate Sun-specific coordinate information (sunpy.coordinates.sun)

The SunPy coordinate framework extends the Astropy coordinates framework. The coordinates guide provides in depth discussion of the structure and concepts underlying the coordinates framework.

Supported Coordinate Systems#

Coordinate system

Abbreviation

SunPy/Astropy equivalent

Notes

Heliocentric Aries Ecliptic (Mean)

HAE (also HEC)

Astropy’s HeliocentricMeanEcliptic

Heliocentric Cartesian

HCC

Heliocentric

Heliocentric Earth Ecliptic

HEE

HeliocentricEarthEcliptic

Heliocentric Earth Equatorial

HEEQ (also HEQ)

HeliographicStonyhurst

Use a Cartesian representation

Heliocentric Inertial

HCI

HeliocentricInertial

Heliocentric Radial

HCR

similar to Heliocentric

Use a cylindrical representation, but with a 90-degree offset in psi

Heliocentric/Heliographic Radial-Tangential-Normal

HGRTN

similar to Heliocentric

The axes are permuted, with HCC X, Y, Z equivalent respectively to HGRTN Y, Z, X

Heliographic Carrington

HGC

HeliographicCarrington

Heliographic Stonyhurst

HGS

HeliographicStonyhurst

Helioprojective Cartesian

HPC

Helioprojective

Geocentric Earth Equatorial (Mean)

GEI

GeocentricEarthEquatorial

Geographic

GEO

Astropy’s ITRS

The precise geographic definitions may differ

Geocentric Solar Ecliptic

GSE

GeocentricSolarEcliptic

For a description of these coordinate systems, see Thompson (2006) and Franz & Harper (2002) (and corrected version).

Reference/API#

sunpy.coordinates Package#

This subpackage contains:

The diagram below shows all of Sun-based and Earth-based coordinate systems available through sunpy.coordinates, as well as the transformations between them. Each frame is labeled with the name of its class and its alias (useful for converting other coordinates to them using attribute-style access).

The frames colored in cyan are implemented in astropy.coordinates, and there are other astronomical frames that can be transformed to that are not shown below (see astropy.coordinates.builtin_frames).

digraph AstropyCoordinateTransformGraph { node [style=filled fillcolor=lightcyan] graph [rankdir=LR] ICRS [shape=oval label="ICRS\n`icrs`"]; CIRS [shape=oval label="CIRS\n`cirs`"]; GCRS [shape=oval label="GCRS\n`gcrs`"]; HCRS [shape=oval label="HCRS\n`hcrs`"]; AltAz [shape=oval label="AltAz\n`altaz`"]; HeliocentricMeanEcliptic [shape=oval label="HeliocentricMeanEcliptic\n`heliocentricmeanecliptic`"]; HeliocentricTrueEcliptic [shape=oval label="HeliocentricTrueEcliptic\n`heliocentrictrueecliptic`"]; Astropy [shape=box3d style=filled fillcolor=lightcyan label="Other frames\nin Astropy"]; ITRS [shape=oval label="ITRS\n`itrs`"]; PrecessedGeocentric [shape=oval label="PrecessedGeocentric\n`precessedgeocentric`"]; GeocentricMeanEcliptic [shape=oval label="GeocentricMeanEcliptic\n`geocentricmeanecliptic`"]; GeocentricTrueEcliptic [shape=oval label="GeocentricTrueEcliptic\n`geocentrictrueecliptic`"]; HeliographicStonyhurst [fillcolor=white shape=oval label="HeliographicStonyhurst\n`heliographic_stonyhurst`"]; HeliocentricEarthEcliptic [fillcolor=white shape=oval label="HeliocentricEarthEcliptic\n`heliocentricearthecliptic`"]; GeocentricEarthEquatorial [fillcolor=white shape=oval label="GeocentricEarthEquatorial\n`geocentricearthequatorial`"]; HeliographicCarrington [fillcolor=white shape=oval label="HeliographicCarrington\n`heliographic_carrington`"]; Heliocentric [fillcolor=white shape=oval label="Heliocentric\n`heliocentric`"]; HeliocentricInertial [fillcolor=white shape=oval label="HeliocentricInertial\n`heliocentricinertial`"]; Helioprojective [fillcolor=white shape=oval label="Helioprojective\n`helioprojective`"]; GeocentricSolarEcliptic [fillcolor=white shape=oval label="GeocentricSolarEcliptic\n`geocentricsolarecliptic`"]; ICRS -> CIRS[ color = "#d95f02" ]; ICRS -> GCRS[ color = "#d95f02" ]; ICRS -> HCRS[ color = "#555555" ]; ICRS -> AltAz[ color = "#d95f02" ]; ICRS -> HeliocentricMeanEcliptic[ color = "#555555" ]; ICRS -> HeliocentricTrueEcliptic[ color = "#555555" ]; ICRS -> Astropy[ color = "#000000" ]; CIRS -> AltAz[ color = "#d95f02" ]; CIRS -> ICRS[ color = "#d95f02" ]; CIRS -> CIRS[ color = "#d95f02" ]; CIRS -> GCRS[ color = "#d95f02" ]; CIRS -> ITRS[ color = "#d95f02" ]; AltAz -> CIRS[ color = "#d95f02" ]; AltAz -> ICRS[ color = "#d95f02" ]; AltAz -> AltAz[ color = "#d95f02" ]; AltAz -> ITRS[ color = "#d95f02" ]; GCRS -> ICRS[ color = "#d95f02" ]; GCRS -> HCRS[ color = "#d95f02" ]; GCRS -> GCRS[ color = "#d95f02" ]; GCRS -> CIRS[ color = "#d95f02" ]; GCRS -> PrecessedGeocentric[ color = "#d95f02" ]; GCRS -> GeocentricMeanEcliptic[ color = "#d95f02" ]; GCRS -> GeocentricTrueEcliptic[ color = "#d95f02" ]; HCRS -> ICRS[ color = "#555555" ]; HCRS -> HCRS[ color = "#555555" ]; HCRS -> HeliographicStonyhurst[ color = "#d95f02" ]; ITRS -> CIRS[ color = "#d95f02" ]; ITRS -> ITRS[ color = "#d95f02" ]; ITRS -> AltAz[ color = "#d95f02" ]; PrecessedGeocentric -> GCRS[ color = "#d95f02" ]; PrecessedGeocentric -> PrecessedGeocentric[ color = "#d95f02" ]; GeocentricMeanEcliptic -> GCRS[ color = "#d95f02" ]; GeocentricMeanEcliptic -> GeocentricMeanEcliptic[ color = "#d95f02" ]; HeliocentricMeanEcliptic -> ICRS[ color = "#555555" ]; HeliocentricMeanEcliptic -> HeliocentricMeanEcliptic[ color = "#555555" ]; HeliocentricMeanEcliptic -> HeliocentricEarthEcliptic[ color = "#d95f02" ]; HeliocentricMeanEcliptic -> GeocentricEarthEquatorial[ color = "#d95f02" ]; GeocentricTrueEcliptic -> GCRS[ color = "#d95f02" ]; GeocentricTrueEcliptic -> GeocentricTrueEcliptic[ color = "#d95f02" ]; HeliocentricTrueEcliptic -> ICRS[ color = "#555555" ]; HeliocentricTrueEcliptic -> HeliocentricTrueEcliptic[ color = "#555555" ]; HeliographicStonyhurst -> HeliographicCarrington[ color = "#d95f02" ]; HeliographicStonyhurst -> Heliocentric[ color = "#d95f02" ]; HeliographicStonyhurst -> HCRS[ color = "#d95f02" ]; HeliographicStonyhurst -> HeliographicStonyhurst[ color = "#d95f02" ]; HeliographicStonyhurst -> HeliocentricInertial[ color = "#d95f02" ]; HeliographicCarrington -> HeliographicStonyhurst[ color = "#d95f02" ]; HeliographicCarrington -> HeliographicCarrington[ color = "#d95f02" ]; Heliocentric -> Helioprojective[ color = "#d95f02" ]; Heliocentric -> HeliographicStonyhurst[ color = "#d95f02" ]; Heliocentric -> Heliocentric[ color = "#d95f02" ]; Helioprojective -> Heliocentric[ color = "#d95f02" ]; Helioprojective -> Helioprojective[ color = "#d95f02" ]; HeliocentricEarthEcliptic -> HeliocentricMeanEcliptic[ color = "#d95f02" ]; HeliocentricEarthEcliptic -> HeliocentricEarthEcliptic[ color = "#d95f02" ]; HeliocentricEarthEcliptic -> GeocentricSolarEcliptic[ color = "#d95f02" ]; GeocentricSolarEcliptic -> HeliocentricEarthEcliptic[ color = "#d95f02" ]; GeocentricSolarEcliptic -> GeocentricSolarEcliptic[ color = "#d95f02" ]; HeliocentricInertial -> HeliographicStonyhurst[ color = "#d95f02" ]; HeliocentricInertial -> HeliocentricInertial[ color = "#d95f02" ]; GeocentricEarthEquatorial -> HeliocentricMeanEcliptic[ color = "#d95f02" ]; GeocentricEarthEquatorial -> GeocentricEarthEquatorial[ color = "#d95f02" ]; Astropy -> ICRS[ color = "#000000" ]; overlap=false rankdir=LR {rank=same; ICRS; HCRS; Astropy} }

  • SunPy frames:

  • Astropy frames:

  • AffineTransform:

  • FunctionTransform:

  • FunctionTransformWithFiniteDifference:

  • StaticMatrixTransform:

  • DynamicMatrixTransform:

Built-in Frame Classes#

ICRS

A coordinate or frame in the ICRS system.

AltAz

A coordinate or frame in the Altitude-Azimuth system (Horizontal coordinates) with respect to the WGS84 ellipsoid.

GCRS

A coordinate or frame in the Geocentric Celestial Reference System (GCRS).

CIRS

A coordinate or frame in the Celestial Intermediate Reference System (CIRS).

ITRS

A coordinate or frame in the International Terrestrial Reference System (ITRS).

HCRS

A coordinate or frame in a Heliocentric system, with axes aligned to ICRS.

PrecessedGeocentric

A coordinate frame defined in a similar manner as GCRS, but precessed to a requested (mean) equinox.

GeocentricMeanEcliptic

Geocentric mean ecliptic coordinates.

HeliocentricMeanEcliptic

Heliocentric mean ecliptic coordinates.

GeocentricTrueEcliptic

Geocentric true ecliptic coordinates.

HeliocentricTrueEcliptic

Heliocentric true ecliptic coordinates.

Functions#

get_body_heliographic_stonyhurst(body[, ...])

Return a HeliographicStonyhurst frame for the location of a solar-system body at a specified time.

get_earth([time, include_velocity])

Return a SkyCoord for the location of the Earth at a specified time in the HeliographicStonyhurst frame.

get_horizons_coord(body[, time, id_type, ...])

Queries JPL HORIZONS and returns a SkyCoord for the location of a solar-system body at a specified time.

propagate_with_solar_surface([rotation_model])

Context manager for coordinate transformations to automatically apply solar differential rotation for any change in observation time.

solar_frame_to_wcs_mapping(frame[, projection])

For a given frame, this function returns the corresponding WCS object.

solar_wcs_frame_mapping(wcs)

This function registers the coordinates frames to their FITS-WCS coordinate type values in the astropy.wcs.utils.wcs_to_celestial_frame registry.

transform_with_sun_center()

Context manager for coordinate transformations to ignore the motion of the center of the Sun.

Classes#

BaseHeliographic(*args, **kwargs)

Base class for HeliographicCarrington (HGC) and HeliographicStonyhurst (HGS) frames.

GeocentricEarthEquatorial(*args, **kwargs)

A coordinate or frame in the Geocentric Earth Equatorial (GEI) system.

GeocentricSolarEcliptic(*args, **kwargs)

A coordinate or frame in the Geocentric Solar Ecliptic (GSE) system.

Heliocentric(*args, **kwargs)

A coordinate or frame in the Heliocentric system, which is observer-based.

HeliocentricEarthEcliptic(*args, **kwargs)

A coordinate or frame in the Heliocentric Earth Ecliptic (HEE) system.

HeliocentricInertial(*args, **kwargs)

A coordinate or frame in the Heliocentric Inertial (HCI) system.

HeliographicCarrington(*args, **kwargs)

A coordinate or frame in the Carrington Heliographic (HGC) system.

HeliographicStonyhurst(*args, **kwargs)

A coordinate or frame in the Stonyhurst Heliographic (HGS) system.

Helioprojective(*args, **kwargs)

A coordinate or frame in the Helioprojective Cartesian (HPC) system, which is observer-based.

NorthOffsetFrame(*args, **kwargs)

A frame which is offset from another frame such that it shares the same origin, but has its "north pole" (i.e., the Z axis) in a different direction.

RotatedSunFrame(*args, **kwargs)

A frame that applies solar rotation to a base coordinate frame.

SunPyBaseCoordinateFrame(*args, **kwargs)

Base class for sunpy coordinate frames.

Class Inheritance Diagram#

Inheritance diagram of sunpy.coordinates.frames.BaseHeliographic, sunpy.coordinates.frames.GeocentricEarthEquatorial, sunpy.coordinates.frames.GeocentricSolarEcliptic, sunpy.coordinates.frames.Heliocentric, sunpy.coordinates.frames.HeliocentricEarthEcliptic, sunpy.coordinates.frames.HeliocentricInertial, sunpy.coordinates.frames.HeliographicCarrington, sunpy.coordinates.frames.HeliographicStonyhurst, sunpy.coordinates.frames.Helioprojective, sunpy.coordinates.metaframes.NorthOffsetFrame, sunpy.coordinates.metaframes.RotatedSunFrame, sunpy.coordinates.frames.SunPyBaseCoordinateFrame

sunpy.coordinates.ephemeris Module#

Ephemeris calculations using SunPy coordinate frames

Functions#

get_body_heliographic_stonyhurst(body[, ...])

Return a HeliographicStonyhurst frame for the location of a solar-system body at a specified time.

get_earth([time, include_velocity])

Return a SkyCoord for the location of the Earth at a specified time in the HeliographicStonyhurst frame.

get_horizons_coord(body[, time, id_type, ...])

Queries JPL HORIZONS and returns a SkyCoord for the location of a solar-system body at a specified time.

sunpy.coordinates.sun Module#

Sun-specific coordinate calculations

Functions#

angular_radius([t])

Return the angular radius of the Sun as viewed from Earth.

sky_position([t, equinox_of_date])

Returns the apparent position of the Sun (right ascension and declination) on the celestial sphere using the equatorial coordinate system, referred to the true equinox of date (as default).

carrington_rotation_number([t])

Return the Carrington rotation number.

carrington_rotation_time(crot[, longitude])

Return the time of a given Carrington rotation.

true_longitude([t])

Returns the Sun's true geometric longitude, referred to the mean equinox of date.

apparent_longitude([t])

Returns the Sun's apparent longitude, referred to the true equinox of date.

true_latitude([t])

Returns the Sun's true geometric latitude, referred to the mean equinox of date.

apparent_latitude([t])

Returns the Sun's apparent latitude, referred to the true equinox of date.

mean_obliquity_of_ecliptic([t])

Returns the mean obliquity of the ecliptic, using the IAU 2006 definition.

true_rightascension([t, equinox_of_date])

Returns the Sun's true geometric right ascension relative to Earth, referred to the mean equinox of date (as default).

true_declination([t, equinox_of_date])

Returns the Sun's true geometric declination relative to Earth, referred to the mean equinox of date (as default).

true_obliquity_of_ecliptic([t])

Returns the true obliquity of the ecliptic, using the IAU 2006 definition.

apparent_rightascension([t, equinox_of_date])

Returns the Sun's apparent right ascension relative to Earth, referred to the true equinox of date (as default).

apparent_declination([t, equinox_of_date])

Returns the Sun's apparent declination relative to Earth, referred to the true equinox of date (as default).

print_params([t])

Print out a summary of solar ephemeris.

B0([time])

Return the B0 angle for the Sun at a specified time, which is the heliographic latitude of the of the center of the disk of the Sun as seen from Earth.

L0([time, light_travel_time_correction, ...])

Return the L0 angle for the Sun at a specified time, which is the apparent Carrington longitude of the Sun-disk center as seen from Earth.

P([time])

Return the position (P) angle for the Sun at a specified time, which is the angle between geocentric north and solar north as seen from Earth, measured eastward from geocentric north.

earth_distance([time])

Return the distance between the Sun and the Earth at a specified time.

orientation(location[, time])

Return the orientation angle for the Sun from a specified Earth location and time.

sunpy.coordinates.utils Module#

Miscellaneous utilities related to coordinates

Functions#

get_rectangle_coordinates(bottom_left, *[, ...])

Specify a rectangular region of interest in longitude and latitude in a given coordinate frame.

solar_angle_equivalency(observer)

Return the equivalency to convert between a physical distance on the Sun and an angular separation as seen by a specified observer.

get_limb_coordinates(observer[, rsun, ...])

Get coordinates for the solar limb as viewed by a specified observer.

Classes#

GreatArc(start, end[, center, points])

Calculate the properties of a great arc at user-specified points between a start and end point on a sphere.

Reference/API for supporting coordinates modules#

The parts of the following modules that are useful to a typical user are already imported into the sunpy.coordinates namespace.

sunpy.coordinates.frames Module#

Common solar physics coordinate systems.

This submodule implements various solar physics coordinate frames for use with the astropy.coordinates module.

Classes#

SunPyBaseCoordinateFrame(*args, **kwargs)

Base class for sunpy coordinate frames.

BaseHeliographic(*args, **kwargs)

Base class for HeliographicCarrington (HGC) and HeliographicStonyhurst (HGS) frames.

HeliographicStonyhurst(*args, **kwargs)

A coordinate or frame in the Stonyhurst Heliographic (HGS) system.

HeliographicCarrington(*args, **kwargs)

A coordinate or frame in the Carrington Heliographic (HGC) system.

Heliocentric(*args, **kwargs)

A coordinate or frame in the Heliocentric system, which is observer-based.

Helioprojective(*args, **kwargs)

A coordinate or frame in the Helioprojective Cartesian (HPC) system, which is observer-based.

HeliocentricEarthEcliptic(*args, **kwargs)

A coordinate or frame in the Heliocentric Earth Ecliptic (HEE) system.

GeocentricSolarEcliptic(*args, **kwargs)

A coordinate or frame in the Geocentric Solar Ecliptic (GSE) system.

HeliocentricInertial(*args, **kwargs)

A coordinate or frame in the Heliocentric Inertial (HCI) system.

GeocentricEarthEquatorial(*args, **kwargs)

A coordinate or frame in the Geocentric Earth Equatorial (GEI) system.

Class Inheritance Diagram#

Inheritance diagram of sunpy.coordinates.frames.SunPyBaseCoordinateFrame, sunpy.coordinates.frames.BaseHeliographic, sunpy.coordinates.frames.HeliographicStonyhurst, sunpy.coordinates.frames.HeliographicCarrington, sunpy.coordinates.frames.Heliocentric, sunpy.coordinates.frames.Helioprojective, sunpy.coordinates.frames.HeliocentricEarthEcliptic, sunpy.coordinates.frames.GeocentricSolarEcliptic, sunpy.coordinates.frames.HeliocentricInertial, sunpy.coordinates.frames.GeocentricEarthEquatorial

sunpy.coordinates.metaframes Module#

Coordinate frames that are defined relative to other frames

Classes#

NorthOffsetFrame(*args, **kwargs)

A frame which is offset from another frame such that it shares the same origin, but has its "north pole" (i.e., the Z axis) in a different direction.

RotatedSunFrame(*args, **kwargs)

A frame that applies solar rotation to a base coordinate frame.

Class Inheritance Diagram#

Inheritance diagram of sunpy.coordinates.metaframes.NorthOffsetFrame, sunpy.coordinates.metaframes.RotatedSunFrame

sunpy.coordinates.transformations Module#

Coordinate Transformation Functions

This module contains the functions for converting one sunpy.coordinates.frames object to another.

Warning

The functions in this submodule should never be called directly, transforming between coordinate frames should be done using the .transform_to methods on BaseCoordinateFrame or SkyCoord instances.

Functions#

transform_with_sun_center()

Context manager for coordinate transformations to ignore the motion of the center of the Sun.

propagate_with_solar_surface([rotation_model])

Context manager for coordinate transformations to automatically apply solar differential rotation for any change in observation time.

hgs_to_hgc(hgscoord, hgcframe)

Convert from Heliographic Stonyhurst to Heliographic Carrington.

hgc_to_hgs(hgccoord, hgsframe)

Convert from Heliographic Carrington to Heliographic Stonyhurst.

hcc_to_hpc(helioccoord, heliopframe)

Convert from Heliocentric Cartesian to Helioprojective Cartesian.

hpc_to_hcc(heliopcoord, heliocframe)

Convert from Helioprojective Cartesian to Heliocentric Cartesian.

hcc_to_hgs(helioccoord, heliogframe)

Convert from Heliocentric Cartesian to Heliographic Stonyhurst.

hgs_to_hcc(heliogcoord, heliocframe)

Convert from Heliographic Stonyhurst to Heliocentric Cartesian.

hpc_to_hpc(from_coo, to_frame)

This converts from HPC to HPC, with different observer location parameters.

hcrs_to_hgs(hcrscoord, hgsframe)

Convert from HCRS to Heliographic Stonyhurst (HGS).

hgs_to_hcrs(hgscoord, hcrsframe)

Convert from Heliographic Stonyhurst to HCRS.

hgs_to_hgs(from_coo, to_frame)

Convert between two Heliographic Stonyhurst frames.

hgc_to_hgc(from_coo, to_frame)

Convert between two Heliographic Carrington frames.

hcc_to_hcc(from_coo, to_frame)

Convert between two Heliocentric frames.

hme_to_hee(hmecoord, heeframe)

Convert from Heliocentric Mean Ecliptic to Heliocentric Earth Ecliptic

hee_to_hme(heecoord, hmeframe)

Convert from Heliocentric Earth Ecliptic to Heliocentric Mean Ecliptic

hee_to_hee(from_coo, to_frame)

Convert between two Heliocentric Earth Ecliptic frames.

hee_to_gse(heecoord, gseframe)

Convert from Heliocentric Earth Ecliptic to Geocentric Solar Ecliptic

gse_to_hee(gsecoord, heeframe)

Convert from Geocentric Solar Ecliptic to Heliocentric Earth Ecliptic

gse_to_gse(from_coo, to_frame)

Convert between two Geocentric Solar Ecliptic frames.

hgs_to_hci(hgscoord, hciframe)

Convert from Heliographic Stonyhurst to Heliocentric Inertial

hci_to_hgs(hcicoord, hgsframe)

Convert from Heliocentric Inertial to Heliographic Stonyhurst

hci_to_hci(from_coo, to_frame)

Convert between two Heliocentric Inertial frames.

hme_to_gei(hmecoord, geiframe)

Convert from Heliocentric Mean Ecliptic to Geocentric Earth Equatorial

gei_to_hme(geicoord, hmeframe)

Convert from Geocentric Earth Equatorial to Heliocentric Mean Ecliptic

gei_to_gei(from_coo, to_frame)

Convert between two Geocentric Earth Equatorial frames.

sunpy.coordinates.wcs_utils Module#

Functions#

solar_wcs_frame_mapping(wcs)

This function registers the coordinates frames to their FITS-WCS coordinate type values in the astropy.wcs.utils.wcs_to_celestial_frame registry.

solar_frame_to_wcs_mapping(frame[, projection])

For a given frame, this function returns the corresponding WCS object.

Attribution#

Some of this documentation was adapted from Astropy under the terms of the BSD License.

This sub-package was initially developed by Pritish Chakraborty as part of GSOC 2014 and Stuart Mumford.