# Frames module¶

## Enums¶

Coordinate frames definitions.

class poliastro.frames.enums.Planes(value)

An enumeration.

## Ecliptic¶

class poliastro.frames.ecliptic.GeocentricSolarEcliptic(*args, copy=True, representation_type=None, differential_type=None, **kwargs)

This system has its X axis towards the Sun and its Z axis perpendicular to the plane of the Earth’s orbit around the Sun (positive North). This system is fixed with respect to the Earth-Sun line. It is convenient for specifying magnetospheric boundaries. It has also been widely adopted as the system for representing vector quantities in space physics databases.

class poliastro.frames.ecliptic.GeocentricMeanEcliptic(*args, copy=True, representation_type=None, differential_type=None, **kwargs)

Geocentric mean ecliptic coordinates. These origin of the coordinates are the geocenter (Earth), with the x axis pointing to the mean (not true) equinox at the time specified by the equinox attribute, and the xy-plane in the plane of the ecliptic for that date.

Be aware that the definition of “geocentric” here means that this frame includes light deflection from the sun, aberration, etc when transforming to/from e.g. ICRS.

The frame attributes are listed under Other Parameters.

Parameters
• data (~astropy.coordinates.BaseRepresentation subclass instance) – A representation object or None to have no data (or use the coordinate component arguments, see below).

• lon (~astropy.coordinates.Angle, optional, must be keyword) – The ecliptic longitude for this object (lat must also be given and representation must be None).

• lat (~astropy.coordinates.Angle, optional, must be keyword) – The ecliptic latitude for this object (lon must also be given and representation must be None).

• distance (~astropy.units.Quantity, optional, must be keyword) – The distance for this object from the geocenter. (representation must be None).

• pm_lon_coslat (~astropy.coordinates.Angle, optional, must be keyword) – The proper motion in the ecliptic longitude (including the cos(lat) factor) for this object (pm_lat must also be given).

• pm_lat (~astropy.coordinates.Angle, optional, must be keyword) – The proper motion in the ecliptic latitude for this object (pm_lon_coslat must also be given).

• radial_velocity (Quantity, optional, must be keyword) – The radial velocity of this object.

• representation_type (~astropy.coordinates.BaseRepresentation subclass, str, optional) – A representation class or string name of a representation class. This sets the expected input representation class, thereby changing the expected keyword arguments for the data passed in. For example, passing representation_type='cartesian' will make the classes expect position data with cartesian names, i.e. x, y, z in most cases unless overriden via frame_specific_representation_info. To see this frame’s names, check out <this frame>().representation_info.

• differential_type (~astropy.coordinates.BaseDifferential subclass, str, dict, optional) – A differential class or dictionary of differential classes (currently only a velocity differential with key ‘s’ is supported). This sets the expected input differential class, thereby changing the expected keyword arguments of the data passed in. For example, passing differential_type='cartesian' will make the classes expect velocity data with the argument names v_x, v_y, v_z unless overriden via frame_specific_representation_info. To see this frame’s names, check out <this frame>().representation_info.

• copy (bool, optional) – If True (default), make copies of the input coordinate arrays. Can only be passed in as a keyword argument.

Other Parameters
• equinox (~astropy.time.Time, optional) – The date to assume for this frame. Determines the location of the x-axis and the location of the Earth (necessary for transformation to non-geocentric systems). Defaults to the ‘J2000’ equinox.

• obstime (~astropy.time.Time, optional) – The time at which the observation is taken. Used for determining the position of the Earth. Defaults to J2000.

poliastro.frames.ecliptic.HeliocentricEclipticJ2000

alias of astropy.coordinates.builtin_frames.ecliptic.HeliocentricEclipticIAU76

## Equatorial¶

class poliastro.frames.equatorial.ICRS(*args, copy=True, representation_type=None, differential_type=None, **kwargs)

A coordinate or frame in the ICRS system.

