satcat.sdk.screening package#

Submodules#

class satcat.sdk.screening.models.Catalog(**data)#

Bases: Model

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

archived: Optional[bool]#
catalog_type: Optional[str]#
epoch: Optional[datetime]#
filename: Optional[str]#
id: str#
ready: Optional[bool]#
class satcat.sdk.screening.models.Conjunction(**data)#

Bases: Model

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

cdm_id: Optional[int]#
collision_probability: Optional[float]#
collision_probability_method: Optional[str]#
created_at: Optional[datetime]#
id: Optional[str]#
property key: str#
key_number: int#
launch_time: Optional[datetime]#
miss_distance_km: float#
originator: Optional[str]#
primary: Optional[Ephemeris]#
secondary: Optional[Ephemeris]#
tca: datetime#
class satcat.sdk.screening.models.CoverageLevel(value)#

Bases: str, Enum

An enumeration.

FULL = 'FULL'#
NO_OVERLAP = 'NO_OVERLAP'#
PARTIAL = 'PARTIAL'#
class satcat.sdk.screening.models.Ephemeris(**data)#

Bases: Model

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

apogee_km: Optional[float]#
archived: Optional[bool]#
comments: Optional[str]#
context: Optional[EphemerisContext]#
current_operational: Optional[bool]#
data_format: Optional[str]#
designation: Optional[EphemerisDesignation]#
ephemeris_source: Union[EphemerisSource, str, None]#
filename: Optional[str]#
has_covariance: Optional[bool]#
hbr_m: Optional[float]#
id: Optional[str]#
launch_time: Optional[datetime]#
norad_id: Optional[int]#
perigee_km: Optional[float]#
solution_time: Optional[datetime]#
usable_time_end: Optional[datetime]#
usable_time_start: Optional[datetime]#
user_id: Optional[str]#
class satcat.sdk.screening.models.EphemerisContext(value)#

Bases: str, Enum

An enumeration.

COLA = 'COLA'#
DECAY = 'DECAY'#
MAINTENANCE = 'MAINTENANCE'#
NOVEL = 'NOVEL'#
ROUTINE = 'ROUTINE'#
class satcat.sdk.screening.models.EphemerisDesignation(value)#

Bases: str, Enum

An enumeration.

DEFINITIVE = 'DEFINITIVE'#
OPERATIONAL = 'OPERATIONAL'#
PREDICTIVE = 'PREDICTIVE'#
THEORETICAL = 'THEORETICAL'#
class satcat.sdk.screening.models.EphemerisGroup(value)#

Bases: str, Enum

An enumeration.

OPERATOR_REPOSITORY = 'OPERATOR_REPOSITORY'#
class satcat.sdk.screening.models.EphemerisSource(value)#

Bases: str, Enum

An enumeration.

CATALOG = 'CATALOG'#
KAYHAN_INTERNAL_PROCESS = 'KAYHAN_INTERNAL_PROCESS'#
PATHFINDER_API = 'PATHFINDER_API'#
PATHFINDER_AUTO_THIRDPARTY = 'PATHFINDER_AUTO_THIRDPARTY'#
SATCAT_API = 'SATCAT_API'#
SPACE_TRACK_PUBLIC = 'SPACE_TRACK_PUBLIC'#
TERTIARY_SCREENER = 'TERTIARY_SCREENER'#
USER_SCREENER = 'USER_SCREENER'#
class satcat.sdk.screening.models.EphemerisType(value)#

Bases: str, Enum

An enumeration.

LAUNCH = 'LAUNCH'#
ON_ORBIT = 'ON_ORBIT'#
class satcat.sdk.screening.models.ExternalCatalog(value)#

Bases: str, Enum

An enumeration.

class satcat.sdk.screening.models.GeminiScreening(**data)#

Bases: Model

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

conjunctions_under_thresholds_count: Optional[int]#
id: str#
status: str#
class satcat.sdk.screening.models.HardBodyShape(value)#

