StkEphemerisFile

java.lang.Object
- agi.foundation.stk.StkEphemerisFile

public class StkEphemerisFile
extends Object

Reads from and writes to STK ephemeris (.e) files. STK ephemeris files can express position, velocity, acceleration, and covariance information, and are useful for getting this type of data into and out of STK.

To read an STK ephemeris file, call the StkEphemerisFile.readFrom(String) method to read the data into memory, and then call the StkEphemerisFile.createPoint() method to create a time-varying Point representing the ephemeris data in the file. Similarly, call StkEphemerisFile.createCovarianceInterpolator() to obtain the Covariance3By3SizeAndOrientationInterpolator representing the covariance data in the file.

You can also build an StkEphemerisFile instance by calling the various configure... methods such as StkEphemerisFile.configureFromPointInterpolator(agi.foundation.geometry.PointInterpolator). Once you've built an appropriate StkEphemerisFile instance, you can save it to a file or another stream by calling StkEphemerisFile.writeTo(Writer).

The following example shows how to write an STK ephemeris (.e) file from a motion evaluator:

// Use any valid TLE to create a propagator, and use that propagator to create a MotionEvaluator.
TwoLineElementSet inputTwoLineElementSet = new TwoLineElementSet(
        "1 20813U 90084A   07157.52757149 -.00000978  00000-0  10000-3 0  8139" + 
        "2 20813  62.3585 177.5907 7234421 261.2958  18.3008  2.01001663122427");
Sgp4Propagator propagator = new Sgp4Propagator(inputTwoLineElementSet);
MotionEvaluator1<Cartesian> motionEvaluator = propagator.getEvaluator();

// Define start time, stop time, and time step that will be used to sample the motion evaluator for ephemeris data.
JulianDate startDate = new JulianDate(new GregorianDate(2007, 6, 1));
JulianDate stopDate = new JulianDate(new GregorianDate(2007, 6, 2));
Duration timeStep = Duration.fromSeconds(60);

// Using the MotionEvaluator created above, output ephemeris data in a format that can be processed by
// the StkEphemerisFile object. Passing null for the ITrackCalculationProgress indicates that the Evaluate step
// should not track progress.
DateMotionCollection1<Cartesian> rawEphemerisData = motionEvaluator.evaluate(startDate, stopDate, timeStep, 0, null);

// The data obtained from the MotionEvaluator is in meters.  Convert to desired units, kilometers in this case.
DateMotionCollection1<Cartesian> rawEphemerisDataKm = new DateMotionCollection1<>();
double toKilometers = 1.0 / 1000.0;
for (int i = 0; i < rawEphemerisData.getCount(); i++) {
    rawEphemerisDataKm.add(rawEphemerisData.getDates().get(i), 
            Cartesian.multiply(rawEphemerisData.getMotions().get(i).getValue(), toKilometers));
}

// Once the raw data has been obtained from the MotionEvaluator, place it into an StkEphemerisFile
// and specify the appropriate coordinate system.
StkEphemerisFile.EphemerisTimePos ephemerisData = new StkEphemerisFile.EphemerisTimePos();
ephemerisData.setCoordinateSystem(propagator.getReferenceFrame());
ephemerisData.setEphemerisData(rawEphemerisDataKm);
StkEphemerisFile ephemerisFile = new StkEphemerisFile();
ephemerisFile.setData(ephemerisData);

// Use the "Properties" element of the STKEphemerisFile to specify any additional supported properties 
// such as the distance unit of the data.
ephemerisFile.getProperties().put("DistanceUnit", "Kilometers");

