Modified ITC¶

Reader, writer and trajectory conversion for the Modified ITC ephemeris format.

ITC¶

ITC ¶

ITC(header: Any)

A Modified ITC ephemeris message.

Read Starlink and other Space-Track Modified ITC files, build messages record by record, and write them back in the same text layout. All values are SI: meters, meters per second, and m², m²/s, m²/s² for the covariance in the header's covariance frame. Properties return copies; to change the header, modify a copy and assign it back.

Example

import brahe as bh

itc = bh.ITC.from_file(
    "test_assets/starlink/MEME_100002_STARLINK-37711_2540149_Operational_1473385800_UNCLASSIFIED.txt"
)
assert len(itc) == 50
assert itc.has_covariance
assert itc.source_name.object_name == "STARLINK-37711"
text = itc.to_string()

traj = itc.to_trajectory()
station = bh.PointLocation(-122.4194, 37.7749, 0.0)
windows = bh.location_accesses([station], [traj], itc.start_epoch, itc.end_epoch, bh.ElevationConstraint(min_elevation_deg=10.0))

Initialize instance.

covariances `property` ¶

covariances: Any

Covariance per record in the header's covariance frame.

Returns:

Type	Description
`Any`	list[numpy.ndarray]: One 6x6 array per record, or an empty list when the file has no covariance.

end_epoch `property` ¶

end_epoch: Any

Epoch of the last record.

Returns:

Type	Description
`Any`	Epoch \| None: Last epoch, or None when empty.

has_covariance `property` ¶

has_covariance: bool

Whether the message carries covariance.

Returns:

Name	Type	Description
`bool`	`bool`	True when every record has a covariance matrix.

header `property` ¶

header: ITCHeader

Header fields.

Returns:

Name	Type	Description
`ITCHeader`	`ITCHeader`	A copy of the header; assign it back (`itc.header = h`) to apply changes.

source_name `property` ¶

source_name: Any

Parsed file name, when loaded from a compliant file name.

Returns:

Type	Description
`Any`	SpaceTrackEphemerisFileName \| None: The parsed name.

start_epoch `property` ¶

start_epoch: Any

Epoch of the first record.

Returns:

Type	Description
`Any`	Epoch \| None: First epoch, or None when empty.

states `property` ¶

states: list[ITCStateVector]

Ephemeris records in epoch order.

Returns:

Type	Description
`list[ITCStateVector]`	list[ITCStateVector]: Copies of the records.

file_name `method descriptor` ¶

file_name(norad_cat_id: int, object_name: str, category: SpaceTrackEphemerisFileCategory, metadata: str) -> SpaceTrackEphemerisFileName

Build a Space-Track compliant file name for this message.

Parameters:

Name	Type	Description	Default
`norad_cat_id`	`int`	NORAD catalog number or analyst number.	required
`object_name`	`str`	Common name of the object.	required
`category`	`SpaceTrackEphemerisFileCategory`	Operational or Special.	required
`metadata`	`str`	Operator-defined metadata; may be empty.	required

Returns:

Name	Type	Description
`SpaceTrackEphemerisFileName`	`SpaceTrackEphemerisFileName`	The name; `str()` gives the text.

Raises:

Type	Description
`BraheError`	If the message has no start epoch or its state frame has no DataType.

from_file `staticmethod` ¶

from_file(path: str) -> ITC

Read and parse a file.

When the file name follows the Space-Track convention its DataType sets the state frame and the parsed name is kept in source_name.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to the file.	required

Returns:

Name	Type	Description
`ITC`	`ITC`	The parsed message.

Raises:

Type	Description
`BraheError`	If the file cannot be read or parsed, or names an unsupported DataType.

from_str `staticmethod` ¶

from_str(content: str) -> ITC

Parse a message from text.

The state frame stays at the header default (EME2000); use from_file to infer it from a compliant file name.

Parameters:

Name	Type	Description	Default
`content`	`str`	Full file text.	required

Returns:

Name	Type	Description
`ITC`	`ITC`	The parsed message.

Raises:

Type	Description
`BraheError`	If the header or any record is malformed.

from_trajectory `staticmethod` ¶

from_trajectory(trajectory: OrbitTrajectory, header: ITCHeader, covariance_variant: OrbitRelativeFrameVariant = None) -> ITC

Build a message from a trajectory's stored samples.

Parameters:

Name	Type	Description	Default
`trajectory`	`OrbitTrajectory`	Six-dimensional Cartesian trajectory.	required
`header`	`ITCHeader`	Header template; start, stop and step are filled from the samples.	required
`covariance_variant`	`OrbitRelativeFrameVariant`	RTN convention for the covariance; `INERTIAL` by default.	`None`

