`orbitforge coverage`

Synopsis


orbitforge coverage --constellation <PATH> [OPTIONS]

Description

Lays a grid over the Earth, propagates the constellation, and tests every grid point against every satellite at every time step. Reports what fraction of the window each point was covered, how many satellites were visible at once, and how long the longest gap was.

Coverage is geometry. It says a satellite was above the mask, not that a usable signal arrived; that is link.

Options

Window and grid.
Parameter	Type	Unit	Default	Required	Description
`--constellation`	path	n/a	—	Yes	Path to a constellation JSON file.
`--start`	string	RFC 3339 UTC	`2026-01-01T00:00:00Z`	No	Analysis start epoch.
`--duration-hours`	float	h	`24`	No	Analysis window length.
`--step-seconds`	float	s	`60`	No	Time step. A gap shorter than this is invisible.
`--grid-deg`	float	deg	—	Yes	Grid spacing. A hole smaller than this can fall between sample points.
`--model`	enum	n/a	`two-body`	No	Propagation model.

Visibility and sensor.
Parameter	Type	Unit	Default	Required	Description
`--min-elevation-deg`	float	deg	—	No	Elevation mask. A point counts as covered only above this angle.
`--sensor-shape`	enum	n/a	—	No	Footprint shape: conical, or rectangular for a pushbroom swath.
`--sensor-half-angle-deg`	float	deg	—	No	Conical sensor half-angle.
`--sensor-cone-deg`	float	deg	—	No	Cone angle for the conical footprint.
`--sensor-along-deg`	float	deg	—	No	Along-track extent of a rectangular footprint.
`--sensor-cross-deg`	float	deg	—	No	Cross-track extent of a rectangular footprint.
`--sensor-pitch-deg`	float	deg	—	No	Sensor pitch offset from nadir.
`--sensor-roll-deg`	float	deg	—	No	Sensor roll offset from nadir, for off-nadir pointing.

This command prints its summary and takes no --output. Run orbitforge coverage --help for the complete flag set.

Worked examples

Coarse survey, no mask


orbitforge coverage \
  --constellation demo.json \
  --duration-hours 6 --step-seconds 60 \
  --grid-deg 10


Coverage over 684 grid points (10 deg), 60 sats, 6.0 h at 60 s:
  mean coverage 70.2% (area-weighted), min 0.0%, fully covered 10.5%, any 68.4%
  max fold 3, max coverage gap 5760 s

Finer grid, longer window, realistic mask


orbitforge coverage \
  --constellation demo.json \
  --duration-hours 24 --step-seconds 120 \
  --grid-deg 5 --min-elevation-deg 25


Coverage over 2664 grid points (5 deg), 60 sats, 24.0 h at 120 s:
  mean coverage 29.6% (area-weighted), min 0.0%, fully covered 0.0%, any 67.6%
  max fold 2, max coverage gap 9960 s

What the elevation mask costs

The two runs above are the same constellation. The differences are worth reading carefully, because they are the single most common source of an over-optimistic coverage claim.

Statistic	No mask, 6 h	25-degree mask, 24 h	Change
Mean coverage	70.2 percent	29.6 percent	Less than half
Fully covered	10.5 percent	0.0 percent	Nothing is continuously covered
Max fold	3	2	One fewer simultaneous satellite
Max gap	5760 s	9960 s	96 minutes becomes 166

Mean coverage more than halved because of the mask, not the constellation. A satellite at 5 degrees elevation is geometrically visible and practically useless: the slant range is at its longest and the signal crosses the most atmosphere.

Quoting coverage without stating the elevation mask is quoting a number that no real ground segment will achieve. State the mask every time.

The fully covered figure falling to zero is the more consequential result. At a 25-degree mask this design has no continuously covered point anywhere on Earth, which rules it out for any service that cannot tolerate an outage.

Grid spacing and step size

Both are cost-versus-truth trades, and both fail in the same direction: too coarse, and you under-report gaps.

Setting	Finer means	Guidance
`--grid-deg`	More points, longer run, smaller holes detected	10 degrees to explore, 2 or better for a quoted result
`--step-seconds`	More samples, longer run, shorter gaps detected	Well below the shortest pass you care about

Going from 10 to 5 degrees quadrupled the point count from 684 to 2664, because the grid is two-dimensional. Halving the spacing again would cost roughly four times as much run time.

Convergence check: halve both and re-run. If the maximum gap grows, the earlier numbers were optimistic and you have not converged.

Sensor footprints

Coverage depends on what the payload can see, not only on line of sight.

Shape	Flags	Models
Conical	`--sensor-shape`, `--sensor-cone-deg`	A symmetric circular footprint about the boresight
Rectangular	`--sensor-along-deg`, `--sensor-cross-deg`	A pushbroom swath, wide across track and narrow along it
Off-nadir	`--sensor-pitch-deg`, `--sensor-roll-deg`	A steered sensor, trading resolution for access

Without sensor flags the analysis uses line of sight subject to the elevation mask, which is the right model for communications. Imaging payloads need the sensor flags, because a pushbroom swath covers dramatically less area than a conical field of the same nominal angle.

orbitforge coverage