agi.foundation.stk

(agi.foundation.models-2024r3.jar)

Class 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.0);

// 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.

Method Summary

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 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(@Nonnull
                          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.

ArgumentNullException - Thrown when writer is null.

writeTo

public final void writeTo(@Nonnull
                          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 the output should have pretty formatting.

Throws:

UnsupportedCaseException - Thrown when the ephemeris file is in an unknown format.

ArgumentNullException - Thrown when writer is null.

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.