If you’re looking for “J2000” coordinates, and aren’t sure if you want to use this or ~astropy.coordinates.FK5, you probably want to use ICRS. It’s more well-defined as a catalog coordinate and is an inertial system, and is very close (within tens of milliarcseconds) to J2000 equatorial.

For more background on the ICRS and related coordinate transformations, see the references provided in the See Also section of the documentation.

Parameters
• data (~astropy.coordinates.BaseRepresentation subclass instance) – A representation object or None to have no data (or use the coordinate component arguments, see below).

• ra (~astropy.coordinates.Angle, optional, must be keyword) – The RA for this object (dec must also be given and representation must be None).

• dec (~astropy.coordinates.Angle, optional, must be keyword) – The Declination for this object (ra must also be given and representation must be None).

• distance (~astropy.units.Quantity, optional, must be keyword) – The Distance for this object along the line-of-sight. (representation must be None).

• pm_ra_cosdec (Quantity, optional, must be keyword) – The proper motion in Right Ascension (including the cos(dec) factor) for this object (pm_dec must also be given).

• pm_dec (Quantity, optional, must be keyword) – The proper motion in Declination for this object (pm_ra_cosdec must also be given).

• radial_velocity (Quantity, optional, must be keyword) – The radial velocity of this object.

• representation_type (~astropy.coordinates.BaseRepresentation subclass, str, optional) – A representation class or string name of a representation class. This sets the expected input representation class, thereby changing the expected keyword arguments for the data passed in. For example, passing representation_type='cartesian' will make the classes expect position data with cartesian names, i.e. x, y, z in most cases unless overriden via frame_specific_representation_info. To see this frame’s names, check out <this frame>().representation_info.

• differential_type (~astropy.coordinates.BaseDifferential subclass, str, dict, optional) – A differential class or dictionary of differential classes (currently only a velocity differential with key ‘s’ is supported). This sets the expected input differential class, thereby changing the expected keyword arguments of the data passed in. For example, passing differential_type='cartesian' will make the classes expect velocity data with the argument names v_x, v_y, v_z unless overriden via frame_specific_representation_info. To see this frame’s names, check out <this frame>().representation_info.

• copy (bool, optional) – If True (default), make copies of the input coordinate arrays. Can only be passed in as a keyword argument.

class poliastro.frames.equatorial.HCRS(*args, copy=True, representation_type=None, differential_type=None, **kwargs)

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

The ICRS has an origin at the Barycenter and axes which are fixed with respect to space.

This coordinate system is distinct from ICRS mainly in that it is relative to the Sun’s center-of-mass rather than the solar system Barycenter. In principle, therefore, this frame should include the effects of aberration (unlike ICRS), but this is not done, since they are very small, of the order of 8 milli-arcseconds.

For more background on the ICRS and related coordinate transformations, see the references provided in the See Also section of the documentation.

The frame attributes are listed under Other Parameters.

Parameters
• data (~astropy.coordinates.BaseRepresentation subclass instance) – A representation object or None to have no data (or use the coordinate component arguments, see below).

• ra (~astropy.coordinates.Angle, optional, must be keyword) – The RA for this object (dec must also be given and representation must be None).

• dec (~astropy.coordinates.Angle, optional, must be keyword) – The Declination for this object (ra must also be given and representation must be None).

• distance (~astropy.units.Quantity, optional, must be keyword) – The Distance for this object along the line-of-sight. (representation must be None).

• pm_ra_cosdec (Quantity, optional, must be keyword) – The proper motion in Right Ascension (including the cos(dec) factor) for this object (pm_dec must also be given).

• pm_dec (Quantity, optional, must be keyword) – The proper motion in Declination for this object (pm_ra_cosdec must also be given).

• radial_velocity (Quantity, optional, must be keyword) – The radial velocity of this object.

• representation_type (~astropy.coordinates.BaseRepresentation subclass, str, optional) – A representation class or string name of a representation class. This sets the expected input representation class, thereby changing the expected keyword arguments for the data passed in. For example, passing representation_type='cartesian' will make the classes expect position data with cartesian names, i.e. x, y, z in most cases unless overriden via frame_specific_representation_info. To see this frame’s names, check out <this frame>().representation_info.

