Interval Methods

Top  Previous  Next

Interval Methods in FreeFlyer provide a means to precisely calculate the start and stop times of a specified event. The precise time for each event can be calculated to millisecond-level accuracy in Millisecond Mode Mission Plans, and to nanosecond-level accuracy in Nanosecond Mode Mission Plans. The accuracy does not depend on the spacecraft’s propagation step size. Three configuration settings are used to control the accuracy of the event times:


FF_Preferences.IntervalEventSkipAccuracy - Controls the minimum event duration for events that will not be skipped by the searching algorithm. The default value is 10 seconds, meaning that events shorter than 10 seconds may not be detected by default.

FF_Preferences.IntervalEventStopAccuracy - Controls the accuracy to which the time boundaries of events are resolved. The default value is 0.1 seconds, meaning that the start and end times of an event will be accurate to within 0.1 seconds by default.

FF_Preferences.IntervalEventReportingBehavior - Controls whether the start and end of propagation are reported as interval method events if an event is ongoing at the start or end of propagation.


There are interval methods available for calculating entry and exit from contact between spacecraft and other assets, passes through umbral and penumbral shadow, intersection times between a spacecraft and a Proximity Zone, and more. For a complete list of the Interval Methods available in FreeFlyer, see the List of Interval Methods in the Appendix. A summary of the available instantaneous and interval methods is presented on the Contact Method Summary page.


This page is divided into six sections:

1.Interval Methods Summary

2.Proper Syntax

3.Interval Method Example: Spacecraft.Access

4.Interval Method Example: Spacecraft.PassData

5.Interval Method Example: Spacecraft.ShadowTimes

6.Interval Method Example: VisibilityCalculator.VisibilityTimes


The following Sample Mission Plans (included with your FreeFlyer installation) demonstrate the use of interval methods:



Interval Methods Summary

There are two approaches to using interval methods:


1.String Version: If an interval method is reported out to a file, it generates a custom-formatted report containing pre-defined header, summary, and detailed data fields. The output of interval methods can be complex, as shown in the PassData section below. As such, each interval method should be reported to a separate file when using the String version of the interval method, and you should not include any other data in the same report. Additionally, you should not save the results of the string version of an interval method to a String object for subsequent parsing or manual reporting. When reporting the string directly to a file, FreeFlyer will close the file at the end of the Mission Plan execution or when you Close a ReportInterface and flush out any partial events that had been noted but not yet reported to the file. The example below shows how to generate a report file using the Spacecraft.ContactTimes() interval method:

Report Spacecraft1.ContactTimes(GroundStation1) to “ContactTimesReport.txt”;

The Spacecraft.Access and Spacecraft.PassData examples below also demonstrate this approach.


Note: If you wish to create a custom-formatted report in the Console, a DataTableWindow, or send results to a custom-formatted output file, you should use the Array version of the interval method.

2.Array Version: Interval methods can also be used to populate arrays with event data. The data in these arrays can then be used to perform further analysis within your Mission Plan or generate custom, user-defined reports. In this form, the interval method returns the number of events that have occurred from one execution of the line to the next (i.e., between each propagation step), and then stores any data about the event crossings in the provided arrays. This provides the ability to perform additional analysis of the state at the time of the event crossing. This example shows how to populate arrays with event times and event types using the ProximityZone.Intersects() interval method:


numEvents = ProximityZone1.Intersects(Spacecraft1, EventTimeArray, EventTypeArray, EventRangeArray);


The numEvents variable indicates the number of intersection entries/exits that occurred during the last propagation step – this variable can then be used to trigger further analysis on the event data in the arrays.


The Spacecraft.ShadowTimes and VisibilityCalculator.VisibilityTimes examples below also demonstrate this approach.