// Finally, write the StkEphemerisFile out.
try (Writer ephemerisWriter = Files.newBufferedWriter(Paths.get(path), StandardCharsets.US_ASCII)) {
    ephemerisFile.writeTo(ephemerisWriter);
}

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`StkEphemerisFile.Covariance` The base class for covariance data.
`static class`	`StkEphemerisFile.CovarianceTimePos` A class that holds the covariance data in the ephemeris file when the ephemeris file is in the "CovarianceTimePos" format.
`static class`	`StkEphemerisFile.CovarianceTimePosVel` A class that holds the covariance data in the ephemeris file when the ephemeris file is in the "CovarianceTimePosVel" format.
`static class`	`StkEphemerisFile.DistanceUnit` The supported distance units of measure for ephemeris and covariance information.
`static class`	`StkEphemerisFile.Ephemeris` The base class for ephemeris data.
`static class`	`StkEphemerisFile.EphemerisLLATimePos` A class that holds the data in the ephemeris file when the ephemeris file is in the "EphemerisLLATimePos" format.
`static class`	`StkEphemerisFile.EphemerisLLATimePosVel` A class that holds the data in the ephemeris file when the ephemeris file is in the "EphemerisLLATimePosVel" format.
`static class`	`StkEphemerisFile.EphemerisLLRTimePos` A class that holds the data in the ephemeris file when the ephemeris file is in the "EphemerisLLRTimePos" format.
`static class`	`StkEphemerisFile.EphemerisLLRTimePosVel` A class that holds the data in the ephemeris file when the ephemeris file is in the "EphemerisLLRTimePosVel" format.
`static class`	`StkEphemerisFile.EphemerisTimePos` A class that holds the data in the ephemeris file when the ephemeris file is in the "EphemerisTimePos" format.
`static class`	`StkEphemerisFile.EphemerisTimePosVel` A class that holds the data in the ephemeris file when the ephemeris file is in the "EphemerisTimePosVel" format.
`static class`	`StkEphemerisFile.EphemerisTimePosVelAcc` A class that holds the data in the ephemeris file when the ephemeris file is in the "EphemerisTimePosVelAcc" format.
`static class`	`StkEphemerisFile.StkTimeFormat` The supported time formats for ephemeris and covariance information.

Constructor Summary

Constructors
Constructor and Description

StkEphemerisFile()
Initializes a new instance.

Constructors
Constructor and Description
`StkEphemerisFile()` Initializes a new instance.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`configureFromPoint(Point point, JulianDate start, JulianDate stop, Duration step, int order)` Configures this instance with values computed by sampling a `Point` over an interval with a fixed step.
`void`	`configureFromPointInterpolator(PointInterpolator pointInterpolator)` Configures the instance to represent the ephemeris and interpolation stored in a `PointInterpolator`.
`void`	`configureInterpolation(InterpolationAlgorithm interpolationAlgorithm, int interpolationDegree)` Configures the `Interpolator` (`get` / `set`) to use the specified interpolation algorithm and polynomial degree.
`Covariance3By3SizeAndOrientationInterpolator`	`createCovarianceInterpolator()` Creates a `Covariance3By3SizeAndOrientationInterpolator` for interpolating over the covariance data held by this instance.
`Point`	`createPoint()` Creates a `Point` whose time-varying position is computed by interpolating over the ephemeris data held by this instance.
`StkEphemerisFile.Covariance`	`getCovarianceData()` Gets the covariance data.
`StkEphemerisFile.Ephemeris`	`getData()` Gets the ephemeris data.
`Map<String,String>`	`getProperties()` Gets a dictionary of key and value pairs in the STK ephemeris file.
`Map<String,String>`	`getPropertiesWithUnsupportedValues()` Gets a dictionary of property names and values for the properties with values specified in the file that are not supported by the `StkEphemerisFile` reader.
`List<JulianDate>`	`getSegmentBoundaryTimes()` Gets the list of segment boundary times in the STK ephemeris file.
`Map<String,String>`	`getUnsupportedProperties()` Gets a dictionary of property names and values for the properties that are contained in the file but that are not supported by the `StkEphemerisFile` reader.
`StkEphemerisFileVersion`	`getVersion()` Gets the ephemeris file version.
`static StkEphemerisFile`	`readFrom(BufferedReader reader)` Reads an STK ephemeris (.e) file from a `BufferedReader`.
`static StkEphemerisFile`	`readFrom(BufferedReader reader, StkEphemerisFileOptions readOptions)` Reads an STK ephemeris (.e) file from a `BufferedReader`.
`static StkEphemerisFile`	`readFrom(String fileName)` Reads an STK ephemeris (.e) file from a specified file.
`static StkEphemerisFile`	`readFrom(String fileName, StkEphemerisFileOptions readOptions)` Reads an STK ephemeris (.e) file from a specified file.
`void`	`setCovarianceData(StkEphemerisFile.Covariance value)` Sets the covariance data.
`void`	`setData(StkEphemerisFile.Ephemeris value)` Sets the ephemeris data.
`void`	`setSegmentBoundaryTimes(List<JulianDate> value)` Sets the list of segment boundary times in the STK ephemeris file.
`void`	`setVersion(StkEphemerisFileVersion value)` Sets the ephemeris file version.
`void`	`writeTo(Writer writer)` Writes this instance to a `Writer` in the STK ephemeris file (.e) format.
`void`	`writeTo(Writer writer, boolean prettyPrinting)` Writes this instance to a `Writer` in the STK ephemeris file (.e) format.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - StkEphemerisFile
```
public StkEphemerisFile()
```
    Initializes a new instance.
