Main Content

states

Obtain position and velocity of satellite or platform

Since R2021a

    Description

    pos = states(sat) returns a 3-by-n-by-m array of the position history pos of each satellite in the vector sat, where n is the number of time samples and m is the number of satellites. The rows represent the x, y, and z coordinates of the satellite in the Geocentric Celestial Reference Frame (GCRF).

    pos = states(pltf) returns a 3-by-n-by-p array of the position history pos of each platform in the vector pltf, where n is the number of time samples and p is the number of platform. The rows represent the x, y, and z coordinates of the platform in the Geocentric Celestial Reference Frame (GCRF).

    example

    [pos,velocity] = states(sat) returns a 3-by-n-by-m array of the inertial velocity velocity of each satellite in the vector sat in the GCRF.

    [pos,velocity] = states(pltf) returns a 3-by-n-by-p array of the inertial velocity velocity of each platform in the vector pltf in the GCRF.

    [___] = states(sat,timeIn) returns one or both of the outputs as 3-by-1-by-m arrays in addition to the position at the specified datetime timeIn. If no time zone is specified in timeIn, the time zone is assumed to be Coordinated Universal Time (UTC).

    [___] = states(pltf,timeIn) returns one or both of the outputs as 3-by-1-by-p arrays in addition to the position at the specified datetime timeIn. If no time zone is specified in timeIn, the time zone is assumed to be Coordinated Universal Time (UTC).

    [___] = states(___,CoordinateFrame=c) returns the outputs in the coordinates specified by c.

    [pos,velocity,timeOut] = states(___) returns the position, velocity history, and the corresponding datetime in UTC for satellites or platforms.

    Examples

    collapse all

    Create a satellite scenario object.

    startTime = datetime(2021,5,25);                      % May 25, 2021, 12:00 AM UTC
    stopTime = datetime(2021,5,26);                       % May 26, 2021, 12:00 AM UTC
    sampleTime = 60;                                      % In seconds
    sc = satelliteScenario(startTime,stopTime,sampleTime);

    Add a satellite to the scenario.

    tleFile = "eccentricOrbitSatellite.tle";
    sat = satellite(sc,tleFile);

    Obtain the position and velocity of the satellite in the Earth-centered Earth-fixed (ECEF) frame corresponding to May 25, 2021, 10:30 PM UTC.

    time = datetime(2021,5,25,22,30,0);
    [position,velocity] = states(sat,time,"CoordinateFrame","ecef")
    position = 3×1
    107 ×
    
       -0.9431
       -3.0675
        2.7404
    
    
    velocity = 3×1
    103 ×
    
       -1.2166
        0.4198
       -1.6730
    
    

    Input Arguments

    collapse all

    Satellite, specified as a row vector of Satellite objects.

    Platform, specified as a row vector of Platform (Satellite Communications Toolbox) objects.

    Time at which the output is calculated, specified as a datetime scalar. If no time zone is specified in timeIn, the time zone is assumed to be UTC.

    Coordinate frame in which the outputs are returned, specified as 'inertial', 'ecef', or 'geographic'.

    • The 'inertial' option returns the position and velocity coordinates in the GCRF.

    • The 'ecef' option returns the position and velocity coordinates in the ECEF frame. For more information on ECEF frames, see Earth-Centered Earth-Fixed Coordinates.

    • The 'geographic' option returns the position as [lat; lon; altitude], where lat and lon are latitude and longitude in degrees and altitude is the height above the surface of the Earth in meters. The velocity returned is in the North-East-Down (NED) frame.

    Output Arguments

    collapse all

    Position history of the satellites in meters, returned as a 3-by-n-by-m array in the GCRF. n is the number of time samples and m is the number of satellites.

    When the AutoSimulate property of the satellite scenario is true, the position history from StartTime to StopTime is returned. Otherwise, the position history from StartTime to SimulationTime is returned.

    Velocity history of the satellites in meters per second, returned as a 3-by-n-by-m array in the GCRF. n is the number of time samples and m is the number of satellites.

    Time samples of the position and velocity of the satellites, returned as a scalar or vector. If time histories of the position and velocity of the satellite are returned, timeOut is a row vector.

    Version History

    Introduced in R2021a