Screening#

Uploading an Ephemeris#

Most Satcat operational on-demand screening workflows begin with uploading an ephemeris file propagated from an owner/operator orbit determination solution. This ephemeris can be any one of the formats supported by Satcat, and may contain any number of maneuvers. To retrieve the list of supported ephemeris file formats from the server, you can use list_ephemeris_formats or the CLI satcat list ephemeris-formats.

Warning

If your ephemeris contains maneuvers, they should be indicated explicitly by whatever mechanism the ephemeris format provides for specifying discontinuities. For example, the CCSDS OEM format dictates that separate “blocks” are separated by discontinuities. This prevents interpolation from taking place over maneuvers, which is critical to the accuracy of screening.

To upload an ephemeris to the Satcat API, use create_ephemeris:

...
ephemeris = client.screening.create_ephemeris(
    "MEME_25544_ISS_Ephemeris_2022181_OEM.txt",
    file_format="oem",
    norad_id=25544
)

You can specify either a filename or an open file-like object in readable binary mode for the create_ephemeris path_or_buf argument.

Note

You must specify both the file format of the ephemeris as well as the NORAD Catalog ID of the object that the ephemeris describes while uploading the file. This information helps us parse your file, and prevents us from screening the data in your file against the catalog data for the same object.

Creating a Screening#

Now that the ephemeris has been uploaded, we can create a screening to identify any conjunctions in the ephemeris with the latest catalog data using create_screening. For example:

...
screening = client.screening.create_screening(
    primaries=[ephemeris],
    add_best_secondary_catalog=True,
    add_operational_ephemeris_repository=True,
    submit=True
)

This is an example of the simplest screening configuration you can create. Let’s review the parameters being used:

primaries

Here, we specify which ephemerides we want to consider “primary” objects for the screening. We want to screen our uploaded ephemeris, so we pass it in the primaries list.

Note

It is possible to include multiple ephemerides as primaries in a single screening.

add_best_secondary_catalog

Here, we specify that Satcat should automatically use the best available catalog data for secondary ephemerides for this screening. Typically, this is a good choice for operational screenings, as it represents both the highest fidelity and the most up-to-date catalog data that you have access to through Satcat.

However, if you would rather configure a specific secondary catalog or specific secondary ephemerides, you can instead use the secondaries parameter.

add_operational_ephemeris_repository

Here, we specify that Satcat should automatically add all ephemeris available on the Satcat servers that have a “designation” of OPERATIONAL and a “usable_time_end” in the future. These can be ephemeris uploaded by your organization, or from any organization that is opted-in to Satcat’s coordination feature, see Operational Data.

submit

Here, we tell the SDK to automatically submit the screening for processing once it has been created.

If you pass submit=False, the screening resource will be created and configured on the Satcat servers, but left in a “configuring” state for you to make further configuration changes through either the SDK, CLI, or the Satcat web platform. You can then submit the screening using submit_screening.

This action can be useful if additional configuration is required for the desired screening job, just as adding or removing primary and secondary screenables, updating screening properties, adding notes, etc.

Note

Multiple secondary sources are supported for application within a single screening, e.g. secondary can consist of entire catalogs, specific objects from catalogs, or ephemerides, include those generated by propagations.

Retrieving Results#

Satcat Screenings are asynchronous operations which are processed in a queue on Satcat servers. Once a screening is submitted, you can check its status using get_screening:

screening = client.screening.get_screening(screening.id)
print(screening.status)

Satcat SDK also provides support for automatically polling a screening and waiting until it is completed, using await_screening_completion:

screening = client.screening.await_screening_completion(screening)

Note

await_screening_completion automatically polls the Satcat API for results. The cadence and timeout of this polling operation can be configured using the poll_interval and timeout parameters.

Once a screening is complete, you can retrieve the conjunctions that were detected by the screening using list_conjunctions:

conjunctions = client.screening.list_conjunctions(screening.id)
print(conjunctions)

Downloading an Ephemeris#

You can also download the content of an ephemeris file on the Satcat servers. This includes:

  • Owner/Operator ephemerides that you have uploaded or have access to

  • Ephemerides created during propagation using the Satcat propagation features

  • Ephemerides from any catalogs to which you have access

To download an ephemeris, all you need is its unique identifier (id) and the file format in which you want the ephemeris to be downloaded. Then, you can use download_ephemeris to download the file content.

Note

Currently, only the "OEM" and "NASA" formats are supported for ephemeris file downloads (case insensitive).

For example, to upload an ephemeris file and download it in another format:

# Upload an ephemeris in the NASA ephemeris file format
ephemeris = client.screening.create_ephemeris(
    "MEME_25544_ISS_NASA_EPHEMERIS.txt",
    file_format="nasa",
    norad_id=25544
)

# Download the ephemeris in the OEM ephemeris file format
oem_file_content = client.screening.download_ephemeris(ephemeris.id, file_format="oem")
print(oem_file_content.read())

Note

The return value of download_ephemeris is a Python File-like object in text mode, not a string. This object is similar to a file object you would get by calling the python open() function to open a file on your disk. To get the str content of the ephemeris file, you may use .read() to read the contents of the file as demonstrated in the above example.

Designating an Ephemeris as OPERATIONAL#

When an ephemeris is created, a designation can be set, this value helps determine its operational status and how it should be interpreted. An OPERATIONAL designation represents the Owner/Operator intended trajectory for an asset, making it a crucial designation for flight operations. Additional information about this designation and others is available for review at Satcat Documentation - Operational Data.

If an ephemeris was created with a non-operational designation, but should be designated as OPERATIONAL for any reason, it can be elevated to this designation by providing its id to the operationalize method below:

ephemeris = client.screening.operationalize_ephemeris(
    ephemeris.id,
)
print(f"{ephemeris.id} designation: {ephemeris.designation}")