- Method Detail
  - createPoint
```
@Nonnull
public final Point createPoint()
```
    Creates a Point whose time-varying position is computed by interpolating over the ephemeris data held by this instance.
    
    Returns:
    
    The point.
    
    Throws:
    
    PropertyInvalidException - Thrown when Data (get / set) is null.
  - createCovarianceInterpolator
```
public final Covariance3By3SizeAndOrientationInterpolator createCovarianceInterpolator()
```
    Creates a Covariance3By3SizeAndOrientationInterpolator for interpolating over the covariance data held by this instance.
    
    Returns:
    
    The interpolator.
    
    Throws:
    
    PropertyInvalidException - Thrown when CovarianceData (get / set) is null.
  - configureFromPointInterpolator
```
public final void configureFromPointInterpolator(@Nonnull
                                                 PointInterpolator pointInterpolator)
```
    Configures the instance to represent the ephemeris and interpolation stored in a PointInterpolator. The Data (get / set) property is replaced with a new instance of StkEphemerisFile.EphemerisTimePos, StkEphemerisFile.EphemerisTimePosVel, or StkEphemerisFile.EphemerisTimePosVelAcc (depending on the number of derivatives available from the PointInterpolator) and any existing information stored in that instance is lost. The Properties (get) are not modified, but values pulled from PointInterpolator will take precedence over values in the Properties (get) collection when writing this instance using StkEphemerisFile.writeTo(Writer).
    
    Parameters:
    
    pointInterpolator - The PointInterpolator with which to configure this instance. The point's Interpolator (get / set) and ReferenceFrame (get / set) properties, as well as the interpolator's Data (get / set) property, must not be null.
    
    Throws:
    
    ArgumentNullException - Thrown when pointInterpolator is null.
  - configureFromPoint
```
public final void configureFromPoint(@Nonnull
                                     Point point,
                                     @Nonnull
                                     JulianDate start,
                                     @Nonnull
                                     JulianDate stop,
                                     @Nonnull
                                     Duration step,
                                     int order)
```
    Configures this instance with values computed by sampling a Point over an interval with a fixed step. The Data (get / set) property is replaced with a new instance of StkEphemerisFile.EphemerisTimePos, StkEphemerisFile.EphemerisTimePosVel, or StkEphemerisFile.EphemerisTimePosVelAcc (depending on the value of the order property) and any existing information stored in that instance is lost. The Properties (get) are not modified, but values pulled from Point will take precedence over values in the Properties (get) collection when writing this instance using StkEphemerisFile.writeTo(Writer). The Interpolator (get / set) property is not configured, so you may want to call StkEphemerisFile.configureInterpolation(agi.foundation.numericalmethods.advanced.InterpolationAlgorithm, int) after calling this method.
    
    Parameters:
    
    point - The point from which to sample positions and optionally velocities and accelerations.
    
    start - The first date at which to sample the point.
    
    stop - The last date at which to sample the point.
    
    step - The step between successive samples. The duration between the second-to-last and last samples will be smaller than this step if the interval is not evenly disable by the step.
    
    order - The number of derivatives to include in the file. 0 includes position only, 1 also includes velocity, and 2 (or greater) also includes acceleration.
    
    Throws:
    
    ArgumentNullException - Thrown when point is null.
  - configureInterpolation
```
public final void configureInterpolation(InterpolationAlgorithm interpolationAlgorithm,
                                         int interpolationDegree)
```
    Configures the Interpolator (get / set) to use the specified interpolation algorithm and polynomial degree. The Data (get / set) property must be set before calling this method.
    
    Parameters:
    
    interpolationAlgorithm - The interpolation algorithm to use.
    
    interpolationDegree - The degree of the polynomial to use for interpolation.
    
    Throws:
    
    PropertyInvalidException - Thrown when Data (get / set) is null.
    
    ArgumentNullException - Thrown when interpolationAlgorithm is null.
    
    ArgumentException - Thrown when interpolationAlgorithm is not supported in STK ephemeris files.
  - getVersion
```
@Nonnull
public final StkEphemerisFileVersion getVersion()
```
    Gets the ephemeris file version.
  - setVersion
```
public final void setVersion(@Nonnull
                             StkEphemerisFileVersion value)
```
    Sets the ephemeris file version.
  - getData
```
public final StkEphemerisFile.Ephemeris getData()
```
    Gets the ephemeris data.
  - setData
