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)

• Bridge module to enable the use of the SkyCoord API to perform computations using SPICE kernels (sunpy.coordinates.spice)

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
Geomagnetic	MAG	Geomagnetic
Solar Magnetic	SM	SolarMagnetic
GeocentricSolarMagnetospheric	GSM	GeocentricSolarMagnetospheric

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:

• A robust framework for working with 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 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).

• 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.
BaseMagnetic(*args, **kwargs)	Base class for frames that rely on the Earth's magnetic model (MAG, SM, and GSM).
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.
GeocentricSolarMagnetospheric(*args, **kwargs)	A coordinate or frame in the GeocentricSolarMagnetospheric (GSM) system.
Geomagnetic(*args, **kwargs)	A coordinate or frame in the Geomagnetic (MAG) 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.
PlanarScreen(vantage_point, *, ...)	Context manager to interpret 2D coordinates as being on the inside of a planar screen.
RotatedSunFrame(*args, **kwargs)	A frame that applies solar rotation to a base coordinate frame.
SolarMagnetic(*args, **kwargs)	A coordinate or frame in the Solar Magnetic (SM) system.
SphericalScreen(center, *[, radius])	Context manager to interpret 2D coordinates as being on the inside of a spherical screen.
SunPyBaseCoordinateFrame(*args, **kwargs)	Base class for sunpy coordinate frames.

Class Inheritance Diagram

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.spice Module

Bridge module to use the SkyCoord API for SPICE computations.

Note

This module requires the optional dependency spiceypy to be installed.

The SPICE observation geometry information system is being increasingly used by space missions to describe the locations of spacecraft and the time-varying orientations of reference frames. While the spiceypy package provides a Python interface for performing SPICE computations, its API is very different from that of SkyCoord.

This module “wraps” spiceypy functionality so that relevant SPICE computations can be accessed using the SkyCoord API. When loading a set of kernels, a frame class and corresponding transformations are created for each SPICE frame. One can also query the location of a body as computed via SPICE or retrieve the field of view (FOV) of an instrument.

To facilitate the conversion of a SPICE-based coordinate to the built-in frames in sunpy.coordinates, every SPICE-based coordinate has the method to_helioprojective(). This method returns a coordinate in the Helioprojective frame with the observer frame attribute appropriately set.

Be aware that when converting a SPICE-based coordinate to/from a built-in frame, there can be small inconsistencies due to differing planetary ephemerides and models for various orientations.

Notes

• 2D coordinates can be transformed only if the to/from frames have the same SPICE body ID as their centers.

• Transformations of velocities are not yet supported.

• SPICE frame names are rendered as uppercase, except for plus/minus characters, which are replaced with lowercase 'p'/'n' characters.

Examples

Coordinates computations using SPICE kernels

Coordinates computations using SPICE kernels

Functions

get_body(body, time, *[, spice_frame, observer])	Get the location of a body via SPICE.
get_fov(instrument, time, *[, resolution])	Get the field of view (FOV) for an instrument via SPICE.
initialize(kernels)	Load one more more SPICE kernels and create corresponding frame classes.
install_frame(spice_frame)	Install a specified SPICE frame.
get_rotation_matrix(source_frame, ...[, to_time])	Get the rotation matrix between the orientations of two SPICE frames.

Classes

SpiceBaseCoordinateFrame(*args, **kwargs)

Base class for all frames generated to represent SPICE frames.

Class Inheritance Diagram

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.
eclipse_amount(observer, *[, moon_radius])	Return the percentage of the Sun that is eclipsed by the Moon.

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.
BaseMagnetic(*args, **kwargs)	Base class for frames that rely on the Earth's magnetic model (MAG, SM, and GSM).
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.
Geomagnetic(*args, **kwargs)	A coordinate or frame in the Geomagnetic (MAG) system.
SolarMagnetic(*args, **kwargs)	A coordinate or frame in the Solar Magnetic (SM) system.
GeocentricSolarMagnetospheric(*args, **kwargs)	A coordinate or frame in the GeocentricSolarMagnetospheric (GSM) system.

Class Inheritance Diagram

sunpy.coordinates.screens Module

Screen class definitions for making assumptions about off-disk emission

Classes

BaseScreen([only_off_disk])
SphericalScreen(center, *[, radius])	Context manager to interpret 2D coordinates as being on the inside of a spherical screen.
PlanarScreen(vantage_point, *, ...)	Context manager to interpret 2D coordinates as being on the inside of a planar screen.

Class Inheritance Diagram

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

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.