Skip to main content

Code Examples

Interaction with Satcat Launch can be fully automated using the Satcat SDK or CLI tools. This page provides examples of how to create, configure, and run Satcat Launch launch screenings in order to help integrate our services into your platform.

Complete Screening Job​

In this example, a launch screening is created and configured with a single primary launch ephemeris, a launch window, and a secondary catalog.

Code Example - Complete Launch Screening Job
# Upload an O/O ephemeris file
ephemeris = client.screening.create_ephemeris(
    "23_Launch_Payload_Caliper.txt",
    file_format="caliper",
    hbr_m=15.0
)

# Configure the launch screening
configuration = kayhan.ScreeningConfiguration(
    screening_type="LAUNCH",
    launch_window_start=kayhan.utc("2023-01-01T00:00:00.000Z"),
    launch_window_end=kayhan.utc("2023-01-01T01:00:00.000Z"),
    launch_window_cadence_s=1,
)

# Create the screening
screening = client.screening.create_screening(
    config=configuration,
    primaries=[ephemeris],
    add_best_secondary_catalog=True,
)

Secondary Data​

Adding a Catalog​

Using a catalog as a secondary tells Satcat Launch to screen the primaries against all ephemerides in the catalog. Satcat Launch provides two indicators to help select an appropriate catalog for a screening:

  • Latest   The most recently created catalog for a given catalog type
  • Best   The latest catalog for the best catalog type available to the user's organization (Typically SP)
Code Example - Retrieve the Latest Catalog
catalog = client.screening.get_latest_catalog()
Code Example - Using the "Best Catalog" Setting
screening = client.screening.create_screening(
    ...
    add_best_secondary_catalog=True,
)

Adding Ephemerides​

One or more ephemerides can be used directly as secondaries instead of a catalog.

Code Example - Uploading an Ephemeris
ephemeris = client.screening.create_ephemeris(
    "23_Launch_Payload_Caliper.txt",
    file_format="caliper",
    hbr_m=15.0
)
Code Example - Use an Ephemeris as a Secondary by Unique ID
# Example 1: Retrieve an explicit Ephemeris by ID (ephemeris_id)
ephemeris = client.screening.get_ephemeris(ephemeris_id)

# Example 2: Retrieve the Ephemeris for a specific object by Norad Catalog ID (e.g. 25544) from a Catalog (by catalog_id)
ephemeris = client.screening.list_catalog_ephemerides(catalog_id, filters=[{"field": "norad_cat_id", "value": 25544}])[0]

# Example 3: Upload an Ephemeris to use as a Secondary
ephemeris = client.screening.create_ephemeris("MEME_12345_OEM_20230301.txt", file_format="OEM", comments="Custom Ephemeris for Object 12345")

screening = client.screening.create_screening(
    ...
    secondaries=[ephemeris]
)

Modifying Threshold Radius Values​

The Threshold Radius is the distance at which two objects in the space domain are considered to have a Conjunction, or "close approach". Satcat Launch also allows setting different threshold radius values for secondary objects of different categories.

Code Example - Setting the Threshold Radius
configuration = kayhan.ScreeningConfiguration(
    ...,
    threshold_radius_km = 15.0
)
screening = client.screening.create_screening(
    config=configuration,
    ...
)

Code Example - Setting a Category-specific Threshold Radius
configuration = kayhan.ScreeningConfiguration(
    ...,
    threshold_radius_manned_km = 200.0,
    threshold_radius_active_km = 25.0,
    threshold_radius_debris_km = 2.5
)
screening = client.screening.create_screening(
    config=configuration,
    ...
)

Strict Coverage​

The Coverage of a Primary is the amount of the Primary ephemeris which overlaps in time with the Secondary ephemerides. Satcat Launch provides an optional "Strict Coverage" configuration parameter (enabled by default) which can be disabled to allow a screening to be performed even with PARTIAL coverage.

Learn more about Coverage

Code Example - Disable Strict Coverage
screening = client.screening.create_screening(
    ...
    strict_coverage=False # manually disable the Strict Coverage setting
)

Submission​

Code Example - Submitting at Creation Time
screening = client.screening.create_screening(
    ...
    submit=True # automatically submit the Screening during creation
)
Code Example - Submitting Manually
client.screening.submit_screening(screening)

Waiting for Results​

Satcat Launch Screenings are asynchronous operations which are processed in a queue on Kayhan servers. Satcat Launch provides tools to check the status of a screening, or automatically poll the server to await its completion.

Code Example - Awaiting Screening Completion
# Refresh the screening object and check its status
screening = client.screening.get_screening(screening.id)
print(screening.status)

# Await the completion of the screening automatically
screening = client.screening.await_screening_completion(screening)

Conjunction Results​

Once the screening is complete, you can review the Conjunctions which were identified during screening.

Code Example - Listing Conjunction Results
conjunctions = client.list_conjunctions(screening)
tip

You can also use the filters, sort_field, sort_direction, and count fields to dynamically query the Screening's Conjunctions. For example, to order the conjunction list by Probability of Collision (highest first):

conjunctions = client.list_conjunctions(
    screening, 
    sort_field="collision_probability", 
    sort_direction="desc"
)