• differential_type (~astropy.coordinates.BaseDifferential subclass, str, dict, optional) – A differential class or dictionary of differential classes (currently only a velocity differential with key ‘s’ is supported). This sets the expected input differential class, thereby changing the expected keyword arguments of the data passed in. For example, passing differential_type='cartesian' will make the classes expect velocity data with the argument names v_x, v_y, v_z unless overriden via frame_specific_representation_info. To see this frame’s names, check out <this frame>().representation_info.

• copy (bool, optional) – If True (default), make copies of the input coordinate arrays. Can only be passed in as a keyword argument.

Other Parameters

obstime (~astropy.time.Time) – The time at which the observation is taken. Used for determining the position of the Sun.

class poliastro.frames.equatorial.MercuryICRS(*args, **kwargs)
class poliastro.frames.equatorial.VenusICRS(*args, **kwargs)
class poliastro.frames.equatorial.GCRS(*args, copy=True, representation_type=None, differential_type=None, **kwargs)

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

GCRS is distinct form ICRS mainly in that it is relative to the Earth’s center-of-mass rather than the solar system Barycenter. That means this frame includes the effects of aberration (unlike ICRS). For more background on the GCRS, see the references provided in the See Also section of the documentation. (Of particular note is Section 1.2 of USNO Circular 179)

This frame also includes frames that are defined relative to the Earth, but that are offset (in both position and velocity) from the Earth.

The frame attributes are listed under Other Parameters.

Parameters
• data (~astropy.coordinates.BaseRepresentation subclass instance) – A representation object or None to have no data (or use the coordinate component arguments, see below).

• ra (~astropy.coordinates.Angle, optional, must be keyword) – The RA for this object (dec must also be given and representation must be None).

• dec (~astropy.coordinates.Angle, optional, must be keyword) – The Declination for this object (ra must also be given and representation must be None).

• distance (~astropy.units.Quantity, optional, must be keyword) – The Distance for this object along the line-of-sight. (representation must be None).

• pm_ra_cosdec (Quantity, optional, must be keyword) – The proper motion in Right Ascension (including the cos(dec) factor) for this object (pm_dec must also be given).

• pm_dec (Quantity, optional, must be keyword) – The proper motion in Declination for this object (pm_ra_cosdec must also be given).

• radial_velocity (Quantity, optional, must be keyword) – The radial velocity of this object.

• representation_type (~astropy.coordinates.BaseRepresentation subclass, str, optional) – A representation class or string name of a representation class. This sets the expected input representation class, thereby changing the expected keyword arguments for the data passed in. For example, passing representation_type='cartesian' will make the classes expect position data with cartesian names, i.e. x, y, z in most cases unless overriden via frame_specific_representation_info. To see this frame’s names, check out <this frame>().representation_info.

• differential_type (~astropy.coordinates.BaseDifferential subclass, str, dict, optional) – A differential class or dictionary of differential classes (currently only a velocity differential with key ‘s’ is supported). This sets the expected input differential class, thereby changing the expected keyword arguments of the data passed in. For example, passing differential_type='cartesian' will make the classes expect velocity data with the argument names v_x, v_y, v_z unless overriden via frame_specific_representation_info. To see this frame’s names, check out <this frame>().representation_info.

• copy (bool, optional) – If True (default), make copies of the input coordinate arrays. Can only be passed in as a keyword argument.

Other Parameters
• obstime (~astropy.time.Time) – The time at which the observation is taken. Used for determining the position of the Earth.

• obsgeoloc (~astropy.coordinates.CartesianRepresentation, ~astropy.units.Quantity) – The position of the observer relative to the center-of-mass of the Earth, oriented the same as BCRS/ICRS. Either [0, 0, 0], ~astropy.coordinates.CartesianRepresentation, or proper input for one, i.e., a ~astropy.units.Quantity with shape (3, …) and length units. Defaults to [0, 0, 0], meaning “true” GCRS.

