Main Page
Most Used SPICELIB APIs

SPICELIB APIs for accessing SPICE kernel data

SPICELIB APIs for computing derived geometry

SPICELIB APIs for checking geometric conditions

SPICELIB APIs for finding times of geometric events

SPICELIB APIs for coordinate conversions

SPICELIB APIs for operations with 3D vectors and matrices

Miscellaneous SPICELIB APIs


Top

Loading and Unloading SPICE Kernels

APIs:

  • FURNSH - loads an individual kernel or a collection of kernels.
  • UNLOAD - unloads an individual kernel or a collection of kernels.

Brief Example:

   Generic LSK and PCK files listed in a meta-kernel named
   "mykernels.furnsh" and containing

      \begindata
         KERNELS_TO_LOAD = (
                            '/kernels/gen/lsk/naif0008.tls'
                            '/kernels/gen/pck/pck00008.tps'
                           )
      \begintext

   are loaded with a single call to FURNSH:

            CALL FURNSH ( 'mykernels.furnsh' )

Reference documents:

  • kernel.req - reference on loading/unloading kernels and text kernel format

Top

Converting between UTC and Ephemeris Time (LSK)

APIs:

  • FURNSH - loads an individual kernel or a collection of kernels.
  • STR2ET - converts a time string to ET seconds past J2000.
  • TIMOUT - converts ET seconds past J2000 to a time string.

Brief Example:

   The following example loads an LSK file, converts a UTC string to ET
   seconds, adds 1 day and converts TDB seconds back to a UTC string in
   ISO DOY format:

            DOUBLE PRECISION   ET
            CHARACTER*(32)     UTC

            DOUBLE PRECISION   SPD

      C
      C     Load LSK file 
      C
            CALL FURNSH  ( 'naif0008.tls' )

      C
      C     Convert UTC to ET 
      C
            CALL STR2ET  ( '2005 DEC 31 12:00', ET )

      C
      C     Add 1 day to ET and convert it back to UTC 
      C
            CALL TIMOUT ( ET+SPD(), 'YYYY-DOYTHR:MN:SC.### ::RND', 
           .              UTC ) 

Reference documents:

  • time.req - reference on time systems and conversions supported in SPICE
  • kernel.req - reference on loading/unloading kernels and text kernel format

Top

Converting between Ephemeris Time and Spacecraft Clock (SCLK)

APIs:

  • FURNSH - loads individual kernels and collections of kernels.
  • SCS2E - converts an SCLK string to ET seconds past J2000.
  • SCE2S - converts ET seconds past J2000 to SCLK string.
  • SCT2E - converts an encoded SCLK to ET seconds past J2000.
  • SCE2C - converts ET seconds past J2000 to encoded SCLK.
  • SCENCD - converts an SCLK string to encoded SCLK.
  • SCDECD - converts an encoded SCLK to SCLK string.

Brief Example:

   The following example loads an LSK file and an MGS SCLK file, then
   converts an MGS SCLK string to ET and encoded SCLK:

            CHARACTER*(32)     SCLK
            DOUBLE PRECISION   ET
            DOUBLE PRECISION   SCLKDP
            INTEGER            SCID

            SCID = -94
      C
      C     Load LSK and SCLK files 
      C
            CALL FURNSH ( 'naif0008.tls' )
            CALL FURNSH ( 'mgs_sclkscet_00061.tsc' )

      C
      C     Convert string SCLK to ET and to encoded SCLK 
      C
            SCLK = '820584056:121'
            CALL SCS2E  ( SCID, SCLK, ET )
            CALL SCENCD ( SCID, SCLK, SCLKDP )

Reference documents:

  • sclk.req - reference on on-board clock (SCLK) implementation in SPICE
  • kernel.req - reference on loading/unloading kernels and text kernel format

Top

Constants and Orientation for Natural Bodies (PCK)

APIs:

  • FURNSH - loads individual kernels and collections of kernels.
  • BODFND - determines whether values exist for some item for a body in the kernel pool.
  • BODVRD - retrieves from the kernel pool the values of an item associated with a body.
  • PXFORM - returns the 3x3 matrix rotating a position vector one frame to another.
  • SXFORM - returns the 6x6 matrix rotating a state vector from one frame to another.
  • PCKFRM - finds the set of reference frame class ID codes of all frames in a binary PCK file.
  • PCKCOV - finds the coverage window for a reference frame in a binary PCK file.

Brief Example:

   The following example retrieves radii for Mars and computes
   orientation of the Mars body-fixed frame:

            DOUBLE PRECISION   ET
            DOUBLE PRECISION   MAT   (3,3)
            DOUBLE PRECISION   RADII (3)
            INTEGER            N

      C
      C     Load LSK and PCK files 
      C
            CALL FURNSH ( 'naif0008.tls' )
            CALL FURNSH ( 'pck00008.tpc' )

      C
      C     Retrieve Mars RADII 
      C
            CALL BODVRD ( 'MARS', 'RADII', 3, N, RADII )

      C
      C     Convert UTC to ET 
      C
            CALL STR2ET ( '2005-DEC-28 12:00', ET )

      C
      C     Compute Mars orientation relative to the J2000 frame 
      C
            CALL PXFORM ( 'J2000', 'IAU_MARS', ET, MAT )

Reference documents:

  • pck.req - reference on Planetary Constants Kernel (PCK) subsystem of SPICE
  • kernel.req - reference on loading/unloading kernels and text kernel format

Top

Computing Transformations Between Frames (FK)

APIs:

  • FURNSH - loads individual kernels and collections of kernels.
  • PXFORM - returns the 3x3 matrix rotating a position vector one frame to another.
  • SXFORM - returns the 6x6 matrix rotating a state vector from one frame to another.
  • PXFRM2 - returns the 3x3 matrix rotating a position vector from one frame at a specified epoch to another frame at a different epoch.

Brief Example:

   The following example computes orientation of the CASSINI ISS WAC
   camera relative to the Saturn body-fixed frame:

            DOUBLE PRECISION   ET
            DOUBLE PRECISION   MAT (3,3)

      C
      C     Load kernels: LSK, PCK, CASSINI SCLK, FK and CK 
      C
            CALL FURNSH ( 'naif0008.tls' )
            CALL FURNSH ( 'pck00008.tpc' )
            CALL FURNSH ( 'cas00101.tsc' )
            CALL FURNSH ( 'cas_v39.tf' )
            CALL FURNSH ( '05362_06002ra.bc' )
      
      C
      C     Convert UTC to ET 
      C
            CALL STR2ET ( '2005-DEC-28 12:00', ET )

      C
      C     Compute orientation of CASSINI relative to J2000 frame 
      C
            CALL PXFORM ( 'IAU_SATURN', 'CASSINI_ISS_WAC', ET, MAT )

Reference documents:

  • frames.req - reference on Frames Kernel (FK) and Frames subsystem of SPICE
  • kernel.req - reference on loading/unloading kernels and text kernel format

