eclipse

Add eclipse analysis object to satellite, ground station, or platform

Since R2023b

Syntax

eclipse(asset)

eclipse(___,Name=Value)

ecl = eclipse(___)

Description

eclipse(asset) adds an eclipse analysis object for each Satellite, GroundStation, or Platform object in asset. All objects in asset must belong to the same satelliteScenario object. An eclipse analysis object is assigned to the Eclipse property of the corresponding Satellite, GroundStation, or Platform object in asset.

eclipse(___,Name=Value) adds eclipse analysis objects according to name-value arguments.

ecl = eclipse(___) returns a vector of eclipse analysis objects in the vector ecl.

Note

This function requires that you download ephemeris data using the Add-On Explorer. To start the Add-On Explorer, in the MATLAB^® Command Window, type aeroDataPackage.

Examples

Add Eclipse Analysis Object to Satellite and Ground Station

Add an eclipse analysis object to a satellite, sat, and ground station, gs, and calculate the eclipse intervals, intvls.

Create a satellite scenario object, sc.

startTime = datetime(2023,4,20);
stopTime = startTime + days(1);
sampleTime = 10; % seconds
sc = satelliteScenario(startTime,stopTime,sampleTime);

Add a ground station, gs, to the scenario, sc.

gs = groundStation(sc, ...
    1.038102, ... % latitude, degrees
    135.980085);  % longitude, degrees

Add a satellite, sat, to the scenario, sc. Set the orbit propagator as a two-body-keplerian.

sat = satellite(sc, ...
    10000000, ... % semimajor axis, meters
    0, ...        % eccentricity
    0, ...        % inclination, degrees
    0, ...        % right ascension of ascending node, degrees
    0, ...        % argument of periapsis, degrees
    0, ...        % true anomaly, degrees
    OrbitPropagator="two-body-keplerian");

Add the eclipse analysis object to the ground station, gs. Include the lunar eclipse in the analysis. By default, the eclipse model is for a dual-cone.

eclGs = eclipse(gs,IncludeLunarEclipse=true)

eclGs = 
  Eclipse with properties:

           EclipseModel: "dual-cone"
    IncludeLunarEclipse: 1

Add the eclipse analysis object to the satellite, sat. Include the lunar eclipse in the analysis. By default, the eclipse model is for a dual-cone.

eclSat = eclipse(sat,IncludeLunarEclipse=true)

eclSat = 
  Eclipse with properties:

           EclipseModel: "dual-cone"
    IncludeLunarEclipse: 1

Inspect the satellite and ground station object properties. Note that their Eclipse properties are nonempty, which indicates that the eclipse analyses have been added.

Eclipse: [1x1 Aero.satellitescenario.Eclipse]

sat

sat = 
  Satellite with properties:

                  Name:  Satellite 2
                    ID:  2
        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:  [1x1 Aero.satellitescenario.Eclipse]
           GroundTrack:  [1x1 matlabshared.satellitescenario.GroundTrack]
                 Orbit:  [1x1 matlabshared.satellitescenario.Orbit]
        CoordinateAxes:  [1x1 matlabshared.satellitescenario.CoordinateAxes]
       OrbitPropagator:  two-body-keplerian
           MarkerColor:  [0.059 1 1]
            MarkerSize:  6
             ShowLabel:  true
        LabelFontColor:  [1 1 1]
         LabelFontSize:  15
         Visual3DModel:  
    Visual3DModelScale:  1

gs

gs = 
  GroundStation with properties:

                 Name:  Ground station 1
                   ID:  1
             Latitude:  1.0381 degrees
            Longitude:  135.98 degrees
             Altitude:  0 meters
    MinElevationAngle:  0 degrees
       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:  [1x1 Aero.satellitescenario.Eclipse]
       CoordinateAxes:  [1x1 matlabshared.satellitescenario.CoordinateAxes]
          MarkerColor:  [1 0.4118 0.1608]
           MarkerSize:  6
            ShowLabel:  true
       LabelFontColor:  [1 1 1]
        LabelFontSize:  15

Calculate the eclipse intervals for both eclipse objects, specified as the vector [eclGs eclSat].