• obsgeovel (~astropy.coordinates.CartesianRepresentation, ~astropy.units.Quantity) – The velocity of the observer relative to the center-of-mass of the Earth, oriented the same as BCRS/ICRS. Either [0, 0, 0], ~astropy.coordinates.CartesianRepresentation, or proper input for one, i.e., a ~astropy.units.Quantity with shape (3, …) and velocity units. Defaults to [0, 0, 0], meaning “true” GCRS.

class poliastro.frames.equatorial.MarsICRS(*args, **kwargs)
class poliastro.frames.equatorial.JupiterICRS(*args, **kwargs)
class poliastro.frames.equatorial.SaturnICRS(*args, **kwargs)
class poliastro.frames.equatorial.UranusICRS(*args, **kwargs)
class poliastro.frames.equatorial.NeptuneICRS(*args, **kwargs)

## Fixed¶

class poliastro.frames.fixed.SunFixed(*args, **kwargs)
equatorial

alias of astropy.coordinates.builtin_frames.hcrs.HCRS

class poliastro.frames.fixed.MercuryFixed(*args, **kwargs)
equatorial
class poliastro.frames.fixed.VenusFixed(*args, **kwargs)
equatorial
class poliastro.frames.fixed.ITRS(*args, copy=True, representation_type=None, differential_type=None, **kwargs)

A coordinate or frame in the International Terrestrial Reference System (ITRS). This is approximately a geocentric system, although strictly it is defined by a series of reference locations near the surface of the Earth. For more background on the ITRS, see the references provided in the See Also section of the documentation.

Parameters
• data (~astropy.coordinates.BaseRepresentation subclass instance) – A representation object or None to have no data (or use the coordinate component arguments, see below).

• representation_type (~astropy.coordinates.BaseRepresentation subclass, str, optional) – A representation class or string name of a representation class. This sets the expected input representation class, thereby changing the expected keyword arguments for the data passed in. For example, passing representation_type='cartesian' will make the classes expect position data with cartesian names, i.e. x, y, z in most cases unless overriden via frame_specific_representation_info. To see this frame’s names, check out <this frame>().representation_info.

• differential_type (~astropy.coordinates.BaseDifferential subclass, str, dict, optional) – A differential class or dictionary of differential classes (currently only a velocity differential with key ‘s’ is supported). This sets the expected input differential class, thereby changing the expected keyword arguments of the data passed in. For example, passing differential_type='cartesian' will make the classes expect velocity data with the argument names v_x, v_y, v_z unless overriden via frame_specific_representation_info. To see this frame’s names, check out <this frame>().representation_info.

• copy (bool, optional) – If True (default), make copies of the input coordinate arrays. Can only be passed in as a keyword argument.

property earth_location

The data in this frame as an ~astropy.coordinates.EarthLocation class.

class poliastro.frames.fixed.MarsFixed(*args, **kwargs)
equatorial
class poliastro.frames.fixed.JupiterFixed(*args, **kwargs)
equatorial
class poliastro.frames.fixed.SaturnFixed(*args, **kwargs)
equatorial
class poliastro.frames.fixed.UranusFixed(*args, **kwargs)
equatorial
class poliastro.frames.fixed.NeptuneFixed(*args, **kwargs)
equatorial

## Util¶

poliastro.frames.util.get_frame(attractor, plane, obstime=<Time object: scale='tt' format='jyear_str' value=J2000.000>)

Returns an appropriate reference frame from an attractor and a plane.

Available planes are Earth equator (parallel to GCRS) and Earth ecliptic. The fundamental direction of both is the equinox of epoch (J2000). An obstime is needed to properly locate the attractor.

Parameters
• attractor () – Body that serves as the center of the frame.

• plane (Planes) – Fundamental plane of the frame.

• obstime (Time) – Time of the frame.