Top

Computing Positions of Spacecraft and Natural Bodies (SPK)

APIs:

  • FURNSH - loads individual kernels and collections of kernels.
  • SPKEZR - returns the state of a target body relative to an observing body.
  • SPKPOS - returns the position of a target body relative to an observing body.
  • SPKCPO - returns the state of a target body relative to a constant-position observer location.
  • SPKCPT - returns the state of a constant-position target location relative to an observing body.
  • SPKCVO - returns the state of a target body relative to a constant-velocity observer location.
  • SPKCVT - returns the state of a constant-velocity target location relative to an observing body.
  • SPKOBJ - finds the set of ID codes for all objects in a specified SPK file.
  • SPKCOV - finds the coverage window for a specified object in a specified SPK file.

Brief Example:

   The following example computes the geometric state (position and
   velocity) of MGS relative to Mars in the J2000 reference frame:

            DOUBLE PRECISION   ET
            DOUBLE PRECISION   STATE (6)
            DOUBLE PRECISION   LT

      C
      C     Load kernels: LSK and MGS and DE SPKs 
      C
            CALL FURNSH ( 'naif0008.tls' )
            CALL FURNSH ( 'de405.bsp' )
            CALL FURNSH ( 'mgs_ext22.bsp' )

      C
      C     Convert UTC to ET 
      C
            CALL STR2ET ( '2006 JAN 31 01:00', ET )

      C
      C     Compute geometric state of MGS relative to Mars 
      C
            CALL SPKEZR ( 'MGS', ET, 'J2000', 'NONE', 'MARS', 
           .              STATE, LT )

Reference documents:

  • spk.req - reference on Spacecraft and Planet Ephemeris (SPK) subsystem of SPICE
  • frames.req - reference on Frames Kernel (FK) and Frames subsystem of SPICE
  • kernel.req - reference on loading/unloading kernels and text kernel format

Top

Computing Orientation for Spacecraft and Instruments (CK)

APIs:

  • FURNSH - loads individual kernels and collections of kernels.
  • PXFORM - returns the 3x3 matrix rotating a position vector one frame to another.
  • SXFORM - returns the 6x6 matrix rotating a state vector from one frame to another.
  • CKOBJ - finds the set of ID codes for all objects in a specified CK file.
  • CKCOV - finds the coverage window for a specified object in a specified CK file.
  • CKGP - gets pointing for a specified CK ID at a specified SCLK time.
  • CKGPAV - gets pointing and angular velocity for a specified CK ID at a specified SCLK time.

Brief Example:

   The following example computes orientation of the CASSINI spacecraft
   provided in CK files using the Frames subsystem routine PXFORM:

            DOUBLE PRECISION   ET
            DOUBLE PRECISION   MAT (3,3)

      C
      C     Load kernels: LSK, CASSINI SCLK, FK and CK 
      C
            CALL FURNSH ( 'naif0008.tls' )
            CALL FURNSH ( 'cas00101.tsc' )
            CALL FURNSH ( 'cas_v39.tf' )
            CALL FURNSH ( '05362_06002ra.bc' )
      
      C
      C     Convert UTC to ET 
      C
            CALL STR2ET ( '2005-DEC-28 12:00', ET )

      C
      C     Compute orientation of CASSINI relative to J2000 frame 
      C
            CALL PXFORM ( 'J2000', 'CASSINI_SC_COORD', ET, MAT )

Reference documents:

  • ck.req - reference on spacecraft orientation (CK) subsystem of SPICE
  • frames.req - reference on Frames Kernel (FK) and Frames subsystem of SPICE
  • kernel.req - reference on loading/unloading kernels and text kernel format

Top

Retrieving Instrument Parameters (IK)

APIs:

  • FURNSH - loads individual kernels and collections of kernels.
  • GETFOV - returns the field-of-view (FOV) configuration for a specified instrument.
  • GDPOOL - returns the double precision value of a kernel variable from the kernel pool.
  • GIPOOL - returns the integer value of a kernel variable from the kernel pool.
  • GCPOOL - returns the character value of a kernel variable from the kernel pool.

Brief Example:

   The following example retrieves the M01 THEMIS IR camera focal
   length and FOV parameters:

            LOGICAL            FOUND
            CHARACTER*(32)     FRAME
            CHARACTER*(32)     SHAPE
            DOUBLE PRECISION   FL
            DOUBLE PRECISION   BSIGHT (3)
            DOUBLE PRECISION   BOUNDS (3,4)
            INTEGER            N

      C
      C     Load THEMIS IK 
      C
            CALL FURNSH ( 'm01_themis_v31.ti' )

      C
      C     Retrieve M01 THEMIS IR camera pixel size 
      C
            CALL GDPOOL ( 'INS-53031_FOCAL_LENGTH', 1, 1, 
           .              N, FL, FOUND )

      C
      C     Retrieve M01 THEMIS IR FOV parameters 
      C
            CALL GETFOV ( -53031, 4, SHAPE, FRAME, BSIGHT, N, 
           .              BOUNDS )

Reference documents:

  • kernel.req - reference on loading/unloading kernels and text kernel format

Top

Computing surface coordinates using digital shape (DSK)

APIs:

  • FURNSH - loads individual kernels and collections of kernels.
  • LATSRF - maps an array of planetocentric longitude/latitude coordinate pairs to surface points on a body, modeled as an ellipsoid or a digital shape (DSK).
  • SRFNRM - maps an array of surface points on a body, modeled as an ellipsoid or a digital shape (DSK), to the corresponding outward surface normal vectors.
  • DSKZ02 - returns plate model size parameters (plate count and vertex count) for a type 2 DSK segment.
  • DSKP02 - returns triangular plates from a type 2 DSK segment.
  • DSKV02 - returns vertices from a type 2 DSK segment.
  • DSKOBJ - returns the set of body ID codes of all objects for which data are provided in a DSK file.
  • DSKSRF - returns the set of surface ID codes for all surfaces associated with a body in a DSK file.

Brief Example:

   The following example computes surface points and normals for 
   for a one-degree longitude/latitude grid on Phobos modeled by 
   a DSK:

            INTEGER               N
            INTEGER               I
            INTEGER               J
            DOUBLE PRECISION      GRID   ( 2, 360 * 179 )
            DOUBLE PRECISION      SRFPTS ( 3, 360 * 179 )
            DOUBLE PRECISION      NORMLS ( 3, 360 * 179 )

            DOUBLE PRECISION      RPD

      C
      C     Load generic PCK and Phobos DSK.
      C
            CALL FURNSH ( 'pck00010.tpc' )
            CALL FURNSH ( 'phobos512.bds' )

      C
      C     Generate longitude/latitude pairs of the grid (without 
      C     poles).
      C
            N = 0
            DO I = 1, 360
               DO J = 1, 179
                  N   = N + 1
                  GRID(1,N) = RPD() *   I
                  GRID(2,N) = RPD() * ( J - 90 )
               END DO
            END DO

      C
      C     Compute surface points based on DSK.
      C
            CALL LATSRF ( 'DSK/UNPRIORITIZED', 'PHOBOS', 0.D0,
           .              'IAU_PHOBOS', N, GRID, SRFPTS(1,1) )

      C
      C     Compute surface normals based on DSK.
      C
            CALL SRFNRM ( 'DSK/UNPRIORITIZED', 'PHOBOS', 0.D0, 
           .              'IAU_PHOBOS', N, SRFPTS(1,1), NORMLS(1,1) )