Bases: str, Enum

An enumeration.

CIRCLE = 'CIRCLE'#
SQUARE = 'SQUARE'#
class satcat.sdk.screening.models.RSO(**data)#

Bases: Model

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

norad_id: int#
object_name: Optional[str]#
object_type: Optional[str]#
class satcat.sdk.screening.models.Screenable(**data)#

Bases: Model

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

catalog: Optional[Catalog]#
catalog_id: Optional[str]#
coverage_level: Optional[CoverageLevel]#
coverage_ratio: Optional[float]#
ephemeris: Optional[Ephemeris]#
ephemeris_group: Optional[EphemerisGroup]#
ephemeris_id: Optional[str]#
external_catalogs: Optional[List[ExternalCatalog]]#
norad_id: Optional[int]#
propagation: Optional[Propagation]#
propagation_id: Optional[str]#
usable_time_end: Optional[datetime]#
usable_time_start: Optional[datetime]#
class satcat.sdk.screening.models.Screening(**data)#

Bases: ScreeningConfiguration

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

completed_at: Optional[datetime]#
conjunctions_count: Optional[int]#
coverage_level: Optional[CoverageLevel]#
coverage_ratio: Optional[float]#
created_at: Optional[datetime]#
id: str#
percent_complete: Optional[float]#
primaries_count: Optional[int]#
property primary_ids_preview: List[int]#
primary_rsos_preview: Optional[List[RSO]]#
screening_type: Optional[ScreeningType]#
secondaries_count: Optional[int]#
started_at: Optional[datetime]#
status: Optional[str]#
updated_at: Optional[datetime]#
class satcat.sdk.screening.models.ScreeningConfiguration(**data)#

Bases: Model

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

auto_archive: bool#
default_secondary_hbr_m: float#
hard_body_shape: HardBodyShape#
include_primary_vs_primary: bool#
launch_window_cadence_s: Optional[float]#
launch_window_end: Optional[datetime]#
launch_window_start: Optional[datetime]#
notes: Optional[str]#
propagation_start_time: Optional[datetime]#
screening_type: ScreeningType#
threshold_radius_active_km: Optional[float]#
threshold_radius_debris_km: Optional[float]#
threshold_radius_km: float#
threshold_radius_manned_km: Optional[float]#
title: Optional[str]#
class satcat.sdk.screening.models.ScreeningType(value)#

Bases: str, Enum

An enumeration.

LAUNCH = 'LAUNCH'#
ON_ORBIT = 'ON_ORBIT'#
class satcat.sdk.screening.screening_client.ScreeningClient(client)#

Bases: object

add_screening_primary(screening, primary=None, norad_id=None, from_best_catalog=True)#

Add a primary to a screening.

Parameters:

  • screening (Screening) – The screening to modify.

  • primary (ScreenableObject) – The object to add to the screening.

  • norad_id (Optional[int], optional) –

    Shortcut field to add an Ephemeris from a Catalog by its Norad Catalog ID. This field may only be used alongside primary if primary is a Catalog to add the ephemeris for a specific object from a Catalog by Norad ID to the screening. This is equivalent to explicitly adding the Ephemeris from the catalog to the screening directly.

    For example, if you wanted to add object 25544’s ephemeris from a given catalog to a screening, you might use:

    client.screening.add_screening_primary(screening, catalog, norad_id=25544)

Returns:

The added Screenable.

Return type:

Screenable

add_screening_secondary(screening, secondary, norad_id=None)#

Add a secondary to a screening.

Parameters:

  • screening (Screening) – The screening to modify.

  • secondary (ScreenableObject) – The object to add to the screening.

  • norad_id (Optional[int], optional) –

    Shortcut field to add an Ephemeris from a Catalog by its Norad Catalog ID. This field may only be used alongside primary if primary is a Catalog to add the ephemeris for a specific object from a Catalog by Norad ID to the screening. This is equivalent to explicitly adding the Ephemeris from the catalog to the screening directly.

    For example, if you wanted to add object 25544’s ephemeris from a given catalog to a screening, you might use:

    client.screening.add_screening_primary(screening, catalog, norad_id=25544)

