satellite

R2026b

Add satellites to satellite scenario

collapse all in page

Syntax

satellite(scenario,file)
satellite(scenario,RINEXdata)
satellite(scenario,semimajoraxis,eccentricity,inclination,RAAN,argofperiapsis,trueanomaly)
satellite(scenario,positiontable)
satellite(scenario,positiontable,velocitytable)
satellite(scenario,positiontimeseries)
satellite(scenario,positiontimeseries,velocitytimeseries)
satellite(___,Name=Value)
sat = satellite(___)

Description

satellite(scenario,file) adds Satellite objects from file to the satellite scenario specified by scenario. The yaw (z) axes of the satellites point toward nadir and the roll (x) axes of the satellites align with their respective inertial velocity vectors.

example

satellite(scenario,RINEXdata) adds Satellite objects from RINEXdata to the satellite scenario specified by scenario.

satellite(scenario,semimajoraxis,eccentricity,inclination,RAAN,argofperiapsis,trueanomaly) adds a Satellite object from Keplerian elements defined in the International Celestial Reference Frame (ICRF) to the satellite scenario.

satellite(scenario,positiontable) adds a Satellite object from position data specified in positiontable (timetable object) to the scenario. This function creates a Satellite with OrbitPropagator="ephemeris".

example

satellite(scenario,positiontable,velocitytable) adds a 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".

example

satellite(scenario,positiontimeseries) adds a Satellite object from position data specified in positiontimeseries to the scenario. This function creates a Satellite with OrbitPropagator="ephemeris".

satellite(scenario,positiontimeseries,velocitytimeseries) adds a Satellite object to 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(___,Name=Value) specifies options using one or more name-value arguments in addition to any input argument combination from previous syntaxes.

sat = satellite(___) returns a vector of handles to the added satellites. Specify any input argument combination from previous syntaxes.

Note

When the AutoSimulate property of the satelliteScenario is false, you can modify satellite only when SimulationStatus is NotStarted. You can use the restart function to reset SimulationStatus to NotStarted, but doing so erases the simulation data.

Examples

collapse all

Open Live Script

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);

Open Live Script

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
    "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)

Open Live Script

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×1 GroundTrack    1×1 GroundTrack

Play the scenario and set the animation speed of the simulation to 40.

play(sc,PlaybackSpeedMultiplier=40)

Open Live Script

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);

Open Live Script

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);

Scenario viewer output with Satellite 41

Play the scenario.

play(sc);

Input Arguments

collapse all

Satellite scenario, specified as a satelliteScenario object.

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

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

Keplerian elements defined in the ICRF, specified as a comma-separated list of vectors. The Keplerian elements are:

  • semimajoraxis (or periapsis radius) – 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 ICRF 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 ICRF 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 ICRF 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 trajectories (eccentricity = 1), semimajoraxis specifies the periapsis radius and must be positive.

For hyperbolic trajectories (eccentricity > 1), semimajoraxis must be negative.

For parabolic orbits, trueanomaly, when wrapped to the range (-180, 180] degrees, cannot equal 180 degrees. At +/-180 degrees the distance from the central body is infinite.

For hyperbolic orbits, trueanomaly, when wrapped to the range (-180, 180] degrees, must be in the open range (-acosd(-1/eccentricity), acosd(-1/eccentricity)) degrees. These limits define the asymptotes of the hyperbola, where the distance from the central body is infinite. True anomaly values at or beyond these limits are physically impossible.

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 are automatically converted to the corresponding value within the acceptable range.

Note

Eccentricity greater than or equal to 1 requires Aerospace Toolbox.

Note

The Keplerian elements define the satellite orbit at the epoch, which is the scenario StartTime at the moment the satellite is created. If you change the StartTime of the scenario after creating a satellite, the satellite orbit is propagated to the new start time.

For more information on Keplerian elements, see Orbital Elements.

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 ICRF unless a CoordinateFrame name-value argument is provided. States are held constant in ICRF for scenario time steps outside of the time range of positiontable.

Data Types: table | timetable

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 ICRF unless a CoordinateFrame name-value argument is provided. States are held constant in ICRF for scenario time steps outside of the time range of velocitytable.

Data Types: table | timetable

Position data in meters, specified as a timeseries object or a tscollection object.

  • If the Data property of the timeseries or tscollection 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 the timeseries or tscollection 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 scenario StartTime property. The timeseries Name property (if defined) is used by default if no names are provided as inputs. Satellite states are assumed to be in the ICRF unless a CoordinateFrame name-value argument is provided. States are held constant in ICRF for scenario time steps outside of the time range of positiontimeseries.

