states

R2026b

Obtain position and velocity of satellite or platform

Syntax

pos = states(sat)

pos = states(pltf)

[pos,velocity] = states(sat)

[pos,velocity] = states(pltf)

[___] = states(sat,timeIn)

[___] = states(pltf,timeIn)

[___] = states(___,Name=Value)

[pos,velocity,timeOut] = states(___)

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 International Celestial Reference Frame (ICRF) with respect to the celestial body specified by the CentralBody property of sat.

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 platforms. The rows represent the x, y, and z coordinates of the platform in the International Celestial Reference Frame (ICRF) with respect to the celestial body specified by the CentralBody property of pltf.

[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 ICRF.

[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 ICRF.

[___] = 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(___,Name=Value) returns the outputs with additional options specified by one or more name-value arguments.

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

Examples

Obtain States of Satellite in ECEF Frame

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.9001
   -3.0897
    2.6716

velocity = 3×1
103 ×

   -1.2151
    0.4417
   -1.7198

Input Arguments

sat — Satellite

row vector of Satellite objects

Satellite, specified as a row vector of Satellite objects.

pltf — Platform

row vector of Platform objects

Platform, specified as a row vector of Platform objects.

timeIn — Time at which output is calculated

datetime scalar

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.

CoordinateFrame — Coordinate frame

'inertial' (default) | 'ecef' | 'geographic' | 'fixed-frame' | 'planetographic'

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

• The 'inertial' option returns the position and velocity coordinates in the ICRF. This is the default.

• 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. When CoordinateFrame is set to 'ecef', the states function calculates velocity after removing the central body's rotation component v_ECEF = TIRF_C_ECEF v_INERTIAL - (ɷ_TIRF x r_ECEF) where ɷ_TIRF = [0;0;0.0000729211585530] rad/s and aligns with the z‑axis of the terrestrial intermediate reference frame (TIRF) and TIRF_C_ECEF is the direction cosine matrix relating TIRF and ECEF frames.

• 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 central body in meters. The velocity returned is in the North-East-Down (NED) frame. When CoordinateFrame is set to 'geographic', the states function calculates ECEF velocity expressed in the NED frame v_NED = ECEF_C_NED  v_ECEF where ECEF_C_NED is a direction cosine matrix relating ECEF and NED frames.

• The 'fixed-frame' option returns the position and velocity in the fixed frame of the reference celestial body, specified by the ReferenceCelestialBody name-value argument. The rows represent x, y, and z components of position in meters and velocity in meters/second. When CentralBody equals "Earth", 'fixed-frame' is equivalent to 'ecef'.

• The 'planetographic' option returns the position as [lat; lon; altitude] with respect to the reference celestial body, specified by the ReferenceCelestialBody name-value argument. Latitude and longitude are in degrees, and altitude is the height above the surface of the reference celestial body in meters. The velocity returned is in the North-East-Down (NED) frame on the reference celestial body. When CentralBody equals "Earth", 'planetographic' is equivalent to 'geographic'.

ReferenceCelestialBody — Reference celestial body for state output

CentralBody property of asset (default) | "Earth" | "Moon"

Since R2026b

Reference celestial body for state output, specified as "Earth" or "Moon". The default value is the CentralBody property of the asset. The states output is computed relative to the specified celestial body regardless of the CentralBody setting of the asset.

Dependencies

• When CoordinateFrame equals "ecef" or "geographic", the ReferenceCelestialBody is ignored. This is equivalent to specifying ReferenceCelestialBody="Earth" with CoordinateFrame="fixed-frame" or "planetographic", respectively.

• When ReferenceCelestialBody equals "Moon", the Moon must have been added to the satellite scenario. Otherwise, the function returns an error.

Data Types: string

Output Arguments

pos — Position history

3-by-n-by-m array

Position history of the satellites or platforms in meters, returned as a 3-by-n-by-m array. n is the number of time samples and m is the number of satellites or platforms. The position value type depends on the coordinate frame and reference celestial body input values.

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 — Velocity history

3-by-n-by-m array

Velocity history of the satellites or platforms in meters per second, returned as a 3-by-n-by-m array. n is the number of time samples and m is the number of satellites or platforms. The velocity value type depends on the coordinate frame and reference celestial body input values.

timeOut — Time samples of position and velocity

scalar | vector

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

Version History

Introduced in R2021a

R2026b: ReferenceCelestialBody name‑value argument added

You can now obtain satellite or platform states with respect to the Moon by specifying the ReferenceCelestialBody name‑value argument as "Moon". States are computed relative to the specified celestial body regardless of the asset's CentralBody property. Use the "fixed-frame" and "planetographic" coordinate frame options to obtain states in Moon body‑fixed or Moon surface coordinates.