Module JNISpice
Package spice.basic

Class 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)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.lang.String frameName  
    • Constructor Summary

      Constructors 
      Constructor Description
      ReferenceFrame​(int code)
      Construct a ReferenceFrame from an integer code.
      ReferenceFrame​(java.lang.String name)
      Construct a ReferenceFrame from a string.
      ReferenceFrame​(ReferenceFrame f)
      Construct a ReferenceFramefrom another ReferenceFrame.This constructor creates a deep copy.
    • Method Summary

      Modifier and Type Method Description
      boolean equals​(java.lang.Object obj)
      Test two ReferenceFrame instances for equality.This method does not throw an exception.
      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.This method normalizes the name if the name is known to the SPICE system.
      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.This method does not throw an exception.
      java.lang.String toString()
      Override toString().This method normalizes the name if the name is known to the SPICE system.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • frameName

        private java.lang.String frameName
    • Constructor Detail

      • ReferenceFrame

        public ReferenceFrame​(java.lang.String name)
                       throws SpiceException
        Construct a ReferenceFrame from a string.
        Parameters:
        name - String
        Throws:
        SpiceException - exception
      • ReferenceFrame

        public ReferenceFrame​(ReferenceFrame f)
        Construct a ReferenceFramefrom another ReferenceFrame.This constructor creates a deep copy.
        Parameters:
        f - ReferenceFrame
    • 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
        Returns:
        int
      • 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
        Returns:
        boolean
      • getIDCode

        public int getIDCode()
                      throws SpiceException
        Return the SPICE frame ID of a reference frame.
        Returns:
        int
        Throws:
        SpiceException - exception
      • 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.
        Returns:
        String
        Throws:
        SpiceException - exception
      • 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
        Returns:
        String
      • getPositionTransformation

        public Matrix33 getPositionTransformation​(ReferenceFrame toFrame,
                                                  Time t)
                                           throws SpiceException
        Return a 3x3 matrix that transforms 3-vectors from one reference frame to another.
        Parameters:
        toFrame - ReferenceFrame
        t - Time
        Returns:
        Matrix33
        Throws:
        SpiceException - exception
      • 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.
        Parameters:
        toFrame - ReferenceFrame
        toTime - Time
        fromTime - Time
        Returns:
        Matrix33
        Throws:
        SpiceException - exception
      • getStateTransformation

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