Returns:

Name	Type	Description
`ITC`	`ITC`	The message.

Raises:

Type	Description
`BraheError`	If the trajectory is empty, not six-dimensional Cartesian, a covariance is smaller than 6x6, or the frame router cannot reach the header's frames.

Example

import brahe as bh

itc = bh.ITC.from_file("test_assets/starlink/MEME_100002_STARLINK-37711_2540149_Operational_1473385800_UNCLASSIFIED.txt")
traj = itc.to_trajectory()
back = bh.ITC.from_trajectory(traj, bh.ITCHeader(ephemeris_source="brahe"))

References

Spaceflight Safety Handbook for Satellite Operators, Version 1.7, 18th Space Defense Squadron, Space-Track.org, https://www.space-track.org/documents/SFS_Handbook_For_Operators_V1.7.pdf
NASA Conjunction Assessment Risk Analysis (CARA), Conjunction Assessment Handbook, NASA/SP-20205011318, Appendix N (RIC-to-ECI covariance transformation, eq. N-13), https://ntrs.nasa.gov/citations/20205011318
NASA CARA Analysis Tools, RIC2ECI.m, https://github.com/nasa/CARA_Analysis_Tools
D. A. Vallado, "Covariance Transformations for Satellite Flight Dynamics Operations," AAS 03-526, AAS/AIAA Astrodynamics Specialist Conference, 2003, https://celestrak.org/publications/AAS/03-526/AAS-03-526.pdf

from_trajectory_with_covariance_variant `staticmethod` ¶

from_trajectory_with_covariance_variant(trajectory: OrbitTrajectory, header: ITCHeader, variant: OrbitRelativeFrameVariant) -> ITC

Build a message from a trajectory with an explicit RTN covariance convention.

A covariance is rotated from the trajectory frame into the header's covariance frame: EME2000 and ITRF through the state-transform Jacobian between the two frames, RTN through the geocentric RTN frame of the sample's own state expressed in GCRF, whatever center the trajectory uses.

Parameters:

Name	Type	Description	Default
`trajectory`	`OrbitTrajectory`	Six-dimensional Cartesian trajectory.	required
`header`	`ITCHeader`	Header template.	required
`variant`	`OrbitRelativeFrameVariant`	`INERTIAL` or `ROTATING`.	required

Returns:

Name	Type	Description
`ITC`	`ITC`	The message.

Raises:

Type	Description
`BraheError`	If the trajectory is empty, not six-dimensional Cartesian, a covariance is smaller than 6x6, or the frame router cannot reach the header's frames.

Example

import brahe as bh

itc = bh.ITC.from_file("test_assets/starlink/MEME_100002_STARLINK-37711_2540149_Operational_1473385800_UNCLASSIFIED.txt")
traj = itc.to_trajectory_with_covariance_variant(bh.OrbitRelativeFrameVariant.ROTATING)
back = bh.ITC.from_trajectory_with_covariance_variant(traj, bh.ITCHeader(), bh.OrbitRelativeFrameVariant.ROTATING)

References

Spaceflight Safety Handbook for Satellite Operators, Version 1.7, 18th Space Defense Squadron, Space-Track.org, https://www.space-track.org/documents/SFS_Handbook_For_Operators_V1.7.pdf
NASA Conjunction Assessment Risk Analysis (CARA), Conjunction Assessment Handbook, NASA/SP-20205011318, Appendix N (RIC-to-ECI covariance transformation, eq. N-13), https://ntrs.nasa.gov/citations/20205011318
NASA CARA Analysis Tools, RIC2ECI.m, https://github.com/nasa/CARA_Analysis_Tools
D. A. Vallado, "Covariance Transformations for Satellite Flight Dynamics Operations," AAS 03-526, AAS/AIAA Astrodynamics Specialist Conference, 2003, https://celestrak.org/publications/AAS/03-526/AAS-03-526.pdf

push_state `method descriptor` ¶

push_state(state: ITCStateVector) -> ndarray

Append a record without covariance.

Parameters:

Name	Type	Description	Default
`state`	`ITCStateVector`	Record with an epoch later than the last one.	required

Raises:

Type	Description
`BraheError`	If the epoch is not increasing or the message already carries covariance.

push_state_with_covariance `method descriptor` ¶

push_state_with_covariance(state: ITCStateVector, covariance: ndarray) -> ndarray

Append a record with its covariance.

Parameters:

