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);
}| 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 and Description |
|---|
StkEphemerisFile()
Initializes a new instance.
|
| 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)
|
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. |
@Nonnull public final Point createPoint()
Point whose time-varying position is computed by interpolating
over the ephemeris data held by this instance.PropertyInvalidException - Thrown when Data (get / set) is null.public final Covariance3By3SizeAndOrientationInterpolator createCovarianceInterpolator()
Covariance3By3SizeAndOrientationInterpolator for interpolating
over the covariance data held by this instance.PropertyInvalidException - Thrown when CovarianceData (get / set) is null.public final void configureFromPointInterpolator(@Nonnull PointInterpolator pointInterpolator)
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).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.ArgumentNullException - Thrown when pointInterpolator is null.public final void configureFromPoint(@Nonnull Point point, @Nonnull JulianDate start, @Nonnull JulianDate stop, @Nonnull Duration step, int order)
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.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.ArgumentNullException - Thrown when point is null.public final void configureInterpolation(InterpolationAlgorithm interpolationAlgorithm, int interpolationDegree)
Interpolator (get / set) to use the specified interpolation algorithm
and polynomial degree. The Data (get / set) property must be set before calling this method.interpolationAlgorithm - The interpolation algorithm to use.interpolationDegree - The degree of the polynomial to use for interpolation.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.@Nonnull public final StkEphemerisFileVersion getVersion()
public final void setVersion(@Nonnull StkEphemerisFileVersion value)
public final StkEphemerisFile.Ephemeris getData()
public final void setData(StkEphemerisFile.Ephemeris value)
public final StkEphemerisFile.Covariance getCovarianceData()
public final void setCovarianceData(StkEphemerisFile.Covariance value)
@Nonnull public final Map<String,String> getProperties()
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.@Nonnull public final Map<String,String> getUnsupportedProperties()
StkEphemerisFile reader. Any information contained in these properties
may not be captured by the reader.@Nonnull public final Map<String,String> getPropertiesWithUnsupportedValues()
StkEphemerisFile reader. Any information contained in these
properties may not be captured by the reader.public final List<JulianDate> getSegmentBoundaryTimes()
public final void setSegmentBoundaryTimes(List<JulianDate> value)
public final void writeTo(Writer writer)
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.writer - The writer to which to write this instance.UnsupportedCaseException - Thrown when the ephemeris file is in an unknown format.public final void writeTo(Writer writer, boolean prettyPrinting)
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.writer - The writer to which to write this instance.prettyPrinting - Whether or not the output should have pretty formatting.UnsupportedCaseException - Thrown when the ephemeris file is in an unknown format.@Nonnull public static StkEphemerisFile readFrom(@Nonnull String fileName)
StkEphemerisFile.readFrom(BufferedReader,StkEphemerisFileOptions) for detailed information.fileName - The name of the file from which to read the ephemeris.StkEphemerisFile instance containing the read ephemeris file.InvalidDataException - Thrown when the STK ephemeris file is invalid or it contains unsupported properties or property values.ArgumentNullException - Thrown when fileName is null.@Nonnull public static StkEphemerisFile readFrom(@Nonnull String fileName, StkEphemerisFileOptions readOptions)
StkEphemerisFile.readFrom(BufferedReader,StkEphemerisFileOptions) for detailed information.fileName - The name of the file from which to read the ephemeris.readOptions - An object containing any additional instructions for the read process.StkEphemerisFile instance containing the read ephemeris file.InvalidDataException - Thrown when the STK ephemeris file is invalid or it contains unsupported properties or property values.ArgumentNullException - Thrown when fileName is null.@Nonnull public static StkEphemerisFile readFrom(@Nonnull BufferedReader reader)
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.reader - The reader from which to read the ephemeris.StkEphemerisFile instance containing the read ephemeris file.InvalidDataException - Thrown when the STK ephemeris file is invalid or it contains unsupported properties or property values.ArgumentNullException - Thrown when reader is null.@Nonnull public static StkEphemerisFile readFrom(@Nonnull BufferedReader reader, StkEphemerisFileOptions readOptions)
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:
reader - The reader from which to read the ephemeris.readOptions - An object containing any additional instructions for the read process.StkEphemerisFile instance containing the read ephemeris file.InvalidDataException - Thrown when the STK ephemeris file is invalid or it contains unsupported properties or property values.ArgumentNullException - Thrown when reader is null.