agi.foundation.spice

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

Class JplSpkEphemerisProvider

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.spice.JplSpkEphemerisProvider

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

Direct Known Subclasses:

AsteroidsBspEphemerisProvider, CeresBspEphemerisProvider, JupiterBspEphemerisProvider, MarsBspEphemerisProvider, NeptuneBspEphemerisProvider, PlanetsBspEphemerisProvider, PlutoBspEphemerisProvider, SaturnBspEphemerisProvider, UranusBspEphemerisProvider, VestaBspEphemerisProvider

public abstract class JplSpkEphemerisProvider
extends DefinitionalObject

The common base for classes for loading and accessing JPL SPK files.

If STK is installed with the Planetary Data Supplement, several relatively small (less than 200 MB each) *.bsp files are available in the STKData/Spice folder of the STK installation. These files are described in the Readme.txt file in the ReadMe folder inside the STKData/Spice folder. They provide enough data to enable all of the available CentralBodies and PlanetarySystemBarycenters to have their CenterOfMassPoint (get / set) be defined in terms of the SolarSystemBarycenter within the CentralBodiesFacet with far greater accuracy and precision than the default analytic ephemeris can provide.

If STK or the Planetary Data Supplement are unavailable, the next best option is to go to the website of the Navigation and Ancillary Information Facility (NAIF) of JPL to download *.bsp ephemerides for planets and planetary moons. Some of these can be massive (greater than 1 GB) because they often contain data that extends hundreds of years into the past and future for astronomical purposes. There is typically a small text *.cmt file with the same name as the *.bsp ephemeris that contains information about what data is contained within each *.bsp file.