Returns:

The added Screenable.

Return type:

Screenable

await_screening_completion(screening, poll_interval=5, timeout=3600)#

Synchronously await the completion of a screening.

Parameters:

  • screening (Screening) – The screening to await.

  • poll_interval (int, optional) – Interval in seconds with which to poll for results. Defaults to 5.

  • timeout (int, optional) – Length in seconds after which the request should time out. TimeoutError is raised if the timeout expires before the screening is completed. Defaults to 3600.

Returns:

The completed Screening.

Return type:

Screening

await_screening_completion_percent_generator(screening, poll_interval=5, timeout=3600)#
Return type:

Screening

client: Client#
create_ephemeris(path_or_buf, file_format='AUTOMATIC', norad_id=None, filename=None, comments=None, hbr_m=None, context=None, designation=None)#
Upload an Ephemeris file to the server.

Note

Uploading an Ephemeris does not automatically trigger it to be screened. For this, you can use create_screening.

Parameters:

  • path_or_buf (Union[PathLike, BinaryIO]) – Path to an ephemeris file, or alternatively an open binary file-like object containing the contents of an ephemeris file. Note that the file should be opened in binary mode, even if the ephemeris file format is a common plaintext format.

  • file_format (str) – The file format. By default, the format will be automatically detected based on the file content.

  • norad_id (Optional[int]) –

    The NORAD Catalog ID of the object which the ephemeris file describes.

    Note

    Specifying the NORAD Catalog ID helps Kayhan ensure that the Ephemeris is not screened against other Ephemerides from the same object. While the NORAD Catalog ID field is optional to support Launch Screening and early-deployment screenings, we strongly recommend that you specify it for all on-orbit Ephemerides.

  • filename (Optional[str], optional) – The filename of the ephemeris file. If path_or_buf is a Path, the filename will be automatically determined. Defaults to None

  • comments (Optional[str], optional) – Optional user-defined comments to attach to the file metadata. Defaults to None

  • hbr_m (Optional[float]) – The hard-body radius of the object in meters

  • context (Union[EphemerisContext, str, None]) – The Pathfinder context metadata for the ephemeris. For more information, see https://app.satcat.io/docs/pathfinder/operational-data/#ephemeris-metadata.

  • designation (Union[EphemerisDesignation, str, None]) – The Pathfinder designation metadata for the ephemeris. For more information, see https://app.satcat.io/docs/pathfinder/operational-data/#ephemeris-metadata.

Returns:

The created Ephemeris

Return type:

Ephemeris

create_screening(config=None, primaries=None, secondaries=None, add_best_secondary_catalog=False, add_operational_ephemeris_repository=False, submit=False)#

Create a Screening on the server.

Parameters:

  • config (ScreeningConfiguration) – The configuration with which to run the screening.

  • primaries (Optional[List[Screenable]], optional) – The list of primaries which should be screened.

  • secondaries (Optional[List[Screenable]], optional) – The list of secondaries which should be screened against.

  • add_best_secondary_catalog (bool, optional) – Whether the secondary catalog determined by the application as “Best” (latest updated data and highest-fidelity available data source) should be automatically added to the screening.

  • add_operational_ephemeris_repository (bool, optional) – Whether all ephemeris with a designation of OPERATIONAL and with a usable_time_end in the future should be automatically added to the screening.

  • submit (bool, optional) – Whether to submit the screening instantly. If False, the screening may be submitted later using client.screening.submit_screening(screening).

Returns:

The created Screening.

Return type:

Screening

download_ephemeris(id, file_format)#

Download the content of an ephemeris as a serialized ephemeris file.

Parameters:

  • id (str) – The ID of the resource to retrieve.

  • file_format (str) –

    The file format to download the ephemeris in.

    Note: Only the formats "OEM" and "NASA" are currently supported. This field is case insensitive.

