Index Page
cspice_pxfrm2
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


   CSPICE_PXFRM2 returns the 3x3 matrix that transforms 
   position vectors from one specified frame at a specified 
   epoch to another specified frame at another specified
   epoch.

   For important details concerning this module's function, please refer to
   the CSPICE routine pxfrm2_c.

I/O

   
   Given:
   
      from     the scalar string name of a reference frame
               recognized by cspice that corresponds to the
               input 'etfrom'.
             
      to       the scalar string name of a reference frame
               recognized by cspice that corresponds to the
               desired output at 'etto'.
      
      etfrom   the double precision scalar or N-vector of epochs
               in ephemeris seconds past the epoch of J2000 (TDB) 
               corresponding to the 'from' reference frame.
             
      etto     the double precision scalar or N-vector of epochs
               in ephemeris seconds past the epoch of J2000 (TDB)
               that corresponds to the 'to' reference frame.

   the call:
   
      cspice_pxfrm2, from, to, etfrom, etto, rotate 
   
   returns:
   
      rotate   a double precision 3x3 matrix or 3x3xN array that
               relates the reference frame 'from' at epoch 'etfrom'
               to the frame 'to' at epoch 'etto'.

               If 'from_pos' is a position relative to the reference
               frame 'from' at time 'etfrom', then the position vector
               'to_pos' is the same position relative to the frame 'to'
               at epoch 'etto'.  
   
               To perform a transformation of a position vector from
               one reference to another: 
               
               either returning DOUBLE ARRAY [1,3]
               
                  to_pos = rotate ## from_pos
               
               or the classic IDL format returning DOUBLE ARRAY[3]
               
                  to_pos = transpose(rotate) # from_pos
               
               or using the Icy 3x3 matrix, 3-vector multiplication
               routine returning DOUBLE ARRAY[3]:
               
                  cspice_mxv, rotate, from_pos, to_pos
   