```
public final void setData(StkEphemerisFile.Ephemeris value)
```
    Sets the ephemeris data.
  - getCovarianceData
```
public final StkEphemerisFile.Covariance getCovarianceData()
```
    Gets the covariance data.
  - setCovarianceData
```
public final void setCovarianceData(StkEphemerisFile.Covariance value)
```
    Sets the covariance data.
  - getProperties
```
@Nonnull
public final Map<String,String> getProperties()
```
    Gets a dictionary of key and value pairs in the STK ephemeris file. After an StkEphemerisFile is read, this dictionary contains all of the key and value pairs in the file. When writing an StkEphemerisFile, these properties are written back to the file, but only if another property does not offer an authoritative value. For example, if the CoordinateSystem (get / set) property is set, any "CoordinateSystem" property in this collection will be overwritten.
  - getUnsupportedProperties
```
@Nonnull
public final Map<String,String> getUnsupportedProperties()
```
    Gets a dictionary of property names and values for the properties that are contained in the file but that are not supported by the StkEphemerisFile reader. Any information contained in these properties may not be captured by the reader.
  - getPropertiesWithUnsupportedValues
```
@Nonnull
public final Map<String,String> getPropertiesWithUnsupportedValues()
```
    Gets a dictionary of property names and values for the properties with values specified in the file that are not supported by the StkEphemerisFile reader. Any information contained in these properties may not be captured by the reader.
  - getSegmentBoundaryTimes
```
public final List<JulianDate> getSegmentBoundaryTimes()
```
    Gets the list of segment boundary times in the STK ephemeris file. Segment boundary times are times that should not be interpolated over.
  - setSegmentBoundaryTimes
```
public final void setSegmentBoundaryTimes(List<JulianDate> value)
```
    Sets the list of segment boundary times in the STK ephemeris file. Segment boundary times are times that should not be interpolated over.
  - writeTo
```
public final void writeTo(Writer writer)
```
    Writes this instance to a Writer in the STK ephemeris file (.e) format. The Writer can be a OutputStreamWriter for writing to a file, a StringWriter for writing to a string, or any number of other types.
    
    Parameters:
    
    writer - The writer to which to write this instance.
    
    Throws:
    
    UnsupportedCaseException - Thrown when the ephemeris file is in an unknown format.
  - writeTo
```
public final void writeTo(Writer writer,
                          boolean prettyPrinting)
```
    Writes this instance to a Writer in the STK ephemeris file (.e) format. The Writer can be a OutputStreamWriter for writing to a file, a StringWriter for writing to a string, or any number of other types.
    
    Parameters:
    
    writer - The writer to which to write this instance.
    
    prettyPrinting - Whether or not the output should have pretty formatting.
    
    Throws:
    
    UnsupportedCaseException - Thrown when the ephemeris file is in an unknown format.
  - readFrom
```
@Nonnull
public static StkEphemerisFile readFrom(@Nonnull
                                                  String fileName)
```
    Reads an STK ephemeris (.e) file from a specified file. See the documentation of StkEphemerisFile.readFrom(BufferedReader,StkEphemerisFileOptions) for detailed information.
    
    Parameters:
    
    fileName - The name of the file from which to read the ephemeris.
    
    Returns:
    
    An StkEphemerisFile instance containing the read ephemeris file.
    
    Throws:
    
    InvalidDataException - Thrown when the STK ephemeris file is invalid or it contains unsupported properties or property values.
    
    ArgumentNullException - Thrown when fileName is null.
  - readFrom
```
@Nonnull
public static StkEphemerisFile readFrom(@Nonnull
                                                  String fileName,
                                                  StkEphemerisFileOptions readOptions)
```
    Reads an STK ephemeris (.e) file from a specified file. See the documentation of StkEphemerisFile.readFrom(BufferedReader,StkEphemerisFileOptions) for detailed information.
    
    Parameters:
    
    fileName - The name of the file from which to read the ephemeris.
    
    readOptions - An object containing any additional instructions for the read process.
    
    Returns:
    
    An StkEphemerisFile instance containing the read ephemeris file.
    
    Throws:
    
    InvalidDataException - Thrown when the STK ephemeris file is invalid or it contains unsupported properties or property values.
    
    ArgumentNullException - Thrown when fileName is null.
  - readFrom
