HiRISE

HiRISE.HiPlan.HiSEAS
Class MroObservation.OrbitalData

java.lang.Object
  extended by HiRISE.HiPlan.HiSEAS.MroObservation.OrbitalData
Enclosing class:
MroObservation

public static final class MroObservation.OrbitalData
extends Object

A simple data model representing a subset of orbital data necessary for planning an MRO-based observation. The data consist of the orbit, the target, the observation's ephemeris time, and the roll angle needed to observe the target.

Instances of the orbital data are obtained via one of the findData methods, each of which requires a Target site and an estimate of a time at which the target site can be observed. These methods compute the geometry necessary to view the target using on a cross-track roll only, generating the ephemeris time of the observation and the roll angle such that the target is observed in a plane perpendicular to the orbit vector, within the allowable roll limit of 30°. If the target cannot be observed within that estimate of time, the methods return a null orbital data model.

In each case, the targeting algorithm uses the JPL NAIF SPICE library to compute the data. The SPICE kernel pool must therefore be loaded with the necessary leap second kernel, spacecraft clock kernel, planetary (target) and spacecraft (observer) ephemeris kernels, and planetary constants kernels. The means by which the kernel pool is managed is not generally important.

The preferred method is findData(Target,int), which takes a candidate orbit number as the estimate of time. To use this method, the MTT (Mars Target Tool) data layer (MttLayer) must be instantiated with an MRO state file. Doing so loads the kernel pool with the state file's kernels, and it adds the contents of the state file's OPTG (orbit propagation, timing, and geometry) to the static data layer's OPTG set. The OPTG is the means by which an ephemeris time estimate is obtained from the simple orbit number; this method thus ensures that the orbit number is tied to the ephemeris time, which is not true of the other findData methods.

For example, to get the orbital data for an observation of a target called aramChaos on orbit 13071 using the state file state_066b01_1_long_v3.nk, use the following code:

        MttLayer mtt = new MttLayer ("state_066b01_1_long_v3.nk");
        MroObservation.OrbitalData data1 = MroObservation.OrbitalData.findData (
                aramChaos,
                13071
        );

Note that the MTT data layer is not directly needed; the instantiation is the only means of adding the OPTG to the static OPTG set, which is required by this version of the method.

Alternatively, one may use the findData methods that take an MroObservation.Orbit and an estimate of the ephemeris time or ephemeris time range. These methods do not require the use of the MTT data layer, although they do require the SPICE kernel pool to be loaded with the necessary kernels. The disadvantage of using these methods is that there is no guarantee or requirement that the orbit and ephemeris time be related; the orbit is used only to set the value of the orbit in the resulting orbital data model.

For example, to get the orbital data for an observation of a target called aramChaos on MroObservation.Orbit 13071a at approximately 295272514.0, use the following code, assuming the kernel pool is appropriately loaded:

        MroObservation.OrbitalData data2 = MroObservation.OrbitalData.findData (
                aramChaos,
                Orbit.valueOf ("13071a"),
                295272514.0
        );

Version:
1.9
Author:
Christian Schaller - UA/PIRL

Field Summary
static double ET_ESTIMATE_MARGIN
          The margin used for finding the ephemeris time from an initial estimate.
 
Method Summary
 boolean equals(Object o)
          Indicates whether some other object is "equal to" this one.
static List<MroObservation.OrbitalData> findAllData(Target target, edu.asu.jmars.layer.obs.mro.MttLayer mttLayer)
          Finds all orbital data models on which the target is observable within a period defined by the MTT data layer.
static MroObservation.OrbitalData findData(Target target, int orbitNumber)
          Finds the orbital data model for an observation of the given target on the specified orbit number.
static MroObservation.OrbitalData findData(Target target, MroObservation.Orbit orbit, double estimatedEt)
          Finds the orbital data model for an observation of the given target on the specified orbit with the initial estimate of ephemeris time.
static MroObservation.OrbitalData findData(Target target, MroObservation.Orbit orbit, double etRangeMin, double etRangeMax)
          Finds the orbital data model for an observation of the given target on the specified orbit within the given ephemeris time range.
 double getEt()
          Gets this model's ephemeris time.
 MroObservation.Orbit getOrbit()
          Gets this model's orbit.
 double getRollAngle()
          Gets this model's roll angle.
 Target getTarget()
          Gets this model's target.
 int hashCode()
          Returns a hash code value for this orbital data model.
 String toString()
          Gets a string representation of this orbital data model.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ET_ESTIMATE_MARGIN

public static final double ET_ESTIMATE_MARGIN
The margin used for finding the ephemeris time from an initial estimate.

See Also:
findData(Target,MroObservation.Orbit,double), Constant Field Values
Method Detail

getOrbit

public MroObservation.Orbit getOrbit()
Gets this model's orbit.

