| ckgpav |
|
Table of contents
Procedure
CKGPAV ( C-kernel, get pointing and angular velocity )
SUBROUTINE CKGPAV ( INST, SCLKDP, TOL, REF, CMAT, AV, CLKOUT,
. FOUND )
Abstract
Get pointing (attitude) and angular velocity for a specified
spacecraft clock time.
Required_Reading
CK
SCLK
Keywords
POINTING
Declarations
IMPLICIT 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/O
VARIABLE 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_Input
INST 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_Output
CMAT 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.
Parameters
None.
Exceptions
1) 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.
Files
CKGPAV 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.
Particulars
How 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
Examples
The 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
Restrictions
1) 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_References
None.
Author_and_Institution
C.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)
Version
SPICELIB 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