`orbitforge conjunction screen`

This is a design-stage screening filter, not an operational conjunction assessment service. Do not use its output to decide whether to execute an avoidance maneuver. Operational decisions require current, high-accuracy state estimates with maintained covariance from an authoritative source. See accuracy and limitations.

Its legitimate use is architectural: does this constellation geometry create conjunction pressure, and how does that change if I alter the design?

Synopsis


orbitforge conjunction screen --constellation <PATH> [OPTIONS]

Description

Propagates every object over a window, finds close approaches under a distance threshold, and reports the time of closest approach and miss distance. When a hard-body radius is supplied it also computes a collision probability.

Two modes:

Mode	Selected by	Screens
Intra-constellation	Default	Every pair within the constellation
Versus catalog	`--catalog`	Each constellation object against every catalog object

Intra-constellation screening answers whether your own design is self-consistent. Walker patterns are constructed so that satellites in adjacent planes do not collide, and this checks that the phasing actually achieves it.

Options

Parameter	Type	Unit	Default	Required	Description
`--constellation`	path	n/a	—	Yes	Path to a constellation JSON file.
`--catalog`	path	n/a	—	No	TLE catalog file. Screens constellation against catalog instead of against itself.
`--start`	string	RFC 3339 UTC	`2026-01-01T00:00:00Z`	No	Screening window start epoch.
`--duration-hours`	float	h	`72`	No	Window length.
`--threshold-km`	float	km	`10`	No	Report approaches closer than this.
`--step-seconds`	float	s	`60`	No	Coarse scan step. Candidate approaches are refined; see the note below.
`--hard-body-m`	float	m	—	No	Combined hard-body radius. Enables Foster 2D collision probability on each event.
`--ric-sigma-km`	string	km	`0.1,0.3,0.1`	No	Per-object radial, in-track, cross-track position sigmas, used with `--hard-body-m`.
`--top`	integer	count	`20`	No	Print at most this many events.
`--json`	path	n/a	—	No	Write the full event list.

Worked example

Screening the 60-satellite Walker shell against itself over 24 hours:


orbitforge conjunction screen \
  --constellation demo.json \
  --duration-hours 24 --threshold-km 10 --top 5


Screened 60 objects (all pairs) over 24.0 h: 0 events under 10 km.

Zero events is the expected and desired result for a well-phased Walker pattern. Satellites within a plane are evenly spaced along track, and the phasing offset staggers adjacent planes so that plane crossings do not coincide with satellites arriving at the crossing point.

A non-zero intra-constellation count is a design finding, not an operations problem. It usually means the phasing factor is wrong for the plane count, and it is fixed by changing the design rather than by planning maneuvers.

Collision probability

Supplying a hard-body radius enables a probability calculation on each event:


orbitforge conjunction screen \
  --constellation demo.json \
  --duration-hours 72 --threshold-km 5 \
  --hard-body-m 10 --ric-sigma-km 0.1,0.3,0.1

The RIC sigmas describe position uncertainty in the radial, in-track, and cross-track directions. In-track uncertainty is conventionally the largest, which the default 0.1,0.3,0.1 reflects: along-track error grows fastest under almost every error source.

The probability is only as meaningful as the covariance you supply. The default sigmas are a placeholder. Substituting real covariance from an orbit determination solution changes the answer by orders of magnitude, and a probability computed from placeholder sigmas should never be quoted as a risk figure.

Step size and missed events

The coarse scan samples at --step-seconds. A conjunction between two objects in low Earth orbit can have a relative velocity of several kilometers per second, so a 60-second step advances the relative position by hundreds of kilometers. Candidate approaches found by the coarse scan are refined to locate the true time of closest approach.

The practical consequence: a threshold much smaller than the distance traveled per step relies entirely on the refinement, so verify convergence by halving the step and confirming the event list is unchanged.

Model basis: Conjunction screening and Foster 2D probability

Assumptions: Objects propagated with the selected model; coarse temporal scan with refinement to the true time of closest approach; collision probability by the Foster 2D method, assuming a Gaussian relative position error, linear relative motion through the encounter, and a combined spherical hard body.
Validity range: Short-duration, high-relative-velocity encounters, where the linear-motion assumption holds. Not valid for long, slow encounters such as co-orbiting objects with small relative velocity.
Accuracy: Entirely governed by input state and covariance quality. With placeholder RIC sigmas the probability is illustrative only. Coarse step size can also cause events to be missed if refinement is not converged.
Reference: Foster and Estes, A parametric analysis of orbital debris collision probability and maneuver rate for space vehicles, NASA JSC, 1992.

orbitforge conjunction screen