Name	Type	Description	Default
`state`	`ITCStateVector`	Record with an epoch later than the last one.	required
`covariance`	`ndarray`	6x6 covariance in the header's covariance frame, SI units.	required

Raises:

Type	Description
`BraheError`	If the epoch is not increasing or earlier records have no covariance.

to_file `method descriptor` ¶

to_file(path: str) -> Any

Write the message to a file.

Parameters:

Name	Type	Description	Default
`path`	`str`	Destination path.	required

Raises:

Type	Description
`BraheError`	If the message has no records or the file cannot be written.

to_string `method descriptor` ¶

to_string() -> str

Render the message as Modified ITC text.

Returns:

Name	Type	Description
`str`	`str`	The file text.

Raises:

Type	Description
`BraheError`	If the message has no records.

to_trajectory `method descriptor` ¶

to_trajectory(covariance_variant: OrbitRelativeFrameVariant = None) -> OrbitTrajectory

Convert the message to an OrbitTrajectory in the header's state frame.

Covariance is attached in the state frame whatever frame the header names for it: RTN with each record's own state, block-diagonally by default, EME2000 and ITRF with the state-transform Jacobian between the covariance frame and the state frame.

Parameters:

Name	Type	Description	Default
`covariance_variant`	`OrbitRelativeFrameVariant`	`INERTIAL` (default, block-diagonal `[[R, 0], [0, R]]`) or `ROTATING` (adds the frame-rate coupling block).	`None`

Returns:

Name	Type	Description
`OrbitTrajectory`	`OrbitTrajectory`	Six-dimensional Cartesian trajectory, named after the source file's object when known.

Raises:

Type	Description
`BraheError`	If the message is empty, or the frame router cannot relate the covariance frame and the state frame at a record's epoch.

Example

import brahe as bh

itc = bh.ITC.from_file("test_assets/starlink/MEME_100002_STARLINK-37711_2540149_Operational_1473385800_UNCLASSIFIED.txt")
traj = itc.to_trajectory()
cov = traj.covariance(itc.start_epoch)

References

Spaceflight Safety Handbook for Satellite Operators, Version 1.7, 18th Space Defense Squadron, Space-Track.org, https://www.space-track.org/documents/SFS_Handbook_For_Operators_V1.7.pdf
NASA Conjunction Assessment Risk Analysis (CARA), Conjunction Assessment Handbook, NASA/SP-20205011318, Appendix N (RIC-to-ECI covariance transformation, eq. N-13), https://ntrs.nasa.gov/citations/20205011318
NASA CARA Analysis Tools, RIC2ECI.m, https://github.com/nasa/CARA_Analysis_Tools
D. A. Vallado, "Covariance Transformations for Satellite Flight Dynamics Operations," AAS 03-526, AAS/AIAA Astrodynamics Specialist Conference, 2003, https://celestrak.org/publications/AAS/03-526/AAS-03-526.pdf

to_trajectory_with_covariance_variant `method descriptor` ¶

to_trajectory_with_covariance_variant(variant: OrbitRelativeFrameVariant) -> OrbitTrajectory

Convert the message to an OrbitTrajectory with an explicit RTN covariance convention.

The covariance is attached in the state frame whatever frame the header names for it. An RTN covariance is rotated with the record's own state expressed in GCRF (the geocentric RTN basis, whatever center the source used); INERTIAL uses the block-diagonal rotation and ROTATING adds the frame-rate coupling. An EME2000 or ITRF covariance is rotated by the state-transform Jacobian from that frame to the state frame at the record epoch, which is the identity when the two agree.

Parameters:

Name	Type	Description	Default
`variant`	`OrbitRelativeFrameVariant`	`INERTIAL` or `ROTATING`.	required

Returns:

Name	Type	Description
`OrbitTrajectory`	`OrbitTrajectory`	The trajectory.

Raises:

Type	Description
`BraheError`	If the message is empty, or the frame router cannot relate the covariance frame and the state frame at a record's epoch.

Example

import brahe as bh

itc = bh.ITC.from_file("test_assets/starlink/MEME_100002_STARLINK-37711_2540149_Operational_1473385800_UNCLASSIFIED.txt")
traj = itc.to_trajectory_with_covariance_variant(bh.OrbitRelativeFrameVariant.ROTATING)
cov = traj.covariance(itc.start_epoch)

References