For asteroids and comets, the best strategy is to go to the website of the Solar System Dynamics (SSD) group of JPL to generate custom *.bsp files using the Horizons Web Application.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	JplSpkEphemerisProvider(JplSpkEphemerisProvider existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.
protected	JplSpkEphemerisProvider(JplSpkFile file) Initializes an instance using the specified JplSpkFile instance.
protected	JplSpkEphemerisProvider(StreamFactory streamFactory) Initializes a new instance with the specified stream factory.
protected	JplSpkEphemerisProvider(String filename) Initializes an instance using the specified JPL SPK filename.

Method Summary

Modifier and Type	Method and Description
protected boolean	checkForSameDefinition(DefinitionalObject other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected abstract boolean	checkForSameDefinition(JplSpkEphemerisProvider other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected int	computeCurrentDefinitionHashCode() Computes a hash code based on the current properties of this object.
void	enumerateDependencies(DependencyEnumerator enumerator) Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon.
protected void	freezeAggregatedObjects() Called by DefinitionalObject.freeze() to also freeze any objects that are considered to be a part of this object.
JplSpkFile	getFile() Gets the JPL SPK file represented by this instance.
static void	modelSolarSystemUsingPlanetaryDataSupplement(CentralBodiesFacet centralBodiesFacet, PlanetsBspEphemerisProvider planetsBsp, AsteroidsBspEphemerisProvider asteroidsBsp, MarsBspEphemerisProvider marsBsp, JupiterBspEphemerisProvider jupiterBsp, SaturnBspEphemerisProvider saturnBsp, UranusBspEphemerisProvider uranusBsp, NeptuneBspEphemerisProvider neptuneBsp, PlutoBspEphemerisProvider plutoBsp) Consistently applies JplSpkEphemerisProvider.useForCentralBodyPositions(agi.foundation.celestial.CentralBodiesFacet) on all of the *.bsp ephemerides available in the STK Planetary Data Supplement to model the entire solar system.
static void	modelSolarSystemUsingPublicJplData(CentralBodiesFacet centralBodiesFacet, JplDE jplDe, CeresBspEphemerisProvider ceresBsp, VestaBspEphemerisProvider vestaBsp, MarsBspEphemerisProvider mar097Bsp, Jup365BspEphemerisProvider jup365Bsp, Sat441BspEphemerisProvider sat441Bsp, Ura111BspEphemerisProvider ura111Bsp, Nep097BspEphemerisProvider nep097Bsp, Plu058BspEphemerisProvider plu058Bsp) Consistently applies JplSpkEphemerisProvider.useForCentralBodyPositions(agi.foundation.celestial.CentralBodiesFacet) on JplDE and some of the *.bsp ephemerides available on the JPL website to model the entire solar system.
abstract void	useForCentralBodyPositions(CentralBodiesFacet centralBodiesFacet) Use this ephemeris provider to define the locations of whichever central bodies and barycenters are directly provided by this file.

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, clone, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, freeze, getCollectionHashCode, getCollectionHashCode, getCollectionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDictionaryHashCode, getIsFrozen, isSameDefinition, throwIfFrozen

Methods inherited from class java.lang.Object

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

Constructor Detail

JplSpkEphemerisProvider

protected JplSpkEphemerisProvider(@Nonnull
                                  String filename)

Initializes an instance using the specified JPL SPK filename.

Parameters:

filename - The full path and filename of the JPL SPK file.

Throws:

ArgumentNullException - Thrown when filename is null.

JplSpkEphemerisProvider

protected JplSpkEphemerisProvider(@Nonnull
                                  StreamFactory streamFactory)

Initializes a new instance with the specified stream factory.

The streams created by streamFactory must support seeking. This means that the streams must implement ISeekableStream or FileInputStream.

Parameters:

streamFactory - The factory to use to create streams to read the JPL SPK data.

Throws:

ArgumentNullException - Thrown when streamFactory is null.

JplSpkEphemerisProvider

protected JplSpkEphemerisProvider(@Nonnull
                                  JplSpkFile file)

Initializes an instance using the specified JplSpkFile instance.

Parameters:

file - The JplSpkFile instance to use.

Throws:

ArgumentNullException - Thrown when file is null.

JplSpkEphemerisProvider

protected JplSpkEphemerisProvider(@Nonnull
                                  JplSpkEphemerisProvider existingInstance,
                                  @Nonnull
                                  CopyContext context)

Initializes a new instance as a copy of an existing instance.

See ICloneWithContext.clone(CopyContext) for more information about how to implement this constructor in a derived class.

Parameters:

existingInstance - The existing instance to copy.

context - A CopyContext that controls the depth of the copy.

Throws:

ArgumentNullException - Thrown when existingInstance or context is null.

Method Detail

checkForSameDefinition

protected final boolean checkForSameDefinition(DefinitionalObject other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Specified by:

checkForSameDefinition in class DefinitionalObject

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

checkForSameDefinition

protected abstract boolean checkForSameDefinition(JplSpkEphemerisProvider other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

computeCurrentDefinitionHashCode

protected int computeCurrentDefinitionHashCode()

Computes a hash code based on the current properties of this object. Derived classes MUST override this method and compute a hash code that combines: a unique hash code seed, the base implementation result, and the hash codes of all new fields introduced by the derived class which are used in the JplSpkEphemerisProvider.checkForSameDefinition(agi.foundation.infrastructure.DefinitionalObject) method.

Overrides:

computeCurrentDefinitionHashCode in class DefinitionalObject

Returns:

The computed hash code.

enumerateDependencies

public void enumerateDependencies(DependencyEnumerator enumerator)

Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon. Derived classes which contain additional dependencies MUST override this method, call the base implementation, and enumerate dependencies introduced by the derived class.

Specified by:

enumerateDependencies in interface IEnumerateDependencies

Overrides:

enumerateDependencies in class DefinitionalObject

Parameters:

enumerator - The enumerator that is informed of the dependencies of this object.

freezeAggregatedObjects

protected void freezeAggregatedObjects()

Called by DefinitionalObject.freeze() to also freeze any objects that are considered to be a part of this object. Derived classes which contain additional aggregated objects MUST override this method, call the base implementation, and freeze aggregated objects introduced by the derived class. The objects that need to be frozen in this method are frequently created in this object's constructor and are not settable via properties.

Overrides:

freezeAggregatedObjects in class DefinitionalObject

getFile

@Nonnull
public final JplSpkFile getFile()

Gets the JPL SPK file represented by this instance.

useForCentralBodyPositions

public abstract void useForCentralBodyPositions(@Nonnull
                                                CentralBodiesFacet centralBodiesFacet)

Use this ephemeris provider to define the locations of whichever central bodies and barycenters are directly provided by this file.

Parameters:

centralBodiesFacet - The central bodies to update to use this data.

modelSolarSystemUsingPlanetaryDataSupplement

public static void modelSolarSystemUsingPlanetaryDataSupplement(@Nonnull
                                                                CentralBodiesFacet centralBodiesFacet,
                                                                @Nonnull
                                                                PlanetsBspEphemerisProvider planetsBsp,
                                                                @Nonnull
                                                                AsteroidsBspEphemerisProvider asteroidsBsp,
                                                                @Nonnull
                                                                MarsBspEphemerisProvider marsBsp,
                                                                @Nonnull
                                                                JupiterBspEphemerisProvider jupiterBsp,
                                                                @Nonnull
                                                                SaturnBspEphemerisProvider saturnBsp,
                                                                @Nonnull
                                                                UranusBspEphemerisProvider uranusBsp,
                                                                @Nonnull
                                                                NeptuneBspEphemerisProvider neptuneBsp,
                                                                @Nonnull
                                                                PlutoBspEphemerisProvider plutoBsp)

Consistently applies JplSpkEphemerisProvider.useForCentralBodyPositions(agi.foundation.celestial.CentralBodiesFacet) on all of the *.bsp ephemerides available in the STK Planetary Data Supplement to model the entire solar system. The planetary system barycenters are computed first and then their updated positions are applied to the positions of Pluto, the planets, and the planetary moons. Both the central bodies facet and the ephemeris providers will have their planetary system barycenters updated.

See the documentation on the individual ephemeris providers to get instructions about how to find the files.

Parameters:

centralBodiesFacet - The central bodies to update to use this data.

planetsBsp - An ephemeris provider constructed using a planets.bsp file.

asteroidsBsp - An ephemeris provider constructed using an asteroids.bsp file.

marsBsp - An ephemeris provider constructed using a mars.bsp or mar097.bsp file.

jupiterBsp - An ephemeris provider constructed using a jupiter.bsp file.

saturnBsp - An ephemeris provider constructed using a saturn.bsp file.

uranusBsp - An ephemeris provider constructed using a uranus.bsp file.

neptuneBsp - An ephemeris provider constructed using a neptune.bsp file.

plutoBsp - An ephemeris provider constructed using a pluto.bsp file.

Throws:

ArgumentNullException - Thrown when centralBodiesFacet or any of the JplSpkEphemerisProvider derived classes are null.

modelSolarSystemUsingPublicJplData

public static void modelSolarSystemUsingPublicJplData(@Nonnull
                                                      CentralBodiesFacet centralBodiesFacet,
                                                      @Nonnull
                                                      JplDE jplDe,
                                                      @Nonnull
                                                      CeresBspEphemerisProvider ceresBsp,
                                                      @Nonnull
                                                      VestaBspEphemerisProvider vestaBsp,
                                                      @Nonnull
                                                      MarsBspEphemerisProvider mar097Bsp,
                                                      @Nonnull
                                                      Jup365BspEphemerisProvider jup365Bsp,
                                                      @Nonnull
                                                      Sat441BspEphemerisProvider sat441Bsp,
                                                      @Nonnull
                                                      Ura111BspEphemerisProvider ura111Bsp,
                                                      @Nonnull
                                                      Nep097BspEphemerisProvider nep097Bsp,
                                                      @Nonnull
                                                      Plu058BspEphemerisProvider plu058Bsp)

Consistently applies JplSpkEphemerisProvider.useForCentralBodyPositions(agi.foundation.celestial.CentralBodiesFacet) on JplDE and some of the *.bsp ephemerides available on the JPL website to model the entire solar system. The Sun and the planetary system barycenters are computed first and then their updated positions are applied to the positions of Ceres, Vesta, Pluto, the planets, and the planetary moons.

See the documentation on the individual ephemeris providers to get instructions about how to find or generate the files.

Parameters:

centralBodiesFacet - The central bodies to update to use this data.

jplDe - An ephemeris provider constructed using a planetary ephemeris file.

ceresBsp - An ephemeris provider constructed using an ceres.bsp file.

vestaBsp - An ephemeris provider constructed using a vesta.bsp file.

mar097Bsp - An ephemeris provider constructed using a mar097.bsp file.

jup365Bsp - An ephemeris provider constructed using a jup365.bsp file.

sat441Bsp - An ephemeris provider constructed using a sat441.bsp file.

ura111Bsp - An ephemeris provider constructed using a ura111.bsp file.

nep097Bsp - An ephemeris provider constructed using a nep097.bsp file.

plu058Bsp - An ephemeris provider constructed using a plu058.bsp file.

Throws:

ArgumentNullException - Thrown when centralBodiesFacet, jplDe, or any of the JplSpkEphemerisProvider derived classes are null.