satellite
Syntax
Description
satellite(
adds a scenario
,semimajoraxis
,eccentricity
,inclination
,RAAN
,argofperiapsis
,trueanomaly
)Satellite
object from
Keplerian elements defined in the Geocentric Celestial Reference Frame
(GCRF) to the satellite scenario.
satellite(
adds a scenario
,positiontable
)Satellite
object from
position data specified in positiontable
(timetable
object) to the scenario. This function creates a Satellite
with
OrbitPropagator="ephemeris"
.
satellite(
adds a scenario
,positiontable
,velocitytable
)Satellite
object from
position data specified in positiontable
(timetable
object) and velocity data specified in velocitytable
(timetable
object) to the scenario. This function creates a Satellite
with
OrbitPropagator="ephemeris"
.
satellite(
adds a scenario
,positiontimeseries
)Satellite
object from
position data specified in positiontimeseries
to the
scenario
. This function creates a Satellite
with
OrbitPropagator="ephemeris"
.
satellite(
adds a scenario
,positiontimeseries
,velocitytimeseries
)Satellite
object to the
scenario
from position (in meters) data specified in
positiontimeseries
(timeseries
object) and
velocity (in meters/second) data specified in velocitytimeseries
(timeseries
object). This function creates a Satellite
with
OrbitPropagator="ephemeris"
.
satellite(___,
specifies options using one or more name-value arguments in addition to any input argument
combination from previous syntaxes. Name,Value
)
returns a
vector of handles to the added satellites. Specify any input argument combination from
previous syntaxes.sat
= satellite(___)
Note
When the AutoSimulate
property of the satelliteScenario
is
false
, you can modify the satellite
only when the
SimulationStatus
is NotStarted
. You can use the
restart
function to
reset SimulationStatus
to NotStarted
, but doing
so erases the simulation data.
Examples
Visualize Satellite Trajectories
Create a satellite scenario object.
sc = satelliteScenario;
Load the satellite ephemeris timetable in the Earth Centered Earth Fixed (ECEF) coordinate frame.
load("timetableSatelliteTrajectory.mat","positionTT","velocityTT");
Add four satellites to the scenario.
sat = satellite(sc,positionTT,velocityTT,"CoordinateFrame","ecef");
Visualize the trajectories of the satellites.
play(sc);
Add Ground Stations to Scenario and Visualize Access Intervals
Create a satellite scenario and add ground stations from latitudes and longitudes.
startTime = datetime(2020,5,1,11,36,0); stopTime = startTime + days(1); sampleTime = 60; sc = satelliteScenario(startTime,stopTime,sampleTime); lat = 10; lon = -30; gs = groundStation(sc,lat,lon);
Add satellites using Keplerian elements.
semiMajorAxis = 10000000;
eccentricity = 0;
inclination = 10;
rightAscensionOfAscendingNode = 0;
argumentOfPeriapsis = 0;
trueAnomaly = 0;
sat = satellite(sc,semiMajorAxis,eccentricity,inclination, ...
rightAscensionOfAscendingNode,argumentOfPeriapsis,trueAnomaly);
Add access analysis to the scenario and obtain the table of intervals of access between the satellite and the ground station.
ac = access(sat,gs); intvls = accessIntervals(ac)
intvls=8×8 table
Source Target IntervalNumber StartTime EndTime Duration StartOrbit EndOrbit
_____________ __________________ ______________ ____________________ ____________________ ________ __________ ________
"Satellite 2" "Ground station 1" 1 01-May-2020 11:36:00 01-May-2020 12:04:00 1680 1 1
"Satellite 2" "Ground station 1" 2 01-May-2020 14:20:00 01-May-2020 15:11:00 3060 1 2
"Satellite 2" "Ground station 1" 3 01-May-2020 17:27:00 01-May-2020 18:18:00 3060 3 3
"Satellite 2" "Ground station 1" 4 01-May-2020 20:34:00 01-May-2020 21:25:00 3060 4 4
"Satellite 2" "Ground station 1" 5 01-May-2020 23:41:00 02-May-2020 00:31:00 3000 5 5
"Satellite 2" "Ground station 1" 6 02-May-2020 02:50:00 02-May-2020 03:39:00 2940 6 6
"Satellite 2" "Ground station 1" 7 02-May-2020 05:58:00 02-May-2020 06:47:00 2940 7 7
"Satellite 2" "Ground station 1" 8 02-May-2020 09:06:00 02-May-2020 09:56:00 3000 8 9
Play the scenario to visualize the ground stations.
play(sc)
Add Satellites to Scenario Using Keplerian Elements
Create a satellite scenario with a start time of 02-June-2020 8:23:00 AM UTC, and the stop time set to one day later. Set the simulation sample time to 60 seconds.
startTime = datetime(2020,6,02,8,23,0); stopTime = startTime + days(1); sampleTime = 60; sc = satelliteScenario(startTime,stopTime,sampleTime);
Add two satellites to the scenario using their Keplerian elements.
semiMajorAxis = [10000000;15000000];
eccentricity = [0.01;0.02];
inclination = [0;10];
rightAscensionOfAscendingNode = [0;15];
argumentOfPeriapsis = [0;30];
trueAnomaly = [0;20];
sat = satellite(sc,semiMajorAxis,eccentricity,inclination, ...
rightAscensionOfAscendingNode,argumentOfPeriapsis,trueAnomaly)
sat = 1x2 Satellite array with properties: Name ID ConicalSensors Gimbals Transmitters Receivers Accesses GroundTrack Orbit OrbitPropagator MarkerColor MarkerSize ShowLabel LabelFontColor LabelFontSize
View the satellites in orbit and the ground tracks over one hour.
show(sat) groundTrack(sat,LeadTime=3600)
ans=1×2 object
1×2 GroundTrack array with properties:
LeadTime
TrailTime
LineWidth
LeadLineColor
TrailLineColor
VisibilityMode
Play the scenario and set the animation speed of the simulation to 40.
play(sc,PlaybackSpeedMultiplier=40)
Visualize GPS Constellation
Set up the satellite scenario.
startTime = datetime(2021,8,5);
stopTime = startTime + days(1);
sampleTime = 60; % seconds
sc = satelliteScenario(startTime,stopTime,sampleTime);
Add satellites to the scenario from a SEM almanac file.
sat = satellite(sc,"gpsAlmanac.txt","OrbitPropagator","gps");
Visualize the GPS constellation.
v = satelliteScenarioViewer(sc);
Add Satellite to Satellite Scenario for Orbit Mean-Elements Message File
Add a satellite to a satellite scenario from a Consultative Committee for Space Data Systems (CCSDS) Orbit Mean-Elements Message (OMM) file.
Create a satellite scenario. Use the epoch defined in the OMM file as the start time for the scenario (default behavior).
startTime = datetime(2020,5,10,0,0,0);
stopTime = startTime + days(1);
sampleTime = 60; % seconds
sc = satelliteScenario(startTime,stopTime,sampleTime);
Add satellites from the OMM file eccentricOrbitSatellite.xml
to the scenario sc
. Use the default names provided in the OMM metadata.
sat1 = satellite(sc, "eccentricOrbitSatellite.xml")
sat1 = Satellite with properties: Name: Satellite 41 ID: 1 ConicalSensors: [1x0 matlabshared.satellitescenario.ConicalSensor] Gimbals: [1x0 matlabshared.satellitescenario.Gimbal] Transmitters: [1x0 satcom.satellitescenario.Transmitter] Receivers: [1x0 satcom.satellitescenario.Receiver] Accesses: [1x0 matlabshared.satellitescenario.Access] Eclipse: [1x0 Aero.satellitescenario.Eclipse] GroundTrack: [1x1 matlabshared.satellitescenario.GroundTrack] Orbit: [1x1 matlabshared.satellitescenario.Orbit] CoordinateAxes: [1x1 matlabshared.satellitescenario.CoordinateAxes] OrbitPropagator: sdp4 MarkerColor: [0.059 1 1] MarkerSize: 6 ShowLabel: true LabelFontColor: [1 1 1] LabelFontSize: 15 Visual3DModel: Visual3DModelScale: 1
Visualize the satellite.
v = satelliteScenarioViewer(sc);
Play the scenario.
play(sc);
Input Arguments
scenario
— Satellite scenario
satelliteScenario
object
Satellite scenario, specified as a satelliteScenario
object.
file
— TLE, Orbit Mean-Elements Message (OMM), or SEM almanac file
character vector | string scalar
Two-line element (TLE), Orbit Mean-Elements Message (OMM) (.xml or .json), or SEM almanac file, specified as a character vector or a string scalar. The file must exist in the current folder, in a folder on the MATLAB® path, or it must include a full or relative path to a file.
For more information on TLE files, see Two Line Element (TLE) Files. For more information on OMM files, see Orbit Mean-Elements Message (OMM) File.
Data Types: char
| string
RINEXdata
— RINEX navigation message
structure
RINEX navigation message output from rinexread
(Navigation Toolbox),
specified as a structure. The navigation message must belong to GPS or Galileo
constellation.
If RINEXdata
contains multiple entries for the same satellite
and StartTime
of scenario
is using
default values, the entry corresponding to the earliest time is used. If StartTime
is explicitly specified, the entry that is closest
to StartTime
is used.
Data Types: struct
Note
This argument requires Navigation Toolbox™.
semimajoraxis
, eccentricity
, inclination
, RAAN
, argofperiapsis
, trueanomaly
— Keplerian elements defined in GCRF
comma-separated list of vectors
Keplerian elements defined in the GCRF, specified as a comma-separated list of vectors. The Keplerian elements are:
semimajoraxis
– This vector defines the semimajor axis of the orbit of the satellite. Each value is equal to half of the longest diameter of the orbit.eccentricity
– This vector defines the shape of the orbit of the satellite.inclination
– This vector defines the angle between the orbital plane and the xy-plane of the GCRF for each satellite in the range [0,180].RAAN
(right ascension of ascending node) – This element defines the angle between the xy-plane of the GCRF and the direction of the ascending node, as seen from the Earth's center of mass for each satellite in the range [0,360). The ascending node is the location where the orbit crosses the xy-plane of the GCRF and goes above the plane.argofperiapsis
(argument of periapsis) – This vector defines the angle between the direction of the ascending node and the periapsis, as seen from the Earth's center of mass in the range [0,360). Periapsis is the location on the orbit that is closest to the Earth's center of mass for each satellite.trueanomaly
– This vector defines the angle between the direction of the periapsis and the current location of the satellite, as seen from the Earth's center of mass for each satellite in the range [0,360).
For elliptical orbits, set semimajoraxis
to positive and
eccentricity
in the range [0,1).
For parabolic and hyperbolic orbits, set semimajoraxis
to
negative, eccentricity
to 1 for parabolic orbits, and greater than
1 for hyperbolic.
For all three kinds of orbits, set inclination
in the range
[0,180] and all other angles in the range [0,360).
Note
All angles defined outside the specified range is automatically converted to the corresponding value within the acceptable range.
For more information on Keplerian elements, see Orbital Elements.
positiontable
— Position data
timetable | table
Position data in meters, specified as a timetable created using the timetable
function or table
function. The positiontable
has exactly one
monotonically increasing column of rowTimes
(datetime
or duration
) and either:
One or more columns of variables, where each column contains data for an individual satellite over time.
One column of 2-D data, where the length of one dimension must equal 3 and the remaining dimension defines the number of satellites in the ephemeris.
One column of 3-D data, where the length of one dimension must equal 3, one dimension is a singleton, and the remaining dimension defines the number of satellites in the ephemeris.
If rowTimes values are of type duration
, time
values are measured relative to the current scenario StartTime
property. The timetable VariableNames
property are used by default if
no names are provided as an input. Satellite states are assumed to be in the GCRF unless
a CoordinateFrame
name-value argument is provided. States are held constant in GCRF for scenario timesteps
outside of the time range of positiontable
.
Data Types: table
| timetable
velocitytable
— Velocity data
timetable | table
Velocity data in meters/second, specified as a timetable created using the timetable
function or the table
function. The velocitytable
has exactly one
monotonically increasing column of rowTimes
(datetime
or duration
), and either:
One or more columns of variables, where each column contains data for an individual satellite over time.
One column of 2-D data, where the length of one dimension must equal 3 and the remaining dimension defines the number of satellites in the ephemeris.
One column of 3-D data, where the length of one dimension must equal 3, one dimension is a singleton, and the remaining dimension defines the number of satellites in the ephemeris.
If rowTimes values are of type duration
, time
values are measured relative to the current scenario StartTime
property. The timetable VariableNames
are used by default if no names
are provided as an input. Satellite states are assumed to be in the GCRF unless a
CoordinateFrame
name-value argument is provided. States are held constant in GCRF for scenario timesteps
outside of the time range of velocitytable
.
Data Types: table
| timetable
positiontimeseries
— Position data
timeseries
object | tscollection
object
Position data in meters, specified as a timeseries
object or a tscollection
object.
If the
Data
property of thetimeseries
ortscollection
object has two dimensions, one dimension must equal 3, and the other dimension must align with the orientation of the time vector.If the
Data
property of thetimeseries
ortscollection
has three dimensions, one dimension must equal 3, either the first or the last dimension must align with the orientation of the time vector, and the remaining dimension defines the number of satellites in the ephemeris.When
timeseries.TimeInfo.StartDate
is empty, time values are measured relative to the current scenarioStartTime
property. The timeseriesName
property (if defined) is used by default if no names are provided as inputs. Satellite states are assumed to be in the GCRF unless aCoordinateFrame
name-value pair is provided. States are held constant in GCRF for scenario timesteps outside of the time range ofpositiontimeseries
.
Data Types: timeseries
| tscollection
velocitytimeseries
— Velocity data
timeseries
object | tscollection
object
Velocity data in meters/second, specified as a timeseries
object or a tscollection
object.
If the
Data
property of thetimeseries
ortscollection
object has two dimensions, one dimension must equal 3, and the other dimension must align with the orientation of the time vector.If the
Data
property of thetimeseries
ortscollection
has three dimensions, one dimension must equal 3, either the first or the last dimension must align with the orientation of the time vector, and the remaining dimension defines the number of satellites in the ephemeris.When
timeseries.TimeInfo.StartDate
is empty, time values are measured relative to the current scenarioStartTime
property. The timeseriesName
property (if defined) is used by default if no names are provided as inputs. Satellite states are assumed to be in the GCRF unless aCoordinateFrame
name-value pair is provided. States are held constant in GCRF for scenario timesteps outside of the time range ofvelocitytimeseries
.
Data Types: timeseries
| tscollection
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.
Example: Name = 'MySatellite'
sets the satellite name to
'MySatellite'
.
CoordinateFrame
— Satellite state coordinate frame
"inertial"
(default) | "ecef"
| "geographic"
Satellite state coordinate frame, specified as the comma-separated pair consisting
of 'CoordinateFrame'
and one of these values:
"inertial"
— Fortimeseries
ortimetable
data, specifying this value accepts the position and velocity in the GCRF frame."ecef"
— Fortimeseries
ortimetable
data, specifying this value accepts the position and velocity in the ECEF frame."geographic"
— Fortimeseries
ortimetable
data, specifying this value accepts the position [lat, lon, altitude], where lat and lon are latitude and longitude in degrees, and altitude is the height above the World Geodetic System 84 (WGS 84) ellipsoid in meters.Velocity is in the local NED frame.
Dependencies
To enable this name value argument, ephemeris data inputs (
timetable
ortimeseries
).When
file
is an OMM file, this argument is ignored.
Data Types: string
| char
GPSweekepoch
— GPS week epoch
date string
GPS week epoch, specified as a date string in "dd-Mmm-yyyy" or 'dd-Mmm-yyyy'
format. The GPS week number specifies the reference date that the function uses when
counting weeks defined in the SEM almanac file. If you do not specify
GPSweekepoch
, the function uses the date that coincides with
the latest GPS week number rollover date before the start time.
This argument applies only if you use a SEM almanac file. If you specify
GPSweekepoch
and you are not using a SEM almanac file, the
function ignores the argument value.
Dependencies
When file
is an OMM file, this argument is ignored.
Data Types: string
| char
Viewer
— Satellite scenario viewer
vector of satelliteScenarioViewer
objects (default) | scalar satelliteScenarioViewer
object | array of satelliteScenarioViewer
objects
Satellite scenario viewer, specified as a scalar, vector, or array of satelliteScenarioViewer
objects. If the AutoSimulate
property of the scenario is false
,
adding a satellite to the scenario disables any previously available timeline and
playback widgets.
Name
— Satellite name
string scalar | string vector | character vector | cell array of character vectors
You can set this property only when calling the satellite
function. After you call satellite
function, this property is read-only.
Satellite name, specified as a comma-separated pair consisting of 'Name'
and a string scalar, string vector, character vector or a cell array of character vectors.
If only one satellite is added, specify
Name
as a string scalar or a character vector.If multiple satellites are added, specify
Name
as a string scalar, character vector, string vector or a cell array of character vectors. All satellites added as a string scalar or a character vector are assigned the same specified name. The number of elements in the string vector or cell array of character vector must equal the number of satellites being added. Each satellite is assigned the corresponding name from the vector or cell array.
The default value when satellite is added to the satellite scenario using
Keplerian orbital elements, TLE file, timeseries, or timetable — "Satellite ID", where
ID
is assigned by the satellite scenario.SEM almanac file or RINEX GPS navigation data — "PRN:prnValue", where prnValue is an integer denoting the pseudorandom noise code of the satellite as specified in the SEM almanac file.
RINEX Galileo navigation data — "GAL Sat IF: id", where "id" is the satellite ID of the Galileo satellite defined in the RINEX navigation data.
Data Types: string
OrbitPropagator
— Name of orbit propagator
"sgp4"
| "sdp4"
| "two-body-keplerian"
| "ephemeris"
| "gps"
| "galileo"
| "numerical"
You can set this property on satellite
object creation and then this
property becomes read-only.
Name of the orbit propagator used for propagating the satellite position and velocity, specified as one of these options.
If you specify the satellite using timetable, table,
timeseries
, ortscollection
, theOrbitPropagator
value is"ephemeris"
.If you specify the satellite using a SEM almanac file or RINEX data containing a GPS navigation message, the
OrbitPropagator
value can take one of these options."gps"
(default)"sgp4"
"sdp4"
"two-body-keplerian"
"numerical"
If you specify the satellite using the RINEX data containing a Galileo navigation message, the
OrbitPropagator
value can take one of these options."galileo"
(default)"sgp4"
"sdp4"
"two-body-keplerian"
"numerical"
If you specify the satellite is added using Keplerian elements,
OrbitPropagator
value can take one of these options."two-body-keplerian"
"sgp4"
"sdp4"
"numerical"
Additionally, if semimajor axis is negative,
OrbitPropagator
value can only be"numerical"
. If semimajor axis is positive, default value is"sgp4"
for periods less than 225 min and"sdp4"
for periods greater than or equal to 225 minutes.If you specify the satellite using a TLE or OMM file, the
OrbitPropagator
value can take one of these options."two-body-keplerian"
"sgp4"
"sdp4"
"numerical"
If the orbital period is less than 225 minutes, the default
OrbitPropagator
value is"sgp4"
. Otherwise, the defaultOrbitPropagator
value is"sdp4"
.If you specify the satellite using
Keplerian
elements, theOrbitPropagator
value can take one of these options."two-body-keplerian"
"sgp4"
"sdp4"
If the RINEX data contains both valid GPS and Galileo navigation messages, you cannot
specify OrbitPropagator
as "gps"
or
"galileo"
using a name-value argument. However, you can still specify it
as "two-body-keplerian"
, "sgp4"
,
"sdp4"
, or "numerical"
.
Visual3DModel
— Name of 3-D model file
zero-length string (default)
Name of the visual 3-D model file that you want to render in the viewer, specified as a string with .GLTF, .GLB, or .STL extension. For GLB and GLTF models, gITF uses a right-hand coordinate system. gITF defines +Y as up, and +Z as forward, and -X as right. A gITF asset faces +Z. For more information, see https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#coordinate-system-and-units. The mesh of the GLB is in meters.
Data Types: string
Visual3DModelScale
— Linear scaling of 3-D model
1
(default) | nonnegative integer
Linear scaling of the visual 3-D model rendered in the viewer, specified as a nonnegative integer. The scaling assumes that the GLB model is in meters.
Data Types: double
Output Arguments
Version History
Introduced in R2021aR2023b: OMM file added to the file argument
You can now add satellites via OMM file to the scenario using the
file
input argument.
R2022b: RINEXdata argument added to the function
You can now add satellites via RINEX navigation data to the scenario using the
RINEXdata
input argument.
R2022a: SEM almanac file added to the file argument
You can now add satellites via SEM almanac file to the scenario using the
file
input argument.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)