JNISpice
version 2.0.0

spice.basic
Class ReferenceFrame

java.lang.Object
  extended by spice.basic.ReferenceFrame

public class ReferenceFrame
extends java.lang.Object

Class ReferenceFrame represents the identities of reference frames and supports transformations between them.

Position and state vector transformation matrices are created by methods of this class. See getPositionTransformation( ReferenceFrame, Time ), getPositionTransformation( ReferenceFrame, Time, Time ) and getStateTransformation( ReferenceFrame, Time ).

Code Examples

The numerical results shown for these examples may differ across platforms. The results depend on the SPICE kernels used as input, the compiler and supporting libraries, and the machine specific arithmetic implementation.

Example 1:

   //
   // Obtain the J2000 to IAU_SATURN position transformation matrix for
   // the epoch 2009 June 25 00:00:00 UTC.
   //
   // Import the SPICE API declarations.
   //
   // The static import of symbols from spice.basic.ReferenceFrame
   // enables use to use constants from that class without prefixing
   // them with their class name.
   //
   import spice.basic.*;
   import static spice.basic.ReferenceFrame.*;

   public class ReferenceFrame_ex2 {

      //
      // Load the JNISpice shared object library or DLL.
      //
      static {   System.loadLibrary ( "JNISpice" );  }

      public static void main ( String[] args ) {

         try
         {
            //
            // Load SPICE kernels via the standard meta-kernel. The
            // static `load' method of class KernelDatabase is equivalent
            // to the "FURNSH" call of other SPICE Toolkits.
            //
            KernelDatabase.load ( "standard.tm" );

            //
            // Create a TDB time representing the UTC time of interest.
            //
            TDBTime et = new TDBTime( "2009 June 25 00:00:00 UTC" );

            ReferenceFrame J2000      = new ReferenceFrame ( "J2000"      );
            ReferenceFrame IAU_SATURN = new ReferenceFrame ( "IAU_SATURN" );

            //
            // Compute the transformation at the time of interest. Note that
            // an instance of any subclass of spice.basic.Time may be used as
            // the input time argument.
            //
            Matrix33 m = J2000.getPositionTransformation( IAU_SATURN, et );

            //
            // Display the transformation matrix. We can print the
            // referenceFrame, TDBTime, and Matrix33 instances
            // since their classes override java.lang.object.toString().
            // Note that `et' will be displayed as a TDB calendar string.
            //
            String endl = System.getProperty( "line.separator" );

            System.out.println ( endl + "Transformation from frame " + J2000 +
                                 " to frame " + IAU_SATURN      + endl +
                                 "at " + et + ":" + endl + endl + m );
         }
         catch ( SpiceException exc )  {
            //
            // If JNISpice threw an exception, display a Java stack
            // trace and any SPICE diagnostic message. Note that all
            // exceptions thrown by JNISpice classes are derived
            // from SpiceException.
            //
            exc.printStackTrace();
         }
      }
   }
When this program was executed on a PC/Linux/java 1.6.0_14/gcc platform, the output was:
Transformation from frame J2000 to frame IAU_SATURN
at 2009 JUN 25 00:01:06.184 (TDB):

 -1.0113056497298978e-01,  -9.9150639953328200e-01,   8.1778166479761040e-02,
  9.9119341126813720e-01,  -1.0747884707743233e-01,  -7.7355794156219220e-02,
  8.5488187996221650e-02,   7.3234944633375220e-02,   9.9364400697516870e-01

Version 2.0.0 28-DEC-2016 (NJB)

Added methods equals(java.lang.Object) and hashCode().

Added method getPositionTransformation(spice.basic.ReferenceFrame toFrame, spice.basic.Time etFrom, spice.basic.Time etTo ).

Bug fix: in the ReferenceFrame(int) constructor, changed code to test for either empty or blank string returned from CSPICE.frmnam.

Version 1.0.0 09-DEC-2009 (NJB)


Constructor Summary
ReferenceFrame(int code)
          Construct a ReferenceFrame from an integer code.
ReferenceFrame(ReferenceFrame f)
          Construct a ReferenceFramefrom another ReferenceFrame.
ReferenceFrame(java.lang.String name)
          Construct a ReferenceFrame from a string.
 
Method Summary
 boolean equals(java.lang.Object obj)
          Test two ReferenceFrame instances for equality.
 FrameInfo getFrameInfo()
          Return frame specification parameters for this instance.
 int getIDCode()
          Return the SPICE frame ID of a reference frame.
 java.lang.String getName()
          Return the name of a reference frame as a String.
 Matrix33 getPositionTransformation(ReferenceFrame toFrame, Time t)
          Return a 3x3 matrix that transforms 3-vectors from one reference frame to another.
 Matrix33 getPositionTransformation(ReferenceFrame toFrame, Time fromTime, Time toTime)
          Return a 3x3 matrix that transforms 3-vectors from one reference frame, evaluated at a specified time, to another, specified at a second time.
 Matrix66 getStateTransformation(ReferenceFrame toFrame, Time t)
          Return a 6x6 matrix that transforms state vectors from one reference frame to another.
 int hashCode()
          Return a hash code for this instance.
 java.lang.String toString()
          Override toString().
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ReferenceFrame

public ReferenceFrame(java.lang.String name)
               throws SpiceException
Construct a ReferenceFrame from a string.

Throws:
SpiceException

ReferenceFrame

public ReferenceFrame(int code)
               throws FrameNotFoundException,
                      SpiceException
Construct a ReferenceFrame from an integer code.

Throws:
FrameNotFoundException
SpiceException

ReferenceFrame

public ReferenceFrame(ReferenceFrame f)
Construct a ReferenceFramefrom another ReferenceFrame. This constructor creates a deep copy.

Method Detail

hashCode

public int hashCode()
Return a hash code for this instance. This method does not throw an exception.

Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)
Test two ReferenceFrame instances for equality. This method does not throw an exception.

Overrides:
equals in class java.lang.Object

getIDCode

public int getIDCode()
              throws SpiceException
Return the SPICE frame ID of a reference frame.

Throws:
SpiceException

getName

public java.lang.String getName()
                         throws SpiceException
Return the name of a reference frame as a String. This method normalizes the name if the name is known to the SPICE system.

Throws:
SpiceException

getFrameInfo

public FrameInfo getFrameInfo()
                       throws FrameNotFoundException,
                              SpiceException
Return frame specification parameters for this instance.

Throws:
FrameNotFoundException
SpiceException

toString

public java.lang.String toString()
Override toString(). This method normalizes the name if the name is known to the SPICE system.

Overrides:
toString in class java.lang.Object

getPositionTransformation

public Matrix33 getPositionTransformation(ReferenceFrame toFrame,
                                          Time t)
                                   throws SpiceException
Return a 3x3 matrix that transforms 3-vectors from one reference frame to another.

Throws:
SpiceException

getPositionTransformation

public Matrix33 getPositionTransformation(ReferenceFrame toFrame,
                                          Time fromTime,
                                          Time toTime)
                                   throws SpiceException
Return a 3x3 matrix that transforms 3-vectors from one reference frame, evaluated at a specified time, to another, specified at a second time.

Throws:
SpiceException

getStateTransformation

public Matrix66 getStateTransformation(ReferenceFrame toFrame,
                                       Time t)
                                throws SpiceException
Return a 6x6 matrix that transforms state vectors from one reference frame to another.

Throws:
SpiceException

JNISpice
version 2.0.0

JNISpice Alpha Test Version 2.0.0 28-JAN-2017 (NJB)