Reference documents:

  • dsk.req - reference on Digital Shape Kernels (DSK) subsystem of SPICE
  • kernel.req - reference on loading/unloading kernels and text kernel format

Top

Mapping Between Object Names and NAIF IDs

APIs:

  • FURNSH - loads individual kernels and collections of kernels.
  • BODC2N - translates the NAIF integer code of a body into a common name for that body.
  • BODN2C - translates the name of a body or object to the corresponding NAIF integer ID code.

Brief Example:

   The following example uses BODN2C to get the NAIF ID for Phobos
   (built into the SPICE system) and for the M01 THEMIS IR camera
   (defined in the M01 FK file):

            LOGICAL            FOUND
            INTEGER            PHOBID
            INTEGER            THIRID

      C
      C     Load FK defining M01 name-ID mappings       
      C
            CALL FURNSH ( 'm01_v28.tf' )

      C
      C     Get NAIF ID for PHOBOS 
      C
            CALL BODN2C ( 'PHOBOS', PHOBID, FOUND )

      C
      C     Get NAIF ID for THEMIS IR camera 
      C
            CALL BODN2C ( 'M01_THEMIS_IR', THIRID, FOUND )

Reference documents:

  • naif_ids.req - reference on object names and IDs supported in SPICE
  • kernel.req - reference on loading/unloading kernels and text kernel format

Top

Mapping between surface names and NAIF IDs

APIs:

  • FURNSH - loads individual kernels and collections of kernels.
  • SRFCSS - translates a surface ID code, together with a body name, to the corresponding surface name.
  • SRFS2C - translates a surface string, together with a body name, to the corresponding surface ID code.
  • SRFC2S - translates a surface ID code, together with a body ID code, to the corresponding surface name.
  • SRFSCC - translates a surface string, together with a body ID code, to the corresponding surface ID code.

Brief Example:

   The following example uses SRFS2C to get the surface ID for 
   the 67P/Churyumov-Gerasimenko DSK surface named 
   'ROS_CG_M001_OMSDLAM_N_V1':

            LOGICAL            FOUND
            INTEGER            SURFID

      C
      C     Load ROS FK defining surface name-ID mappings       
      C
            CALL FURNSH ( 'ROS_V25.TF' )

      C
      C     Get NAIF ID for the surface 'ROS_CG_M001_OMSDLAM_N_V1'
      C
            CALL SRFS2C ( 'ROS_CG_M001_OMSDLAM_N_V1', 
           .              '67P/C-G', 
           .              SURFID, FOUND )

Reference documents:

  • dsk.req - reference on Digital Shape Kernels (DSK) subsystem of SPICE
  • naif_ids.req - reference on object names and IDs supported in SPICE
  • kernel.req - reference on loading/unloading kernels and text kernel format

Top

Computing Planetocentric, Planetodetic, and Planetographic Coordinates

APIs:

  • RECLAT - converts from rectangular to planetocentric coordinates.
  • LATREC - converts from planetocentric to rectangular coordinates.
  • SRFREC - converts from planetocentric lat/lon of a surface point on a body to rectangular coordinates.
  • RECGEO - converts from rectangular to geodetic coordinates.
  • GEOREC - converts from geodetic to rectangular coordinates.
  • RECPGR - converts from rectangular to planetographic coordinates.
  • PGRREC - converts from planetographic to rectangular coordinates.

Brief Example:

   The following example computes the planetocentric, planetodetic and
   planetographic coordinates for a point given as a Cartesian vector
   with respect to Mars in the Mars body-fixed frame (IAU_MARS):

            DOUBLE PRECISION   VEC   (3)
            DOUBLE PRECISION   RADII (3)
            DOUBLE PRECISION   F
            DOUBLE PRECISION   PCR
            DOUBLE PRECISION   PCLON
            DOUBLE PRECISION   PCLAT
            DOUBLE PRECISION   PDALT
            DOUBLE PRECISION   PDLON
            DOUBLE PRECISION   PDLAT
            DOUBLE PRECISION   PGALT
            DOUBLE PRECISION   PGLON
            DOUBLE PRECISION   PGLAT
            INTEGER            N

      C
      C     Load PCK file 
      C
            CALL FURNSH( 'pck00008.tpc' )

      C
      C     Retrieve MARS RADII 
      C
            CALL BODVRD( 'MARS', 'RADII', 3, N, RADII )
            F = (RADII(1)-RADII(3))/RADII(1)

      C
      C     Package 3D vector 
      C
            CALL VPACK ( 3373.850D0, -351.034D0, -117.267D0, 
           .              VEC )

      C
      C     Compute planetocentric coordinates 
      C
            CALL RECLAT( VEC, PCR, PCLON, PCLAT )

      C
      C     Compute planetodetic coordinates 
      C
            CALL RECGEO( VEC, RADII(1), F, PDLON, PDLAT, PDALT )

      C
      C     Compute planetographic coordinates 
      C
            CALL RECPGR( 'MARS', VEC, RADII(1), F, PGLON, 
           .              PGLAT, PGALT )

Reference documents:

  • pck.req - reference on Planetary Constants Kernel (PCK) subsystem of SPICE

Top

Computing Surface Intercept Point

APIs:

  • SINCPT - computes the surface intercept point of the ray on a body, modeled as an ellipsoid or a digital shape (DSK), at a specified epoch.
  • DSKXV - computes ray-surface intercepts for a set of rays, using data provided by multiple loaded DSK segments.
  • DSKXSI - computes a ray-surface intercept using data provided by multiple loaded DSK segments and returns information about the source of the data defining the surface on which the intercept was found.