intvls = eclipseIntervals(eclSat)

intvls=12×9 table
        Asset         EclipsingBody      IntervalNumber         StartTime                EndTime           Duration    MinimumEclipseStatus    StartOrbit    EndOrbit
    _____________    ________________    ______________    ____________________    ____________________    ________    ____________________    __________    ________

    "Satellite 2"    "Earth"                    1          20-Apr-2023 01:17:50    20-Apr-2023 01:53:10      2120                  0               1            1    
    "Satellite 2"    "Moon"                     2          20-Apr-2023 02:43:30    20-Apr-2023 02:56:40       790            0.87839               1            2    
    "Satellite 2"    "Earth"                    3          20-Apr-2023 04:03:50    20-Apr-2023 04:39:10      2120                  0               2            2    
    "Satellite 2"    "Moon"                     4          20-Apr-2023 05:53:50    20-Apr-2023 06:49:40      3350            0.17465               3            3    
    "Satellite 2"    "Earth and Moon"           5          20-Apr-2023 06:49:40    20-Apr-2023 06:51:20       100                  0               3            3    
    "Satellite 2"    "Earth"                    6          20-Apr-2023 06:51:20    20-Apr-2023 07:25:00      2020                  0               3            3    
    "Satellite 2"    "Earth"                    7          20-Apr-2023 09:35:40    20-Apr-2023 10:11:00      2120                  0               4            4    
    "Satellite 2"    "Earth"                    8          20-Apr-2023 12:21:30    20-Apr-2023 12:56:50      2120                  0               5            5    
    "Satellite 2"    "Earth"                    9          20-Apr-2023 15:07:30    20-Apr-2023 15:42:50      2120                  0               6            6    
    "Satellite 2"    "Earth"                   10          20-Apr-2023 17:53:20    20-Apr-2023 18:28:40      2120                  0               7            7    
    "Satellite 2"    "Earth"                   11          20-Apr-2023 20:39:20    20-Apr-2023 21:14:40      2120                  0               8            8    
    "Satellite 2"    "Earth"                   12          20-Apr-2023 23:25:10    21-Apr-2023 00:00:00      2090                  0               9            9    

Input Arguments

asset — Satellite or ground station

vector | scalar

Satellite, GroundStation, or Platform object, specified as a scalar or vector. These objects must belong to the same satelliteScenario object. The function adds the eclipse analysis object to the Eclipse property of the corresponding asset in asset.

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'EclipseModel=dual-cone'

EclipseModel — Eclipse model

dual-cone (default) | cylindrical

Eclipse model to calculate solar occultation as observed from the position of the parent asset, specified as

• dual-cone — Fraction can be 0.0 (Umbra), between 0.0 and 1.0 (Penumbra or Antumbra), or 1.0 (Sunlight).

• cylindrical — Fraction can be 0.0 (Umbra) or 1.0 (Sunlight). - Region can be 0 (Umbra) or 1 (Sunlight).

  - Region can be 0 (Umbra), 1 (Sunlight), 2 (Penumbra), or 3 (Antumbra).

Example: 'EclipseModel=dual-cone'

Data Types: char | string

IncludeLunarEclipse — Lunar eclipse

false or 0 (default) | true or 1

To enable lunar eclipse for eclipse calculation, set this value true. Otherwise, set it to false.

Example: 'IncludeLunarEclipse=false'

Data Types: logical

Output Arguments

ecl — Eclipse objects

scalar | vector

Eclipse objects, returned as a scalar or vector.

Limitations

• When the AutoSimulate property of the satellite scenario is false, you can call eclipse only when SimulationStatus is NotStarted. Otherwise, you must call the restart function to reset SimulationStatus to NotStarted. Calling restart removes the simulation data.

• The function ignores:

  • Atmospheric refractions.

  • Sunlight transit time delays.

• The function assumes Earth, Moon, and Sun possess spherical geometries, with radii equal to their equatorial radii.

• When the value of EclipsingBody from the solar occultation interval table is Earth and Moon, the predicted value of MinimumEclipseStatus is lower than the actual value.

Version History

Introduced in R2023b