Accessing Data in an Ephemeris

Once an Ephemeris object has been configured appropriately and contains data, that data can be accessed in a variety of ways.

General Ephemeris Data

This section deals with retrieving data from an Ephemeris object for all ephemeris formats, including version 1 of the FreeFlyer ephemeris format. Versions 2 and higher of the FreeFlyer ephemeris format have special interfaces that can be used and extra data that can be retrieved, all discussed later in this guide.

Vector Information

Vector-specific information can be retrieved from an Ephemeris object, including the current vector index and the values contained in that vector, as shown in the syntax examples below:

index = myEphem.CurrentIndex; //Returns the current index of the Ephemeris

Report index, myEphem.GetVectorData(index); //Returns the Array of data contained in the vector at the given index

Ephemeris Information

Header information can also be queried from an Ephemeris object. This includes the number of states in the ephemeris, the time span of the ephemeris, the next and previous epochs in the ephemeris around the Ephemeris.CurrentIndex. Syntax examples are provided below:

numVectors = myEphem.LoadEphemeris("SampleEphemeris.ephem"); //LoadEphemeris returns the number of ephemeris states in the file

numVectors = myEphem.NumberOfVectors; //The NumberOfVectors property of the Ephemeris object will return the same after loading

startEpoch = myEphem.StartEpoch; //The first epoch in the ephemeris

endEpoch = myEphem.EndEpoch; //The last epoch in the ephemeris

nextEpoch = myEphem.NextEpoch; //The next epoch after the current vector in the ephemeris

priorEpoch = myEphem.PriorEpoch; //The prior epoch before the current vector in the ephemeris

FreeFlyer Ephemeris Format-Specific Data

FreeFlyer provides additional interfaces to allow users to access additional information in FreeFlyer ephemeris formatted files. These extra interfaces include discontinuity information, customized column details (corresponding to the TITLE section of the ephemeris), and vector comments. These interfaces are located in the FFEphemProperties child object of the Ephemeris object. Below is the script necessary to access this child object:

myEphem.FFEphemProperties

Discontinuity Data

Discontinuities are modeled in the FreeFlyer ephemeris format with vectors that contain a pre- and post-discontinuity state. Discontinuities cannot be interpolated across, and instead must have states on both sides of the discontinuity to model the Spacecraft state. In many cases discontinuities are used to represent changes to a Spacecraft's state due to orbital events like maneuvers. Because each column in the FreeFlyer ephemeris format can be interpolated independent of the others, any subset of columns may marked with a discontinuity at a given epoch. This means that the marked columns cannot be interpolated across the discontinuity, but other columns could still be interpolated across that epoch since they are not discontinuous.

See the discontinuities section of the FreeFlyer Ephemeris File documentation for a full discussion of how to mark and use discontinuities in the format. Below are examples of how to access the discontinuity data in a FreeFlyer ephemeris.

Report myEphem.GetVectorData(rowIndex, 0 /*0 = Before, 1 = After Discontinuity*/); //Returns discontinuous vector data

Report myEphem.GetInterpolatedVectorData(epoch); //Returns vector data interpolated to the specified epoch

Report myEphem.GetInterpolatedVectorData(epoch, colIndicesArray); //Returns vector data interpolated to the specified epoch only for columns with specified indices

Report myEphem.GetInterpolatedVectorData(epoch, colLabelStrArray); //Returns vector data interpolated to the specified epoch only for columns with specified labels

Alias ffEphem = myEphem.FFEphemProperties; //This alias lets us shorten the following lines of script

Report ffEphem.IsVectorDiscontinuous(rowIndex); //Returns 1 if the vector at rowIndex has any discontinuities

Report ffEphem.IsVectorDiscontinuous(rowIndex, colIndex); //Returns 1 if the vector at rowIndex has a discontinuity in the column with specified index

Report ffEphem.IsVectorDiscontinuous(rowIndex, colIndicesArray); //Returns 1 if the vector at rowIndex has a discontinuity in any of the columns with specified indices

Report ffEphem.IsVectorDiscontinuous(rowIndex, "Column Label"); //Returns 1 if the vector at rowIndex has a discontinuity in the column with specified label

Report ffEphem.IsVectorDiscontinuous(rowIndex, colLabelStrArray); //Returns 1 if the vector at rowIndex has a discontinuity in any of the columns with specified labels

Report ffEphem.DiscontinuousVectors; //Returns an array of vector indices for vectors with discontinuities

Report ffEphem.DiscontinuityDelimiter; //This property allows you to set and get the delimiter between discontinuous states in the ephemeris

ffEphem.DiscontinuityStepBehavior = 1; //Specifies the behavior for which state of a discontinuous vector is loaded into a Spacecraft when it is stepped to that vector

Column Information