Brief Example:

   The following example computes the surface intercept point of the
   MGS MOC NA camera boresight with the surface of Mars modeled as
   an ellipsoid:

            LOGICAL            FOUND
            CHARACTER*(32)     FRAME
            CHARACTER*(32)     SHAPE
            DOUBLE PRECISION   ET
            DOUBLE PRECISION   BSIGHT (3)
            DOUBLE PRECISION   BOUNDS (3,4)
            DOUBLE PRECISION   SPOINT (3)
            DOUBLE PRECISION   TRGEPC
            DOUBLE PRECISION   SRFVEC (3)
            INTEGER            N

      C
      C     Load kernels: LSK, PCK, MGS SCLK, planet/satellite 
      C     ephemeris SPK, MGS spacecraft SPK, MGS spacecraft
      C     CK, MGS FK, and MOC IK
      C
            CALL FURNSH ( 'naif0008.tls'           )
            CALL FURNSH ( 'mars_iau2000_v0.tpc'    )
            CALL FURNSH ( 'mgs_sclkscet_00061.tsc' )
            CALL FURNSH ( 'mar063.bsp'             )
            CALL FURNSH ( 'mgs_ext22.bsp'          )
            CALL FURNSH ( 'mgs_sc_ext22.bc'        )
            CALL FURNSH ( 'mgs_v10.tf'             )
            CALL FURNSH ( 'mgs_moc_v20.ti'         )

      C
      C     Retrieve MOC NA camera boresight direction 
      C
            CALL GETFOV ( -94031, 4, SHAPE, FRAME, BSIGHT, N, 
           .              BOUNDS )

      C
      C     Convert UTC to ET 
      C
            CALL STR2ET ( '2006 JAN 31 01:00', ET )

      C
      C     Compute surface intercept point 
      C
            CALL SINCPT ( 'ELLIPSOID', 'MARS', ET, 'IAU_MARS',
           .              'CN+S', 'MGS', FRAME, BSIGHT,
           .              SPOINT, TRGEPC, SRFVEC, FOUND )

Top

Computing Sub-observer and Sub-solar Points

APIs:

  • SUBPNT - computes the sub-observer point on a body, modeled as an ellipsoid or a digital shape (DSK), at a particular epoch.
  • SUBSLR - computes the sub-solar point on a body, modeled as an ellipsoid or a digital shape (DSK), as seen by an observer at a particular epoch.

Brief Example:

   The following example computes the sub-spacecraft and sub-solar
   points on Mars, modeled as an ellipsoid, for MGS:

            DOUBLE PRECISION   ET
            DOUBLE PRECISION   SCRAFT (3)
            DOUBLE PRECISION   SSOLAR (3)
            DOUBLE PRECISION   SRFVEC (3)
            DOUBLE PRECISION   TRGEPC

      C
      C     Load kernels: LSK, PCK, planet/satellite SPK
      C     and MGS spacecraft SPK
      C
            CALL FURNSH ( 'naif0008.tls'         )
            CALL FURNSH ( 'mars_iau2000_v0.tpc'  )
            CALL FURNSH ( 'mar063.bsp'           )
            CALL FURNSH ( 'mgs_ext22.bsp'        )

      C
      C     Convert UTC to ET 
      C
            CALL STR2ET ( '2006 JAN 31 01:00', ET )

      C
      C     Compute sub-spacecraft point 
      C
            CALL SUBPNT ( 'Near point: ellipsoid', 'MARS',  
           .              ET, 'IAU_MARS', 'LT+S', 'MGS', 
           .              SCRAFT, TRGEPC, SRFVEC )

      C
      C     Compute sub-solar point 
      C
            CALL SUBSLR ( 'Near point: ellipsoid', 'MARS',  
           .              ET, 'IAU_MARS', 'LT+S', 'MGS', 
           .              SSOLAR, TRGEPC, SRFVEC )

Top

Computing Illumination Angles

APIs:

  • ILUMIN - computes the illumination angles at a specified surface point of a target body, modeled as an ellipsoid or a digital shape (DSK), as seen from an observer body, illuminated by the Sun.
  • ILLUMG - computes the illumination angles at a specified surface point of a target body, modeled as an ellipsoid or a digital shape (DSK), as seen from an observer body, illuminated by a user specified body.
  • ILLUMF - computes the illumination angles at a specified surface point of a target body, modeled as an ellipsoid or a digital shape (DSK), as seen from an observer body, illuminated by a user specified body, with flags indicating whether the point is visible from the observer and whether it is illuminated.
  • PHASEQ - computes the apparent phase angle between the centers of target, observer, and illuminator ephemeris objects.

Brief Example:

   The following example computes the illumination angles for a point
   specified using planetocentric coordinates, observed by MGS:

            DOUBLE PRECISION   R
            DOUBLE PRECISION   LON
            DOUBLE PRECISION   LAT
            DOUBLE PRECISION   POINT  (3)
            DOUBLE PRECISION   ET
            DOUBLE PRECISION   PHASE
            DOUBLE PRECISION   SOLAR
            DOUBLE PRECISION   EMISSN
            DOUBLE PRECISION   TRGEPC
            DOUBLE PRECISION   SRFVEC (3)

            DOUBLE PRECISION   RPD

            R   = 3390.42D0
            LON =  175.30D0
            LAT =  -14.59D0
      C
      C     Load kernels: LSK, PCK, planet/satellite SPK
      C     and MGS spacecraft SPK 
      C
            CALL FURNSH ( 'naif0008.tls'         )
            CALL FURNSH ( 'mars_iau2000_v0.tpc'  )
            CALL FURNSH ( 'mar063.bsp'           )
            CALL FURNSH ( 'mgs_ext22.bsp'        )

      C
      C     Convert planetocentric r/lon/lat to Cartesian vector 
      C
            CALL LATREC( R, LON * RPD(), LAT * RPD(), POINT )

      C
      C     Convert UTC to ET 
      C
            CALL STR2ET ( '2006 JAN 31 01:00', ET )

      C
      C     Compute illumination angles, modeling Mars as
      C     an ellipsoid
      C
            CALL ILUMIN ( 'Ellipsoid', 'MARS', ET, 'IAU_MARS',
           .              'LT+S', 'MGS', POINT, 
           .              TRGEPC, SRFVEC, PHASE, SOLAR, EMISSN )

Top

Computing limb and terminator

APIs:

  • LIMBPT - computes limb points on a body, modeled as an ellipsoid or a digital shape (DSK).
  • TERMPT - computes umbral or penumbral terminator points on a body, modeled as an ellipsoid or a digital shape (DSK).

Brief Example:

   The following example computes the apparent limb points on 
   Phobos, modeled by a DSK, as seen from Mars:

            INTEGER               MAXN
            PARAMETER           ( MAXN = 10000 )

            DOUBLE PRECISION      ET
            DOUBLE PRECISION      Z      ( 3 )
            INTEGER               NPTS   ( MAXN )
            DOUBLE PRECISION      POINTS ( 3, MAXN )
            DOUBLE PRECISION      TRGEPS ( MAXN )
            DOUBLE PRECISION      TANGTS ( 3, MAXN )

            DOUBLE PRECISION      DPR

            DATA                  Z      / 0.D0, 0.D0, 1.D0 /

      C
      C     Load kernels: LSK, PCK, planet/satellite SPK
      C     and Phobos DSK
      C
            CALL FURNSH ( 'naif0011.tls'  )
            CALL FURNSH ( 'pck00010.tpc'  )
            CALL FURNSH ( 'de430.bsp'     )
            CALL FURNSH ( 'mar097.bsp'    )
            CALL FURNSH ( 'phobos512.bds' )

      C
      C     Convert UTC to ET 
      C
            CALL STR2ET ( '2008 AUG 11 00:00:00', ET )

      C
      C     Compute limps points in 360 cutting half-planes 
      C     spaced 1 degree apart about the Mars-Phobos 
      C     direction.
      C
            CALL LIMBPT ( 'TANGENT/DSK/UNPRIORITIZED', 'PHOBOS', ET,
           .              'IAU_PHOBOS', 'CN+S', 'CENTER', 'MARS', Z,
           .              1.D0/DPR(), 360,  1.D-4, 1.D-7, MAXN, 
           .              NPTS, POINTS, TRGEPS, TANGTS )