If an event starts before the beginning of the propagation span, FreeFlyer will label the start of the propagation as the start of the event by default. Likewise, if an event extends past the end of the propagation span, FreeFlyer labels the end of propagation as the end of the event when the interval method is reported using its String version. FreeFlyer does not propagate backward to find the start of an event that occurred before the start of the propagation span, or continue propagating after the end of the propagation span in order to find the end of an event. To prevent FreeFlyer from labeling the start or end of propagation as an event, use the FF_Preferences.IntervalEventReportingBehavior property.



Proper Syntax

Interval Methods are considered "Properties and Methods with a State," which means that FreeFlyer internally stores historical data when these methods are called. Although this functionality is very powerful, it is important to use it correctly. When using an interval method, it is important to call the method for every step of the analysis. So, for a typical analysis loop, you might have something like this. The Spacecraft.PassData interval method reports when a GroundStation can see a Spacecraft.


While (mySC.ElapsedTime < TIMESPAN(1 days));

     Report mySC.PassData(myGS) to "passData.Report";

     Step mySC;



Never use an interval method inside an If statement that checks the state of the event. For example, the Spacecraft.Contact instantaneous method can be used to report whether a GroundStation can see a Spacecraft, but the PassData interval method needs to be able to evaluate the times when contact is lost in order to accurately calculate the crossing time from AOS to LOS. If the call to PassData is placed inside this If statement (as shown in the following example), it would report incorrect results.


// Syntax shown as an example of what NOT to do

While (mySC.ElapsedTime < TIMESPAN(2 days));

 If (mySC.Contact(myGS));

         Report mySC.PassData(myGS) to "PassData.txt";


 Step mySC;



Interval Methods with Lists

You can use interval methods with Lists of objects. For example, you may want to loop through a List of GroundStations and report pass data between a Spacecraft and each GroundStation in the List, as shown in the example below. Each time the GroundStation argument passed to the PassData interval method is changed, FreeFlyer keeps track of this internally as a new state.


Variable i;

Spacecraft sc;

List<GroundStation> gsList;


gsList.Count = 3;


While (sc.ElapsedTime < TIMESPAN(1 days));

     For i = 0 to gsList.Count-1;

           Report sc.PassData(gsList[i]) to "PassDataReport.txt";


     Step sc;



Run "notepad.exe PassDataReport.txt";


Note: In millisecond timing precision mode, properties and methods with a state are automatically reset at the start of each iteration of a For loop; the "without reset" keywords must be used to prevent the state from being reset. This is necessary so that the historical data tracked within the interval method is not reset at the start of each iteration of the For loop. This is explained in further detail on the Properties and Methods with a State page.


While (sc.ElapsedDays < 1);

     For i = 0 to gsList.Count-1 without reset;

           Report sc.PassData(gsList[i]) to "PassDataReport.txt";


     Step sc;




Interval Method Example: Spacecraft.Access

The Spacecraft.Access Method returns the start time, end time, and duration of a Spacecraft's view of a Region, GroundStation, CelestialObject, or another Spacecraft.


In the example below, the first Report command, which generates "AccessReport.txt", calculates mySpacecraft's access to myGroundStation. The Access time is based on any active Sensors on the Spacecraft.


The second Report command shows how to use the Access method using only one of the Sensors on a Spacecraft that has multiple Sensors. The Report, generating "SensorReport.txt", calculates the access of mySpacecraft to the Sun, using only mySpacecraft.Sensors[0].


Spacecraft.Access Example


While (mySpacecraft.ElapsedTime < TIMESPAN(5 days));

     View mySpacecraft, myGroundStation<800>;

     Report mySpacecraft.Access(myGroundStation) to "AccessReport.txt";

     Report mySpacecraft.Access(Sun.BodyID, mySpacecraft.Sensors[0]) to "SensorReport.txt";

     Step mySpacecraft;



Output Excerpt from "AccessReport"


Access Event                             Entry Epoch                     Exit Epoch                     Duration(min)


myGroundStation --> mySpacecraft   Jan 01 2020 18:54:54.506835937   Jan 01 2020 18:56:25.986328125       1.524658203

