# SunPy coordinates¶

The SunPy coordinates submodule is an implementation of the common solar physics coordinate frames using the Astropy coordinates framework.

Warning

The accuracy of the transformations in this module have not been rigorously verified. They have been compared to sunpy.wcs and match to numerical precision. Independent verification will be added at a later date.

## Getting Started¶

The easiest interface to the coordinates module is through the SkyCoord class:

>>> import astropy.units as u
>>> from astropy.coordinates import SkyCoord
>>> import sunpy.coordinates
>>> c = SkyCoord(-100*u.arcsec, 500*u.arcsec, frame='helioprojective')
>>> c = SkyCoord(x=-72241.0*u.km, y=361206.1*u.km, z=589951.4*u.km, frame='heliocentric')
>>> c = SkyCoord(70*u.deg, -30*u.deg, frame='heliographic_stonyhurst')
>>> c
<SkyCoord (HelioGraphicStonyhurst: dateobs=None): (lon, lat, rad) in (deg, deg, km)
(70.0, -30.0, 695508.0)>


SunPy implements support for the following solar physics coordinate systems:

• Helioprojective (Cartesian) HelioProjective
• Heliocentric HelioCentric
• Heliographic Stonyhurst HelioGraphicStonyhurst
• Heliographic Carrington HelioGraphicCarrington

for a complete description of these frames see sunpy.coordinates.frames, for a more detailed description of the frames see Thompson (2006)

SkyCoord and all other coordinates objects also support array coordinates. These work the same as single-value 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='helioprojective')
>>> c
<SkyCoord (HelioProjective: D0=149597870.7 km, dateobs=None, L0=0.0 deg, B0=0.0 deg, rsun=695508.0 km): (Tx, Ty) in arcsec
[(-500.0, 100.0), (400.0, 200.0)]>
>>> c[0]
<SkyCoord (HelioProjective: D0=149597870.7 km, dateobs=None, L0=0.0 deg, B0=0.0 deg, rsun=695508.0 km): (Tx, Ty) in arcsec
(-500.0, 100.0)>


### Accessing Coordinates¶

Individual coordinates can be accessed via attributes on the SkyCoord object, but the names of the components of the coordinates for each frame differ. For a full description of all the properties of the frames see sunpy.coordinates.frames.

#### HelioProjective¶

For the helioprojective frame the coordinates are access as Tx and Ty representing theta x and y. These are the same coordinates that are often referred to as ‘solar-x’ and ‘solar-y’.

>>> c = SkyCoord(-500*u.arcsec, 100*u.arcsec, frame='helioprojective')
>>> c.Tx
<Longitude180 -500.0 arcsec>
>>> c.Ty
<Latitude 100.0 arcsec>


#### Heliocentric¶

Heliocentric normally a Cartesian frame so the coordinates are accessed as x,y,z:

>>> c = SkyCoord(-72241.0*u.km, 361206.1*u.km, 589951.4*u.km, frame='heliocentric')
>>> c.x
<Quantity -72241.0 km>
>>> c.y
<Quantity 361206.1 km>
>>> c.z
<Quantity 589951.4 km>


#### HeliographicStonyhurst and HeliographicCarrington¶

Both the heliographic frames use latitude, longitude and radius which are accessed as follows:

>>> c = SkyCoord(70*u.deg, -30*u.deg, frame='heliographic_stonyhurst')
>>> c.lat
<Latitude -30.0 deg>
>>> c.lon
<Longitude180 70.0 deg>
<Distance 695508.0 km>


## Design of the Coordinates Module¶

This module 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). Currently, the SunPy frames are not transformable to the frames in Astropy, as there is no transformation defined between the two sets of 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 (sunpy.coordinates.representation). 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 package. 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 dateobs or L0 and B0 for observer location. Only the frames where this data is meaningful have these attributes, i.e. only the Helioprojective frames have L0 and B0. 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.

## Coordinates and WCS¶

The sunpy.coordinates package provides a mapping between FITS-WCS CTYPE convention and the coordinate frames as defined in sunpy.coordinates. This is used via the astropy.wcs.utils.wcs_to_celestial_frame function, with which the SunPy frames are registered upon being imported. This list is used by packages such as wcsaxes to convert from astropy.wcs.WCS objects to coordinate frames.

The sunpy.map.GenricMap class creates astropy.wcs.WCS objects as amap.wcs, however, it adds some extra attributes to the WCS object to be able to fully specify the coordinate frame. It adds heliographic_longitude, heliographic_latitude and dsun.

If you want to obtain a un-realized coordinate frame corresponding to a GenericMap object you can do the following:

>>> from astropy.wcs.utils import wcs_to_celestial_frame
>>> import sunpy.coordinates
>>> import sunpy.map
>>> from sunpy.data.sample import AIA_171_IMAGE

>>> amap = sunpy.map.Map(AIA_171_IMAGE)

>>> wcs_to_celestial_frame(amap.wcs)
<Helioprojective Frame (D0=1.48940609627e+11 m, dateobs=2011-03-1910:54:00.340000, L0=0.0 deg, B0=-7.064078 deg, rsun=695508.0 km)>


## sunpy.coordinates Package¶

### 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¶

 HeliographicStonyhurst(*args, **kwargs) A coordinate or frame in the Stonyhurst Heliographic system. HeliographicCarrington(*args, **kwargs) A coordinate or frame in the Carrington Heliographic system. Heliocentric(*args, **kwargs) A coordinate or frame in the Heliocentric system. Helioprojective(*args, **kwargs) A coordinate or frame in the Helioprojective (Cartesian) system.

### sunpy.coordinates.transformations Module¶

Coordinate Transformation Functions

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

The diagram below shows all of the coordinate systems built into the coordinates package, their aliases (useful for converting other coordinates to them using attribute-style access) and the pre-defined transformations between them. The user is free to override any of these transformations by defining new transformations between these systems, but the pre-defined transformations should be sufficient for typical usage.

#### Functions¶

 hgs_to_hgc(hgscoord, hgcframe) Transform from Heliographic Stonyhurst to Heliograpic Carrington. hgc_to_hgs(hgccoord, hgsframe) Convert from Heliograpic Carrington to Heliographic Stonyhurst. hcc_to_hpc(helioccoord, heliopframe) Convert from Heliocentic 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 Heliograpic Carrington.

### sunpy.coordinates.representation Module¶

SunPy specific representations.

This submodule extends astropy.coordinates.representations with two Spherical representation classes, primarily for use with the Helioprojective coordinate system, due to the convention of Longitude going from -180 to 180 degrees.

#### Classes¶

 Longitude180 Quantity class that represents Longitude. SphericalWrap180Representation(lon, lat, ...) Representation of points in 3D Spherical coordinates. UnitSphericalWrap180Representation(lon, lat) Representation of points in 3D Spherical coordinates.

### 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.