propagateOrbit

Calculate position and velocity in International Celestial Reference Frame (ICRF)

Since R2023b

Syntax

[positions,velocities] = propagateOrbit(time,tleStruct)

[positions,velocities] = propagateOrbit(time,a,ecc,incl,RAAN,argp,nu)

[positions,velocities] = propagateOrbit(time,rEpoch,vEpoch)

[positions,velocities] = propagateOrbit(___,time,Name=Value)

Description

[positions,velocities] = propagateOrbit(time,tleStruct) calculates the positions and velocities in the International Celestial Reference Frame (ICRF) corresponding to the time specified by time using the two-line-element (TLE) data defined by tleStruct.

[positions,velocities] = propagateOrbit(time,a,ecc,incl,RAAN,argp,nu) calculates the positions and velocities using specified orbital elements to define epoch states. The function assumes that the epoch is the current Universal Time Coordinated (UTC) date and time and is the first element in the time argument.

[positions,velocities] = propagateOrbit(time,rEpoch,vEpoch) calculates the positions and velocities at the epoch defined by rEpoch and vEpoch. The function assumes that the epoch is the current UTC date and time and is the first element in the time argument.

[positions,velocities] = propagateOrbit(___,time,Name=Value) calculates the positions and velocities using one or more name-value arguments.

Examples

Read Data from TLE File and Calculate Position and Velocity from Data

Read data from the TLE file 'leoSatelliteConstellation.tle' and calculate the position and velocity from the TLE structure, tleStruct.

Read the data from the TLE file 'leoSatelliteConstellation.tle', which is on the MATLAB® path and provided with Aerospace Toolbox.

tleStruct = tleread('leoSatelliteConstellation.tle')

tleStruct=40×1 struct array with fields:
    Name
    SatelliteCatalogNumber
    Epoch
    BStar
    RightAscensionOfAscendingNode
    Eccentricity
    Inclination
    ArgumentOfPeriapsis
    MeanAnomaly
    MeanMotion

Calculate the position and velocity corresponding to the input time using the TLE data defined in tleStruct.

[r,v] = propagateOrbit(datetime(2022, 1, 3, 12, 0, 0),tleStruct);

Input Arguments

time — Julian dates or datetime

1-by-m vector | m-by-1 vector

Julian dates or datetime, specified as a 1-by-m vector or m-by-1 vector of datetime objects or doubles. time must be strictly increasing.

When you specify a datetime object whose TimeZone property is empty, propagateOrbit assumes that the datetime object time zone is UTC.

Example: datetime(2023,6,16)

Example: juliandate(2023,6,16)

Data Types: double

a — Semimajor axes

numSc-element vector | scalar

Semimajor axes, specified as a numSc-element vector or scalar, in meters. If all spacecraft have the same semimajor axis, you can specify a as a scalar. numSc is the number of spacecraft.

Example: 10000000

Example: [8000000 10000000]

Data Types: double

ecc — Orbit eccentricity

numSc-element vector | scalar

Orbit eccentricity (deviation of orbital curve from circular), specified as an numSc-element vector or scalar. If all spacecraft have the same eccentricity, you can specify ecc as a scalar. numSc is the number of spacecraft.

Example: 0.1

Example: [0.1 0.2]

incl — Inclination

numSc-element vector | scalar

Inclination, vertical tilt of the ellipse with respect to the ICRF xy plane measured at the ascending node, specified as a numSc-element vector or scalar. numSc is the number of spacecraft.

Example: 10

Example: [20 30]

RAAN — Right ascension of ascending node (RAAN)

numSc-element vector | scalar

Right ascension of ascending node (RAAN), specified as a numSc-element vector or scalar in degrees. If all spacecraft have the same right ascension of ascending node, you can specify RAAN as a scalar. numSc is the number of spacecraft.

Example: 10

Example: [20 30], if there are two spacecraft

argp — Argument of periapsis

numSc-element vector | scalar

Argument of periapsis, the angle from orbit ascending node to periapsis (closest point of orbit to the central body), specified as a numSc-element vector or a scalar. If all spacecraft have the same argument of periapsis, you can specify RAAN as a scalar.numSc is the number of spacecraft.

Example: 10

Example: [20 30], if there are two spacecraft

nu — True anomaly

numSc-element vector | scalar

True anomaly, the angle between periapsis and initial position of spacecraft, specified as a numSc-element vector or scalar. If all spacecraft have the same argument of periapsis, you can specify nu as a scalar. numSc is the number of spacecraft.

Example: 10

Example: [20 30], if there are two spacecraft

rEpoch — Position at epoch

3-by-1 vector | 3-by-numSc matrix