Returns:
the orbit.

getTarget

public Target getTarget()
Gets this model's target.

Returns:
the target.

getEt

public double getEt()
Gets this model's ephemeris time. This time is the time at which the target is observable with the roll angle.

Returns:
the ephemeris time.

getRollAngle

public double getRollAngle()
Gets this model's roll angle. This roll angle is that necessary to observe the target at the ephemeris time.

Returns:
the roll angle in radians.

toString

public String toString()
Gets a string representation of this orbital data model.

Overrides:
toString in class Object
Returns:
a string representation of this orbital data model.

hashCode

public int hashCode()
Returns a hash code value for this orbital data model.

Overrides:
hashCode in class Object
Returns:
a hash code value for this orbital data model.

equals

public boolean equals(Object o)
Indicates whether some other object is "equal to" this one. Two orbital data models are equal if they have the same target, orbit, ephemeris time, and roll angle.

Overrides:
equals in class Object
Parameters:
o - the object to which this object is compared.
Returns:
true if the objects are equal; false otherwise.

findData

public static MroObservation.OrbitalData findData(Target target,
                                                  int orbitNumber)
Finds the orbital data model for an observation of the given target on the specified orbit number. If the target is not observable, a null is returned instead.

This method requires that the MTT data layer be initialized with an OPTG that defines the orbit number in question. It also requires that the SPICE kernel pool be loaded with the necessary SPICE kernels to compute the geometry; initializing the MTT data layer with an applicable state file, however, also loads the kernel pool.

Parameters:
target - the target site, which must be on Mars.
orbitNumber - the orbit number in question.
Returns:
an orbital data model or null.
Throws:
NullPointerException - if the target is null.
IllegalArgumentException - if the target body is not Mars.

findData

public static MroObservation.OrbitalData findData(Target target,
                                                  MroObservation.Orbit orbit,
                                                  double estimatedEt)
Finds the orbital data model for an observation of the given target on the specified orbit with the initial estimate of ephemeris time.

The ephemeris time parameter is merely an estimate of the time at which the target is actually observable with only a cross-track roll of up to 30°. The resulting data model may not have the same ephemeris time. If the target is not observable within ET_ESTIMATE_MARGIN seconds of the estimate, a null is returned instead. This method requires that the SPICE kernel pool be loaded with the SPICE kernels necessary to compute the geometry.

Note that this method does not make direct use of the input orbit; it is merely descriptive and copied directly to the resulting data model. There is no guarantee that the resulting model's ephemeris time matches this orbit number.

Parameters:
target - the target site, which must be on Mars.
orbit - the orbit on which the target is to be observed.
estimatedEt - the initial estimate of the model's ephemeris time.
Returns:
an orbital data model or null.
Throws:
NullPointerException - if the target or orbit is null.
IllegalArgumentException - if the target body is not Mars.

findData

public static MroObservation.OrbitalData findData(Target target,
                                                  MroObservation.Orbit orbit,
                                                  double etRangeMin,
                                                  double etRangeMax)
Finds the orbital data model for an observation of the given target on the specified orbit within the given ephemeris time range.

The ephemeris time range is a limit on the time during which the observation can occur. If the target is not observable within this range, a null is returned instead. This method requires that the SPICE kernel pool be loaded with the SPICE kernels necessary to compute the geometry.

Note that this method does not make direct use of the input orbit; it is merely descriptive and copied directly to the resulting data model. There is no guarantee that the resulting model's ephemeris time matches this orbit number.

Parameters:
target - the target site, which must be on Mars.
orbit - the orbit on which the target is to be observed.
etRangeMin - the minimum ephemeris time for the search.
etRangeMax - the maximum ephemeris time for the search.
Returns:
an orbital data model or null.
Throws:
NullPointerException - if the target or orbit is null.
IllegalArgumentException - if the target body is not Mars or if etRangeMin > etRangeMax.

findAllData

public static List<MroObservation.OrbitalData> findAllData(Target target,
                                                           edu.asu.jmars.layer.obs.mro.MttLayer mttLayer)
Finds all orbital data models on which the target is observable within a period defined by the MTT data layer. The data layer supplies the state information, including SPICE kernels and the OPTG (orbit propagation, timing, and geometry) file necessary to find the orbits. No other constraints are applied to the search.

If no orbits are found, the method returns an empty list.

Parameters:
target - the target site, which must be on Mars.
mttLayer - the MTT data layer describing the period of coverage.
Returns:
all orbital data models or an empty list.
Throws:
NullPointerException - if the target or MTT data layer is null.
IllegalArgumentException - if the target body is not Mars.

HiRISE

Copyright (C) Arizona Board of Regents on behalf of the Planetary Image Research Laboratory, Lunar and Planetary Laboratory at the University of Arizona