Returns:

A file-like object opened in text mode containing the contents of the formatted ephemeris file.

Return type:

TextIO

get_api_spec()#

Retrieve the OpenAPI specification from the server.

Return type:

dict

get_catalog(id)#

Get a Catalog by ID from the server.

Parameters:

id (str) – The ID of the resource to retrieve.

Returns:

The retrieved Catalog.

Return type:

Catalog

get_conjunction_ccsds(screening_id, conjunction_id)#

List single Conjunction in CCSDS format which belong to a Screening by the Screenings’s ID.

Parameters:

  • screening_id (str) – ID of Screening job for conjunctions

  • conjunction_id (str) – ID of individual Conjunction

Returns:

The Conjunction resource.

Return type:

Dict[str, Any]

get_ephemeris(id)#

Get an Ephemeris by ID from the server.

Parameters:

id (str) – The ID of the resource to retrieve.

Returns:

The retrieved Ephemeris.

Return type:

Ephemeris

get_latest_catalog(catalog_type='SP')#

Get the latest ready catalog for a given catalog type which is not archived.

Parameters:

catalog_type (str, optional) – The catalog type to retrieve, defaults to BEST_CATALOG_TYPE.

Returns:

The retrieved catalog.

Return type:

Catalog

get_screening(id)#

Get a Screening by ID from the server.

Parameters:

id (str) – The ID of the resource to retrieve.

Returns:

The retrieved Screening.

Return type:

Screening

list_catalog_ephemerides(id, filters=None, count=None, sort_field='created_at', sort_direction=SortDirection.DESC)#

List the Ephemerides which belong to a Catalog by the Catalog’s ID.

Parameters:

  • filters (Optional[List[Dict]], optional) – Filters to apply to the list of resources, defaults to None.

  • count (Optional[int], optional) – Maximum number of results to return. If None, return the entire collection. Defaults to None.

  • sort_field (str, optional) – The field on which to sort results, defaults to DEFAULT_SORT_FIELD.

  • sort_direction (str, optional) – The direction in which to sort results, defaults to “asc”.

Returns:

The retrieved collection of resources.

Return type:

Collection[Ephemeris]

list_catalogs(filters=None, count=None, latest=False, sort_field='created_at', sort_direction=SortDirection.DESC)#

List the Catalogs to which the authenticated user has access.

Parameters:

  • filters (Optional[List[Dict]], optional) – Filters to apply to the list of resources, defaults to None.

  • count (Optional[int], optional) – Maximum number of results to return. If None, return the entire collection. Defaults to None.

  • sort_field (str, optional) – The field on which to sort results, defaults to DEFAULT_SORT_FIELD.

  • sort_direction (str, optional) – The direction in which to sort results, defaults to “asc”.

Returns:

The retrieved collection of resources.

Return type:

Collection[Catalog]

list_conjunctions(screening_id, filters=None, count=None, sort_field='created_at', sort_direction=SortDirection.DESC)#

List the Conjunctions which were generated by a Screening.

Parameters:

  • screening_id (str) – The id of the screening.

  • filters (Optional[List[Dict]], optional) – Filters to apply to the list of resources, defaults to None.

  • count (Optional[int], optional) – Maximum number of results to return. If None, return the entire collection. Defaults to None.

  • sort_field (str, optional) – The field on which to sort results, defaults to DEFAULT_SORT_FIELD.

  • sort_direction (str, optional) – The direction in which to sort results, defaults to “asc”.

Returns:

The retrieved collection of resources.

Return type:

Collection[Conjunction]

list_conjunctions_ccsds(screening_id, filters=None, count=None, sort_field='created_at', sort_direction=SortDirection.DESC)#

List the Conjunctions in CCSDS format which belong to a Screening by the Screenings’s ID.

