1# -*- coding: utf-8 -*-
2# Licensed under a 3-clause BSD style license - see LICENSE.rst
3"""
4Coordinate frames tied to the Equator and Equinox of Earth.
5
6TEME is a True equator, Mean Equinox coordinate frame used in NORAD TLE
7satellite files.
8
9TETE is a True equator, True Equinox coordinate frame often called the
10"apparent" coordinates. It is the same frame as used by JPL Horizons
11and can be combined with Local Apparent Sidereal Time to calculate the
12hour angle.
13"""
14
15from astropy.utils.decorators import format_doc
16from astropy.coordinates.representation import (CartesianRepresentation, CartesianDifferential)
17from astropy.coordinates.baseframe import BaseCoordinateFrame, base_doc
18from astropy.coordinates.builtin_frames.baseradec import BaseRADecFrame, doc_components
19from astropy.coordinates.attributes import TimeAttribute, EarthLocationAttribute
20from .utils import DEFAULT_OBSTIME, EARTH_CENTER
21
22__all__ = ['TEME', 'TETE']
23
24doc_footer_teme = """
25    Other parameters
26    ----------------
27    obstime : `~astropy.time.Time`
28        The time at which the frame is defined.  Used for determining the
29        position of the Earth.
30"""
31
32doc_footer_tete = """
33    Other parameters
34    ----------------
35    obstime : `~astropy.time.Time`
36        The time at which the observation is taken.  Used for determining the
37        position of the Earth.
38    location : `~astropy.coordinates.EarthLocation`
39        The location on the Earth.  This can be specified either as an
40        `~astropy.coordinates.EarthLocation` object or as anything that can be
41        transformed to an `~astropy.coordinates.ITRS` frame. The default is the
42        centre of the Earth.
43"""
44
45
46@format_doc(base_doc, components=doc_components, footer=doc_footer_tete)
47class TETE(BaseRADecFrame):
48    """
49    An equatorial coordinate or frame using the True Equator and True Equinox (TETE).
50
51    Equatorial coordinate frames measure RA with respect to the equinox and declination
52    with with respect to the equator. The location of the equinox and equator vary due
53    the gravitational torques on the oblate Earth. This variation is split into precession
54    and nutation, although really they are two aspects of a single phenomena. The smooth,
55    long term variation is known as precession, whilst smaller, periodic components are
56    called nutation.
57
58    Calculation of the true equator and equinox involves the application of both precession
59    and nutation, whilst only applying precession gives a mean equator and equinox.
60
61    TETE coordinates are often referred to as "apparent" coordinates, or
62    "apparent place". TETE is the apparent coordinate system used by JPL Horizons
63    and is the correct coordinate system to use when combining the right ascension
64    with local apparent sidereal time to calculate the apparent (TIRS) hour angle.
65
66    For more background on TETE, see the references provided in the
67    :ref:`astropy:astropy-coordinates-seealso` section of the documentation.
68    Of particular note are Sections 5 and 6 of
69    `USNO Circular 179 <https://arxiv.org/abs/astro-ph/0602086>`_) and
70    especially the diagram at the top of page 57.
71
72    This frame also includes frames that are defined *relative* to the center of the Earth,
73    but that are offset (in both position and velocity) from the center of the Earth. You
74    may see such non-geocentric coordinates referred to as "topocentric".
75
76    The frame attributes are listed under **Other Parameters**.
77    """
78
79    obstime = TimeAttribute(default=DEFAULT_OBSTIME)
80    location = EarthLocationAttribute(default=EARTH_CENTER)
81
82# Self transform goes through ICRS and is defined in icrs_cirs_transforms.py
83
84
85@format_doc(base_doc, components="", footer=doc_footer_teme)
86class TEME(BaseCoordinateFrame):
87    """
88    A coordinate or frame in the True Equator Mean Equinox frame (TEME).
89
90    This frame is a geocentric system similar to CIRS or geocentric apparent place,
91    except that the mean sidereal time is used to rotate from TIRS. TEME coordinates
92    are most often used in combination with orbital data for satellites in the
93    two-line-ephemeris format.
94
95    Different implementations of the TEME frame exist. For clarity, this frame follows the
96    conventions and relations to other frames that are set out in Vallado et al (2006).
97
98    For more background on TEME, see the references provided in the
99    :ref:`astropy:astropy-coordinates-seealso` section of the documentation.
100    """
101
102    default_representation = CartesianRepresentation
103    default_differential = CartesianDifferential
104
105    obstime = TimeAttribute()
106
107# Transformation functions for getting to/from TEME and ITRS are in
108# intermediate rotation transforms.py
109