Spaceflight Safety Handbook for Satellite Operators, Version 1.7, 18th Space Defense Squadron, Space-Track.org, https://www.space-track.org/documents/SFS_Handbook_For_Operators_V1.7.pdf
NASA Conjunction Assessment Risk Analysis (CARA), Conjunction Assessment Handbook, NASA/SP-20205011318, Appendix N (RIC-to-ECI covariance transformation, eq. N-13), https://ntrs.nasa.gov/citations/20205011318
NASA CARA Analysis Tools, RIC2ECI.m, https://github.com/nasa/CARA_Analysis_Tools
D. A. Vallado, "Covariance Transformations for Satellite Flight Dynamics Operations," AAS 03-526, AAS/AIAA Astrodynamics Specialist Conference, 2003, https://celestrak.org/publications/AAS/03-526/AAS-03-526.pdf

ITCHeader¶

ITCHeader ¶

ITCHeader(created: Any = None, ephemeris_start: Any = None, ephemeris_stop: Any = None, step_size: Any = None, ephemeris_source: Any = None, state_frame: Any = None, covariance_frame: Any = None)

Header of a Modified ITC file.

The typed fields mirror Starlink's descriptive header lines. The state frame is not written in the file body; ITC.from_file infers it from the file name's DataType and it defaults to CelestialFrame.EME2000.

Example

import brahe as bh

header = bh.ITCHeader(ephemeris_source="blend")
assert header.state_frame == bh.CelestialFrame.EME2000
assert header.covariance_frame == bh.ITCCovarianceFrame.RTN

Initialize instance.

covariance_frame `property` ¶

covariance_frame: ITCCovarianceFrame

Frame of the covariance matrices.

Returns:

Name	Type	Description
`ITCCovarianceFrame`	`ITCCovarianceFrame`	Covariance frame.

created `property` ¶

created: Any

File creation time.

Returns:

Type	Description
`Any`	Epoch \| None: Creation epoch, if present.

ephemeris_source `property` ¶

ephemeris_source: Any

Free-text source label.

Returns:

Type	Description
`Any`	str \| None: Source label, if present.

ephemeris_start `property` ¶

ephemeris_start: Any

Declared first epoch.

Returns:

Type	Description
`Any`	Epoch \| None: Start epoch, if present.

ephemeris_stop `property` ¶

ephemeris_stop: Any

Declared last epoch.

Returns:

Type	Description
`Any`	Epoch \| None: Stop epoch, if present.

state_frame `property` ¶

state_frame: CelestialFrame

Frame of the state vectors.

Returns:

Name	Type	Description
`CelestialFrame`	`CelestialFrame`	State frame.

step_size `property` ¶

step_size: Any

Declared step between records.

Returns:

Type	Description
`Any`	float \| None: Step in seconds, if present.

ITCStateVector¶

ITCStateVector ¶

ITCStateVector(epoch: Any, position: Any, velocity: Any)

One Modified ITC record: epoch, position and velocity in SI units.

Example

import brahe as bh
import numpy as np

epoch = bh.Epoch(2026, 9, 11, 1, 42, 42.0, 0.0, time_system=bh.TimeSystem.UTC)
state = bh.ITCStateVector(epoch, np.array([7.0e6, 0.0, 0.0]), np.array([0.0, 7.5e3, 0.0]))
assert state.position[0] == 7.0e6

Initialize instance.

epoch `property` ¶

epoch: Epoch

Record epoch.

Returns:

Name	Type	Description
`Epoch`	`Epoch`	The epoch.

position `property` ¶

position: ndarray

Position in the header's state frame.

Returns:

Type	Description
`ndarray`	numpy.ndarray: Position, meters, shape (3,).

velocity `property` ¶

velocity: ndarray

Velocity in the header's state frame.

Returns:

Type	Description
`ndarray`	numpy.ndarray: Velocity, meters per second, shape (3,).

to_vector `method descriptor` ¶

to_vector() -> ndarray

The record's position and velocity as a single Cartesian state.

Returns:

Type	Description
`ndarray`	numpy.ndarray: `[x, y, z, vx, vy, vz]` in the header's state frame, meters and meters per second, shape (6,).

Example

import brahe as bh
import numpy as np

epoch = bh.Epoch(2026, 9, 11, 1, 42, 42.0, 0.0, time_system=bh.TimeSystem.UTC)
state = bh.ITCStateVector(epoch, np.array([7.0e6, 0.0, 0.0]), np.array([0.0, 7.5e3, 0.0]))
assert state.to_vector()[4] == 7.5e3

ITCCovarianceFrame¶

ITCCovarianceFrame ¶

ITCCovarianceFrame()

Frame in which a Modified ITC file expresses its covariance.

UVW is Space-Track's name for the radial, in-track, cross-track frame and is what RTN writes.

Example

import brahe as bh

