@spec compute(Orbis.Elements.t(), DateTime.t(), Orbis.Ephemeris.t()) ::
  {:ok, map()} | {:error, String.t()}

Compute all standard angles for a satellite at a given time.

Propagates the TLE, gets Sun and Moon positions from the ephemeris, and returns a map of angles.

Parameters

• tle - parsed %Orbis.Elements{} struct
• datetime - DateTime.t() observation time
• ephemeris - loaded %Orbis.Ephemeris{} handle

Returns

%{
  sun_angle: float(),       # nadir-to-Sun angle in degrees
  moon_angle: float(),      # nadir-to-Moon angle in degrees
  sun_elevation: float(),   # Sun elevation above local horizontal
  earth_angle: float()      # Earth angular radius from satellite
}

@spec earth_angular_radius({float(), float(), float()}) :: float()

Angular radius of the Earth as seen from the satellite.

This is the half-angle of the cone that just encloses the Earth's disk as seen from the satellite's position: asin(R_earth / |sat_position|).

Useful for eclipse geometry — if the Sun is within this angular radius of the anti-nadir direction, the satellite may be in Earth's shadow.

Parameters

• satellite_gcrs_position - {x, y, z} satellite position in GCRS (km)

Returns angular radius in degrees.

@spec moon_angle(
  {float(), float(), float()},
  {float(), float(), float()}
) :: float()

Angle between satellite nadir (toward Earth) and the Moon direction.

Parameters

• satellite_gcrs_position - {x, y, z} satellite position in GCRS (km)
• moon_position_from_earth - {x, y, z} Moon position relative to Earth (km)

Returns angle in degrees.

@spec phase_angle(
  {float(), float(), float()},
  {float(), float(), float()},
  {float(), float(), float()}
) :: float()

Sun-satellite-observer phase angle.

The phase angle is the angle at the satellite between the Sun and the observer. It determines the illumination geometry for optical brightness estimation:

• 0 deg = full phase (Sun behind observer, satellite fully lit)
• 180 deg = new phase (Sun behind satellite, satellite in shadow from observer)

Parameters

• satellite_gcrs_position - {x, y, z} satellite position in GCRS (km)
• sun_position_from_earth - {x, y, z} Sun position relative to Earth (km)
• observer_position - {x, y, z} observer position in GCRS (km)

Returns phase angle in degrees (0 to 180).

@spec sun_angle(
  {float(), float(), float()},
  {float(), float(), float()}
) :: float()

Angle between satellite nadir (toward Earth) and the Sun direction.

The nadir vector points from the satellite toward Earth's center, i.e., it is the negation of the satellite's GCRS position.

Parameters

• satellite_gcrs_position - {x, y, z} satellite position in GCRS (km)
• sun_position_from_earth - {x, y, z} Sun position relative to Earth (km)

Returns angle in degrees (0 = Sun is directly below satellite toward Earth, 180 = Sun is directly above/away from Earth).

@spec sun_elevation(
  {float(), float(), float()},
  {float(), float(), float()}
) :: float()

Sun elevation above or below the satellite's local horizontal plane.

The local horizontal plane is perpendicular to the radial (nadir) vector. Positive elevation means the Sun is on the sunlit (away from Earth) side; negative means it is on the shadow (Earth) side.

Parameters

• satellite_gcrs_position - {x, y, z} satellite position in GCRS (km)
• sun_position_from_earth - {x, y, z} Sun position relative to Earth (km)

Returns elevation in degrees (-90 to +90).