| Earth Observation Mission CFI Software Visibility Software User Manual |

Public Member Functions

# EECFI::SwathStar Class Reference

Class to make operations involving a swath for star visibility. More...

Inheritance diagram for EECFI::SwathStar:

List of all members.

## Public Member Functions
| SwathStar ()
| Empty Class constructor.
| SwathStar (const OrbitId &orbitId, string swathFileUpper, string swathFileLower) throw (CfiError)
| Class constructor with parameters, for star visibility with STF file.
| SwathStar (const OrbitId &orbitId, long orbitNum, string swathFileUpper, string swathFileLower) throw (CfiError)
| Class constructor with parameters, for star visibility, with SDF file.
| ~SwathStar () throw (CfiError)
| Class destructor.
void | set (const OrbitId &orbitId, string swathFileUpper, string swathFileLower) throw (CfiError)
| Set values of parameters, for star visibility, with STF file.
void | set (const OrbitId &orbitId, long orbitNum, string swathFileUpper, string swathFileLower) throw (CfiError)
| Set values of parameters, for star visibility, with SDF file.
VisibilityList | starVisTime (long startOrbit, long stopOrbit, string starId, string starDBFile, double minDuration, double &starRaDeg, double &starDecDeg) throw (CfiError)
| Calculate the visibility segments for which a star is visible from the satellite using a star database.
VisibilityList | starVisTime (long startOrbit, long stopOrbit, double starRa, double starDec, double minDuration, double &starRaDeg, double &starDecDeg) throw (CfiError)
| Calculate the visibility segments for which a star is visible from the satellite using the Right ascension and declination of a star.

## Detailed Description

Class to make operations involving a swath for star visibility.

## Constructor & Destructor Documentation

EECFI::SwathStar::SwathStar | ( |  | ) |

Empty Class constructor.

EECFI::SwathStar::SwathStar | ( | const OrbitId & | orbitId,
|  | string | swathFileUpper,
|  | string | swathFileLower |
| ) |  |  | throw (CfiError)

Class constructor with parameters, for star visibility with STF file.

Parameters:

  | orbitId | Orbit Id.
  | swathFileUpper | File name of the inertial swath-file for the appropiate instrument mode, which defines the upper limit of the FOV.
  | swathFileLower | File name of the inertial swath-file for the appropiate instrument mode, which defines the lower limit of the FOV.

EECFI::SwathStar::SwathStar | ( | const OrbitId & | orbitId,
|  | long | orbitNum,
|  | string | swathFileUpper,
|  | string | swathFileLower |
| ) |  |  | throw (CfiError)

Class constructor with parameters, for star visibility, with SDF file.

Parameters:

  | orbitId | Orbit Id.
  | orbitNum | Swath points are generated every "orbitNum" orbits.
  | swathFileUpper | File name of the inertial swath-file for the appropiate instrument mode, which defines the upper limit of the FOV.
  | swathFileLower | File name of the inertial swath-file for the appropiate instrument mode, which defines the lower limit of the FOV.

EECFI::SwathStar::~SwathStar | ( |  | ) | throw (CfiError)

Class destructor.

## Member Function Documentation

void EECFI::SwathStar::set | ( | const OrbitId & | orbitId,
|  | string | swathFileUpper,
|  | string | swathFileLower |
| ) |  |  | throw (CfiError)

Set values of parameters, for star visibility, with STF file.

Parameters:

  | orbitId | Orbit Id.
  | swathFileUpper | File name of the inertial swath-file for the appropiate instrument mode, which defines the upper limit of the FOV.
  | swathFileLower | File name of the inertial swath-file for the appropiate instrument mode, which defines the lower limit of the FOV.

void EECFI::SwathStar::set | ( | const OrbitId & | orbitId,
|  | long | orbitNum,
|  | string | swathFileUpper,
|  | string | swathFileLower |
| ) |  |  | throw (CfiError)

Set values of parameters, for star visibility, with SDF file.