Position at epoch, specified as a 3-by-1 vector or 3-by-numSc matrix. If all spacecraft have the same initial position at epoch, you can specify rEpoch as a 3-element vector. numSc is the number of spacecraft.

Example: [10000000;1000;2000]

Example: [10000000 12000000;1000 2000;2000 4000], if there are two spacecraft

Dependencies

rEpoch and the corresponding vEpoch vectors cannot be parallel.

vEpoch — Velocity at epoch

3-by-1 vector | 3-by-numSc matrix

Velocity at epoch, specified as a 3-by-1 vector or 3-by-numSc matrix. If all spacecraft have the same initial velocity at epoch, you can specify vEpoch as a 3-element vector. numSc is the number of spacecraft.

Example: [0;8000;0]

Example: [0 100;8000 9000;200 300], if there are two spacecraft

Dependencies

vEpoch and the corresponding rEpoch vectors cannot be parallel.

tleStruct — TLE structures

numSc-element vector

TLE structures representing TLE data, specified as an numSc-element vector. numSc is the number of spacecraft. To create the TLE structure file, consider using tleread. For more information on TLE-file structures, see Two Line Element (TLE) Files.

Example: tleread("leoSatelliteConstellation.tle")

Data Types: string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: PropModel="two-body-keplerian" specifies two-body-keplerian as the propagation method.

Epoch — Epoch

first value of time argument (default) | scalar

Epoch, specified as a scalar datetime, specified as a double.

When you specify a datetime object whose TimeZone property is empty, the propagateOrbit function assumes that the datetime object time zone is UTC.

Example: datetime(2023,6,19)

Dependencies

When the epoch states are specified using tleStruct, do not specify this name-value argument.

Data Types: double

PropModel — Orbital state propagation method

"general-perturbations" (default) | "two-body-keplerian" | "sgp4" | "sdp4"

Orbital state propagation method, specified as one of these values:

• "general-perturbations" — "sgp4" or "sdp4", depending on orbital period. When the orbital period corresponding to the epoch states is less than 225 minutes, the propagation model is "sgp4". Otherwise, it is "sdp4".

• "two-body-keplerian" — Two-body Keplerian orbit propagator.

• "sgp4" — Simplified General Perturbations-4 orbit propagator.

• "sdp4" — Simplified Deep-Space Perturbations-4 orbit propagator.

Example: PropModel="two-body-keplerian"

Data Types: char | string

BStar — Aerodynamic drag term

0 (default) | numSc-element vector | scalar

Aerodynamic drag term, specified as a numSc-element vector or scalar. If all spacecraft use the same Bstar value, you can specify this argument as a scalar. numSc is the number of spacecraft.

Example: BStar=0

Example: BStar=[0.0001 0.0002], if there are two spacecraft

Dependencies

propagateOrbit uses this value when:

• PropModel is set to "general-perturbations", "sgp4", or "sdp4".

• Epoch states are not specified using tleStruct.

Data Types: double

InputCoordinateFrame — Input coordinate frame of rEpoch and vEpoch

"icrf" (default) | "fixed-frame" | "geographic"

Input coordinate frame of rEpoch and vEpoch, specified as one of these values:

• "icrf" — rEpoch and vEpoch are defined in the ICRF in meters and m/s respectively.

• "fixed-frame" — rEpoch and vEpoch are defined in the Earth-centered Earth-fixed (ECEF) frame in m and m/s respectively.

• "geographic" — rEpoch is defined as latitude (degrees), longitude (degrees), and altitude (meters). vEpoch is defined in the fixed-frame velocity represented in the North-East-Down (NED) frame defined by rEpoch.

Example: InputCoordinateFrame="fixed-frame"

Data Types: char | string

OutputCoordinateFrame — Output coordinate frame of posititions and velocities

"icrf" (default) | "fixed-frame" | "geographic"

Output coordinate frame of output positions and velocities, specified as one of these values:

• "icrf" — positions and velocities are defined in the ICRF in m and m/s respectively.

• "fixed-frame" — positions and velocities are defined in the Earth-centered Earth-fixed (ECEF) frame in m and m/s respectively.

• "geographic" — positions is defined as latitude (degrees), longitude (degrees), and altitude (meters). velocities is defined in the fixed-frame velocity represented in the North-East-Down (NED) frame defined by rEpoch.

Example: OutputCoordinateFrame="geographic"

Data Types: char | string

Output Arguments

positions — Positions

3-by-m-by-numSc array

Positions, returned as a 3-by-m-by-numSc array. m is the number of time samples. numSc is the number of spacecraft.

velocities — Velocities

3-by-m-by-numSc array

Velocities, returned as a 3-by-m-by-numSc array. m is the number of time samples. numSc is the number of spacecraft.

Version History

Introduced in R2023b