Main Content

propagateOrbit

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

Since R2023b

    Description

    example

    [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

    collapse all

    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)
    r = 
    r(:,:,1) =
    
       1.0e+06 *
    
       -4.3726
        1.2106
       -5.6292
    
    
    r(:,:,2) =
    
       1.0e+06 *
    
        2.8278
        3.3101
        5.7417
    
    
    r(:,:,3) =
    
       1.0e+06 *
    
       -1.6252
        6.4804
        2.7661
    
    
    r(:,:,4) =
    
       1.0e+06 *
    
       -6.4733
        3.1872
       -0.4959
    
    
    r(:,:,5) =
    
       1.0e+06 *
    
       -6.5300
       -1.8740
       -2.5197
    
    
    r(:,:,6) =
    
       1.0e+06 *
    
        4.2696
       -2.9549
        5.0050
    
    
    r(:,:,7) =
    
       1.0e+06 *
    
       -4.3207
       -0.2621
       -5.8029
    
    
    r(:,:,8) =
    
       1.0e+06 *
    
       -0.4354
        6.3188
        3.5007
    
    
    r(:,:,9) =
    
       1.0e+06 *
    
        3.1625
       -4.6176
       -4.5565
    
    
    r(:,:,10) =
    
       1.0e+06 *
    
       -6.4680
       -0.5957
       -3.1486
    
    
    r(:,:,11) =
    
       1.0e+06 *
    
       -5.0509
       -4.3876
       -2.7586
    
    
    r(:,:,12) =
    
       1.0e+06 *
    
       -4.5717
        4.3305
        3.5445
    
    
    r(:,:,13) =
    
       1.0e+06 *
    
       -4.8265
        0.2134
        5.3573
    
    
    r(:,:,14) =
    
       1.0e+06 *
    
        3.3022
       -3.9510
       -5.0798
    
    
    r(:,:,15) =
    
       1.0e+06 *
    
       -6.4064
       -2.3789
       -2.3156
    
    
    r(:,:,16) =
    
       1.0e+06 *
    
        4.9215
       -1.5755
       -5.0658
    
    
    r(:,:,17) =
    
       1.0e+06 *
    
       -4.2865
        0.5024
        5.7884
    
    
    r(:,:,18) =
    
       1.0e+06 *
    
       -4.1508
       -5.3584
       -2.5396
    
    
    r(:,:,19) =
    
       1.0e+06 *
    
        0.8586
       -4.2505
       -5.8000
    
    
    r(:,:,20) =
    
       1.0e+06 *
    
        1.6331
       -3.9315
       -5.8582
    
    
    r(:,:,21) =
    
       1.0e+06 *
    
       -3.4834
       -2.7205
        5.7141
    
    
    r(:,:,22) =
    
       1.0e+06 *
    
       -0.3378
       -5.8660
        4.1801
    
    
    r(:,:,23) =
    
       1.0e+06 *
    
       -2.3699
       -5.9500
       -3.3499
    
    
    r(:,:,24) =
    
       1.0e+06 *
    
       -3.5223
       -3.3199
        5.3567
    
    
    r(:,:,25) =
    
       1.0e+06 *
    
        5.8316
       -2.5668
       -3.4419
    
    
    r(:,:,26) =
    
       1.0e+06 *
    
        0.5307
       -4.0214
        5.9809
    
    
    r(:,:,27) =
    
       1.0e+06 *
    
       -2.5070
       -3.5297
        5.7770
    
    
    r(:,:,28) =
    
       1.0e+06 *
    
        5.2806
       -1.5994
       -4.6575
    
    
    r(:,:,29) =
    
       1.0e+06 *
    
       -6.7516
       -2.5075
        0.5515
    
    
    r(:,:,30) =
    
       1.0e+06 *
    
       -4.7709
        2.9142
       -4.5849
    
    
    r(:,:,31) =
    
       1.0e+06 *
    
       -3.5965
        2.7142
       -5.6577
    
    
    r(:,:,32) =
    
       1.0e+06 *
    
       -3.5367
       -2.2889
        5.8683
    
    
    r(:,:,33) =
    
       1.0e+06 *
    
       -7.2201
        0.2849
        0.1373
    
    
    r(:,:,34) =
    
       1.0e+06 *
    
       -4.9627
       -1.2222
       -5.1376
    
    
    r(:,:,35) =
    
       1.0e+06 *
    
        0.6899
       -4.5016
        5.5907
    
    
    r(:,:,36) =
    
       1.0e+06 *
    
        4.0468
        2.2131
       -5.5739
    
    
    r(:,:,37) =
    
       1.0e+06 *
    
       -5.3549
       -4.8576
       -0.1584
    
    
    r(:,:,38) =
    
       1.0e+06 *
    
        6.0404
       -1.8887
        3.4976
    
    
    r(:,:,39) =
    
       1.0e+06 *
    
        5.4127
        1.6086
        4.5006
    
    
    r(:,:,40) =
    
       1.0e+06 *
    
       -6.4090
        1.6928
       -2.9143
    
    
    v = 
    v(:,:,1) =
    
       1.0e+03 *
    
        0.4943
       -7.1498
       -1.9149
    
    
    v(:,:,2) =
    
       1.0e+03 *
    
       -4.0192
        6.0766
       -1.5144
    
    
    v(:,:,3) =
    
       1.0e+03 *
    
       -4.9766
        1.0605
       -5.4091
    
    
    v(:,:,4) =
    
       1.0e+03 *
    
       -1.4616
       -3.9252
       -6.1322
    
    
    v(:,:,5) =
    
       1.0e+03 *
    
        3.2088
       -3.7044
       -5.5631
    
    
    v(:,:,6) =
    
       1.0e+03 *
    
        0.9341
        6.6797
        3.1401
    
    
    v(:,:,7) =
    
       1.0e+03 *
    
        1.8369
       -7.1027
       -1.0508
    
    
    v(:,:,8) =
    
       1.0e+03 *
    
       -5.0858
        2.3556
       -4.8638
    
    
    v(:,:,9) =
    
       1.0e+03 *
    
        6.3179
        0.5077
        3.8802
    
    
    v(:,:,10) =
    
       1.0e+03 *
    
        2.9293
       -4.4690
       -5.1661
    
    
    v(:,:,11) =
    
       1.0e+03 *
    
        4.6556
       -1.9379
       -5.4413
    
    
    v(:,:,12) =
    
       1.0e+03 *
    
       -5.3740
       -1.6816
       -4.8478
    
    
    v(:,:,13) =
    
       1.0e+03 *
    
       -3.2646
       -6.1068
       -2.7019
    
    
    v(:,:,14) =
    
       1.0e+03 *
    
        6.5709
        1.5692
        3.0633
    
    
    v(:,:,15) =
    
       1.0e+03 *
    
        3.3442
       -3.5794
       -5.5948
    
    
    v(:,:,16) =
    
       1.0e+03 *
    
        4.7665
        4.7091
        3.1755
    
    
    v(:,:,17) =
    
       1.0e+03 *
    
       -2.5062
       -6.8824
       -1.2637
    
    
    v(:,:,18) =
    
       1.0e+03 *
    
        4.8713
       -1.1945
       -5.4657
    
    
    v(:,:,19) =
    
       1.0e+03 *
    
        6.7905
        2.7845
       -1.0447
    
    
    v(:,:,20) =
    
       1.0e+03 *
    
        6.4822
        3.5498
       -0.5660
    
    
    v(:,:,21) =
    
       1.0e+03 *
    
        2.5726
       -6.7711
       -1.6434
    
    
    v(:,:,22) =
    
       1.0e+03 *
    
        4.9552
       -3.4072
       -4.3792
    
    
    v(:,:,23) =
    
       1.0e+03 *
    
        5.5151
        0.5805
       -4.9428
    
    
    v(:,:,24) =
    
       1.0e+03 *
    
        2.2327
       -6.5935
       -2.6017
    
    
    v(:,:,25) =
    
       1.0e+03 *
    
       -0.5055
        5.4920
       -4.9559
    
    
    v(:,:,26) =
    
       1.0e+03 *
    
        7.3355
        1.1602
        0.1376
    
    
    v(:,:,27) =
    
       1.0e+03 *
    
        6.8592
       -2.4664
        1.4629
    
    
    v(:,:,28) =
    
       1.0e+03 *
    
       -1.4396
        6.2341
       -3.7779
    
    
    v(:,:,29) =
    
       1.0e+03 *
    
        1.8985
       -3.7666
        6.1154
    
    
    v(:,:,30) =
    
       1.0e+03 *
    
       -5.5694
       -3.0137
        3.8774
    
    
    v(:,:,31) =
    
       1.0e+03 *
    
       -6.0027
       -3.8907
        1.9583
    
    
    v(:,:,32) =
    
       1.0e+03 *
    
        4.3350
       -6.0269
        0.2515
    
    
    v(:,:,33) =
    
       1.0e+03 *
    
       -0.0514
       -4.3235
        6.0454
    
    
    v(:,:,34) =
    
       1.0e+03 *
    
       -1.5791
       -6.5457
        3.0929
    
    
    v(:,:,35) =
    
       1.0e+03 *
    
        7.1302
       -1.1357
       -1.7937
    
    
    v(:,:,36) =
    
       1.0e+03 *
    
       -5.2628
        4.8689
       -1.8870
    
    
    v(:,:,37) =
    
       1.0e+03 *
    
        2.8075
       -3.2824
        6.0458
    
    
    v(:,:,38) =
    
       1.0e+03 *
    
        4.0290
        3.9657
       -4.8152
    
    
    v(:,:,39) =
    
       1.0e+03 *
    
        1.4390
        6.1548
       -3.9152
    
    
    v(:,:,40) =
    
       1.0e+03 *
    
       -3.4278
       -4.0127
        5.2093
    
    

    Input Arguments

    collapse all

    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

    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

    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]

    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]

    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

    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

    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

    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.

    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.

    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, 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

    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

    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

    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

    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

    collapse all

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

    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

    See Also

    |