Top

Computing and Propagating Orbital Elements

APIs:

  • CONICS - determines the state of an orbiting body from a set orbital elements.
  • OSCELT - determines the set of orbital elements corresponding to the state of a body.

Brief Example:

   The following example computes the set of orbital elements for the
   state of the Mars Express spacecraft at a given time:

            INTEGER            N
            DOUBLE PRECISION   GM
            DOUBLE PRECISION   ET
            DOUBLE PRECISION   STATE (6)
            DOUBLE PRECISION   LT
            DOUBLE PRECISION   ELTS  (8)

      C
      C     Load kernels: LSK, MEX trajectory SPK, and gravity PCK 
      C
            CALL FURNSH ( 'NAIF0008.TLS'                 )
            CALL FURNSH ( 'ORMM__050901000000_00165.BSP' )
            CALL FURNSH ( 'DE403-MASSES.TPC'             )

      C
      C     Retrieve GM for Mars 
      C
            CALL BODVRD ( 'MARS', 'GM', 1, N, GM )

      C
      C     Convert UTC to ET 
      C
            CALL STR2ET ( '2005 SEP 02 04:50:45', ET )

      C
      C     Compute state of MEX at given UTC 
      C
            CALL SPKEZR ( 'MEX', ET, 'MARSIAU', 'NONE', 'MARS', 
           .              STATE, LT )

      C
      C     Compute orbital elements 
      C
            CALL OSCELT ( STATE, ET, GM, ELTS )

Top

Checking for in Field-Of-View (FOV) conditions

APIs:

  • FOVRAY - determines if a specified ray is within the FOV of a specified instrument at a given time.
  • FOVTRG - determines if a specified ephemeris object is within the FOV of a specified instrument at a given time.

Brief Example:

   The following example determines if Phoebe is in the CASSINI
   ISS NAC FOV on 2004-06-11 18:00 UTC:

            DOUBLE PRECISION      ET
            LOGICAL               VISIBL

      C        
      C     Load kernels.
      C
            CALL FURNSH( 'cas_2004_v17.tm' )

      C
      C     Convert UTC to ET.
      C
            CALL STR2ET ( '2004-06-11 18:00', ET )
 
      C
      C     Check for in-FOV condition.
      C
            CALL FOVTRG ( 'CASSINI_ISS_NAC', 'PHOEBE', 
           .              'ELLIPSOID', 'IAU_PHOEBE', 'CN+S', 
           .              'CASSINI', ET, VISIBL )

Top

Checking for occultation conditions

APIs:

  • OCCULT - determines the occultation condition (not occulted, partially, etc.) of one target relative to another target as seen by an observer at a given time, with targets modeled as points, ellipsoids, or digital shapes (DSK).

Brief Example:

   The following example determines if the Sun is occulted by Saturn as
   seen from CASSINI on 2005-05-03 06:00 UTC, with both Sun and Saturn
   modeled as ellipsoids:

            DOUBLE PRECISION      ET
            INTEGER               OCLTID

      C        
      C     Load kernels.
      C
            CALL FURNSH( 'cas_2005_v18.tm' )

      C
      C     Convert UTC to ET.
      C
            CALL STR2ET ( '2005-05-03 06:00', ET )

      C
      C     Check for in-FOV condition.
      C
            CALL OCCULT ( 'SATURN', 'ELLIPSOID', 'IAU_SATURN', 
     .                    'SUN',    'ELLIPSOID', 'IAU_SUN', 
     .                    'CN',     'CASSINI',    ET,  OCLTID )

            IF ( OCLTID .GT. 0 ) THEN
               WRITE(*,*) 'CASSINI IS IN SATURN SHADOW."
            END IF

Top

Finding times of events satisfying numerical constraints

APIs:

  • GFDIST - determines time intervals when a specified constraint on observer-target distance is met.
  • GFILUM - determines time intervals when a specified constraint on the observed phase, solar incidence, or emission angle at a surface point is met.
  • GFPA - determines time intervals when a specified constraint on the phase angle between the illuminator, target, and observer body centers is met.
  • GFPOSC - determines time intervals when a coordinate of an observer-target position vector satisfies a numerical constraint.
  • GFRR - determines time intervals when a specified constraint on the observer-target range rate is met.
  • GFSEP - determines time intervals when the angular separation between the position vectors of two target bodies relative to an observer satisfies a numerical relationship.
  • GFSNTC - determines time intervals when a coordinate of a ray-surface intercept position vector satisfies a numerical constraint.
  • GFSUBC - determines time intervals when a coordinate of a sub-observer point position vector satisfies a numerical constraint.

Brief Example:

   The following example determines time intervals between Jan 1 and
   and April 1, 2007 when the distance between the Moon and the Earth
   was greater than 400,000 km.

            INCLUDE 'gf.inc'

            DOUBLE PRECISION      SPD

            INTEGER               LBCELL
            PARAMETER           ( LBCELL = -5 )

            INTEGER               MAXWIN
            PARAMETER           ( MAXWIN = 20000 )

            DOUBLE PRECISION      ADJUST
            DOUBLE PRECISION      CNFINE ( LBCELL : 2 )
            DOUBLE PRECISION      ET0
            DOUBLE PRECISION      ET1
            DOUBLE PRECISION      REFVAL
            DOUBLE PRECISION      RESULT ( LBCELL : MAXWIN )
            DOUBLE PRECISION      STEP
            DOUBLE PRECISION      WORK   ( LBCELL : MAXWIN, NWDIST )

      C
      C     Load kernels.
      C
            CALL FURNSH( 'naif0008.tls' )
            CALL FURNSH( 'de421.bsp'    )

      C
      C     Initialize windows.
      C
            CALL SSIZED ( MAXWIN, RESULT )
            CALL SSIZED ( 2,      CNFINE )

      C
      C     Store the time bounds in the confinement window.
      C
            CALL STR2ET ( '2007 JAN 1', ET0 )
            CALL STR2ET ( '2007 APR 1', ET1 )

            CALL WNINSD ( ET0, ET1, CNFINE )

      C
      C     Set search parameters. Use a step size of 1 day (in 
      C     units of seconds).
      C
            STEP   = SPD()
            REFVAL = 4.D5
            ADJUST = 0.D0

      C
      C     Perform search.
      C
            CALL GFDIST ( 'MOON', 'NONE', 'EARTH', '>',   
           .              REFVAL, ADJUST, STEP,    CNFINE, 
           .              MAXWIN, NWDIST, WORK,    RESULT )