myGroundStation --> mySpacecraft   Jan 02 2020 07:00:29.443359375   Jan 02 2020 07:03:27.788085937       2.972412109

myGroundStation --> mySpacecraft   Jan 03 2020 18:44:12.832031250   Jan 03 2020 18:46:47.885742187       2.584228516

myGroundStation --> mySpacecraft   Jan 04 2020 06:49:57.802734375   Jan 04 2020 06:51:57.260742187       1.990966797

myGroundStation --> mySpacecraft   Jan 05 2020 07:33:38.920898437   Jan 05 2020 07:35:16.040039062       1.618652344

myGroundStation --> mySpacecraft   Jan 05 2020 18:33:35.185546875   Jan 05 2020 18:36:39.975585937       3.079833984


Output Excerpt from "SensorReport"


Access Event                            Entry Epoch                     Exit Epoch                  Duration(min)


Sun --> mySpacecraft_Sensor1   Jan 01 2020 00:09:14.150390625   Jan 01 2020 00:20:14.428710937      11.004638672

Sun --> mySpacecraft_Sensor1   Jan 01 2020 01:48:10.576171875   Jan 01 2020 01:59:11.147460937      11.009521484

Sun --> mySpacecraft_Sensor1   Jan 01 2020 03:27:07.001953125   Jan 01 2020 03:38:07.719726562      11.011962891

Sun --> mySpacecraft_Sensor1   Jan 01 2020 05:06:03.354492187   Jan 01 2020 05:17:04.438476562      11.018066406



Interval Method Example: Spacecraft.PassData

The Spacecraft.PassData method provides detailed information on the contact between a GroundStation and a Spacecraft. For each contact period, the content of the information is presented in two parts, Summary and Detailed. The Summary, which is provided first, includes:


Acquisition of Signal (AOS)

Loss of Signal (LOS)

The duration of the contact

The maximum elevation of the contact


The Detailed section is presented in tabular form at the frequency of the propagation step size during the contact period, and provides:


The Epoch of the data point




Range Rate of the Spacecraft with respect to the GroundStation


Spacecraft.PassData Example


While (mySC.ElapsedTime().ToDays() < 1);

     Report mySC.PassData(myGS) to "passData.Report";
     Step mySC;


Output Excerpt


                                            Contact myGroundStation to mySpacecraft


          AOS                       LOS                            Duration(min)   MaxElevation(deg)

Jan 01 2020 06:19:55.825195312   Jan 01 2020 06:27:47.944335937      7.868652344      25.201605860


         Epoch                    Azimuth(deg)   Elevation(deg)     Range(km)      RangeRate(km/sec)

Jan 01 2020 06:19:55.825195312     41.435311272    10.003623663    2189.441030164    -5.386444260

Jan 01 2020 06:20:00.000000000     41.943987785    10.312267826    2167.031598449    -5.348902080

Jan 01 2020 06:25:00.000000000    118.954660392    23.022054964    1481.673470996     2.261181911

Jan 01 2020 06:27:47.944335937    152.504608539     9.997339828    2175.405126641     5.388411819


                                            Contact myGroundStation to mySpacecraft


          AOS                              LOS                      Duration(min)   MaxElevation(deg)

Jan 01 2020 07:57:38.129882812   Jan 01 2020 08:05:20.727539062       7.709960938      24.685316686


         Epoch                    Azimuth(deg)    Elevation(deg)     Range(km)      RangeRate(km/sec)

Jan 01 2020 07:57:38.129882812    343.201420121     10.003078374    2191.215989595    -5.420000590

Jan 01 2020 08:00:00.000000000    317.249113102     21.079710580    1565.522311510    -2.977750395

Jan 01 2020 08:05:00.000000000    238.233610780     11.569935717    2069.138821348     5.170478558

Jan 01 2020 08:05:20.727539062    235.574157873      9.996855882    2178.605866646     5.385971325



