agi.foundation.stk

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

Class StkAttitudeFile

java.lang.Object

agi.foundation.stk.StkAttitudeFile

public class StkAttitudeFile
extends Object

Reads from and writes to STK attitude (.a) files. STK attitude files can express orientation and angular velocity, and are useful for getting this type of data into and out of STK.

To read an STK attitude file, call the StkAttitudeFile.readFrom(String) method to read the data into memory, and then call the StkAttitudeFile.createAxes() method to create a time-varying Axes representing the attitude data in the file.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	StkAttitudeFile.Attitude The base class for attitude data.
static class	StkAttitudeFile.AttitudeTimeQuatAngVels A class that holds the data in the attitude file when the attitude file is in the "AttitudeTimeQuatAngVels" format.
static class	StkAttitudeFile.AttitudeTimeQuaternions A class that holds the data in the attitude file when the attitude file is in the "AttitudeTimeQuaternions" or "AttitudeTimeQuatScalarFirst" format.
static class	StkAttitudeFile.AttitudeTimeQuatScalarFirst A class that holds the data in the attitude file when the attitude file is in the "AttitudeTimeQuatScalarFirst" format.

Constructor Summary

Constructors

Constructor and Description
StkAttitudeFile() Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
void	configureFromAxes(Axes axes, JulianDate start, JulianDate stop, Duration step, int order) Configures this instance with values computed by sampling an Axes over an interval with a fixed step.
void	configureFromAxesInterpolator(AxesInterpolator axesInterpolator) Configures the instance to represent the attitude and interpolation stored in an AxesInterpolator.
void	configureInterpolation(InterpolationAlgorithm interpolationAlgorithm, int interpolationDegree) Configures the Interpolator (get / set) to use the specified interpolation algorithm and polynomial degree.
Axes	createAxes() Creates an Axes whose time-varying orientation is computed by interpolating over the attitude data held by this instance.
StkAttitudeFile.Attitude	getData() Gets the attitude data.
Map<String,String>	getProperties() Gets a dictionary of key and value pairs in the STK attitude 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 StkAttitudeFile reader.
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 StkAttitudeFile reader.
StkAttitudeFileVersion	getVersion() Gets the attitude file version.
static StkAttitudeFile	readFrom(BufferedReader reader) Reads an STK attitude (.a) file from a BufferedReader.
static StkAttitudeFile	readFrom(BufferedReader reader, StkAttitudeFileOptions readOptions) Reads an STK attitude (.a) file from a BufferedReader.
static StkAttitudeFile	readFrom(String fileName) Reads an STK attitude (.a) file from a specified file.
static StkAttitudeFile	readFrom(String fileName, StkAttitudeFileOptions readOptions) Reads an STK attitude (.a) file from a specified file.
void	setData(StkAttitudeFile.Attitude value) Sets the attitude data.
void	setVersion(StkAttitudeFileVersion value) Sets the attitude file version.
void	writeTo(Writer writer) Writes this instance to a Writer in the STK attitude file (.a) format.
void	writeTo(Writer writer, boolean prettyPrinting) Writes this instance to a Writer in the STK attitude file (.a) format.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StkAttitudeFile

public StkAttitudeFile()

Initializes a new instance.

Method Detail

createAxes

@Nonnull
public final Axes createAxes()

Creates an Axes whose time-varying orientation is computed by interpolating over the attitude data held by this instance.

Returns:

The axes.

Throws:

PropertyInvalidException - Thrown when Data (get / set) is null.

configureFromAxesInterpolator

public final void configureFromAxesInterpolator(@Nonnull
                                                AxesInterpolator axesInterpolator)

Configures the instance to represent the attitude and interpolation stored in an AxesInterpolator. The Data (get / set) property is replaced with a new instance of StkAttitudeFile.AttitudeTimeQuaternions, or StkAttitudeFile.AttitudeTimeQuatAngVels (depending on the number of derivatives available from the AxesInterpolator) and any existing information stored in that instance is lost. The Properties (get) are not modified, but values pulled from AxesInterpolator will take precedence over values in the Properties (get) collection when writing this instance using StkAttitudeFile.writeTo(Writer).

Parameters:

axesInterpolator - The AxesInterpolator with which to configure this instance. The point's Interpolator (get / set) and ReferenceAxes (get / set) properties, as well as the interpolator's Data (get / set) property, must not be null.

Throws:

ArgumentNullException - Thrown when axesInterpolator is null.

configureFromAxes

public final void configureFromAxes(@Nonnull
                                    Axes axes,
                                    @Nonnull
                                    JulianDate start,
                                    @Nonnull
                                    JulianDate stop,
                                    @Nonnull
                                    Duration step,
                                    int order)

