orbitforge import-ephem
Synopsis
orbitforge import-ephem (--oem <PATH> | --sp3 <PATH>) --name <NAME> --output <PATH> [OPTIONS]Description
Builds a constellation from externally supplied trajectories rather than from
orbital elements. Where import-tle brings in mean
elements to be propagated by SGP4, this brings in a table of states already
computed by someone else.
Use it to reproduce a trajectory exactly as another organization produced it, which is the usual requirement when working to an operator’s delivered ephemeris or a precise orbit product.
Options
| Parameter | Type | Unit | Default | Required | Description |
|---|---|---|---|---|---|
--oem | path | n/a | — | No | CCSDS Orbit Ephemeris Message, KVN format. Mutually exclusive with `--sp3`. |
--sp3 | path | n/a | — | No | SP3-c or SP3-d precise ephemeris. Mutually exclusive with `--oem`. |
--name | string | n/a | — | Yes | Constellation name, used for identifiers and labels. |
--output | path | n/a | — | Yes | Output constellation JSON path. |
--fov-deg | float | deg | 45 | No | Payload field of view assigned to every imported satellite. Ephemeris files carry no payload information. |
The two formats
| Format | Origin | Typical content |
|---|---|---|
| CCSDS OEM | Space agency and operator interchange | Position and velocity at tabulated epochs, with metadata declaring frame, time system, and interpolation method |
| SP3-c/d | GNSS precise orbit products | Position, and often clock, at a fixed interval, historically for navigation satellites |
Both are tables of states. Neither is a model, which is the important consequence: nothing in the file tells you how to compute a state outside the span it covers.
Only the ephemeris model is valid
Satellites imported this way must be propagated with --model ephemeris, and
only within the span the table covers. Outside it there is nothing to
interpolate.
Selecting a different model fails rather than silently substituting one:
Error: simulation failed
Caused by:
satellite `demo-s0-p00-sat00` has no ephemeris table; ephemeris propagation requires one (import via OEM or SP3)The converse error, selecting numerical on ephemeris-imported satellites, is
worse in principle: it would propagate from the first state under a force model
that has nothing to do with whatever produced the table, and the result would
diverge from the delivered trajectory it was supposed to reproduce.
What a table does and does not carry
| Carried | Not carried |
|---|---|
| Position and velocity at tabulated epochs | Payload field of view |
| Reference frame and time system, in OEM metadata | Mass, area, attitude |
| The span it covers | Any force model or ballistic coefficient |
| Sometimes a covariance, in OEM | A way to extrapolate |
--fov-deg exists for the same reason it does on TLE import: coverage analysis
needs a sensor and the file has none.
Interpolation
Between tabulated epochs the state is interpolated. The accuracy of that interpolation depends on the table’s own step relative to the orbital period: a table at 60-second steps supports far tighter interpolation than one at 15 minutes.
An OEM declares its intended interpolation method and degree in metadata, and honoring that declaration is what makes the reproduction faithful. A precise product tabulated for a specific interpolation scheme will not reproduce correctly under a different one.
Choosing an import path
The branch matters because the import path determines the propagation model, not the other way round. Two of the three leave you no choice at all.
See also
import-tlefor two-line element sources.simulateto propagate the result.- Propagation fidelity.
main (pre-release)