Parameters:

  • screening_id (str) – ID of Screening job for conjunctions

  • filters (Optional[List[Dict]], optional) – Filters to apply to the list of resources, defaults to None.

  • count (Optional[int], optional) – Maximum number of results to return. If None, return the entire collection. Defaults to None.

  • sort_field (str, optional) – The field on which to sort results, defaults to DEFAULT_SORT_FIELD.

  • sort_direction (str, optional) – The direction in which to sort results, defaults to “asc”.

Returns:

The retrieved collection of resources.

Return type:

List[Dict[str, Any]]

list_ephemerides(filters=None, count=None, sort_field='created_at', sort_direction=SortDirection.DESC)#

List the Ephemerides to which the authenticated user has access.

Parameters:

  • filters (Optional[List[Dict]], optional) – Filters to apply to the list of resources, defaults to None.

  • count (Optional[int], optional) – Maximum number of results to return. If None, return the entire collection. Defaults to None.

  • sort_field (str, optional) – The field on which to sort results, defaults to DEFAULT_SORT_FIELD.

  • sort_direction (str, optional) – The direction in which to sort results, defaults to “asc”.

Returns:

The retrieved collection of resources.

Return type:

Collection[Ephemeris]

list_ephemeris_formats()#

Retrieve the list of supported ephemeris file formats.

Return type:

Collection[str]

list_screening_primaries(screening_id, filters=None, count=None, sort_field='created_at', sort_direction=SortDirection.DESC)#

List the primaries attached to a screening.

Parameters:

  • screening_id (str) – The id of the screening.

  • filters (Optional[List[Dict]], optional) – Filters to apply to the list of resources, defaults to None.

  • count (Optional[int], optional) – Maximum number of results to return. If None, return the entire collection. Defaults to None.

  • sort_field (str, optional) – The field on which to sort results, defaults to DEFAULT_SORT_FIELD.

  • sort_direction (str, optional) – The direction in which to sort results, defaults to “asc”.

Return type:

Collection[Screenable]

Returns:

The retrieved collection of resources.

:r type: Collection[models.Screenable]

list_screening_secondaries(screening_id, filters=None, count=None, sort_field='created_at', sort_direction=SortDirection.DESC)#

List the secondaries attached to a screening.

Parameters:

  • screening_id (str) – The id of the screening.

  • filters (Optional[List[Dict]], optional) – Filters to apply to the list of resources, defaults to None.

  • count (Optional[int], optional) – Maximum number of results to return. If None, return the entire collection. Defaults to None.

  • sort_field (str, optional) – The field on which to sort results, defaults to DEFAULT_SORT_FIELD.

  • sort_direction (str, optional) – The direction in which to sort results, defaults to “asc”.

Returns:

The retrieved collection of resources.

Return type:

Collection[Screenable]

list_screenings(filters=None, count=None, sort_field='created_at', sort_direction=SortDirection.DESC, show_archived=False)#

List the Screenings to which the authenticated user has access.

Parameters:

  • filters (Optional[List[Dict]], optional) – Filters to apply to the list of resources, defaults to None.

  • count (Optional[int], optional) – Maximum number of results to return. If None, return the entire collection. Defaults to None.

  • sort_field (str, optional) – The field on which to sort results, defaults to DEFAULT_SORT_FIELD.

  • sort_direction (str, optional) – The direction in which to sort results, defaults to “asc”.

  • show_archived (bool, optional) – Whether to include archived screenings in the results.

Returns:

The retrieved collection of resources.

Return type:

Collection[models.Screenings]

operationalize_ephemeris(ephemeris_id)#

Operationalize an ephemeris by ID.

Parameters:

ephemeris_id (str) – The ID of the resource to designate as ‘OPERATIONAL’.

Returns:

The updated Ephemeris.

Return type:

Ephemeris

resolve_to_screenable(input)#
Return type:

Screenable

submit_screening(screening)#

Submit the Screening for asynchronous processing on the server. Note that screenings may only be submitted if they have the "CREATED" status.

Parameters:

screening (Screening) – The Screening to submit.

Returns:

The submitted Screening.

Return type:

Screening