Configures this instance with values computed by sampling an Axes over an interval with a fixed step. The Data (get / set) property is replaced with a new instance of StkAttitudeFile.AttitudeTimeQuaternions, or StkAttitudeFile.AttitudeTimeQuatAngVels (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 Axes will take precedence over values in the Properties (get) collection when writing this instance using StkAttitudeFile.writeTo(Writer). The Interpolator (get / set) property is not configured, so you may want to call StkAttitudeFile.configureInterpolation(agi.foundation.numericalmethods.advanced.InterpolationAlgorithm, int) after calling this method.

Parameters:

axes - The axes from which to sample orientations and optionally angular velocities.

start - The first date at which to sample the axes.

stop - The last date at which to sample the axes.

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 orientation only and 1 (or greater) also includes angular velocity.

Throws:

ArgumentNullException - Thrown when axes is null.

configureInterpolation

public final void configureInterpolation(@Nonnull
                                         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 StkAttitudeFileVersion getVersion()

Gets the attitude file version.

setVersion

public final void setVersion(@Nonnull
                             StkAttitudeFileVersion value)

Sets the attitude file version.

getData

public final StkAttitudeFile.Attitude getData()

Gets the attitude data.

setData

public final void setData(StkAttitudeFile.Attitude value)

Sets the attitude data.

getProperties

@Nonnull
public final Map<String,String> getProperties()

Gets a dictionary of key and value pairs in the STK attitude file.

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 StkAttitudeFile 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 StkAttitudeFile reader. Any information contained in these properties may not be captured by the reader.

writeTo

public final void writeTo(@Nonnull
                          Writer writer)

Writes this instance to a Writer in the STK attitude file (.a) 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 attitude 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 attitude file (.a) 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 attitude file is in an unknown format.

ArgumentNullException - Thrown when writer is null.

readFrom

@Nonnull
public static StkAttitudeFile readFrom(@Nonnull
                                                 String fileName)

Reads an STK attitude (.a) file from a specified file. See the documentation of StkAttitudeFile.readFrom(BufferedReader,StkAttitudeFileOptions) for detailed information.

Parameters:

fileName - The name of the file from which to read the attitude.

Returns:

An StkAttitudeFile instance containing the read attitude file.

Throws:

InvalidDataException - Thrown when the STK attitude file is invalid, or it contains unsupported properties or property values.

ArgumentNullException - Thrown when fileName is null.

readFrom

@Nonnull
public static StkAttitudeFile readFrom(@Nonnull
                                                 String fileName,
                                                 StkAttitudeFileOptions readOptions)

Reads an STK attitude (.a) file from a specified file. See the documentation of StkAttitudeFile.readFrom(BufferedReader,StkAttitudeFileOptions) for detailed information.

Parameters:

fileName - The name of the file from which to read the attitude.

readOptions - An object containing any additional instructions for the read process.

Returns:

An StkAttitudeFile instance containing the read attitude file.

Throws:

InvalidDataException - Thrown when the STK attitude file is invalid, or it contains unsupported properties or property values.

ArgumentNullException - Thrown when fileName is null.

readFrom

@Nonnull
public static StkAttitudeFile readFrom(@Nonnull
                                                 BufferedReader reader)

Reads an STK attitude (.a) 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 StkAttitudeFile.readFrom(BufferedReader,StkAttitudeFileOptions) for detailed information.

Parameters:

reader - The reader from which to read the attitude.

Returns:

An StkAttitudeFile instance containing the read attitude file.

Throws:

InvalidDataException - Thrown when the STK attitude file is invalid, or it contains unsupported properties or property values.

ArgumentNullException - Thrown when reader is null.

readFrom

@Nonnull
public static StkAttitudeFile readFrom(@Nonnull
                                                 BufferedReader reader,
                                                 StkAttitudeFileOptions readOptions)

Reads an STK attitude (.a) 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 attitude 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 "CoordinateAxes" property can specify any coordinate axes that is known to STK's Vector Geometry Tool in the current scenario. In the general case, it's impossible to determine from the attitude file itself, in the absence of an STK scenario, what that coordinate axes 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 attitude 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 StkAttitudeFileOptions 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 attitude file using this method:

• Only the following properties are supported: BlockingFactor (ignored), InterpolationOrder, InterpolationMethod, NumberOfAttitudePoints, AttitudeDeviations (ignored), ScenarioEpoch, CentralBody, CoordinateAxesEpoch, CoordinateAxes, TimeFormat.
• Only the following CentralBody values are supported: Earth, Sun, Moon.
• When the CentralBody is Earth, only the following CoordinateAxes values are supported: ICRF, J2000, Inertial, Fixed, TrueOfDate, TrueOfEpoch, MeanOfDate, MeanOfEpoch, TEMEOfDate, TEMEOfEpoch.
• When the CentralBody is Sun or Moon, only the following CoordinateAxes values are supported: Inertial, Fixed.
• Only the following InterpolationMethod values are supported: Lagrange, Hermite.
• Only the following TimeFormat value is supported: EpSec.
• Only the following AttitudeDeviations value is supported: Rapid. In addition, this property will NOT automatically affect access computations as it will in STK.
• Only the following attitude formats are supported: AttitudeTimeQuaternions, AttitudeTimeQuatScalarFirst, AttitudeTimeQuatAngVels.

Parameters:

reader - The reader from which to read the attitude.

readOptions - An object containing any additional instructions for the read process.

Returns:

An StkAttitudeFile instance containing the read attitude file.

Throws:

InvalidDataException - Thrown when the STK attitude file is invalid, or it contains unsupported properties or property values.

ArgumentNullException - Thrown when reader is null.