Reference documents:

  • gf.req - reference on the Geometry Finder (GF) subsystem of SPICE

Top

Finding times of events satisfying FOV constraints

APIs:

  • GFRFOV - determines time intervals when a specified ray intersects the space bounded by the field-of-view (FOV) of a specified instrument.
  • GFTFOV - determines time intervals when a specified ephemeris object intersects the space bounded by the field-of-view (FOV) of a specified instrument.

Brief Example:

   The following example determines time intervals between 09:00 and
   11:15 UTC on Jun 11, 2004 when Saturn's satellite Phoebe was within
   the FOV of the Cassini narrow angle camera (CASSINI_ISS_NAC).

            INTEGER               LBCELL
            PARAMETER           ( LBCELL = -5 )
 
            INTEGER               MAXWIN
            PARAMETER           ( MAXWIN = 10000 )

            DOUBLE PRECISION      CNFINE ( LBCELL : MAXWIN )
            DOUBLE PRECISION      ET0
            DOUBLE PRECISION      ET1
            DOUBLE PRECISION      RESULT ( LBCELL : MAXWIN )
            DOUBLE PRECISION      STEPSZ

      C        
      C     Load kernels.
      C
            CALL FURNSH( 'naif0009.tls'               )
            CALL FURNSH( 'cpck05Mar2004.tpc'          )
            CALL FURNSH( '981005_PLTEPH-DE405S.bsp'   )
            CALL FURNSH( '020514_SE_SAT105.bsp'       )
            CALL FURNSH( '030201AP_SK_SM546_T45.bsp'  )
            CALL FURNSH( 'cas_v37.tf'                 )
            CALL FURNSH( '04135_04171pc_psiv2.bc'     )
            CALL FURNSH( 'cas00084.tsc'               )
            CALL FURNSH( 'cas_iss_v09.ti'             )

      C
      C     Initialize windows.
      C
            CALL SSIZED ( MAXWIN, CNFINE )
            CALL SSIZED ( MAXWIN, RESULT )

      C
      C     Insert search time interval bounds into the
      C     confinement window.
      C
            CALL STR2ET ( '2004 JUN 11 09:00', ET0 )
            CALL STR2ET ( '2004 JUN 11 11:15', ET1 )
 
            CALL WNINSD ( ET0, ET1, CNFINE )

      C        
      C     Set search parameters. Use a step size of 
      C     10 seconds.
      C
            STEPSZ = 10.D0

      C
      C     Perform the search.
      C
            CALL GFTFOV ( 'CASSINI_ISS_NAC', 'PHOEBE', 'ELLIPSOID', 
           .              'IAU_PHOEBE', 'LT+S', 'CASSINI', STEPSZ, 
           .              CNFINE, RESULT )

Reference documents:

  • gf.req - reference on the Geometry Finder (GF) subsystem of SPICE

Top

Finding times of occultations

APIs:

  • GFOCLT - determines time intervals when an observer sees one target occulted by another, with targets modeled as points, ellipsoids, or digital shapes (DSK).

Brief Example:

   The following example determines time intervals in December, 2001
   when the Sun is occulted by the Moon (solar eclipses) as seen from
   the center of the Earth, with both Sun and Moon modeled as 
   ellipsoids:

            INTEGER               LBCELL
            PARAMETER           ( LBCELL = -5 )

            INTEGER               MAXWIN
            PARAMETER           ( MAXWIN = 2 * 100 )

            DOUBLE PRECISION      CNFINE ( LBCELL : MAXWIN )
            DOUBLE PRECISION      ET0
            DOUBLE PRECISION      ET1
            DOUBLE PRECISION      RESULT ( LBCELL : MAXWIN )
            DOUBLE PRECISION      STEP

      C        
      C     Load kernels.
      C        
            CALL FURNSH( 'naif0008.tls'  )
            CALL FURNSH( 'de421.bsp'     )
            CALL FURNSH( 'pck00008.tpc'  )

      C
      C     Initialize the confinement and result windows.
      C
            CALL SSIZED ( MAXWIN, CNFINE )
            CALL SSIZED ( MAXWIN, RESULT )

      C
      C     Insert the time bounds into the confinement
      C     window.
      C
            CALL STR2ET ( '2001 DEC 01', ET0 )
            CALL STR2ET ( '2002 JAN 01', ET1 )

            CALL WNINSD ( ET0, ET1, CNFINE )

      C
      C     Select a 3-minute step. We'll ignore any occultations
      C     lasting less than 3 minutes.
      C
            STEP = 180.D0

      C
      C     Perform the search.
      C
            CALL GFOCLT ( 'ANY',
           .              'MOON',  'ELLIPSOID', 'IAU_MOON',
           .              'SUN',   'ELLIPSOID', 'IAU_SUN',
           .              'LT',    'EARTH',     STEP,  
           .              CNFINE,  RESULT                  )

Reference documents:

  • gf.req - reference on the Geometry Finder (GF) subsystem of SPICE

Top

Converting from and to rectangular coordinates

APIs:

  • RECLAT - converts from rectangular to latitudinal coordinates.
  • LATREC - converts from latitudinal to rectangular coordinates.
  • SRFREC - converts from planetocentric lat/lon of a surface point on a body to rectangular coordinates.
  • RECGEO - converts from rectangular to geodetic coordinates.
  • GEOREC - converts from geodetic to rectangular coordinates.
  • RECPGR - converts from rectangular to planetographic coordinates.
  • PGRREC - converts from planetographic to rectangular coordinates.
  • RECRAD - converts from rectangular coordinates to range, right ascension, and declination.
  • RADREC - converts from range, right ascension, and declination to rectangular coordinates.
  • RECSPH - converts from rectangular to spherical coordinates.
  • SPHREC - converts from spherical to rectangular coordinates.
  • RECCYL - converts from rectangular to cylindrical coordinates.
  • CYLREC - converts from cylindrical to rectangular coordinates.

