Table of contents
CSPICE_CKGP returns pointing (attitude) for a specified
spacecraft clock time.
Given:
inst the NAIF integer ID for the instrument, spacecraft, or other
structure for which pointing is requested.
help, inst
LONG = Scalar
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 the encoded spacecraft clock time for which pointing is
requested.
help, sclkdp
DOUBLE = Scalar
The Icy routines cspice_scencd and cspice_sce2c respectively
convert spacecraft clock strings and ephemeris time to
encoded spacecraft clock. The inverse conversions are
performed by cspice_scdecd and cspice_sct2e.
tol a time tolerance in ticks, the units of encoded spacecraft clock
time.
help, tol
DOUBLE = Scalar
The Icy routine cspice_sctiks converts a spacecraft clock
tolerance duration from its character string
representation to ticks. cspice_scfmt performs the inverse
conversion.
The C-matrix returned by cspice_ckgp 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 the desired reference frame for the returned pointing.
help, ref
STRING = Scalar
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'. See the discussion of `cmat' below for
details.
Consult the SPICE document "Frames" for a discussion
of supported reference frames.
the call:
cspice_ckgp, inst, sclkdp, tol, ref, cmat, clkout, found
returns:
cmat 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).
help, cmat
DOUBLE = Array[3,3]
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')
clkout the encoded spacecraft clock time associated with the returned
C-matrix.
help, clkout
DOUBLE = Scalar
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 cspice_ckgp to satisfy a pointing request.
This algorithm determines the pointing instance (and
therefore the associated time value) that is returned.
found True if a record was found to satisfy the pointing request.
help, found
BOOLEAN = Scalar
`found' will be False otherwise.
None.
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.
1) The following example program uses ckgp_c to get C-matrices for a
set of images whose SCLK counts (un-encoded character string
versions) are contained in the array `sclkch'.
If available, the program will get the corrected pointing values.
For each C-matrix, a unit pointing vector is constructed and
printed.
Use the CK kernel below to load the CASSINI image navigated
spacecraft pointing and orientation data.
04153_04182ca_ISS.bc
Use the SCLK kernel below to load the CASSINI spacecraft clock
time correlation data required for the conversion between
spacecraft clock string representation and double precision
encoding of spacecraft clock counts.
cas00071.tsc
Example code begins here.
PRO ckgp_ex1
;;
;; Constants for this program:
;;
;; -- The code for the CASSINI spacecraft clock is -82.
;;
;; -- The code for CASSINI spacecraft reference frame
;; is -82000.
;;
;; -- Spacecraft clock times for successive CASSINI navigation
;; images always differ by more than 1.0 seconds. This is an
;; acceptable tolerance, and must be converted to "ticks"
;; (units of encoded SCLK) for input to cspice_ckgp.
;;
;; -- The reference frame we want is J2000.
;;
;; -- The CASSINI ISS camera boresight in the spacecraft
;; frame is (0.0005760, -0.99999982, -0.0001710).
;;
SC = -82
INST = -82000
REF = 'J2000'
TOL = '1.0'
BORE = [ 0.0005760d, -0.99999982d, -0.0001710d]
NPICS = 2
CK = '04153_04182ca_ISS.bc'
SCLK = 'cas00071.tsc'
SCLKCH = [ '1465644281.0' , '1465644351.0' ]
;;
;; Load the CK pointing file.
;;
cspice_furnsh, CK
;;
;; Need to load a CASSINI SCLK kernel to convert from
;; clock string to ticks. Although not required for
;; the CASSINI spacecraft clock, most modern spacecraft
;; clocks require a leapseconds kernel to be loaded in
;; addition to an SCLK kernel.
;;
cspice_furnsh, SCLK
;;
;; Convert tolerance from CASSINI formatted character string
;; SCLK to ticks, which are units of encoded SCLK.
;;
cspice_sctiks, SC, TOL, toltik
for i = 0, (NPICS-1) do begin
;;
;; cspice_ckgp requires encoded spacecraft clock time.
;;
cspice_scencd, SC, sclkch[i], sclkdp
;;
;; Retrieve the 'REF' reference frame to 'INST' reference frame
;; transformation matrix at time sclkdp with a tolerance
;; 'toltik'.
;;
;; [INST] = [cmat][ref]
;;
cspice_ckgp, INST, sclkdp, toltik, REF, cmat, clkout, found
;;
;; Did we find pointing information within (+/-) 'toltik' of the
;; requested time.
;;
if ( found ) then begin
;;
;;
;; Transform the 'BORE' vector from 'INST' reference frame to
;; 'REF' frame.
;; T
;; [ref] = [cmat] [INST]
;;
;; The Icy code to perform the same operation.
;;
;; cspice_mtxv, cmat, BORE, bore_ref
;;
bore_ref = cmat # BORE
cspice_scdecd, SC, clkout, clkch
print, 'Input SCLK time : ', sclkch[i]
print, ' CASSINI SCLK time: ', clkch
print, FORMAT='(A,3F11.7)', $
' CASSINI ISS boresight:', bore_ref
print, ' '
endif else begin
print, 'Pointing not found for SCLK time: ', sclkch[i]
endelse
endfor
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_kclear
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Input SCLK time : 1465644281.0
CASSINI SCLK time: 1/1465644281.171
CASSINI ISS boresight: 0.9376789 0.3444125 0.0462419
Input SCLK time : 1465644351.0
CASSINI SCLK time: 1/1465644351.071
CASSINI ISS boresight: 0.9376657 0.3444504 0.0462266
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 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)
^
|
cspice_ckgp 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)
cspice_ckgp 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. cspice_ckgp 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. cspice_ckgp
returns pointing for the epoch closest to the
request time sclkdp.
Case 3: pointing is not available
----------------------------------
sclkdp
\ tol
| /
|/\
Your request [--+--]
. . .
Segment (==---===========----=======---------===--)
cspice_ckgp returns no pointing; the output
found flag is set to False.
Tolerance and segment priority
==============================
cspice_ckgp 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.
The search ends when a segment is found that can provide pointing
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)
^
|
|
cspice_ckgp 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)
^
|
cspice_ckgp 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, cspice_ckgp 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 (---=============-----====--------==--)
^
|
|
cspice_ckgp 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 (---=============-----====--------==--)
^
|
cspice_ckgp 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 (===============)
^
|
cspice_ckgp returns this instance
Segment A (=====================)
^
|
"Best" answer
1) If a C-kernel file has not been loaded using cspice_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.
4) If any of the input arguments, `inst', `sclkdp', `tol' or
`ref', is undefined, an error is signaled by the IDL error
handling system.
5) If any of the input arguments, `inst', `sclkdp', `tol' or
`ref', is not of the expected type, or it does not have the
expected dimensions and size, an error is signaled by the Icy
interface.
6) If any of the output arguments, `cmat', `clkout' or `found',
is not a named variable, an error is signaled by the Icy
interface.
cspice_ckgp searches through files loaded by cspice_furnsh to locate a
segment that can satisfy the request for pointing for instrument `inst'
at time `sclkdp'. You must load a C-kernel file using cspice_furnsh prior
to calling this routine.
None.
ICY.REQ
CK.REQ
SCLK.REQ
None.
J. Diaz del Rio (ODC Space)
B.V. Semenov (JPL)
E.D. Wright (JPL)
-Icy Version 1.0.3, 31-MAY-2021 (JDR)
Edited the header to comply with NAIF standard, extending the
argument descriptions. Updated the code, input times and kernel set
to work with PDS archived CASSINI data. Added call to cspice_kclear
in code example.
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections, and
completed -Particulars section.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added arguments' type and size information in the -I/O section.
-Icy Version 1.0.2, 03-JUN-2010 (BVS)
Edits to header. Added warning regarding non-zero tolerance.
-Icy Version 1.0.1, 09-JUN-2006 (EDW)
Edits to header. Improved argument descriptions.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
get CK pointing
|