```
@Nonnull
public static StkEphemerisFile readFrom(@Nonnull
                                                  BufferedReader reader)
```
    Reads an STK ephemeris (.e) file from a BufferedReader. The BufferedReader can be a BufferedReader for reading from a file, a BufferedReader for reading from a string, or any number of other types. See the documentation of StkEphemerisFile.readFrom(BufferedReader,StkEphemerisFileOptions) for detailed information.
    
    Parameters:
    
    reader - The reader from which to read the ephemeris.
    
    Returns:
    
    An StkEphemerisFile instance containing the read ephemeris file.
    
    Throws:
    
    InvalidDataException - Thrown when the STK ephemeris file is invalid or it contains unsupported properties or property values.
    
    ArgumentNullException - Thrown when reader is null.
  - readFrom
```
@Nonnull
public static StkEphemerisFile readFrom(@Nonnull
                                                  BufferedReader reader,
                                                  StkEphemerisFileOptions readOptions)
```
    Reads an STK ephemeris (.e) file from a BufferedReader. The BufferedReader can be a BufferedReader for reading from a file, a BufferedReader for reading from a string, or any number of other types.
    
    The STK ephemeris file format is a mix of well-defined, unambiguous properties, and fairly STK-specific properties that are difficult to interpret outside of the context of STK. For example, the "CoordinateSystem" property can specify any coordinate system that is known to STK's Vector Geometry Tool in the current scenario. In the general case, it's impossible to determine from the ephemeris file itself, in the absence of an STK scenario, what that coordinate system actually means. As a result, this method should be considered a "best effort" that works well in most common cases, but that may have problems with certain ephemeris files.
    
    By default, when this method does not understand a property or property value read from the file, it will throw an InvalidDataException describing the problem. You can attempt to read files with unsupported properties or property values setting the IgnoreUnsupportedProperties (get / set) and IgnorePropertiesWithUnsupportedValues (get / set) properties of the StkEphemerisFileOptions passed to this method to true. With these properties set, unsupported properties and property values will be added to the UnsupportedProperties (get) and PropertiesWithUnsupportedValues (get) dictionaries, respectively, and the reader can make no guarantees that its results will match STK.
    
    Here are the known limitations, compared to STK, when reading an ephemeris file using this method:
    - Only the following properties are supported: NumberOfEphemerisPoints, NumberOfCovariancePoints, ScenarioEpoch, CoordinateSystemEpoch, CoordinateSystem, DistanceUnit, CentralBody, InterpolationMethod, InterpolationOrder, InterpolationSamplesM1, BlockingFactor (ignored), TimeFormat, and CovarianceFormat.
    - Only the following CentralBody values are supported: Earth, Sun, and Moon.
    - When the CentralBody is Earth, only the following CoordinateSystem values are supported: ICRF, J2000, Inertial, Fixed, TrueOfDate, TrueOfEpoch, MeanOfDate, MeanOfEpoch, TEMEOfDate, and TEMEOfEpoch.
    - When the CentralBody is Sun or Moon, only the following CoordinateSystem values are supported: Inertial and Fixed.
    - Only the following DistanceUnit values are supported: Meters, Kilometers, Kilofeet, Feet, NauticalMiles, and StatuteMiles.
    - Only the following InterpolationMethod values are supported: Lagrange, Hermite, and LagrangeVOP.
    - Only the following TimeFormat values are supported: EpSec, GPSG, UTCG, TAIG, and TDTG.
    - Only the following ephemeris formats are supported: EphemerisTimePos, EphemerisTimePosVel, EphemerisTimePosVelAcc, EphemerisLLATimePos, EphemerisLLATimePosVel, EphemerisLLRTimePos, and EphemerisLLRTimePosVel.
    - Only the following covariance formats are supported: CovarianceTimePos and CovarianceTimePosVel.
    Parameters:
    
    reader - The reader from which to read the ephemeris.
    
    readOptions - An object containing any additional instructions for the read process.
    
    Returns:
    
    An StkEphemerisFile instance containing the read ephemeris file.
    
    Throws:
    
    InvalidDataException - Thrown when the STK ephemeris file is invalid or it contains unsupported properties or property values.
    
    ArgumentNullException - Thrown when reader is null.

Class StkEphemerisFile

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Method Detail

createPoint

createCovarianceInterpolator

configureFromPointInterpolator

configureFromPoint

configureInterpolation

getVersion

setVersion

getData

setData

getCovarianceData

setCovarianceData

getProperties

getUnsupportedProperties

getPropertiesWithUnsupportedValues

getSegmentBoundaryTimes

setSegmentBoundaryTimes

writeTo

writeTo

readFrom

readFrom

readFrom

readFrom