`orbitforge import-tle`

Synopsis


orbitforge import-tle --input <PATH> --name <NAME> --output <PATH> [OPTIONS]

Description

Reads a NORAD two-line element file and builds a constellation from real, cataloged objects. This is how you analyze an existing fleet rather than a design.

Imported satellites carry their source TLE, which is what makes --model sgp4 available on later commands.

Options

Parameter	Type	Unit	Default	Required	Description
`--input`	path	n/a	—	Yes	TLE file, in two-line or three-line named format.
`--name`	string	n/a	—	Yes	Constellation name, used for identifiers and labels.
`--output`	path	n/a	—	Yes	Output constellation JSON path.
`--epoch`	string	RFC 3339 UTC	—	No	Common reference epoch. Defaults to the latest TLE epoch in the file.
`--fov-deg`	float	deg	`45`	No	Payload field of view assigned to every imported satellite. TLEs carry no payload information, so this is yours to supply.

Worked example


orbitforge import-tle \
  --input stations.tle \
  --name iss-demo \
  --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

The second line is not decoration. TLEs are fitted to observations around their epoch, and propagating far from it extrapolates a fit rather than integrating physics. Passing the printed epoch to simulate --start keeps the analysis where the elements are valid.

Ignore it and you will silently propagate from a default epoch that may be months away from the data, producing positions that are confidently wrong.

Input format

Both the two-line and three-line named forms are accepted:


ISS (ZARYA)
1 25544U 98067A   26176.70356236  .00009385  00000+0  17567-3 0  9997
2 25544  51.6325 257.9368 0004376 231.2480 128.8118 15.49425151573072

The optional first line is the object name. Without it, satellites are identified by catalog number.

Malformed entries are skipped rather than aborting the import, and the count is reported. A non-zero skip count is worth investigating: it usually means a truncated download or a checksum failure rather than a genuinely bad object.

What a TLE does and does not carry

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

Everything in the right column must be supplied separately. --fov-deg exists precisely because coverage analysis needs a sensor and the TLE has none.

Only SGP4 is valid

TLEs are fitted to the SGP4 model. The two are a matched pair, and the element set has no meaning outside it. Propagating imported TLEs with --model numerical or --model j2 produces a confidently wrong trajectory, because the elements are mean elements in SGP4’s own theory rather than osculating elements any other propagator can consume.

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

Model basis: TLE import and SGP4 propagation

Assumptions: Elements are mean elements in the SGP4/SDP4 theory at the stated epoch; the file's checksum and format follow the NORAD two-line specification; all satellites are re-referenced to a single common epoch for joint analysis.
Validity range: Near the element epoch. Accuracy degrades with epoch age, typically to kilometers within days and substantially worse across weeks, and degrades faster for low-perigee objects where drag dominates.
Accuracy: Position error of order one kilometer at epoch for a well-tracked object, growing with epoch age. TLEs carry no covariance, so no uncertainty is available from the data itself.
Reference: Hoots and Roehrich, Spacetrack Report No. 3, Models for Propagation of NORAD Element Sets, and its 2006 revision by Vallado and others.

orbitforge import-tle