Parameters:

  | orbitId | Orbit Id.
  | orbitNum | Swath points are generated every "orbitNum" orbits.
  | swathFileUpper | File name of the inertial swath-file for the appropiate instrument mode, which defines the upper limit of the FOV.
  | swathFileLower | File name of the inertial swath-file for the appropiate instrument mode, which defines the lower limit of the FOV.

References EECFI::CfiError::addMsg().

VisibilityList EECFI::SwathStar::starVisTime | ( | long | startOrbit,
|  | long | stopOrbit,
|  | string | starId,
|  | string | starDBFile,
|  | double | minDuration,
|  | double & | starRaDeg,
|  | double & | starDecDeg |
| ) |  |  | throw (CfiError)

Calculate the visibility segments for which a star is visible from the satellite using a star database.

# Overview

The SwathStar::starVisTime function computes stars visibility segments, the orbital segments for which a given star is visible with a given instrument from the satellite.
An orbital segment is a time interval along the orbit, defined by start and stop times expressed as seconds elapsed since the ascending node crossing.
In addition, SwathStar::starVisTime calculates for every start and end of the visibility segment a coverage flag, determining which side of the FOV the event took place.
SwathStar::starVisTime requires access to several data structures and files to produce its results:

- the orbitId (OrbitId class) providing the orbital data. The orbitId can be initialized with the following data or files, also for precise propagation if applicable (see [ORBIT_SUM]):
  - data for an orbital change
  - Orbit scenario files
  - Predicted orbit files
  - Orbit Event Files
  - Restituted orbit files
  - DORIS Preliminary orbit files
  - DORIS Navigator files
  - TLE files
- Two Inertial Reference Swath Files. The Swath data can be provided by:
  - A swath template file produced off-line by the EO_VISIBILITY library (Swath::genSwath function).
  - A swath definition file, describing the swath geometry. In this case the SwathStar::starVisTime generates the swath points for a number of orbits given by the user.
- (Optional) The Star’s Database File, describing the location in right ascension and declination of a star, described by its corresponding identifier.

The time intervals used by SwathStar::starVisTime are expressed in absolute orbit numbers. To transform from relative to absolute orbits, RelANXTime::toAbsolute can be used. This is valid for both:

- input parameter "Orbit Range": first and last orbit to be considered.
- output parameter "Data Relay Satellite Visibility Segments": time segments with time expressed as {absolute orbit number, number of seconds since ANX, number of microseconds}

The output segments will be ordered chronologically.
Users who need to use processing times must make use of the conversion routines provided in EO_ORBIT ANXTime class (ANXTime::timeToOrbit and ANXTime::orbitToTime methods).

# Swath Definition

SwathStar::starVisTime calculates stars visibility segments for FOV corresponding to limb-sounding instruments observing inertial objects. The corresponding template files are generated off-line by the EO_VISIBILITY CFI software (Swath::genSwath function).

## Inertial Swaths

The FOV for a Limb-sounding instrument observing inertial objects is calculated using two main parameters.

- The FOV projection on the celestial sphere is determined by two set of swaths, one corresponding to a higher (TOP) and a lower (BOTTOM) altitude over the ellipsoid, hence defining the elevation range of the FOV
- The azimuth range is defined as such, the extremes corresponding to the left and right sides. In addition Swath::genSwath generates coordinates for a middle point

The instantaneous FOV projected on the celestial sphere can be represented as a series of points defined by their Right Ascension and Declination coordinates.
The top and bottom lines sweep the azimuth range at a constant tangent altitude, whilst the left and right side have a constant azimuth value with changing tangent altitude.
The shape of FOV should be similar to that shown in the diagram below with the dotted lines, whilst the algorithm implemented in SwathStar::starVisTime uses a simplified model joining the points with straight line.
As the satellite evolves around the orbit and the FOV sweeps the celestial sphere, a star can enter the FOV. SwathStar::starVisTime calculates that time and returns a flag indicating which part of the FOV (LEFT, TOP, RIGHT or BOTTOM) first detected the star. The same is done when the star exits the FOV.

## Splitting swaths

