Import a real fleet

What you will accomplish

A constellation built from real cataloged objects, propagated in a way that is actually valid.

Two mistakes make this analysis worthless, and neither produces an error message. This guide is mostly about avoiding them.

Prerequisites

Installation complete.
A TLE file, from CelesTrak, Space-Track, or the examples directory.

Steps

Import


orbitforge import-tle \
  --input stations.tle \
  --name iss \
  --output iss.json


Imported 24 satellites (skipped 0) -> iss.json
Reference epoch: 2026-06-25T19:29:47Z. Simulate with --start 2026-06-25T19:29:47Z

Read the second line

That line is the entire discipline of this guide. Copy the epoch.

skipped 0 is the other thing to check. A non-zero count usually means a truncated download rather than genuinely bad objects.

Propagate at the right epoch, with the right model


orbitforge simulate \
  --constellation iss.json \
  --start 2026-06-25T19:29:47Z \
  --duration-hours 2 \
  --model sgp4


Simulated 24 satellites over 2.0 h at 60 s steps (121 samples each) using sgp4.

The two silent failures

Failure one: the default epoch

Omit --start and the run uses the default epoch, 2026-01-01T00:00:00Z, which is nearly six months before these elements were fitted:


orbitforge simulate --constellation iss.json --duration-hours 2 --model sgp4


Simulated 24 satellites over 2.0 h at 60 s steps (121 samples each) using sgp4.

That output is identical to the correct run. Same satellite count, same sample count, same model, no warning.

TLEs are fitted to observations around their epoch. Propagating months away extrapolates a fit rather than integrating physics, and the accuracy degrades from roughly a kilometer at epoch to far worse across weeks, faster for low-perigee objects where drag dominates.

Nothing in the tool, the output, or the exported files will tell you the positions are meaningless. The only defense is passing the epoch the import reported.

Failure two: the wrong propagation model


orbitforge simulate --constellation iss.json --model numerical --duration-hours 2

TLE elements are mean elements in SGP4’s own theory, not osculating elements another propagator can consume. Feeding them to a numerical or J2 model produces a trajectory that is confidently wrong: the arithmetic succeeds while the inputs mean something different from what the model assumes.

Use --model sgp4 on every command that consumes a TLE-imported constellation.

Checking your work

Two questions to ask of any result from imported elements:

How old are the elements? Compare the reported reference epoch against your analysis window. Days is fine, weeks is marginal, months is not.
Which model ran? The simulate summary prints it. If it does not say sgp4 on a TLE import, the result is invalid regardless of how reasonable it looks.

What a TLE does not give you

Carried	Not carried
Mean elements at an epoch	Payload or field of view
B-star drag term	Mass, area, attitude
Catalog identifiers	Transmit power or antenna
Epoch	Any covariance

--fov-deg exists on the import for exactly this reason: coverage analysis needs a sensor and the file has none, so you supply one and should say so when quoting the result.

The missing covariance matters more than it looks. There is no uncertainty information in the data at all, so any probability computed downstream, such as a collision probability, rests on covariance you supplied from elsewhere.

Analyzing the imported fleet

Once imported and propagated correctly, every analysis works normally:


orbitforge coverage --constellation iss.json \
  --start 2026-06-25T19:29:47Z \
  --duration-hours 6 --step-seconds 60 --grid-deg 10 --model sgp4
 
orbitforge conjunction screen --constellation iss.json \
  --start 2026-06-25T19:29:47Z \
  --duration-hours 24 --threshold-km 10

Pass --start and --model sgp4 on every one. The epoch discipline is not a property of the import; it applies to every command that touches the result.

Next steps

import-tle reference for the full flag set.
TLE format for what each field means.
Propagation fidelity.

Question? Give us feedbackDocuments Varaha Constellation Designer main (pre-release)