Brief Example:

   The following example computes the planetocentric, planetodetic and
   planetographic coordinates for a point given as a Cartesian vector
   with respect to Mars in the Mars body-fixed frame (IAU_MARS):

            DOUBLE PRECISION   VEC   (3)
            DOUBLE PRECISION   RADII (3)
            DOUBLE PRECISION   F
            DOUBLE PRECISION   PCR
            DOUBLE PRECISION   PCLON
            DOUBLE PRECISION   PCLAT
            DOUBLE PRECISION   PDALT
            DOUBLE PRECISION   PDLON
            DOUBLE PRECISION   PDLAT
            DOUBLE PRECISION   PGALT
            DOUBLE PRECISION   PGLON
            DOUBLE PRECISION   PGLAT
            INTEGER            N

      C
      C     Load PCK file 
      C
            CALL FURNSH( 'pck00008.tpc' )

      C
      C     Retrieve MARS RADII 
      C
            CALL BODVRD( 'MARS', 'RADII', 3, N, RADII )
            F = (RADII(1)-RADII(3))/RADII(1)

      C
      C     Pack 3D vector 
      C
            CALL VPACK ( 3373.850D0, -351.034D0, -117.267D0, VEC )

      C
      C     Compute planetocentric coordinates 
      C
            CALL RECLAT( VEC, PCR, PCLON, PCLAT )

      C
      C     Compute planetodetic coordinates 
      C
            CALL RECGEO( VEC, RADII(1), F, PDLON, PDLAT, PDALT )

      C
      C     Compute planetographic coordinates 
      C
            CALL RECPGR( 'MARS', VEC, RADII(1), F, PGLON, PGLAT, 
           .             PGALT )

Top

Converting from and to Spherical Coordinates

APIs:

  • SPHREC - converts from spherical to rectangular coordinates.
  • RECSPH - converts from rectangular to spherical coordinates.
  • SPHCYL - converts from spherical to cylindrical coordinates.
  • CYLSPH - converts from cylindrical to spherical coordinates.
  • SPHLAT - converts from spherical to latitudinal coordinates.
  • LATSPH - converts from latitudinal to spherical coordinates.

Brief Example:

   The following example computes the spherical coordinates of a point
   specified as a Cartesian vector:

            DOUBLE PRECISION   VEC (3)
            DOUBLE PRECISION   R
            DOUBLE PRECISION   COLAT
            DOUBLE PRECISION   LON

            CALL VPACK  ( 1.0D0, 1.0D0, 1.0D0, VEC )

            CALL RECSPH ( VEC, R, COLAT, LON )

Top

Converting from and to cylindrical coordinates

APIs:

  • CYLREC - converts from cylindrical to rectangular coordinates.
  • RECCYL - converts from rectangular to cylindrical coordinates.
  • CYLSPH - converts from cylindrical to spherical coordinates.
  • SPHCYL - converts from spherical to cylindrical coordinates.
  • CYLLAT - converts from cylindrical to latitudinal coordinates.
  • LATCYL - converts from latitudinal to cylindrical coordinates.

Brief Example:

   The following example computes the cylindrical coordinates of a
   point specified as a Cartesian vector:

            DOUBLE PRECISION   VEC (3)
            DOUBLE PRECISION   R
            DOUBLE PRECISION   LON
            DOUBLE PRECISION   Z

            CALL VPACK  ( 1.0D0, 1.0D0, 1.0D0, VEC )

            CALL RECCYL ( VEC, R, LON, Z )

Top

Converting from and to Latitudinal Coordinates

APIs:

  • LATREC - converts from latitudinal to rectangular coordinates.
  • RECLAT - converts from rectangular to latitudinal coordinates.
  • LATSPH - converts from latitudinal to spherical coordinates.
  • SPHLAT - converts from spherical to latitudinal coordinates.
  • LATCYL - converts from latitudinal to cylindrical coordinates.
  • CYLLAT - converts from cylindrical to latitudinal coordinates.

Brief Example:

   The following example converts the planetocentric coordinates of a
   point to a Cartesian vector:
      
            DOUBLE PRECISION   VEC (3)
            DOUBLE PRECISION   R
            DOUBLE PRECISION   LON
            DOUBLE PRECISION   LAT

            DOUBLE PRECISION   RPD

            R   = 3390.42D0
            LON =  175.30D0
            LAT =  -14.59D0

            CALL LATREC( R, LON * RPD(), LAT * RPD(), VEC )

Top

Converting from and to R, RA, and DEC

APIs:

  • RADREC - converts from range, right ascension, and declination to rectangular coordinates.
  • RECRAD - converts from rectangular coordinates to range, right ascension, and declination.

Brief Example:

   The following example computes the unit vector corresponding to an
   RA and DEC given in degrees:

            DOUBLE PRECISION   RA
            DOUBLE PRECISION   DEC
            DOUBLE PRECISION   VEC(3)

            DOUBLE PRECISION   RPD
 
            RA  = 120.0D0
            DEC = -30.0D0

            CALL RADREC( 1.0, RA * RPD(), DEC * RPD(), VEC )

Top

Converting from and to Geodetic Coordinates

APIs:

  • GEOREC - converts from geodetic to rectangular coordinates.
  • RECGEO - converts from rectangular to geodetic coordinates.

Brief Example:

   The following example converts the areodetic coordinates of a
   landing site (Lon = 175.3 deg, Lat = -14.59 deg, Alt = -1.91 km),
   given relative to the IAU 2000 Mars ellipsoid, to a Cartesian
   vector:

            DOUBLE PRECISION   LON
            DOUBLE PRECISION   LAT
            DOUBLE PRECISION   ALT
            DOUBLE PRECISION   RADII (3)
            DOUBLE PRECISION   F
            DOUBLE PRECISION   VEC   (3)
            INTEGER            N

            DOUBLE PRECISION   RPD

            CALL FURNSH( 'PCK00008.TPC' )

            CALL BODVRD( 'MARS', 'RADII', 3, N, RADII )
            F = (RADII(1)-RADII(3))/RADII(1)

            LON =  175.30D0 * RPD()
            LAT =  -14.59D0 * RPD()
            ALT =   -1.91D0

            CALL GEOREC( LON, LAT, ALT, RADII(1), F, VEC )

Top

Transforming states from one coordinate system to another

APIs:

  • XFMSTA - transforms states between coordinate systems -- rectangular, cylindrical, latitudinal, spherical, geodetic, and planetographic.

Brief Example:

   The following example converts a state specified in the 
   rectangular coordinate system (X, Y, Z, DX, DY, DZ) to 
   the state specified in the latitudinal coordinate system 
   (R, LONG, LAT, DR, DLONG, DLAT):

            DOUBLE PRECISION      ISTATE(6)
            DOUBLE PRECISION      OSTATE(6)

            ISTATE(1) = 1000.D0
            ISTATE(2) = 2000.D0
            ISTATE(3) = 3000.D0
            ISTATE(4) =   20.D0
            ISTATE(5) =  -40.D0
            ISTATE(6) =  -60.D0

            CALL XFMSTA ( ISTATE, 'RECTANGULAR', 
           .              'LATITUDINAL', ' ', 
           .              OSTATE )

            WRITE(*,*) 'R     = ', OSTATE(1), ' KM'
            WRITE(*,*) 'LONG  = ', OSTATE(2), ' RAD'
            WRITE(*,*) 'LAT   = ', OSTATE(3), ' RAD'
            WRITE(*,*) 'DR    = ', OSTATE(4), ' KM/S'
            WRITE(*,*) 'DLONG = ', OSTATE(5), ' RAD/S'
            WRITE(*,*) 'DLAT  = ', OSTATE(6), ' RAD/S'