As it was shown in figure 11, the accuracy and precision of SwathStar::starVisTime strongly depends on how close the projection used in the algorithm is to the real world. Higher accuracy can be obtained splitting the azimuth range in sub-swaths.
Furthermore, splitting the swath would be necessary if the FOV was to cover an azimuth range larger than 180 degrees.
Note: It is important to note that if the FOV covers the value of 90 or 270 degrees in azimuth, one of the extremes (LEFT or RIGHT) of the STF must correspond to that azimuth value.

## Orbital Changes

If SwathStar::starVisTime is used with a range of orbits that includes an orbital change (e.g. change in the repeat cycle or cycle length), the behaviour depends on the swath files introduced as input:

- If swath template files are used, SwathStar::starVisTime automatically will ignore the orbits that do not correspond with the template files (i.e. no visibility segments will be generated for those orbits), since swath template files are generated from a reference orbit with a particular geometry, so they are not valid for a different geometry.
- If swath definition files are introduced, SwathStar::starVisTime will perform the computations across orbital changes, and will return the visibility segments corresponding to the whole orbital range. Internally, swath templates valid for every orbital change are generated to perform the calculations.

## Format of Swath Template File

If a swath template file with the variable header tags Start_Validity_Range and Stop_Validity_Range is used as input, only the segments belonging to that orbit range will be returned.

Parameters:

  | startOrbit | First absolute orbit, segment filter; segments will be filtered as from the beginning of first orbit. First Orbit for the orbit initialization will be used when absolute orbit is set to zero. Allowed range: =0; or >=start_osf.
  | stopOrbit | Last absolute orbit, segment filter. For orbitId initialized with orbital changes, when stopOrbit = 0 the stopOrbit will be set to the minimum value between: the last orbit within the orbital change of the start_orbit. startOrbit+cycle_length-1 (i.e. the input orbit range will be a complete cycle) Allowed range: =0; or >=start_osf.
  | starId | Identification of the star, as defined in starDBFile.
  | starDBFile | File name of the star database file.
  | minDuration | Minimum duration for segments; only segments with a duration longer than minDuration will be given as output [s]. Allowed range: >=0.
  | starRaDeg | [OUTPUT] Right Ascension of the star, in TOD, for the UTC halfway starOrbit and stopOrbit [deg].
  | starDecDeg | [OUTPUT] Declination of the star, in TOD, for the UTC halfway starOrbit and stopOrbit [deg]

Returns:
  Visibility segments..

VisibilityList EECFI::SwathStar::starVisTime | ( | long | startOrbit,
|  | long | stopOrbit,
|  | double | starRa,
|  | double | starDec,
|  | double | minDuration,
|  | double & | starRaDeg,
|  | double & | starDecDeg |
| ) |  |  | throw (CfiError)

Calculate the visibility segments for which a star is visible from the satellite using the Right ascension and declination of a star.

Parameters:

  | startOrbit | First absolute orbit, segment filter; segments will be filtered as from the beginning of first orbit. First Orbit for the orbit initialization will be used when absolute orbit is set to zero. Allowed range: =0; or >=start_osf.
  | stopOrbit | Last absolute orbit, segment filter. For orbitId initialized with orbital changes, when stopOrbit = 0 the stopOrbit will be set to the minimum value between: the last orbit within the orbital change of the start_orbit. startOrbit+cycle_length-1 (i.e. the input orbit range will be a complete cycle) Allowed range: =0; or >=start_osf.
  | starRa | Right ascension of star, in TOD. Only used if starDBFile is not equal to the empty string ("") [deg]. Allowed range: (-180., 180).
  | starDec | Declination of star, in TOD. Only used if starDBFile is not equal to the empty string ("") [deg]. Allowed range: (-90., 90).
  | minDuration | Minimum duration for segments; only segments with a duration longer than minDuration will be given as output [s]. Allowed range: >=0.
  | starRaDeg | [OUTPUT] Right Ascension of the star, in TOD, for the UTC halfway starOrbit and stopOrbit [deg].
  | starDecDeg | [OUTPUT] Declination of the star, in TOD, for the UTC halfway starOrbit and stopOrbit [deg]

Returns:
  Visibility segments.