|
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.
See Also
|