Main Content

satellite

Add satellites to satellite scenario

Description

sat = satellite(scenario,tlefile) adds a Satellite object from TLE file to the satellite scenario specified by scenario, specified as a string scalar or character vector. 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.

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

example

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

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

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

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

Examples

collapse all

Add four satellites to the satellite scenario from a position timetable to a satellite scenario and visualize their trajectories.

Create a default satellite scenario object.

sc = satelliteScenario;

Load a satellite ephemeris timetable, assuming the data is in the GCRF coordinate frame.

load("timetableSatelliteTrajectory.mat","positionTT");

Add the satellites to the scenario.

sat = satellite(sc,positionTT);

Visualize the trajectories of the satellites.

play(sc);

Add four satellites to the satellite scenario from position and velocity timetables in the Earth Centered Earth Fixed (ECEF) frame and visualize their trajectories.

Create a default satellite scenario object.

sc = satelliteScenario;

Load a satellite ephemeris timetable, assuming the data is in the ECEF coordinate frame.

load("timetableSatelliteTrajectory.mat","positionTT","velocityTT");

Add the satellites to the scenario.

sat = satellite(sc,positionTT,velocityTT,"CoordinateFrame","ecef")

Visualize the trajectories of the satellites.

play(sc);

Create 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:32:00      3060          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:59:00    02-May-2020 06:47:00      2880          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)

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 = 
  1×2 Satellite array with properties:

    Name
    ID
    ConicalSensors
    Gimbals
    Transmitters
    Receivers
    Accesses
    GroundTrack
    Orbit
    OrbitPropagator
    MarkerColor
    MarkerSize
    ShowLabel
    LabelFontSize
    LabelFontColor

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
    TrailLineColor
    LeadLineColor
    VisibilityMode

play(sc)

Input Arguments

collapse all

Satellite scenario, specified as a satelliteScenario object.

Name of a TLE file, specified as a character vector or a string scalar. The TLE file must exist in the current directory, exist in a directory on the MATLAB® path, or include a full or relative path to a file.

For more information on TLE files, see Two Line Element (TLE) Files.

Data Types: char | string

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.

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

For more information on Keplerian elements, see Orbital Elements.

Position data in meters, specified as a timetable created using the timetable function. positiontable has exactly one monotonically increasing column of rowTimes (datetime or duration values) and one or more columns of variables, where each column contains an individual satellite position over time.

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

Data Types: table | timetable

Velocity data in meters/second, specified as a timetable created using the timetable function. velocitytable has exactly one monotonically increasing column of rowTimes (datetime or duration values) and one or more columns of variables, where each column contains an individual satellite position over time.

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

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 GCRF unless a CoordinateFrame name-value pair is provided. States are held constant in GCRF for scenario timesteps 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 GCRF unless a CoordinateFrame name-value pair is provided. States are held constant in GCRF for scenario timesteps outside of the time range of velocitytimeseries.

Data Types: timeseries | tscollection

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'Name','MySatellite' sets the satellite name to 'MySatellite'.

Satellite scenario viewer, specified as a row vector of satelliteScenarioViewer objects.

Data Types: char | string

You can set this property only when calling satellite. After you call satellite, 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 vector or a cell array of character vectors. The number of elements in the string vector or cell array must be equal to the number of satellites being added.

In the default value, idx is the count of the satellite added by the satellite object function. If another satellite of the same name exists, a suffix _idx2 is added, where idx2 is an integer that is incremented by 1 starting from 1 until the name duplication is resolved.

Data Types: char | string

You can set this property when calling satellite only. After you call satellite, this property is read-only.

Name of the orbit propagator used for propagating satellite position and velocity, specified as the comma-separated pair consisting of 'OrbitPropagator' and either "two-body-keplerian", "sgp4", "sdp4", or "ephemeris".

Dependencies

OrbitPropagator is not available for ephemeris data inputs (timetable or timeseries). In these cases, satellite ignores this name-value pair.

Data Types: string | char

Satellite state coordinate frame, specified as the comma-separated pair consisting of 'CoordinateFrame' and one of these values:

  • "inertial" — For timeseries or timetable data, specifying this value accepts the position and velocity in the GCRF frame.

  • "ecef" — For timeseries or timetable data, specifying this value accepts the position and velocity in the ECEF frame.

  • "geographic" — For timeseries or timetable 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 or timeseries).

Data Types: string | char

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.

Introduced in R2021a