assert bh.ITCCovarianceFrame.parse("UVW") == bh.ITCCovarianceFrame.RTN
assert str(bh.ITCCovarianceFrame.RTN) == "UVW"

Initialize instance.

EME2000 `class-attribute` ¶

EME2000: Any = ITCCovarianceFrame.EME2000

Frame in which a Modified ITC file expresses its covariance.

UVW is Space-Track's name for the radial, in-track, cross-track frame and is what RTN writes.

Example

import brahe as bh

assert bh.ITCCovarianceFrame.parse("UVW") == bh.ITCCovarianceFrame.RTN
assert str(bh.ITCCovarianceFrame.RTN) == "UVW"

ITRF `class-attribute` ¶

ITRF: Any = ITCCovarianceFrame.ITRF

Frame in which a Modified ITC file expresses its covariance.

UVW is Space-Track's name for the radial, in-track, cross-track frame and is what RTN writes.

Example

import brahe as bh

assert bh.ITCCovarianceFrame.parse("UVW") == bh.ITCCovarianceFrame.RTN
assert str(bh.ITCCovarianceFrame.RTN) == "UVW"

RTN `class-attribute` ¶

RTN: Any = ITCCovarianceFrame.RTN

Frame in which a Modified ITC file expresses its covariance.

UVW is Space-Track's name for the radial, in-track, cross-track frame and is what RTN writes.

Example

import brahe as bh

assert bh.ITCCovarianceFrame.parse("UVW") == bh.ITCCovarianceFrame.RTN
assert str(bh.ITCCovarianceFrame.RTN) == "UVW"

parse `staticmethod` ¶

parse(token: str) -> ITCCovarianceFrame

Parse the covariance-frame header token.

Parameters:

Name	Type	Description	Default
`token`	`str`	Fourth header line of a Modified ITC file, case-insensitive.	required

Returns:

Name	Type	Description
`ITCCovarianceFrame`	`ITCCovarianceFrame`	The frame.

Raises:

Type	Description
`BraheError`	If the token is not one the handbook lists.

token `method descriptor` ¶

token() -> str

The token written on the fourth header line.

Returns:

Name	Type	Description
`str`	`str`	`UVW`, `EME2000` or `ITRF`.

Modified ITC¶

ITC¶

ITC ¶

covariances property ¶

end_epoch property ¶

has_covariance property ¶

header property ¶

source_name property ¶

start_epoch property ¶

states property ¶

file_name method descriptor ¶

from_file staticmethod ¶

from_str staticmethod ¶

from_trajectory staticmethod ¶

from_trajectory_with_covariance_variant staticmethod ¶

push_state method descriptor ¶

push_state_with_covariance method descriptor ¶

to_file method descriptor ¶

to_string method descriptor ¶

to_trajectory method descriptor ¶

to_trajectory_with_covariance_variant method descriptor ¶

ITCHeader¶

ITCHeader ¶

covariance_frame property ¶

created property ¶

ephemeris_source property ¶

ephemeris_start property ¶

ephemeris_stop property ¶

state_frame property ¶

step_size property ¶

ITCStateVector¶

ITCStateVector ¶

epoch property ¶

position property ¶

velocity property ¶

to_vector method descriptor ¶

ITCCovarianceFrame¶

ITCCovarianceFrame ¶

EME2000 class-attribute ¶

ITRF class-attribute ¶

RTN class-attribute ¶

parse staticmethod ¶

token method descriptor ¶

See Also¶

covariances `property` ¶

end_epoch `property` ¶

has_covariance `property` ¶

header `property` ¶

source_name `property` ¶

start_epoch `property` ¶

states `property` ¶

file_name `method descriptor` ¶

from_file `staticmethod` ¶

from_str `staticmethod` ¶

from_trajectory `staticmethod` ¶

from_trajectory_with_covariance_variant `staticmethod` ¶

push_state `method descriptor` ¶

push_state_with_covariance `method descriptor` ¶

to_file `method descriptor` ¶

to_string `method descriptor` ¶

to_trajectory `method descriptor` ¶

to_trajectory_with_covariance_variant `method descriptor` ¶

covariance_frame `property` ¶

created `property` ¶

ephemeris_source `property` ¶

ephemeris_start `property` ¶

ephemeris_stop `property` ¶

state_frame `property` ¶

step_size `property` ¶

epoch `property` ¶

position `property` ¶

velocity `property` ¶

to_vector `method descriptor` ¶

EME2000 `class-attribute` ¶

ITRF `class-attribute` ¶

RTN `class-attribute` ¶

parse `staticmethod` ¶

token `method descriptor` ¶