SunPy coordinates¶
This subpackage contains:
A robust framework for working with solarphysics coordinate systems
Functions to obtain the locations of solarsystem bodies (
sunpy.coordinates.ephemeris
)Functions to calculate Sunspecific coordinate information (
sunpy.coordinates.sun
)
The SunPy coordinate framework extends the Astropy coordinates framework.
Supported Coordinate Systems¶
Coordinate system 
Abbreviation 
SunPy/Astropy equivalent 
Notes 

Heliocentric Aries Ecliptic (Mean) 
HAE (also HEC) 
Astropy’s 

Heliocentric Cartesian 
HCC 

Heliocentric Earth Ecliptic 
HEE 

Heliocentric Earth Equatorial 
HEEQ (also HEQ) 
Use a Cartesian representation 

Heliocentric Inertial 
HCI 

Heliocentric Radial 
HCR 
similar to 
Use a cylindrical representation, but with a 90degree offset in 
Heliocentric/Heliographic RadialTangentialNormal 
HGRTN 
similar to 
The axes are permuted, with HCC X, Y, Z equivalent respectively to HGRTN Y, Z, X 
Heliographic Carrington 
HGC 

Heliographic Stonyhurst 
HGS 

Helioprojective Cartesian 
HPC 

Geocentric Earth Equatorial (Mean) 
GEI 