Data Types: timeseries | tscollection

Velocity data in meters/second, specified as a timeseries object or a tscollection object.

  • If the Data property of the timeseries or tscollection 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 the timeseries or tscollection 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 scenario StartTime property. The timeseries Name property (if defined) is used by default if no names are provided as inputs. Satellite states are assumed to be in the ICRF unless a CoordinateFrame name-value argument is provided. States are held constant in ICRF for scenario time steps outside of the time range of velocitytimeseries.

Data Types: timeseries | tscollection

Name-Value Arguments

collapse all

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

Since R2026b

Celestial body relative to which the Keplerian element inputs (semimajorAxis, eccentricity, inclination, RAAN, argofperiapsis, and trueanomaly) or ephemeris data inputs (timetable or timeseries) are defined, specified as "Earth" or "Moon".

You can specify "Moon" only when using Keplerian element inputs or ephemeris data inputs. When CentralBody equals "Moon", TLE, OMM, SEM almanac, and RINEX data inputs are not supported and result in an error.

Dependencies

  • When CentralBody equals "Moon" and you explicitly specify the OrbitPropagator name-value argument, it must equal "two-body-keplerian" or "numerical". When using timetable or timeseries inputs, the propagator is set to "ephemeris" automatically.

  • When CoordinateFrame equals "ecef" or "geographic", the CentralBody is assumed to be "Earth" and this input is ignored.

Data Types: string

Satellite state coordinate frame, specified as one of these values:

  • "inertial" — Accepts position and velocity in the International Celestial Reference Frame (ICRF), with the origin at the celestial body specified by the CentralBody name‑value argument.

  • "ecef" — Accepts position and velocity in the Earth‑Centered Earth‑Fixed (ECEF) frame. The central body is assumed to be "Earth", and the CentralBody argument is ignored.

  • "geographic" — Accepts position as [lat, lon, altitude], where latitude and longitude are Earth latitude and longitude in degrees, and altitude is the height above the WGS 84 ellipsoid in meters. Velocity is specified in the local North‑East‑Down (NED) frame on Earth. The central body is assumed to be Earth, and the CentralBody argument is ignored.

  • "fixed-frame" — Accepts position and velocity in the fixed frame of the celestial body specified by the CentralBody name‑value argument. When CentralBody equals "Earth", this option is equivalent to "ecef".

  • "planetographic" — Accepts position as [lat, lon, altitude], where latitude and longitude are planetographic coordinates of the celestial body in degrees, and altitude is the height above the reference ellipsoid of the celestial body in meters. Velocity is specified in the local NED frame on the celestial body. The celestial body is specified by the CentralBody name‑value argument. When CentralBody equals "Earth", this option is equivalent to "geographic".

Dependencies

  • This input is available only when using ephemeris data inputs (timetable or timeseries).

  • When file is an OMM file, this argument is ignored.

Data Types: string | char

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

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.

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 name-value argument 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 — "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.

  • Timetable - Variable names of the timetable object.

  • Timeseries - Name of the timeseries object if populated, otherwise "Satellite ID", where ID is assigned by satellite scenario.

Data Types: string

You can set this property when you create a satellite object, 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 values:

  • If you specify the satellite using timetable, table, timeseries, or tscollection, the OrbitPropagator 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 be one of these values:

    • "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 be one of these values:

    • "galileo" (default)

    • "sgp4"

    • "sdp4"

    • "two-body-keplerian"

    • "numerical"

  • If you specify the satellite using Keplerian elements, OrbitPropagator value can be one of these values:

    • "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 be one of these values:

    • "two-body-keplerian"

    • "sgp4"

    • "sdp4"

    • "numerical"

    If the orbital period is less than 225 minutes, the default OrbitPropagator value is "sgp4". Otherwise, the default OrbitPropagator value is "sdp4".

  • If you specify the satellite using Keplerian elements, the OrbitPropagator value can be one of these values:

    • "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".

Dependencies

When CentralBody equals "Moon" and you explicitly specify the OrbitPropagator name-value argument, only "two-body-keplerian" and "numerical" are valid. Setting OrbitPropagator to "sgp4", "sdp4", "gps", or "galileo" when CentralBody equals "Moon" returns an error. When using timetable or timeseries inputs, the propagator is set to "ephemeris" automatically.

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

collapse all

Satellite in the scenario, returned as a Satellite object belonging to the satellite scenario specified by scenario.

You can modify the Satellite object by changing its property values.

Version History

Introduced in R2021a

expand all

See Also

Objects

Functions

Topics