ckgpav |
Table of contents
ProcedureCKGPAV ( C-kernel, get pointing and angular velocity ) SUBROUTINE CKGPAV ( INST, SCLKDP, TOL, REF, CMAT, AV, CLKOUT, . FOUND ) AbstractGet pointing (attitude) and angular velocity for a specified spacecraft clock time. Required_ReadingCK SCLK KeywordsPOINTING DeclarationsIMPLICIT NONE INCLUDE 'frmtyp.inc' INCLUDE 'zzctr.inc' INTEGER INST DOUBLE PRECISION SCLKDP DOUBLE PRECISION TOL CHARACTER*(*) REF DOUBLE PRECISION CMAT ( 3, 3 ) DOUBLE PRECISION AV ( 3 ) DOUBLE PRECISION CLKOUT LOGICAL FOUND Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- INST I NAIF ID of instrument, spacecraft, or structure. SCLKDP I Encoded spacecraft clock time. TOL I Time tolerance. REF I Reference frame. CMAT O C-matrix pointing data. AV O Angular velocity vector. CLKOUT O Output encoded spacecraft clock time. FOUND O .TRUE. when requested pointing is available. Detailed_InputINST is the NAIF integer ID for the instrument, spacecraft, or other structure for which pointing and angular velocity are requested. For brevity we will refer to this object as the "instrument," and the frame fixed to this object as the "instrument frame" or "instrument-fixed" frame. SCLKDP is the encoded spacecraft clock time for which pointing and angular velocity are requested. The SPICELIB routines SCENCD and SCE2C respectively convert spacecraft clock strings and ephemeris time to encoded spacecraft clock. The inverse conversions are performed by SCDECD and SCT2E. TOL is a time tolerance in ticks, the units of encoded spacecraft clock time. The SPICELIB routine SCTIKS converts a spacecraft clock tolerance duration from its character string representation to ticks. SCFMT performs the inverse conversion. The C-matrix - angular velocity vector pair returned by CKGPAV is the one whose time tag is closest to SCLKDP and within TOL units of SCLKDP. (More in $Particulars, below.) In general, because using a non-zero tolerance affects selection of the segment from which the data is obtained, users are strongly discouraged from using a non-zero tolerance when reading CKs with continuous data. Using a non-zero tolerance should be reserved exclusively to reading CKs with discrete data because in practice obtaining data from such CKs using a zero tolerance is often not possible due to time round off. REF is the desired reference frame for the returned pointing and angular velocity. The returned C-matrix CMAT gives the orientation of the instrument designated by INST relative to the frame designated by REF. When a vector specified relative to frame REF is left-multiplied by CMAT, the vector is rotated to the frame associated with INST. The returned angular velocity vector AV expresses the angular velocity of the instrument designated by INST relative to the frame designated by REF. See the discussion of CMAT and AV below for details. Consult the SPICE document "Frames" for a discussion of supported reference frames. Detailed_OutputCMAT is a rotation matrix that transforms the components of a vector expressed in the reference frame specified by REF to components expressed in the frame tied to the instrument, spacecraft, or other structure at time CLKOUT (see below). Thus, if a vector v has components x,y,z in the REF reference frame, then v has components x',y',z' in the instrument fixed frame at time CLKOUT: .- -. .- -. .- -. | x' | | | | x | | y' | = | CMAT | | y | | z' | | | | z | '- -' '- -' '- -' If you know x', y', z', use the transpose of the C-matrix to determine x, y, z as follows: .- -. .- -.T .- -. | x | | | | x' | | y | = | CMAT | | y' | | z | | | | z' | '- -' '- -' '- -' (Transpose of CMAT) AV is the angular velocity vector. This is the axis about which the reference frame tied to the instrument is rotating in the right-handed sense at time CLKOUT. The magnitude of AV is the magnitude of the instantaneous velocity of the rotation, in radians per second. AV is expressed relative to the frame designated by REF. CLKOUT is the encoded spacecraft clock time associated with the returned C-matrix and the returned angular velocity vector. This value may differ from the requested time, but never by more than the input tolerance TOL. The $Particulars section below describes the search algorithm used by CKGPAV to satisfy a pointing request. This algorithm determines the pointing instance (and therefore the associated time value) that is returned. FOUND is .TRUE. if a record was found to satisfy the pointing request. FOUND will be .FALSE. otherwise. ParametersNone. Exceptions1) If a C-kernel file has not been loaded using FURNSH prior to a call to this routine, an error is signaled by a routine in the call tree of this routine. 2) If TOL is negative, found is set to .FALSE. 3) If REF is not a supported reference frame, an error is signaled by a routine in the call tree of this routine and FOUND is set to .FALSE. FilesCKGPAV searches through files loaded by FURNSH to locate a segment that can satisfy the request for pointing and angular velocity for instrument INST at time SCLKDP. You must load a C-kernel file using FURNSH prior to calling this routine. ParticularsHow the tolerance argument is used ================================== Reading a type 1 CK segment (discrete pointing instances) --------------------------------------------------------- In the diagram below - "0" is used to represent discrete pointing instances (quaternions, angular velocity vectors, and associated time tags). - "( )" are used to represent the end points of the time interval covered by a segment in a CK file. - SCLKDP is the time at which you requested pointing. The location of SCLKDP relative to the time tags of the pointing instances is indicated by the "+" sign. - TOL is the time tolerance specified in the pointing request. The square brackets "[ ]" represent the endpoints of the time interval SCLKDP-TOL : SCLKDP+TOL - The quaternions occurring in the segment need not be evenly spaced in time. Case 1: pointing is available ------------------------------ SCLKDP \ TOL | / |/\ Your request [--+--] . . . Segment (0-----0--0--0--0--0--0---0--0------------0--0--0--0) ^ | CKGPAV returns this instance. Case 2: pointing is not available ---------------------------------- SCLKDP \ TOL | / |/\ Your request [--+--] . . . Segment (0-----0--0--0--0--0--0---0--0--0---------0--0--0--0) CKGPAV returns no pointing; the output FOUND flag is set to .FALSE. Reading a type 2, 3, 4, or 5 CK segment (continuous pointing) ------------------------------------------------------------- In the diagrams below - "==" is used to represent periods of continuous pointing. - "--" is used to represent gaps in the pointing coverage. - "( )" are used to represent the end points of the time interval covered by a segment in a CK file. - SCLKDP is the time at which you requested pointing. The location of SCLKDP relative to the time tags of the pointing instances is indicated by the "+" sign. - TOL is the time tolerance specified in the pointing request. The square brackets "[ ]" represent the endpoints of the time interval SCLKDP-TOL : SCLKDP+TOL - The quaternions occurring in the periods of continuous pointing need not be evenly spaced in time. Case 1: pointing is available at the request time -------------------------------------------------- SCLKDP \ TOL | / |/\ Your request [--+--] . . . . . . . . . Segment (==---===========---=======----------===--) ^ | The request time lies within an interval where continuous pointing is available. CKGPAV returns pointing at the requested epoch. Case 2: pointing is available "near" the request time ------------------------------------------------------ SCLKDP \ TOL | / |/\ Your request [--+--] . . . Segment (==---===========----=======---------===--) ^ | The request time lies in a gap: an interval where continuous pointing is *not* available. CKGPAV returns pointing for the epoch closest to the request time SCLKDP. Case 3: pointing is not available ---------------------------------- SCLKDP \ TOL | / |/\ Your request [--+--] . . . Segment (==---===========----=======---------===--) CKGPAV returns no pointing; the output FOUND flag is set to .FALSE. Tolerance and segment priority ============================== CKGPAV searches through loaded C-kernels to satisfy a pointing request. Last-loaded files are searched first. Individual files are searched in backwards order, so that between competing segments (segments containing data for the same object, for overlapping time ranges), the one closest to the end of the file has highest priority. CKGPAV considers only those segments that contain both pointing and angular velocity data, as indicated by the segment descriptor. The search ends when a segment is found that can provide pointing and angular velocity for the specified instrument at a time falling within the specified tolerance on either side of the request time. Within that segment, the instance closest to the input time is located and returned. The following four cases illustrate this search procedure. Segments A and B are in the same file, with segment A located further towards the end of the file than segment B. Both segments A and B contain discrete pointing data, indicated by the number 0. Case 1: Pointing is available in the first segment searched. Because segment A has the highest priority and can satisfy the request, segment B is not searched. SCLKDP \ TOL | / |/\ Your request [--+--] . . . Segment A (0-----------------0--------0--0-----0) ^ | | CKGPAV returns this instance Segment B (0--0--0--0--0--0--0--0--0--0--0--0--0--0--0--0--0) Case 2: Pointing is not available in the first segment searched. Because segment A cannot satisfy the request, segment B is searched. SCLKDP \ TOL | / |/\ Your request [--+--] . . . Segment A (0-----------------0--------0--0-----0) . . . Segment B (0--0--0--0--0--0--0--0--0--0--0--0--0--0--0--0--0) ^ | CKGPAV returns this instance Segments that contain continuous pointing data are searched in the same manner as segments containing discrete pointing data. For request times that fall within the bounds of continuous intervals, CKGPAV will return pointing at the request time. When the request time does not fall within an interval, then a time at an endpoint of an interval may be returned if it is the closest time in the segment to the user request time and is also within the tolerance. In the following examples, segment A is located further towards the end of the file than segment C. Segment A contains discrete pointing data and segment C contains continuous data, indicated by the "=" character. Case 3: Pointing is not available in the first segment searched. Because segment A cannot satisfy the request, segment C is searched. SCLKDP \ TOL | / |/\ Your request [--+--] . . . . . . Segment A (0-----------------0--------0--0-----0) . . . . . . Segment C (---=============-----====--------==--) ^ | | CKGPAV returns this instance In the next case, assume that the order of segments A and C in the file is reversed: A is now closer to the front, so data from segment C are considered first. Case 4: Pointing is available in the first segment searched. Because segment C has the highest priority and can satisfy the request, segment A is not searched. SCLKDP / | TOL | / |/\ Your request [--+--] . . . . . . Segment C (---=============-----====--------==--) ^ | CKGPAV returns this instance Segment A (0-----------------0--------0--0-----0) ^ | "Best" answer The next case illustrates an unfortunate side effect of using a non-zero tolerance when reading multi-segment CKs with continuous data. In all cases when the look-up interval formed using tolerance overlaps a segment boundary and the request time falls within the coverage of the lower priority segment, the data at the end of the higher priority segment will be picked instead of the data from the lower priority segment. Case 5: Pointing is available in the first segment searched. Because segment C has the highest priority and can satisfy the request, segment A is not searched. SCLKDP / | TOL | / |/\ Your request [--+--] . . . . . . Segment C (===============) ^ | CKGPAV returns this instance Segment A (=====================) ^ | "Best" answer ExamplesThe numerical results shown for this example 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. 1) The following example program uses CKGPAV to get C-matrices and associated angular velocity vectors for a set of images whose SCLK counts (un-encoded character string versions) are known. For each C-matrix, a unit pointing vector is constructed and printed along with the angular velocity vector. Note: if the C-kernels of interest do not contain angular velocity data, then the SPICELIB routine CKGP should be used to read the pointing data. An example program in the header of the SPICELIB routine CKGP demonstrates this. We need to load also an SCLK kernel to convert from clock string to 'ticks.' Although not required for older spacecraft clocks, most modern spacecraft ones require a leapseconds kernel to be loaded in addition to an SCLK kernel. Use the meta-kernel shown below to load the required SPICE kernels. KPL/MK File name: ckgpav_ex1.tm This meta-kernel is intended to support operation of SPICE example programs. The kernels shown here should not be assumed to contain adequate or correct versions of data required by SPICE-based user applications. 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 -------------------- ----------------------- cas00071.tsc CASSINI SCLK 04153_04182ca_ISS.bc CASSINI image navigated spacecraft CK \begindata KERNELS_TO_LOAD = ( 'cas00071.tsc' '04153_04182ca_ISS.bc' ) \begintext End of meta-kernel Example code begins here. PROGRAM CKGPAV_EX1 IMPLICIT NONE C C Constants for this program. C C -- The code for the CASSINI spacecraft clock is -82. C C -- The code for CASSINI spacecraft reference frame is C -82000. C C -- Spacecraft clock times for successive CASSINI C navigation images always differ by more than 1.0 C seconds. This is an acceptable tolerance, and must C be converted to "ticks" (units of encoded SCLK) for C input to CKGPAV. C C -- The reference frame we want is J2000. C C -- The CASSINI ISS camera boresight in the spacecraft C frame is (0.0005760, -0.99999982, -0.0001710). C INTEGER NPICS PARAMETER ( NPICS = 2 ) INTEGER TIMLEN PARAMETER ( TIMLEN = 30 ) INTEGER REFLEN PARAMETER ( REFLEN = 32 ) CHARACTER*(TIMLEN) CLKCH CHARACTER*(REFLEN) REF CHARACTER*(TIMLEN) SCLKCH ( NPICS ) CHARACTER*(TIMLEN) TOL DOUBLE PRECISION AV ( 3 ) DOUBLE PRECISION CLKOUT DOUBLE PRECISION CMAT ( 3, 3 ) DOUBLE PRECISION SCLKDP DOUBLE PRECISION TOLTIK DOUBLE PRECISION ISSFIX ( 3 ) DOUBLE PRECISION VINERT ( 3 ) INTEGER SC INTEGER I INTEGER INST LOGICAL FOUND DATA SCLKCH / '1465644281.0', . '1465644351.0' / DATA ISSFIX / 0.00057600D0, . -0.99999982D0, . -0.00017100D0 / SC = -82 INST = -82000 TOL = '1.0' REF = 'J2000' C C Load kernels. C CALL FURNSH ( 'ckgpav_ex1.tm' ) C C Convert tolerance from CASSINI formatted character C string SCLK to ticks which are units of encoded SCLK. C CALL SCTIKS ( SC, TOL, TOLTIK ) DO I = 1, NPICS C C CKGPAV requires encoded spacecraft clock. C CALL SCENCD ( SC, SCLKCH( I ), SCLKDP ) CALL CKGPAV ( INST, SCLKDP, TOLTIK, REF, CMAT, AV, . CLKOUT, FOUND ) IF ( FOUND ) THEN C C Use the transpose of the C-matrix to transform the C boresight vector from camera-fixed to reference C coordinates. C CALL MTXV ( CMAT, ISSFIX, VINERT ) CALL SCDECD ( SC, CLKOUT, CLKCH ) WRITE(*,*) 'Requested SCLK time : ', SCLKCH(I) WRITE(*,*) ' CASSINI SCLK time: ', CLKCH WRITE(*,'(A,3F11.7)') . ' CASSINI ISS boresight :', VINERT WRITE(*,'(A,3F11.7)') . ' Angular velocity vector:', AV WRITE(*,*) ' ' ELSE WRITE (*,*) 'Pointing not found for time ', . SCLKCH(I) END IF END DO END When this program was executed on a Mac/Intel/gfortran/64-bit platform, the output was: Requested SCLK time : 1465644281.0 CASSINI SCLK time: 1/1465644281.171 CASSINI ISS boresight : 0.9376789 0.3444125 0.0462419 Angular velocity vector: 0.0000000 0.0000000 0.0000000 Requested SCLK time : 1465644351.0 CASSINI SCLK time: 1/1465644351.071 CASSINI ISS boresight : 0.9376657 0.3444504 0.0462266 Angular velocity vector: 0.0000000 0.0000000 0.0000000 Restrictions1) Only loaded C-kernel segments containing both pointing and angular velocity data will be searched by this reader. Segments containing only pointing data will be skipped over. Literature_ReferencesNone. Author_and_InstitutionC.H. Acton (JPL) N.J. Bachman (JPL) J. Diaz del Rio (ODC Space) J.M. Lynch (JPL) B.V. Semenov (JPL) W.L. Taber (JPL) R.E. Thurman (JPL) I.M. Underwood (JPL) VersionSPICELIB Version 5.3.1, 02-JUL-2021 (JDR) Edited the header to comply with NAIF standard. Updated the example code, input times and kernel set to work with PDS archived CASSINI data. Added missing entry in $Versions section. SPICELIB Version 5.3.0, 23-SEP-2013 (BVS) Updated to save the input frame name and POOL state counter and to do frame name-ID conversion only if the counter has changed. SPICELIB Version 5.2.1, 03-JUN-2010 (BVS) Header update: description of the tolerance and $Particulars section were expanded to address some problems arising from using a non-zero tolerance. SPICELIB Version 5.2.0, 25-AUG-2005 (NJB) Updated to remove non-standard use of duplicate arguments in MTXV, MXM and VADD calls. SPICELIB Version 5.1.2, 29-JAN-2004 (NJB) Header update: descriptions of input arguments REF and AV were expanded. SPICELIB Version 5.1.1, 27-JUL-2003 (CHA) (NJB) Various header corrections were made. SPICELIB Version 5.1.0, 23-FEB-1999 (WLT) The previous editions of this routine did not properly handle the case when TOL was negative. The routine now returns a value of .FALSE. for FOUND as is advertised above. SPICELIB Version 5.0.0, 28-JUL-1997 (WLT) The previous routine incorrectly computed the angular velocity of the transformation from the request frame to the platform frame of the C-matrix for non-inertial reference frames. SPICELIB Version 4.1.0, 20-DEC-1995 (WLT) A call to FRINFO did not have enough arguments and went undetected until Howard Taylor of ACT. Many thanks go out to Howard for tracking down this error. SPICELIB Version 4.0.0, 19-SEP-1995 (WLT) The routine was upgraded so that the reference frame may be non-inertial. SPICELIB Version 3.0.0, 05-OCT-1994 (WLT) The previous versions all computed an incorrect value for the angular velocity if the frame specified by REF was different from the reference frame of the segment from which the angular velocity was extracted. This has now been corrected. SPICELIB Version 2.0.1, 10-MAR-1992 (WLT) Comment section for permuted index source lines was added following the header. SPICELIB Version 2.0.0, 30-AUG-1991 (JML) 1) The $Particulars section was updated to show how the search algorithm processes segments with continuous pointing data. 2) It was specified that the angular velocity vector gives the right-handed axis about which the instrument frame rotates. 3) The example program now loads an SCLK kernel. 4) FAILED is checked after the call to IRFROT to handle the case where the reference frame is invalid and the error handling is not set to abort. 5) FAILED is checked in the DO WHILE loop to handle the case where an error is detected by a SPICELIB routine inside the loop and the error handling is not set to abort. SPICELIB Version 1.1.0, 02-NOV-1990 (JML) 1) The variable NEEDAV is no longer being saved. 2) In the example program, the calling sequences for SCENCD and CKGPAV were corrected. 3) The restriction that a C-kernel file must be loaded was explicitly stated. SPICELIB Version 1.0.0, 07-SEP-1990 (RET) (IMU) |
Fri Dec 31 18:36:02 2021