Geographic 
GEO 
Astropy’s 
The precise geographic definitions may differ 
Geocentric Solar Ecliptic 
GSE 
For a description of these coordinate systems, see Thompson (2006) and Franz & Harper (2002) (and corrected version).
Getting Started¶
The easiest interface to work with coordinates is through the SkyCoord
class:
>>> import astropy.units as u
>>> from astropy.coordinates import SkyCoord
>>> from sunpy.coordinates import frames
>>> c = SkyCoord(100*u.arcsec, 500*u.arcsec, frame=frames.Helioprojective)
>>> c = SkyCoord(x=72241.0*u.km, y=361206.1*u.km, z=589951.4*u.km, frame=frames.Heliocentric)
>>> c = SkyCoord(70*u.deg, 30*u.deg, frame=frames.HeliographicStonyhurst)
>>> c
<SkyCoord (HeliographicStonyhurst: obstime=None): (lon, lat, radius) in (deg, deg, km)
(70., 30., 695700.)>
It is also possible to use strings to specify the frame but in that case make sure to
explicitly import sunpy.coordinates
as it registers SunPy’s coordinate frames with
the Astropy coordinates framework:
>>> import astropy.units as u
>>> from astropy.coordinates import SkyCoord
>>> import sunpy.coordinates
>>> c = SkyCoord(100*u.arcsec, 500*u.arcsec, frame='helioprojective', observer='earth')
>>> c
<SkyCoord (Helioprojective: obstime=None, rsun=695700.0 km, observer=earth): (Tx, Ty) in arcsec
(100., 500.)>
SkyCoord
and all coordinate frames
support array coordinates. These work the same as singlevalue coordinates,
but they store multiple coordinates in a single object. When you’re going to
apply the same operation to many different coordinates, this is a better choice
than a list of SkyCoord
objects, because it will be
much faster than applying the operation to each
SkyCoord
in a for
loop:
>>> c = SkyCoord([500, 400]*u.arcsec, [100, 200]*u.arcsec, frame=frames.Helioprojective)
>>> c
<SkyCoord (Helioprojective: obstime=None, rsun=695700.0 km, observer=None): (Tx, Ty) in arcsec
[(500., 100.), ( 400., 200.)]>
>>> c[0]
<SkyCoord (Helioprojective: obstime=None, rsun=695700.0 km, observer=None): (Tx, Ty) in arcsec
(500., 100.)>
Accessing Coordinates¶
Individual coordinates can be accessed via attributes on the SkyCoord object, but the names of the components of the coordinates can depend on the the frame and the chosen representation (e.g., Cartesian versus spherical).
Helioprojective
¶
For the helioprojective frame, the theta_x and theta_y components are accessed as
Tx
and Ty
, respectively:
>>> c = SkyCoord(500*u.arcsec, 100*u.arcsec, frame=frames.Helioprojective)
>>> c.Tx
<Longitude 500. arcsec>
>>> c.Ty
<Latitude 100. arcsec>
Heliocentric
¶
Heliocentric is typically used with Cartesian components:
>>> c = SkyCoord(72241.0*u.km, 361206.1*u.km, 589951.4*u.km, frame=frames.Heliocentric)
>>> c.x
<Quantity 72241. km>
>>> c.y
<Quantity 361206.1 km>
>>> c.z
<Quantity 589951.4 km>
HeliographicStonyhurst
and HeliographicCarrington
¶
Both of the heliographic frames have the components of latitude, longitude and radius:
>>> c = SkyCoord(70*u.deg, 30*u.deg, frame=frames.HeliographicStonyhurst)
>>> c.lat
<Latitude 30. deg>
>>> c.lon
<Longitude 70. deg>
>>> c.radius
<Distance 695700. km>
Heliographic Stonyhurst, when used with Cartesian components, is known as Heliocentric
Earth Equatorial (HEEQ). Here’s an example of how to use
HeliographicStonyhurst
for HEEQ coordinates:
>>> c = SkyCoord(72241.0*u.km, 361206.1*u.km, 589951.4*u.km,
... representation_type='cartesian', frame=frames.HeliographicStonyhurst)
>>> c.x
<Quantity 72241. km>
>>> c.y
<Quantity 361206.1 km>
>>> c.z
<Quantity 589951.4 km>
Transforming Between Coordinate Frames¶
Both SkyCoord
and
BaseCoordinateFrame
instances have a
transform_to
method. This can be used to
transform the frame to any other frame, either implemented in SunPy or in
Astropy (see also Transforming between Systems).
An example of transforming the center of the solar disk to Carrington
coordinates is:
>>> c = SkyCoord(0*u.arcsec, 0*u.arcsec, frame=frames.Helioprojective, obstime="20170726",
... observer="earth")
>>> c
<SkyCoord (Helioprojective: obstime=20170726T00:00:00.000, rsun=695700.0 km, observer=<HeliographicStonyhurst Coordinate for 'earth'>): (Tx, Ty) in arcsec
(0., 0.)>
>>> c.transform_to(frames.HeliographicCarrington)
<SkyCoord (HeliographicCarrington: obstime=20170726T00:00:00.000, observer=<HeliographicStonyhurst Coordinate for 'earth'>): (lon, lat, radius) in (deg, deg, AU)
(283.95956776, 5.31701821, 0.00465047)>
It is also possible to transform to any coordinate system implemented in Astropy. This can be used to find the position of the solar limb in AltAz equatorial coordinates:
>>> from astropy.coordinates import EarthLocation, AltAz
>>> time = '20170711 15:00'
>>> greenbelt = EarthLocation(lat=39.0044*u.deg, lon=76.8758*u.deg)
>>> greenbelt_frame = AltAz(obstime=time, location=greenbelt)
>>> west_limb = SkyCoord(900*u.arcsec, 0*u.arcsec, frame=frames.Helioprojective,
... observer=greenbelt.get_itrs(greenbelt_frame.obstime), obstime=time)
>>> west_limb.transform_to(greenbelt_frame)
<SkyCoord (AltAz: obstime=20170711 15:00:00.000, location=(1126916.53031967, 4833386.58391627, 3992696.62211575) m, pressure=0.0 hPa, temperature=0.0 deg_C, relative_humidity=0.0, obswl=1.0 micron): (az, alt, distance) in (deg, deg, m)
(111.40782056, 57.1660434, 1.51859559e+11)>
Observer Location Information¶
The Helioprojective
, Heliocentric
and HeliographicCarrington
frames are defined by the location of
the observer. For example in Helioprojective
the
observer is at the origin of the coordinate system. This information is encoded
in such observerbased frames as the observer
attribute, which is itself an instance of the
HeliographicStonyhurst
frame.
The observer
can be a string for a solarsystem body (e.g., “earth” or
“mars”), and
get_body_heliographic_stonyhurst
will be used
with the specified obstime
to fully specify the observer location. If
the observer location is not fully specified, or not present at all, most
transformations cannot be performed.
The location of the observer is automatically populated from meta data when
coordinate frames are created using map.
In the case of HeliographicCarrington
, one can specify observer='self'
to indicate that the coordinate itself should be used as the observer for defining the coordinate frame.
It is possible to convert from a Helioprojective
frame with one observer location to another
Helioprojective
frame with a different observer
location, by converting through Heliographic
, this
does involve making an assumption of the radius of the Sun to calculate the
position on the solar sphere. The conversion can be performed as follows:
# Input coordinate
>>> hpc1 = SkyCoord(0*u.arcsec, 0*u.arcsec, observer="earth", obstime="20170726", frame=frames.Helioprojective)
Define a new Helioprojective frame with a different observer.
>>> import sunpy.coordinates
>>> hpc_out = sunpy.coordinates.Helioprojective(observer="venus", obstime="20170726")
Perform the transformation from one to the other.
>>> hpc2 = hpc1.transform_to(hpc_out)
An example with two maps, named aia
and stereo
:
>>> hpc1 = SkyCoord(0*u.arcsec, 0*u.arcsec, frame=aia.coordinate_frame)
>>> hpc2 = hpc1.transform_to(stereo.coordinate_frame)
Design of the Coordinates SubPackage¶
This subpackage works by defining a collection of Frames
(sunpy.coordinates.frames
), which exists on a transformation graph, where the
transformations between the coordinate frames are then defined and registered
with the transformation graph (sunpy.coordinates.transformations
). It is also
possible to transform SunPy frames to Astropy frames.
Positions within these Frames
are stored as a Representation
of a
coordinate, a representation being a description of a point in a Cartesian,
spherical or cylindrical system (see Using and Designing Coordinate Representations). A frame
that contains a representation of one or many points is said to have been
‘realized’.
For a more in depth look at the design and concepts of the Astropy coordinates system see Overview of astropy.coordinates Concepts
Frames and SkyCoord¶
The SkyCoord
class is a high level wrapper around the
astropy.coordinates
subpackage. It provides an easier way to create and transform
coordinates, by using string representations for frames rather than the classes
themselves and some other usability improvements, for more information see the
SkyCoord
documentation.
The main advantage provided by SkyCoord
is the support it
provides for caching Frame attributes. Frame attributes are extra data specified
with a frame, some examples in sunpy.coordinates
are obstime
or
observer
for observer location. Only the frames where this data is
meaningful have these attributes, i.e. only the Helioprojective frames have
observer
. However, when you transform into another frame and then back to a
projective frame using SkyCoord
it will remember the attributes previously
provided, and repopulate the final frame with them. If you were to do
transformations using the Frames alone this would not happen.
The most important implication for this in sunpy.coordinates
is the rsun
parameter in the projective frames. If you create a projective frame with a
rsun
attribute, if you convert back to a projective frame it will be set
correctly. It should also be noted that, if you create a Heliographic frame and
then transform to a projective frame with an rsun
attribute, it will not
match the radius
coordinate in the Heliographic frame. This is because you may
mean to be describing a point above the defined ‘surface’ of the Sun.
More Detailed Information¶
Reference/API¶
sunpy.coordinates Package¶
This subpackage contains:
A robust framework for working with coordinate systems
Functions to obtain the locations of solarsystem bodies (
sunpy.coordinates.ephemeris
)Functions to calculate Sunspecific coordinate information (
sunpy.coordinates.sun
)
The diagram below shows all of Sunbased and Earthbased 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 attributestyle 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
).

