| Earth Observation Mission CFI Software Usage Guide for Object Oriented Software |

# VISIBILITY CALCULATION

The Earth Observation CFI Visibility library contains a set of classes and methods to compute the time intervals in which a satellite instrument has visiblity of:

- an Earth zone
- a ground station
- a data relay satellite (DRS)
- a star

The visibility is computed for an orbit interval requested by the user.

The following list details the possibilities to follow for computing the visibility segments:

1. For Earth Zones (one or more):

   - Initialise the Swath and SwathId objects
   - Initialize an object of type AttitudeDef if you want to use an attitude different from the one defined in the swath definition
   - Create an object of type ZoneInfoList with the zone or zones. Note: it can be used a zone file or ZoneRec objects.
   - Get the visibility for a zone defined in a file with Swath::zoneVisTimeCompute

2. For Ground Stations (one or more):

   - Initialise the Swath and SwathId objects
   - Initialize an object of type AttitudeDef if you want to use an attitude different from the one defined in the swath definition
   - Create an object of type StationInfoList with the zone or zones. Note: it can be used a zone file or StationRec objects.
   - Get the visibility for a zone defined in a file with Swath::stationVisTimeCompute

3. For Starcrafts:

   - For source and target satellites, you must initialize OrbitId with the orbital information and the attitude frames objects (SatNomTransId, SatTransId and InstrTransId)
   - Initialize an object of type LinkData with the source satellite masks and minimum link altitude
   - Get the visibility for the Starcraft with the method scVisTime.

4. Star Visibility:

   - Construct an object of the SwathStar class defined in the CFI Visibility library. The object can be created with the empty constructor and then call the set method or it can be directly created using the constructor with the parameters. The SwathStar needs as inputs the OrbitId and the upper and the lower swath file names.

   - Get the visibility with one of the method starVisTime. One method takes the star from the input star database file and the star name. The second method takes the star data directly from the input parameters.

Finally, the visibility segments are returned in a VisibilityList object that is is a list of VisibilitySegment. A VisibilitySegment is a TimeSegment plus an extra information about the segment. That information depends on the way in which the segment was computed. To retrieve the extra information, it has to be called to the suitable method of VisibilitySegment. The following table shows the type of extra information that can be retrieved:

Visibility method | Extra Info Class | VisibilitySegment method to retrieve the info
zoneVisTimeCompute | ZoneExtraInfo | getZoneExtraInfo
stationVisTimeCompute | StationExtraInfo | getStationExtraInfo
mapping | MappingExtraInfo | getMappingExtraInfo
starVisTime | StarExtraInfo | getStarExtraInfo

## Example

The followin example shows how to get the zone visibility segments and how to retrieve the info from the segment list. Note that other visibility functions work in a similar way ( the example provided with the installation packages provides a more complete example). Note the following steps in the computation:

- TimeCorrelation, Model initialisation...
- Orbit Initialisation
- Swath constructor
- Visibility computation
- Getting extra info from the time segments

    // ------------------------------------------------------------------------
    //
    //                           JAVA Example Program.
    //                           VISIBILITY CALCULATIONS
    //
    // ------------------------------------------------------------------------

    import EECFI.*;

    import java.util.Vector;
    import java.lang.String;
    import java.lang.Long;

    // Main program
    public class Example
    {
      public static void main(String[] args)
      {

        //-------------------------------------------------
        // Put all the code inside try-catch statements
        //  so, if something fails, an exception is thrown
        //-------------------------------------------------
        try
        {

          // ------------------------------------------------------------------------
          // Satellite Id, ModelId and TimeCorrelatins initialization
          // ------------------------------------------------------------------------

          SatId satId = new SatId(XPCFI_SAT_ENVISAT);

          ModelId          modelId = new ModelId(); //Do nothing: using default models.

          double[] initTime = new double[4];

          initTime[0]   = -245.1000000000000000;   // TAI time [days]
          initTime[1]   = -245.0995949074074074;   // UTC time [days] (= TAI - 35.0 s)
          initTime[2]   = -245.0995879629629630;   // UT1 time [days] (= TAI - 35.6 s)
          initTime[3]   = -245.0997800925925926;   // GPS time [days] (= TAI - 19.0 s)

          TimeCorrelation  timeId = new TimeCorrelation( initTime );

          // ------------------------------------------------------------------------
          // Initialise orbit Id
          // ------------------------------------------------------------------------

          double time0, time1;
          long orbit0, orbit1;

          Vector<String> inputFiles = new String();

          long orbitMode    = XOCFI_ORBIT_INIT_OSF_MODE;
          long timeInitMode = XOCFI_SEL_FILE;
          long timeRef      = XOCFI_TIME_UTC;

          inputFiles.addElement( "./data/OSF.EEF" );

          OrbitId orbitId = new OrbitId( satId, modelId, timeId, timeRef, orbitMode,
                           inputFiles, timeInitMode, time0, time1, orbit0, orbit1 );

          // ------------------------------------------------------------------------
          // Initialization of SwathId object (With Swath Definition file)
          // ------------------------------------------------------------------------
          AtmosId atmosId = new AtmosId();

          SwathInfo swathInfo = new SwathInfo();
          String swathTempFile = new String("./RA_2___501_.N1");

          swathInfo.type = XVCFI_FILE_STF;
          swathInfo.filename = swathTempFile;
          SwathId swathId = new SwathId(atmosId, swathInfo);

          Swath swathTemp = new Swath( orbitId, swathTempFile );

          // ------------------------------------------------------------------------
          // Obtain zone visibility segments
          // ------------------------------------------------------------------------
          VisibilityList visList;

          String zoneDBFile  = new String("./ZONE_DB");
          String zoneId      = new String("ZANA____");

          AttitudeDef attDef = new AttitudeDef();

          SwathId swathId = new SwathId();

          VisTime startTime= new VisTime(XVCFI_ORBIT_TYPE, 0., 1800, 0, 0);
          VisTime stopTime = new VisTime(XVCFI_ORBIT_TYPE,  0., 2300, 0, 0);

          VisTimeInterval searchInterval = new VisTimeInterval(startTime, stopTime);

          ZoneInfo zoneInfo = new ZoneInfo();
          zoneInfo.zoneId = zoneId;
          zoneInfo.type = XVCFI_USE_ZONE_DB_FILE;
          zoneInfo.zoneDBFilename = zoneDBFile;
          zoneInfo.projection = XDCFI_GNOMONIC;
          zoneInfo.minDuration = 0.;

          ZoneInfoList zoneInfoList = new ZoneInfoList();
          zoneInfoList.calcFlag = XVCFI_COMPUTE;
          zoneInfoList.zoneInfo.addElement(zoneInfo);

          visList = swathTemp.zoneVisTimeCompute( attDef, swathId, zoneInfoList, searchInterval);

          // Show the last segment
          VisibilitySegment  lastSegment = visList.segments.elementAt[(int)visList.size()-1];
          System.out.println( "\tNumber of segments found for zone "
               + zoneId + " = "
               + visList.size() );
          System.out.println( "\tSegment " + visList.size() + ": ( "
               + lastSegment.start.orbit        + ", "
               + lastSegment.start.seconds      + ", "
               + lastSegment.start.microseconds + " ) -> ( "
               + lastSegment.stop.orbit         + ", "
               + lastSegment.stop.seconds       + ", "
               + lastSegment.stop.microseconds + " )" );

          // ------------------------------------------------------------------------
          // Obtain zone visibility segments extra information, coverage for zoneVisTime
          // ------------------------------------------------------------------------
          ZoneExtraInfo zoneExtra;
          Vector<Long> covVec = new Vector<Long>();

          for (long i = 0 ; i < visList.size(); i++ )
          {
            zoneExtra = visList[i].getZoneExtraInfo();
            covVec.addElement( zoneExtra.coverage );
          }

          System.out.println( "\tCoverage for segment " + visList.size()
               + " = " + covVec[covVec.size()-1] );

          // Empty list
          visList.segments.clear();

        }
        //end try

        catch (CfiError cfiError)
        {
          //If an exception is thrown, there have been errors during execution
          Vector<String> errorMessages = new Vector<String>();

          // Get error messages
          errorMessages = cfiError.getMsg(errorMessages);

          // Pring Error messages
          for (int i = 0; i < errorMessages.size(); i++)
          {
            System.out.println( errorMessages.elementAt(i) );
          }
        }

      }

    }