SunPy coordinates¶

This sub-package contains:

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 `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`

HCR

similar to `Heliocentric`

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

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

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, rsun=695700.0 km): (lon, lat) in deg
(70., -30.)>
```

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 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=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, 1*u.AU, frame=frames.HeliographicStonyhurst)
>>> c.lat
<Latitude -30. deg>
>>> c.lon
<Longitude 70. deg>
<Distance 1. AU>
```

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="2017-07-26",
...              observer="earth")
>>> c
<SkyCoord (Helioprojective: obstime=2017-07-26T00: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=2017-07-26T00:00:00.000, rsun=695700.0 km, 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 = '2017-07-11 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=2017-07-11 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 observer-based frames as the `observer` attribute, which is itself an instance of the `HeliographicStonyhurst` frame. The `observer` can be a string for a solar-system 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="2017-07-26", frame=frames.Helioprojective)

Define a new Helioprojective frame with a different observer.
>>> import sunpy.coordinates
>>> hpc_out = sunpy.coordinates.Helioprojective(observer="venus", obstime="2017-07-26")

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 Sub-Package¶

This sub-package 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` sub-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 `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.

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`).

• SunPy frames:

• Astropy frames:

• AffineTransform:

• FunctionTransform:

• FunctionTransformWithFiniteDifference:

• StaticMatrixTransform:

• DynamicMatrixTransform:

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. `solar_frame_to_wcs_mapping`(frame[, projection]) For a given frame, this function returns the corresponding WCS object. This function registers the coordinates frames to their FITS-WCS coordinate type values in the `astropy.wcs.utils.wcs_to_celestial_frame` registry. 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.

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¶

 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). Return the Carrington rotation number. `carrington_rotation_time`(crot[, longitude]) 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. `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). 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 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.

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.