SunPy frames:

Astropy frames:

AffineTransform: ➝

FunctionTransform: ➝

FunctionTransformWithFiniteDifference: ➝

StaticMatrixTransform: ➝

DynamicMatrixTransform: ➝
Functions¶

Return a 

Return a 

Queries JPL HORIZONS and returns a 

For a given frame, this function returns the corresponding WCS object. 
This function registers the coordinates frames to their FITSWCS coordinate type values in the 

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

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

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

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

A coordinate or frame in the Heliocentric system, which is observerbased. 

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

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

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

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

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

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. 

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

Base class for sunpy coordinate frames. 
Class Inheritance Diagram¶
sunpy.coordinates.ephemeris Module¶
Ephemeris calculations using SunPy coordinate frames
Functions¶

Return a 

Return a 

Queries JPL HORIZONS and returns a 
sunpy.coordinates.sun Module¶
Sunspecific coordinate calculations
Functions¶

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

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). 
Return the Carrington rotation number. 


Return the time of a given Carrington rotation. 

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

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

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

Returns the Sun’s apparent latitude, referred to the true equinox of date. 
Returns the mean obliquity of the ecliptic, using the IAU 2006 definition. 


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

Returns the Sun’s true geometric declination relative to Earth, referred to the mean equinox of date (as default). 
Returns the true obliquity of the ecliptic, using the IAU 2006 definition. 


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

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

Print out a summary of solar ephemeris. 

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. 

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

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. 

Return the distance between the Sun and the Earth at a specified 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¶

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

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

Calculate the properties of a great arc at userspecified points between a start and end point on a sphere. 
Attribution¶
Some of this documentation was adapted from Astropy under the terms of the BSD License.
This subpackage was initially developed by Pritish Chakraborty as part of GSOC 2014 and Stuart Mumford.