Interval Method Example: Spacecraft.ShadowTimes

The Spacecraft.ShadowTimes interval method returns the entry time, exit time, and duration of a Spacecraft's pass through the shadow of the spacecraft's central body. Events are reported for Penumbra, Umbra, or Annular shadow condition geometries.



In this example, the two-argument form of Spacecraft.ShadowTimes is used. This form provides the ability to perform additional analysis of the state at the time of the event crossing, such as calculation of mySpacecraft.Height. Similar syntax is used for the ShadowTimes, EarthShadowTimes, and MoonShadowTimes methods.


numEvents (variable) is the number of shadow events that occurred between the last Spacecraft step and the current Spacecraft step

EventTime (array) is the time that the event occurred

EventType (array) is the type of the event that occurred





Entry into Annular Shadow


Exit from Annular Shadow


Entry into Umbral Shadow


Exit from Umbral Shadow


Entry into Penumbral Shadow


Exit from Penumbral Shadow


ShadowTimes Example


Variable i;

Variable numEvents;


Array EventType;

TimeSpanArray EventTime;


While (mySpacecraft.ElapsedTime < TIMESPAN(1 days));


      View mySpacecraft;

      numEvents = mySpacecraft.ShadowTimes(EventTime, EventType);


      For i = 0 to numEvents-1;

            Step mySpacecraft to (mySpacecraft.Epoch == EventTime[i]);

            Report mySpacecraft.EpochText, mySpacecraft.Height, numEvents, EventTime[i].ConvertToCalendarDate(), EventType[i];



      Step mySpacecraft;



Output Excerpt






Jan 01 2020 00:06:53.232421875



Jan 01 2020 00:06:53.232421875


Jan 01 2020 00:07:03.193359375



Jan 01 2020 00:07:03.193359375


Jan 01 2020 01:11:50.815429687



Jan 01 2020 01:11:50.815429687


Jan 01 2020 01:12:00.703125000



Jan 01 2020 01:12:00.703125000


Jan 01 2020 01:45:49.877929687



Jan 01 2020 01:45:49.877929687



Interval Method Example: VisibilityCalculator.VisibilityTimes

The VisibilityCalculator.VisibilityTimes interval method returns the start and end times of visibility across any or all of the Segments associated with the VisibilityCalculator. Each Segment has a defined observer and target, and can be configured with user-specified occulting bodies, celestial object shape models, and refraction models. The example below shows how to compute the times when any of a set of three Sensors on a Spacecraft can see a particular GroundStation.


// Create the observers and target

GroundStation gs;

Spacecraft sc;





// Create the VisibilityCalculator and Segments

VisibilityCalculator VisibilityCalc;

VisibilityCalc.VisibilityRequirement = 1;  // Any






Variable i;

Variable numEvents;

TimeSpanArray EventTimes[0];

Array EventTypes[0];

StringArray EventTypeLabels = {"""Start of visibility""End of visibility"};


// Set up the Segments

For i = 0 to VisibilityCalc.Segments.Count-1;


      sc.Sensors[i].BoresightAngles[2] = i*20;







// Propagate and determine visibility times when *any* of the Sensors can see the GroundStation

While (sc.ElapsedTime < TIMESPAN(1 days));


      numEvents = VisibilityCalc.VisibilityTimes(sc.Epoch, EventTimes, EventTypes);


      For i = 0 to numEvents-1;        

            Report EventTimes[i].ConvertToCalendarDate(), EventTypeLabels[EventTypes[i]];



      View sc, gs;

      Step sc;



Output Excerpt




Jan 01 2020 02:05:02.197265625

Start of visibility

Jan 01 2020 02:17:37.763671875

End of visibility


Spacecraft with three Sensors calculating visibility to a GroundStation

Spacecraft with three Sensors calculating visibility to a GroundStation



See Also

List of Interval Methods

Contact Method Summary

Properties and Methods with a State