Top

Performing simple operations on 3D vectors

APIs:

  • VPACK - packs three scalar components into a vector.
  • VUPACK - unpacks three scalar components from a vector.
  • VADD - adds two 3D vectors.
  • VSUB - computes the difference between two 3D vectors.
  • VCRSS - computes the cross product of two 3D vectors.
  • VDOT - computes the dot product of two 3D vectors.
  • VREL - returns the relative difference between two 3D vectors
  • VSCL - multiplies a scalar and a 3D vector.
  • VMINUS - negates a 3D vector.
  • VEQU - makes one 3D vector equal to another.
  • VZERO - indicates whether a 3D vector is the zero vector.
  • VSEP - finds the separation angle between two 3D vectors.
  • VDIST - returns the distance between two 3D vectors.
  • VNORM - computes the magnitude of a 3D vector.
  • VHAT - finds the unit vector along a 3D vector.
  • UCRSS - computes the normalized cross product of two 3D vectors.
  • UNORM - normalizes a 3D vector and return its magnitude.

Brief Example:

   The following example prints the angular separation between two 3D
   vectors in degrees:

            DOUBLE PRECISION   A (3)
            DOUBLE PRECISION   B (3)

            DOUBLE PRECISION   VSEP
            DOUBLE PRECISION   DPR

            CALL VPACK( 1.0D0, 0.0D0, 0.0D0, A )
            CALL VPACK( 1.0D0, 1.0D0, 0.0D0, B )

            WRITE(*,*) 'ANGULAR SEPARATION, DEG =', VSEP(A,B) * DPR()

Top

Projecting, Combining and Rotating 3D vectors

APIs:

  • VPERP - finds the component of a 3D vector that is perpendicular to a second 3D vector.
  • VPROJ - finds the projection of one 3D vector onto another 3D vector.
  • VROTV - rotates a 3D vector about a specified axis 3D vector by a specified angle.
  • ROTVEC - transform a 3D vector to a new coordinate system rotated by an angle about X, Y, or Z.
  • VLCOM - computes the vector linear combination a*v1 + b*v2 of two 3D vectors.
  • VLCOM3 - computes the vector linear combination a*v1 + b*v2 + c*v3 of three 3D vectors.

Brief Example:

   The following example finds the projection of one 3D vector onto
   another 3D vector:

            DOUBLE PRECISION   A (3)
            DOUBLE PRECISION   B (3)
            DOUBLE PRECISION   C (3)

            CALL VPROJ( A, B, C )

Top

Performing Simple Operations on 3x3 Matrices

APIs:

  • MXM - multiplies two 3x3 matrices.
  • MXMT - multiplies a 3x3 matrix and the transpose of another 3x3 matrix.
  • MXV - multiplies a 3x3 matrix with a 3D vector.
  • MTXM - multiplies the transpose of a 3x3 matrix and a 3x3 matrix.
  • MTXV - multiplies the transpose of a 3x3 matrix on the left with a 3D vector on the right.
  • VTMV - multiplies the transpose of a 3D vector, a 3x3 matrix, and a 3D vector.
  • XPOSE - transposes a 3x3 matrix.
  • MEQU - sets one 3x3 matrix equal to another.
  • DET - computes the determinant of a 3x3 matrix.
  • TRACE - returns the trace of a 3x3 matrix.

Brief Example:

   The following example multiples two matrices and converts the
   resulting matrix to a SPICE-style quaternion:

            DOUBLE PRECISION   MAT1 (3,3)
            DOUBLE PRECISION   MAT2 (3,3)
            DOUBLE PRECISION   MAT3 (3,3)
            DOUBLE PRECISION   Q    (4)

            CALL MXM( MAT1, MAT2, MAT3 )
            CALL M2Q( MAT3, Q )

Top

Creating and Converting Transformation Matrices

APIs:

  • ROTATE - calculates the 3x3 matrix for a rotation of an angle about the X, Y or Z axis.
  • ROTMAT - applies a rotation of an angle about the X, Y, or Z axis to a matrix.
  • TWOVEC - builds the transformation to a frame based on two vectors.
  • EUL2M - constructs a rotation matrix from a set of Euler angles.
  • M2EUL - factors a matrix as a product of three rotations about specified axes.
  • RAXISA - computes the axis of the rotation given by a matrix and the angle about that axis.
  • AXISAR - construct a rotation matrix that rotates vectors by an angle about an axis.
  • M2Q - finds a unit quaternion corresponding to a specified rotation matrix.
  • Q2M - find the rotation matrix corresponding to a specified unit quaternion.

Brief Example:

   The following example creates a transformation matrix from right
   ascension, declination, and twist given in degrees:

            DOUBLE PRECISION   RA
            DOUBLE PRECISION   DEC
            DOUBLE PRECISION   TWIST
            DOUBLE PRECISION   MAT   (3,3)

            DOUBLE PRECISION   RPD

            RA    =   10.0D0
            DEC   =   20.0D0
            TWIST = -135.0D0

            RA    = RA    * RPD()
            DEC   = DEC   * RPD()
            TWIST = TWIST * RPD()

            CALL EUL2M( TWIST, HALFPI() - DEC, RA, 3, 2, 3, MAT )

Reference documents:

  • rotation.req - reference on different representations of rotation transformations

Top

Accessing Physical and Mathematical Constants

APIs:

  • HALFPI - returns half the value of pi.
  • PI - returns the value of pi.
  • TWOPI - returns twice the value of pi.
  • DPR - returns the number of degrees per radian.
  • RPD - returns the number of radians per degree.
  • SPD - returns the number of seconds in a day.
  • JYEAR - returns the number of seconds per Julian year.
  • TYEAR - returns the number of seconds per tropical year.
  • CLIGHT - returns the speed of light in vacuo (km/sec)
  • B1900 - returns the Julian Date corresponding to Besselian date 1900.0.
  • B1950 - returns the Julian Date corresponding to Besselian date 1950.0.
  • J1900 - returns the Julian Date of 1899 DEC 31 12:00:00 (1900 JAN 0.5).
  • J1950 - returns the Julian Date of 1950 JAN 01 00:00:00 (1950 JAN 1.0).
  • J2000 - returns the Julian Date of 2000 JAN 01 12:00:00 (2000 JAN 1.5).
  • J2100 - returns the Julian Date of 2100 JAN 01 12:00:00 (2100 JAN 1.5).

Brief Example:

   The following example sets angle to pi/2 and prints it in degrees:

            DOUBLE PRECISION   ANGLE

            DOUBLE PRECISION   HALFPI
            DOUBLE PRECISION   DPR

            ANGLE = HALFPI()

            WRITE(*,*) 'ANGLE, DEG = ', ANGLE * DPR()