# `Astro.Coordinates`
[🔗](https://github.com/kipcole9/astro/blob/v2.1.0/lib/astro/coordinates.ex#L1)

Coordinate transformations for high-precision lunar and solar
position calculations.

Provides:
- Conversion of UTC `DateTime` to TDB seconds past J2000.0 (the time
  argument used by JPL ephemerides).
- Conversion of TDB seconds back to UTC `DateTime`.
- Rotation of ICRF/J2000 Cartesian coordinates to the true equator and
  equinox of date using IAU 1980 precession and nutation.
- Conversion of equatorial Cartesian to spherical (RA, Dec, distance).
- Greenwich Apparent Sidereal Time (GAST) for the topocentric iteration.

## Time scale convention

JPL ephemeris data is in TDB (Barycentric Dynamical Time). For the
purpose of rise/set calculations, TDB ≈ TT to within 2 ms; this
difference is negligible and TDB is treated as TT here.

ΔT = TT − UTC varies over time; see `Astro.Time.delta_t/1` for the
unified computation.

## Reference

Precession: Lieske et al. (1977), A&A 58, 1–16.
Nutation:   IAU 1980 series, Wahr (1981), Meeus Ch.22 (top 17 terms).
GAST:       Meeus Ch.12 with equation of the equinoxes.

# `cartesian_to_spherical`

```elixir
@spec cartesian_to_spherical({float(), float(), float()}) ::
  {float(), float(), float()}
```

Converts equatorial Cartesian coordinates to spherical coordinates.

### Arguments

* `{x, y, z}` is an equatorial Cartesian position vector in
  kilometers.

### Returns

* `{ra_deg, dec_deg, distance_km}` where right ascension is
  in degrees in the range [0, 360), declination is in degrees
  in the range [-90, 90], and distance is in kilometers.

# `dynamical_time_from_moment`

Converts a moment to dynamical time (TDB seconds past J2000.0).

Delegates to `Astro.Time.dynamical_time_from_moment/1`.

### Arguments

* `moment` is a moment (fractional days since epoch).

### Returns

* TDB seconds past J2000.0 as a float.

# `dynamical_time_to_moment`

Converts dynamical time back to a moment.

Delegates to `Astro.Time.dynamical_time_to_moment/1`.

### Arguments

* `dynamical_time` is TDB seconds past J2000.0.

### Returns

* A moment (fractional days since epoch) as a float.

# `gast`

```elixir
@spec gast(float()) :: float()
```

Computes Greenwich Apparent Sidereal Time (GAST) in degrees.

GMST is computed from UT1 (≈ UTC) using Meeus equation 12.4,
then corrected by the equation of the equinoxes (Δψ · cos ε)
to obtain GAST.

### Arguments

* `dynamical_time` is TDB seconds past J2000.0. ΔT is
  subtracted internally to recover UT1 for the sidereal
  rotation rate.

### Returns

* GAST in degrees, normalized to the range [0, 360).

# `icrf_to_true_equator`

```elixir
@spec icrf_to_true_equator({float(), float(), float()}, float()) ::
  {float(), float(), float()}
```

Rotates a J2000.0 ICRF Cartesian vector to the true equator
and equinox of date, applying IAU 1980 precession and nutation.

The precession matrix uses Lieske (1977) angles and the nutation
uses the top 17 terms of the IAU 1980 series via `Astro.Earth.nutation/1`.

### Arguments

* `{x, y, z}` is a Cartesian position vector in the ICRF/J2000
  frame, in any consistent unit (typically kilometers).

* `dynamical_time` is TDB seconds past J2000.0.

### Returns

* `{x', y', z'}` in the true equator and equinox of date frame,
  in the same units as the input.

# `julian_centuries_from_dynamical_time`

Returns Julian centuries from J2000.0 for the given dynamical time.

Delegates to `Astro.Time.julian_centuries_from_dynamical_time/1`.

### Arguments

* `dynamical_time` is TDB seconds past J2000.0.

### Returns

* Julian centuries from J2000.0 as a float.

---

*Consult [api-reference.md](api-reference.md) for complete listing*