SKYTRACE / V1← Back to dashboard

DOCUMENTATION / V1 USER GUIDE

SKYTRACE, explained simply.

A practical guide to the dashboard, TLE and OMM orbital data, freshness checks, screening results, and the limits of this experimental aerospace-engineering platform.

Important: SKYTRACE is an exploratory screening prototype, not an operational collision-warning or collision-avoidance service. A healthy dashboard or backend does not guarantee that fresh orbital data is available.

01. Use the dashboard

  1. Open the SKYTRACE dashboard.
  2. Read the summary cards and note the response timestamp.
  3. Review the closest-approach results table.
  4. Search by object name or catalog ID.
  5. Change the sorting order.
  6. Select Run screening to request a new response.

The dashboard's current screening action is instantaneous: it compares calculated object positions at one timestamp. It is not a future sampled-window run.

02. Understand TLE and OMM data

TLE (Two-Line Element): a fixed-format representation of mean orbital elements in two lines. TLE catalog identifiers are limited to five digits. SKYTRACE validates TLE structure, matching catalog identifiers, and line checksums.

OMM XML (Orbit Mean-Elements Message): a standardized XML representation of general-perturbations orbital elements and metadata. SKYTRACE parses OMM XML records and initializes SGP4 satellite objects from them. OMM can represent catalog identifiers beyond the five-digit TLE limitation.

SGP4: the propagation model used to calculate a satellite state from supported GP elements. SKYTRACE reports position in kilometres and velocity in kilometres per second, in the TEME frame.

OMM is a format, not a guarantee of newer or more accurate orbital data. Source and epoch still matter.

The API prefers OMM snapshots when available and retains a TLE fallback path. Snapshot retrieval time and element epoch are different.

CelesTrak GP data format documentation ↗

03. Read freshness and data-quality warnings

  • Fresh: element epoch is within the configured maximum age.
  • Stale: element epoch is older than the configured maximum age.
  • Future epoch: element epoch is later than the reference time.
  • Invalid epoch: epoch is missing, malformed, or unsupported by time-system rules.
  • Duplicate state: matching numerical states; a data-quality flag, not a collision alert.

The default freshness threshold is six hours. The configurable range is 0.1–72 hours. A larger threshold changes inclusion; it does not improve accuracy or quantify uncertainty.

An OMM epoch without an explicit UTC offset is interpreted as UTC only when the record declares TIME_SYSTEM=UTC. Explicit offsets are normalized to UTC. Unsupported naive epochs are invalid.

A newly downloaded file can contain old orbital elements. Retrieval time is not element epoch.

04. Understand screening and results

Separation (km): Euclidean distance between propagated position vectors. Catalog ID: object identifier. UTC: Coordinated Universal Time. Closest separation: the smallest separation among results returned for that calculation.

Instantaneous screening propagates eligible records to one timestamp. This is what the dashboard's current Run screening action requests.

Sampled-window screening evaluates separation at discrete timestamps. Its minimum is the smallest value among samples actually evaluated, not a guaranteed continuous-time minimum.

The TLE CLI is scripts/screen_approaches.py. The OMM sampled-window CLI is scripts/screen_omm.py.

python scripts/screen_omm.py --help
python scripts/screen_omm.py --data-file data/raw/<snapshot-name>.omm.xml --hours 1 --step-seconds 60

The OMM CLI accepts --data-file (required), --hours, --step-seconds, --top, --max-age-hours, and optional --start. It requires at least two fresh records.

05. Troubleshoot unavailable screening

HTTP 503 — insufficient fresh orbital data

The backend may be healthy while no available snapshot contains at least two records inside the freshness threshold. The API rejects the request rather than presenting stale data as current.

  1. Read the API error detail and freshness counts.
  2. Check /health separately.
  3. Wait for upstream orbital elements to update and retry later.
  4. Do not repeatedly force downloads or raise the age threshold just to obtain results.
  5. Do not treat an old result as current when a new request fails.

Backend health: https://skytrace-api.onrender.com/health. A successful health response confirms that the process responds; it does not prove fresh orbital data is available.

A free hosted backend may sleep while idle, so its first request can take longer. This is separate from stale or unavailable orbital elements.

06. Know the scientific limitations

  • Instantaneous screening compares positions at one timestamp.
  • Sampled-window calculations inspect discrete timestamps and can miss a closer approach between samples.
  • TLE/OMM age alone does not measure orbital uncertainty.
  • SKYTRACE does not calculate collision probability.
  • It does not provide covariance-based uncertainty propagation or validated operational risk classification.
  • Duplicate-state flags are data-quality findings, not collision alerts.
  • Passing software tests does not independently validate predictions against operational conjunction data.
Responsible use: SKYTRACE is an engineering and learning tool. Do not use it as the sole basis for spacecraft operations, manoeuvres, or collision-avoidance decisions.