Orbis.Eclipse (Orbis v0.8.0)

Copy Markdown View Source

Earth shadow (eclipse) prediction for satellites.

Determines whether a satellite is in full sunlight, penumbra, or umbra using a conical shadow model. This is critical for satellite power budgets, thermal analysis, and optical visibility.

Shadow Model

Uses the conical shadow model which computes the penumbra and umbra cones cast by Earth given the Sun's position. The satellite's position relative to these cones determines its illumination state.

Example

# Direct usage with pre-computed positions
status = Orbis.Eclipse.status(satellite_gcrs_position, sun_position_from_earth)
# => :sunlit | :penumbra | :umbra

# Convenience: propagate + transform + check in one call
status = Orbis.Eclipse.check(tle, datetime, ephemeris)

Summary

Functions

check(tle, datetime, ephemeris)

Convenience function: propagate a TLE, transform to GCRS, fetch the Sun position from an ephemeris, and return the eclipse status.

shadow_fraction(arg1, arg2)

Compute the shadow fraction for a satellite.

status(sat_pos, sun_pos)

Determine the eclipse status of a satellite.

Functions

check(tle, datetime, ephemeris)

@spec check(Orbis.Elements.t(), DateTime.t(), Orbis.Ephemeris.t()) ::
  {:ok, :sunlit | :penumbra | :umbra} | {:error, String.t()}

Convenience function: propagate a TLE, transform to GCRS, fetch the Sun position from an ephemeris, and return the eclipse status.

Parameters

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

Returns

  • :sunlit, :penumbra, or :umbra

Example

{:ok, tle} = Orbis.parse_tle(line1, line2)
eph = Orbis.Ephemeris.load("de421.bsp")
status = Orbis.Eclipse.check(tle, ~U[2024-06-21 12:00:00Z], eph)

shadow_fraction(arg1, arg2)

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

Compute the shadow fraction for a satellite.

Returns a value from 0.0 (full sunlight) to 1.0 (full umbra). Values between 0 and 1 indicate partial shadow (penumbra).

Parameters

  • sat_pos - satellite GCRS position {x, y, z} in km
  • sun_pos - Sun position relative to Earth {x, y, z} in km (vector from Earth center to the Sun)

status(sat_pos, sun_pos)

@spec status(
  {float(), float(), float()},
  {float(), float(), float()}
) :: :sunlit | :penumbra | :umbra

Determine the eclipse status of a satellite.

Parameters

  • sat_pos - satellite GCRS position {x, y, z} in km
  • sun_pos - Sun position relative to Earth {x, y, z} in km (i.e., the vector from Earth center to the Sun)

Returns

  • :sunlit - satellite is in full sunlight
  • :penumbra - satellite is partially shadowed
  • :umbra - satellite is in full shadow