# states

Obtain position and velocity of satellite

Since R2021a

## Syntax

``pos = states(sat)``
``[pos,velocity] = states(sat)``
``[___] = states(sat,timeIn)``
``[___] = states(___,CoordinateFrame=C)``
``[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 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.```
````[___] = 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(___,CoordinateFrame=C)` returns the outputs in the coordinates specified by `C`.```
````[pos,velocity,timeOut] = states(___)` returns the position and velocity history of the satellites and the corresponding datetime in UTC.```

## 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.

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