Examples


    Any numerical results shown for this example may differ between
    platforms as the results depend on the SPICE kernels used as input
    and the machine specific arithmetic implementation.
    
    Example(1):

        Suppose that MGS has taken a picture of Mars at time 'etrec' with
        the MOC narrow angle camera. We want to know the latitude and
        longitude associated with two pixels projected to Mars'
        surface:  the boresight and one along the boundary of the
        field of view (FOV). Due to light time, the photons taken in
        the picture left Mars at time 'etemit', when Mars was at a
        different state than at time 'etrec'.
        
        In order to solve this problem, we could use the 'cspice_sincpt'
        routine for both pixels, but this would be slow.  Instead, we
        will assume that the light time for each pixel is the same. We
        will call 'cspice_sincpt' once to get the light time and surface point
        associated with the boresight. Then, we will rotate the first
        FOV boundary vector from the camera frame at 'etrec' to the
        body-fixed Mars frame at 'etemit', and call the faster routine
        'cspice_surfpt' to retrieve the surface point for the FOV boundary
        vector.
        
        This example problem could be extended to find the latitude
        and longitude associated with every pixel in an instrument's
        field of view, but this example is simplified to only solve
        for two pixels:  the boresight and one along the boundary of
        the field of view.
        
        Assumptions:
        
            1)  The light times from the surface points in the camera's
                field of view to the camera are equal.
            
            2)  The camera offset from the center of gravity of the
                spacecraft is zero. If the data are more accurate
                and precise, this assumption can be easily discarded.
            
            3)  An ellipsoid shape model for the target body is
                sufficient.
            
            4)  The boundary field of view vector returned from 'getfov_c'
                is associated with a boundary field of view pixel. If
                this example were extended to include a geometric camera
                model, this assumption would not be needed since the
                direction vectors associated with each pixel would be
                calculated from the geometric camera model.
        
        Use the meta-kernel shown below to load the required SPICE
        kernels.
        
            KPL/MK
            
            File name: mgs_ex.tm
            
            This is the meta-kernel file for the example problem for
            the subroutine PXFRM2. These kernel files can be found in
            the NAIF archives.
            
            In order for an application to use this meta-kernel, the
            kernels referenced here must be present in the user's
            current working directory.
            
            The names and contents of the kernels referenced
            by this meta-kernel are as follows:
            
                File name                     Contents
                ---------                     --------
                de421.bsp                     Planetary ephemeris
                pck00009.tpc                  Planet orientation and
                                              radii
                naif0009.tls                  Leapseconds
                mgs_ext12_ipng_mgs95j.bsp     MGS ephemeris
                mgs_moc_v20.ti                MGS MOC instrument
                                              parameters
                mgs_sclkscet_00061.tsc        MGS SCLK coefficients
                mgs_sc_ext12.bc               MGS s/c bus attitude
                
                \begindata
                
                KERNELS_TO_LOAD = ( 'de421.bsp',
                                 'pck00009.tpc',
                                 'naif0009.tls',
                                 'mgs_ext12_ipng_mgs95j.bsp',
                                 'mgs_moc_v20.ti',
                                 'mgs_sclkscet_00061.tsc',
                                 'mgs_sc_ext12.bc' )
            
            \begintext
        
        End of meta-kernel.
        
        Beginning of example proram.
        
        ;;
        ;; Local variables
        ;;
        ;; The meta-kernel to be loaded is the variable 'metakr'.
        
        metakr = 'mgs_ex.tm'
        
        ;;
        ;; MGS_MOC_NA is the name of the camera that took
        ;; the picture being analyzed.
        ;;
        
        camera = 'MGS_MOC_NA'
        
        ;; 
        ;; ABCORR is the desired light time and stellar
        ;; aberration correction setting.
        ;; 
        
        ABCORR = 'CN+S'
        NCORNR = 4
        
        ;;
        ;; ------------------ Program Setup ------------------
        ;;
        ;; Load kernels
        ;;
        cspice_furnsh, metakr
        
        ;; 
        ;; Convert the time the picture was taken from a
        ;; UTC time string to seconds past J2000, TDB.
        ;; 
        cspice_str2et, '2003 OCT 13 06:00:00 UTC', etrec
        
        ;;
        ;; Assume the one-way light times from different
        ;; surface points on Mars to MGS within the camera's
        ;; FOV are equal. This means the photons that make
        ;; up different pixels were all emitted from Mars at
        ;; 'etemit' and received by MGS at 'etrec'.  It would be
        ;; slow to process images using 'cspice_sincpt' for every
        ;; pixel.  Instead, we will use 'cspice_sincpt' on the
        ;; boresight pixel and use 'cspice_surfpt' for the first FOV
        ;; boundary pixel.  If this example program were extended
        ;; to include all of the camera's pixels, 'cspice_surfpt' would
        ;; be used for the remaining pixels.
        ;; 
        ;; Get the MGS MOC Narrow angle camera (MGS_MOC_NA)
        ;; ID code. Then look up the field of view (FOV)
        ;; parameters by calling 'cspice_getfov'.
        ;;
        
        cspice_bodn2c, camera, camid, found
        
        if ( ~found ) then begin
        
          print, 'SPICE(NOTRANSLATION)'  + $
                 'Could not find ID code for instrument ', camera
          return
        
        endif 
        
        ;;
        ;; 'cspice_getfov' will return the name of the camera-fixed frame
        ;; in the string 'obsref', the camera boresight vector in
        ;; the array 'bsight', and the FOV corner vectors in the
        ;; array 'bounds'.
        ;;
        
        cspice_getfov, camid, NCORNR, shape, obsref, bsight, bounds
        
        print, 'Observation Reference Frame: ', obsref
        
        ;;
        ;; ----------- Boresight Surface Intercept -----------
        ;;
        ;; Retrieve the time, surface intercept point, and vector
        ;; from MGS to the boresight surface intercept point
        ;; in IAU_MARS coordinates.
        ;;
        
        cspice_sincpt, 'Ellipsoid', 'Mars',  etrec, 'iau_mars', $
                      ABCORR,     'MGS',   obsref, bsight,    $
                      spoint,      etemit, srfvec, found
        
        if ( ~found ) then begin
        
          print, 'SPICE(NOINTERCEPT)'  + $
                 'Intercept not found for the boresight vector.'
          return
        
        endif 
        
        ;;  
        ;; Convert the intersection point of the boresight
        ;; vector and Mars from rectangular into latitudinal
        ;; coordinates. Convert radians to degrees.
        ;;
        
        cspice_reclat, spoint, radius, lon, lat
        
        lon = lon * cspice_dpr()
        lat = lat * cspice_dpr()
        
        print, 'Boresight surface intercept coordinates:'
        print, '    Radius    (km) : ', radius
        print, '    Latitude  (deg): ', lat
        print, '    Longitude (deg): ', lon
        
        ;; ------ 1st Boundary FOV Surface Intercept (cspice_surfpt) ------
        ;;
        ;; Now we will transform the first FOV corner vector into the
        ;; IAU_MARS frame so the surface intercept point can be
        ;; calculated using cspice_surfpt, which is faster than cspice_subpnt.
        ;; 
        ;; If this example program were extended to include all
        ;; of the pixels in the camera's FOV, a few steps, such as
        ;; finding the rotation matrix from the camera frame to the
        ;; IAU_MARS frame, looking up the semi-axis values for Mars,
        ;; and finding the position of MGS with respect to Mars could
        ;; be done once and used for every pixel.
        ;; 
        ;; Find the rotation matrix from the ray's reference
        ;; frame at the time the photons were received (etrec)
        ;; to IAU_MARS at the time the photons were emitted
        ;; (etemit).
        ;;  
        
        cspice_pxfrm2, obsref, 'iau_mars', etrec, etemit, rotate
        
        ;;  
        ;; Look up the semi-axis values for Mars.
        ;;
        
        cspice_bodvrd, 'mars', 'RADII', 3, radii
        
        ;;
        ;; Find the position of the center of Mars with respect
        ;; to MGS.  The position of the observer with respect
        ;; to Mars is required for the call to 'cspice_surfpt'.  Note:
        ;; the apparent position of MGS with respect to Mars is
        ;; not the same as the negative of Mars with respect to MGS.
        ;;  
        
        cspice_vsub, spoint, srfvec, pos_mgs_wrt_mars
        
        ;;
        ;; The first boundary FOV pixel must be rotated into the
        ;; IAU_MARS reference frame.
        ;;
        
        cspice_mxv, rotate, bounds[*,1], bndvec
        
        ;;
        ;; Calculate the surface point of the boundary FOV
        ;; vector.
        ;;
        
        cspice_surfpt, pos_mgs_wrt_mars,   bndvec, radii[0], $
                     radii[1], radii[2], spoint, found
        
        if ( ~found ) then begin
        
          print, 'SPICE(NOTFOUND)'  + $
                 'Could not calculate surface point.'
          return
        
        endif 
        
        tmp = spoint
        
        ;;
        ;; Convert the intersection point of the boundary
        ;; FOV vector and Mars from rectangular into
        ;; latitudinal coordinates. Convert radians
        ;; to degrees.
        ;;
        
        cspice_reclat, spoint, radius, lon, lat
        
        lon = lon * cspice_dpr()
        lat = lat * cspice_dpr()
        
        print, 'Boundary vector surface intercept coordinates'
        print, 'using cspice_surfpt:'
        print, '    Radius    (km) :  ', radius
        print, '    Latitude  (deg):  ', lat
        print, '    Longitude (deg):  ', lon
        print, '    Emit time using boresight LT (s):  ', etemit
        
        ;;
        ;; ------ 1st Boundary FOV Surface Intercept Verification ----
        ;;
        ;; For verification only, we will calculate the surface
        ;; intercept coordinates for the first boundary vector
        ;; using 'cspice_sincpt' and compare to the faster
        ;; 'cspice_surfpt' method.
        ;;
        
        cspice_sincpt, 'Ellipsoid', 'Mars',  etrec, 'iau_mars',   $
                      ABCORR,     'MGS',   obsref, bounds[*,1], $
                      spoint,      etemit, srfvec, found
        
        if ( ~found ) then begin
        
          print, 'SPICE(NOINTERCEPT)'  + $
                 'Intercept not found for the boundary FOV vector.'
          return
        
        endif 
        
        ;;
        ;; Convert the intersection point of the first boundary
        ;; vector and Mars from rectangular into latitudinal
        ;; coordinates. Convert radians to degrees.
        ;;
        
        cspice_reclat, spoint, radius, lon, lat
        
        lon = lon * cspice_dpr()
        lat = lat * cspice_dpr()
        
        print, 'Boundary vector surface intercept coordinates'
        print, 'using cspice_sincpt:'
        print, '    Radius    (km) :  ', radius
        print, '    Latitude  (deg):  ', lat
        print, '    Longitude (deg):  ', lon
        print, '    Emit time using boresight LT (s):  ', etemit
        
        distance = cspice_vdist( tmp, spoint )
        
        print, 'Distance between surface points of the first'
        print, 'boundary vector using cspice_surfpt and cspice_sincpt:'
        print, '    Distance (mm):    ', distance*(1E6)
        
        ;;
        ;; It's always good form to unload kernels after use,
        ;; particularly in IDL due to data persistence.
        ;;
        cspice_kclear

    IDL outputs:

        Observation Reference Frame: MGS_MOC_NA
        Boresight surface intercept coordinates:
            Radius    (km) :        3384.9404
            Latitude  (deg):       -48.479580
            Longitude (deg):       -123.43645
        Boundary vector surface intercept coordinates
        using cspice_surfpt:
            Radius    (km) :         3384.9397
            Latitude  (deg):        -48.481636
            Longitude (deg):        -123.39882
            Emit time using boresight LT (s):     1.1929686e+08
        Boundary vector surface intercept coordinates
        using cspice_sincpt:
            Radius    (km) :         3384.9397
            Latitude  (deg):        -48.481636
            Longitude (deg):        -123.39882
            Emit time using boresight LT (s):     1.1929686e+08

Particulars


   None.

Required Reading


   ICY.REQ
   ROTATION.REQ
   FRAMES.REQ

Version


   -Icy Version 1.0.1, 02-FEB-2017, SCK (JPL), BVS (JPL)

      Shortened permutted index entry.

   -Icy Version 1.0.0, 12-OCT-2011, SCK (JPL)

Index_Entries


   Position transformation matrix for different epochs
 



Wed Apr  5 17:58:03 2017