Eclipse

POST/eclipse

Purpose

Finds when each satellite is in Earth’s shadow, distinguishing full shadow (umbra) from partial shadow (penumbra), and reports the fraction of the window each spacecraft spent in sunlight.

This drives power and thermal design: the longest eclipse sets battery capacity, and the eclipse count sets charge-cycle life.

Request

Parameter	Type	Unit	Default	Required	Description
`constellation_id`	string	n/a	—	Yes	Identifier of an existing constellation.
`start`	string	RFC 3339 UTC	`2026-01-01T00:00:00Z`	No	Analysis start epoch.
`duration_hours`	number	h	`6`	No	Analysis window length.
`step_seconds`	number	s	`60`	No	Scan step. Interval boundaries are refined below this resolution.
`propagation_model`	string	n/a	`two_body`	No	Propagation model.

Example


curl -s -X POST http://127.0.0.1:8080/eclipse \
  -H 'content-type: application/json' \
  -d '{"constellation_id":"demo","duration_hours":6.0}'


{
  "constellation_id": "demo",
  "start": "2026-01-01T00:00:00Z",
  "duration_hours": 6.0,
  "step_seconds": 60.0,
  "model": "two_body",
  "satellites": [
    {
      "satellite_id": "demo-s0-p00-sat00",
      "satellite_name": "demo-s0-p00-sat00",
      "sunlit_percent": 62.317708333333336,
      "umbra_seconds": 8057.34375,
      "penumbra_seconds": 82.03125,
      "intervals": []
    }
  ]
}

Response elided; one entry per satellite, each with its own intervals array.

Reading the result

Per-satellite fields.
Parameter	Type	Unit	Default	Required	Description
`sunlit_percent`	number	percent	—	No	Fraction of the window in full sunlight.
`umbra_seconds`	number	s	—	No	Total time in full shadow across the window.
`penumbra_seconds`	number	s	—	No	Total time in partial shadow.
`intervals`	array	n/a	—	No	Individual shadow entries with start and end times. This is what battery sizing needs.

Use intervals, not umbra_seconds, for battery sizing. The total is the sum across the whole window; what sizes a battery is the longest single interval, and only the array carries that.

Penumbra is about one percent of shadowed time

82 seconds of penumbra against 8057 seconds of umbra. The transition between full sun and full shadow takes well under a minute.

That is a power-bus requirement rather than a curiosity: array output collapses over tens of seconds, so the bus must handle a near-step transfer to battery. Modeling eclipse as an instantaneous switch is fine for energy budgeting and poor for transient analysis.

The response echoes its configuration

start, duration_hours, step_seconds, and model are repeated back. Given that unknown fields are silently ignored, this echo is the only confirmation that the settings you sent were the settings used. Check it.

Window length and sizing

A six-hour window answers what the shadow geometry looks like now. It does not answer what the worst eclipse of the mission will be, which is what battery sizing actually needs, because beta angle varies seasonally.

Run a window long enough to include that variation before quoting a figure.