Main Content

satelliteScenario

Satellite scenario

    Description

    The satelliteScenario object represents a 3D arena consisting of satellites, ground stations, and the interactions between them. Use this object to model satellite constellations, model ground station networks, perform access analyses between the satellites and the ground stations, and visualize the results.

    Creation

    Description

    example

    sc = satelliteScenario creates a default satellite scenario object.

    example

    sc = satelliteScenario(startTime,stopTime,sampleTime) sets the StartTime, StopTime, and SampleTime properties to the values of startTime, stopTime, and sampleTime, respectively.

    example

    sc = satelliteScenario(___,'AutoSimulate'=false) sets the AutoSimulate property to a specified value.

    Properties

    expand all

    Start time of the satellite scenario simulation in UTC, specified as a datetime scalar.

    The default StartTime is the current UTC time if no satellites are present in the scenario. Otherwise, it is the earliest value among

    • the current UTC time.

    • the epoch defined in the TLE files.

    • the reference time deduced from the GPS week number defined in SEM files.

    • the earliest time deduced from RINEX navigation data for GPS and Galileo.

    • the initial time in the timetable and timeseries.

    If the StartTime, StopTime, or SampleTime properties are explicitly specified, the StartTime property no longer updates with further additions of satellites.

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

    Data Types: datetime

    Stop time of the satellite scenario simulation in UTC, specified as a datetime scalar. The default StopTime is StartTime + longest orbital period among the satellites in the scenario. If no satellites are added to the scenario, the default StopTime is the same as the default StartTime. If the StartTime, StopTime, or SampleTime properties are explicitly specified, the StopTime property no longer updates with further additions of satellites.

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

    Data Types: datetime

    Sample time of the satellite scenario simulation, specified as a real-valued scalar. The default sample time is set such that there are 100 samples between StartTime and StopTime. If the default StartTime and StopTime are the same, which is the case when no satellites are added to the scenario, the default SampleTime is 60 seconds. If the StartTime, StopTime, or SampleTime properties are explicitly specified, the SampleTime property no longer updates with further additions of satellites.

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

    Data Types: double

    This property is read-only.

    Current simulation time of the satellite scenario simulation in UTC, specified as a datetime scalar. Call the restart function to reset the time to StartTime.

    Dependencies

    To enable this property, set AutoSimulate to false.

    Data Types: datetime

    This property is read-only.

    Simulation status of the satellite scenario, specified as one of the following:

    • 'NotStarted' — No call to the advance function has been made

    • 'InProgress' — Simulation is running

    • 'Completed' — Simulation is finished

    The simulation starts when the first call to the advance function is made. The simulation continues until one of the following occurs:

    • The simulation reaches the StopTime.

    • A new asset is added to the satellite scenario.

    • Certain properties of the asset (satellites, ground stations, gimbals, conical sensors, and so on) have been modified, such as MountingLocation or MountingAngles. Refer to the properties to determine if modifying them can stop the simulation.

    Call the restart function to restart the simulation, erase the simulation data, and set SimulationStatus to NotStarted.

    Dependencies

    To enable this property, set AutoSimulate to false.

    Option to simulate the satellite scenario automatically, specified as one of these numeric or logical values.

    • 1 (true) — Simulate the satellite scenario automatically on any call to an analysis function, such as states or accessIntervals.

    • 0 (false)— Simulate the satellite scenario only by calling the advance function.

    Changing the AutoSimulate value erases the previous simulation data.

    Data Types: double

    Satellites in the scenario, returned as a row vector of Satellite objects. To create a Satellite object and add it to the satellite scenario, use the satellite object function. After adding satellites to the scenario, this property is read-only.

    Ground stations in the scenario, returned as a row vector of GroundStation objects. To create a GroundStation object and add it to the satellite scenario, use the groundStation object function. After adding ground stations to the scenario, this property is read-only.

    Option to automatically show graphics, specified as a logical 1 (true) or 0 (false). This property determines if entities added to the scenario are automatically shown in an open satelliteScenarioViewer window.

    Object Functions

    groundStationAdd ground station to satellite scenario
    satelliteAdd satellites to satellite scenario
    satelliteScenarioViewerCreate viewer for satellite scenario
    advanceMove simulation forward by one sample time
    restartRestart simulation from beginning
    playPlay satellite scenario simulation results on viewer

    Examples

    collapse all

    Specify the start time in the current time zone as yesterday. The simulation lasts for half a day.

    startTime = datetime("yesterday","TimeZone","local");
    stopTime = startTime + days(0.5);

    Specify the sample time as 60 seconds. Create a satellite scenario object, specifying the start time, stop time, and sample time.

    sampleTime = 60;
    sc = satelliteScenario(startTime,stopTime,sampleTime)
    sc = 
      satelliteScenario with properties:
    
             StartTime: 30-Aug-2022 04:00:00
              StopTime: 30-Aug-2022 16:00:00
            SampleTime: 60
          AutoSimulate: 1
            Satellites: [1x0 matlabshared.satellitescenario.Satellite]
        GroundStations: [1x0 matlabshared.satellitescenario.GroundStation]
               Viewers: [0x0 matlabshared.satellitescenario.Viewer]
              AutoShow: 1
    
    

    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)

    Create a satellite scenario object and set the AutoSimulate property to false to enable manual simulation of the satellite scenario.

    startTime = datetime(2022,1,12);
    stopTime = startTime + days(0.5);
    sampleTime = 60;                             % Seconds
    sc = satelliteScenario('AutoSimulate',false);

    Add a GPS satellite constellation to the scenario.

    sat = satellite(sc,"gpsAlmanac.txt");

    Simulate the scenario using the advance function.

    while advance(sc)
    end

    Obtain the satellite position histories.

    p = states(sat);

    AutoSimulate is false, so restart the scenario before adding a ground station.

    restart(sc);

    Add a ground station to the scenario.

    gs = groundStation(sc);

    Add access analysis between each satellite and ground station.

    ac = access(sat,gs);

    Simulate the scenario and determine the access intervals.

    while advance(sc)
    end
    intvls1 = accessIntervals(ac)
    intvls1=35×8 table
         Source           Target           IntervalNumber         StartTime                EndTime           Duration    StartOrbit    EndOrbit
        ________    ___________________    ______________    ____________________    ____________________    ________    __________    ________
    
        "PRN:1"     "Ground station 32"          1           11-Jan-2020 23:20:25    12-Jan-2020 05:15:47      21322        NaN          NaN   
        "PRN:2"     "Ground station 32"          1           12-Jan-2020 04:03:16    12-Jan-2020 07:40:50      13055        NaN          NaN   
        "PRN:3"     "Ground station 32"          1           11-Jan-2020 19:50:06    11-Jan-2020 21:38:53     6527.3        NaN          NaN   
        "PRN:3"     "Ground station 32"          2           12-Jan-2020 01:52:43    12-Jan-2020 06:42:49      17406        NaN          NaN   
        "PRN:4"     "Ground station 32"          1           11-Jan-2020 19:50:06    12-Jan-2020 00:11:11      15665        NaN          NaN   
        "PRN:4"     "Ground station 32"          2           12-Jan-2020 04:54:02    12-Jan-2020 07:40:50      10008        NaN          NaN   
        "PRN:5"     "Ground station 32"          1           12-Jan-2020 05:52:03    12-Jan-2020 07:40:50     6527.3        NaN          NaN   
        "PRN:6"     "Ground station 32"          1           12-Jan-2020 02:43:29    12-Jan-2020 07:40:50      17841        NaN          NaN   
        "PRN:7"     "Ground station 32"          1           11-Jan-2020 21:09:52    12-Jan-2020 03:27:00      22628        NaN          NaN   
        "PRN:8"     "Ground station 32"          1           11-Jan-2020 20:33:36    12-Jan-2020 03:19:45      24369        NaN          NaN   
        "PRN:9"     "Ground station 32"          1           11-Jan-2020 19:50:06    12-Jan-2020 00:47:27      17841        NaN          NaN   
        "PRN:9"     "Ground station 32"          2           12-Jan-2020 05:08:32    12-Jan-2020 07:40:50     9138.2        NaN          NaN   
        "PRN:10"    "Ground station 32"          1           12-Jan-2020 00:32:56    12-Jan-2020 01:59:58     5221.8        NaN          NaN   
        "PRN:11"    "Ground station 32"          1           11-Jan-2020 22:15:09    12-Jan-2020 04:39:32      23063        NaN          NaN   
        "PRN:12"    "Ground station 32"          1           12-Jan-2020 04:32:16    12-Jan-2020 07:40:50      11314        NaN          NaN   
        "PRN:13"    "Ground station 32"          1           12-Jan-2020 00:03:56    12-Jan-2020 02:50:44      10008        NaN          NaN   
          ⋮
    
    

    Visualize the simulation results.

    v = satelliteScenarioViewer(sc,'ShowDetails',false);
    play(sc);

    Verify that the access intervals are the same when you set the AutoSimulate property to true.

    sc.AutoSimulate = true;
    intvls2 = accessIntervals(ac)
    intvls2=35×8 table
         Source           Target           IntervalNumber         StartTime                EndTime           Duration    StartOrbit    EndOrbit
        ________    ___________________    ______________    ____________________    ____________________    ________    __________    ________
    
        "PRN:1"     "Ground station 32"          1           11-Jan-2020 23:20:25    12-Jan-2020 05:15:47      21322        NaN          NaN   
        "PRN:2"     "Ground station 32"          1           12-Jan-2020 04:03:16    12-Jan-2020 07:48:06      13490        NaN          NaN   
        "PRN:3"     "Ground station 32"          1           11-Jan-2020 19:50:06    11-Jan-2020 21:38:53     6527.3        NaN          NaN   
        "PRN:3"     "Ground station 32"          2           12-Jan-2020 01:52:43    12-Jan-2020 06:42:49      17406        NaN          NaN   
        "PRN:4"     "Ground station 32"          1           11-Jan-2020 19:50:06    12-Jan-2020 00:11:11      15665        NaN          NaN   
        "PRN:4"     "Ground station 32"          2           12-Jan-2020 04:54:02    12-Jan-2020 07:48:06      10444        NaN          NaN   
        "PRN:5"     "Ground station 32"          1           12-Jan-2020 05:52:03    12-Jan-2020 07:48:06     6962.4        NaN          NaN   
        "PRN:6"     "Ground station 32"          1           12-Jan-2020 02:43:29    12-Jan-2020 07:48:06      18276        NaN          NaN   
        "PRN:7"     "Ground station 32"          1           11-Jan-2020 21:09:52    12-Jan-2020 03:27:00      22628        NaN          NaN   
        "PRN:8"     "Ground station 32"          1           11-Jan-2020 20:33:36    12-Jan-2020 03:19:45      24369        NaN          NaN   
        "PRN:9"     "Ground station 32"          1           11-Jan-2020 19:50:06    12-Jan-2020 00:47:27      17841        NaN          NaN   
        "PRN:9"     "Ground station 32"          2           12-Jan-2020 05:08:32    12-Jan-2020 07:48:06     9573.3        NaN          NaN   
        "PRN:10"    "Ground station 32"          1           12-Jan-2020 00:32:56    12-Jan-2020 01:59:58     5221.8        NaN          NaN   
        "PRN:11"    "Ground station 32"          1           11-Jan-2020 22:15:09    12-Jan-2020 04:39:32      23063        NaN          NaN   
        "PRN:12"    "Ground station 32"          1           12-Jan-2020 04:32:16    12-Jan-2020 07:48:06      11749        NaN          NaN   
        "PRN:13"    "Ground station 32"          1           12-Jan-2020 00:03:56    12-Jan-2020 02:50:44      10008        NaN          NaN   
          ⋮
    
    

    Visualize the scenario.

    play(sc);

    Tips

    • When saving the satellite scenario, either save the entire workspace containing the scenario object or save the scenario object itself.

    Version History

    Introduced in R2021a