FreeFlyer has the ability to add and remove custom columns using the FreeFlyer ephemeris format, and so it becomes important to be able to easily manage those custom columns. The user can access column information including the column labels, unit labels, interpolators, and mapped Spacecraft properties, as shown in the syntax example below.

Report myEphem.FFEphemProperties.ColumnDelimiter; //This property allows you to set and get the delimiter between columns in the ephemeris

Report myEphem.FFEphemProperties.ColumnInterpolators; //This property allows you to set and get the interpolators for the ephemeris columns

Report myEphem.FFEphemProperties.ColumnLabels; //This property allows you to set and get the labels for the ephemeris columns

Report myEphem.FFEphemProperties.ColumnSpacecraftProperties; //This property allows you to set and get the mapped properties for the ephemeris columns

Report myEphem.FFEphemProperties.ColumnUnitLabels; //This property allows you to set and get the unit labels for the ephemeris columns

Vector Comments

Vector comments in the FreeFlyer ephemeris format are either set by the Put command itself or through the SetVectorComment method, but can also be retrieved from ephemeris files that are loaded in through the following syntax.

Report myEphem.FFEphemProperties.GetVectorComment(index);

EphemerisVector Object

The EphemerisVector object allows for convenient handling of multiple different object types in the FreeFlyer ephemeris format's columns, including String objects, Variable objects, and TimeSpan objects. This is necessary to take advantage of these different column object types in version 3 of the FreeFlyer ephemeris format, but it is also convenient for other ephemeris formats in a limited capacity based on what that format supports.

Using an EphemerisVector

The EphemerisVector object can be created directly in FreeFlyer script or accessed from an Ephemeris object when you retrieve a full vector from it at a given index. EphemerisVector objects are, by design, always associated to a specific ephemeris, and can even be handled and then added to the Ephemeris without the need for the Put command. Many of these interfaces are demonstrated in the FreeFlyer script examples below, where an Ephemeris object is loaded into the EphemerisVector and then the new EphemerisVector is set into the Ephemeris object itself using the Ephemeris.SetVectorData method.

Ephemeris myEphem;

myEphem.LoadEphemeris("SampleEphemeris.ephem");

EphemerisVector ephemVec(myEphem); //By using this constructor, the EphemerisVector is initialized with our ephemeris's column details

ephemVec.InitializeColumns(myEphem); //If we used an empty constructor we could initialize the EphemerisVector's columns here

ephemVec.Epoch = mySpacecraft.Epoch;

ephemVec.SetStringValue("SomeStringColumnLabel", "Value"); //Set a String value to a String column

ephemVec.SetVariableValue("SomeVariableColumnLabel", someValue); //Set a Variable value to a Variable column

ephemVec.SetTimeSpanValue("SomeTimeSpanColumnLabel", TimeSpan.FromDays(2)); //Set a TimeSpan value to a TimeSpan column

ephemVec.Comment = "Some Comment";

myEphem.SetVectorData(index, ephemVec); //Set the EphemerisVector into the Ephemeris object at a given index

The Ephemeris.AddVectorData method can also be used to set data at the end of an Ephemeris or at a specified epoch in the form of an EphemerisVector, Spacecraft state, or Array.

Array scState = {mySpacecraft.Position, mySpacecraft.Velocity};

myEphem.AddVectorData(ephemVec); //Adds the data contained in the EphemerisVector ephemVec to the Ephemeris

myEphem.AddVectorData(mySpacecraft); //Adds the state data for mySpacecraft to the Ephemeris

myEphem.AddVectorData(mySpacecraft.Epoch, scState); //Adds the position and velocity data contained in the Array scState at the given epoch

The EphemerisVector.InitializeColumns method, as shown above, can also be used repeatedly to associate a new Ephemeris object to the EphemerisVector. In doing this, you can reuse an EphemerisVector throughout a Mission Plan.

Getting an EphemerisVector

The other primary use-case for the EphemerisVector object is to get data from the Ephemeris and report and handle it with ease. The following script example showcases doing just that.

Ephemeris myEphem;

myEphem.LoadEphemeris("SampleEphemeris.ephem");

EphemerisVector ephemVec; //We use this constructor because we'll initialize it from the Ephemeris's data

ephemVec = myEphem.GetFullVectorData(index);

Report ephemVec.Epoch;

Report ephemVec.GetStringValue("SomeStringColumnLabel"); //Returns a String value for a particular column

Report ephemVec.GetVariableValue("SomeVariableColumnLabel"); //Returns a Variable value for a particular column

Report ephemVec.GetTimeSpanValue("SomeTimeSpanColumnLabel"); //Returns a TimeSpan value for a particular column

Report ephemVec.Comment;

Note: If the EphemerisVector object's column details do not match the column details of the Ephemeris to which it is being added, FreeFlyer will throw a runtime error.