Table of contents
CSPICE_SCENCD encodes a character representation of spacecraft clock time
into a double precision number.
Given:
sc the standard NAIF ID of the spacecraft whose clock's time is
being encoded.
help, sc
LONG = Scalar
sclkch the character representation of some spacecraft's clock
count, or an N-vector of representations.
help, sclkch
STRING = Scalar or STRING = Array[N]
`sclkch' will have the following general format:
'pp/sclk_string', or just
'sclk_string'
'pp' is an integer greater than or equal to one
and is called the partition number.
Each mission is divided into some number of partitions.
A new partition starts when the spacecraft clock
resets, either to zero, or to some other
value. Thus, the first partition for any mission
starts with launch, and ends with the first clock
reset. The second partition starts immediately when
the first stopped, and so on.
In order to be completely unambiguous about a
particular time, you need to specify a partition number
along with the standard clock string.
Information about when partitions occur for different
missions is contained in a spacecraft clock kernel
file, which needs to be loaded into the kernel pool,
using the routine cspice_furnsh.
The routine cspice_scpart is used to read the partition
start and stop times, in encoded units of SCLK (called
"ticks" -- see `sclkdp' below) from the kernel file.
If the partition number is included, it must be
separated from the rest of the string by a '/'.
Any number of spaces may separate the partition number,
the '/', and the rest of the clock string.
If the partition number is omitted, a default partition
will be assumed. The default partition is the lowest-
numbered partition that contains the given clock time.
If the clock time does not fall in any of the
partition boundaries then an error is signaled.
'sclk_string' is a spacecraft specific clock string.
Using Galileo as an example, the full format is
wwwwwwww:xx:y:z
where z is a mod-8 counter (values 0-7) which
increments approximately once every 8 1/3 ms., y is a
mod-10 counter (values 0-9) which increments once
every time z turns over, i.e., approximately once every
66 2/3 ms., xx is a mod-91 (values 0-90) counter
which increments once every time y turns over, i.e.,
once every 2/3 seconds. wwwwwwww is the Real-Time Image
Count (RIM), which increments once every time xx turns
over, i.e., once every 60 2/3 seconds. The roll-over
expression for the RIM is 16777215, which corresponds
to approximately 32 years.
wwwwwwww, xx, y, and z are referred to interchangeably
as the fields or components of the spacecraft clock.
SCLK components may be separated by any of these
five characters: ' ' ':' ',' '-' '.'
Any number of spaces can separate the components and
the delimiters. The presence of the RIM component
is required. Successive components may be omitted, and
in such cases are assumed to represent zero values.
Values for the individual components may exceed the
maximum expected values. For instance, '0:0:0:9' is
an acceptable Galileo clock string, and will convert
to the same number of ticks as '0:0:1:1'.
Consecutive delimiters containing no intervening digits
are treated as if they delimit zero components.
Trailing zeros should always be included to match the
length of the counter. For example, a Galileo clock
count of '25684.90' should not be represented as
'25684.9'.
Some spacecraft clock components have offset, or
starting, values different from zero. For example,
with an offset value of 1, a mod 20 counter would
cycle from 1 to 20 instead of from 0 to 19.
See the SCLK required reading for a detailed
description of the Voyager and Mars Observer clock
formats.
the call:
cspice_scencd, sc, sclkch, sclkdp
returns:
sclkdp the double precision encoding of `sclkch', or an N-vector of
encodings.
help, sclkdp
DOUBLE = Scalar or DOUBLE = Array[N]
The encoding is such that order and proximity will be
preserved. That is, if t1, t2, and t3 are spacecraft
clock times, and t1*, t2*, and t3* are their encodings,
then if
t1 < t2 < t3, and
t2 is closer to t1 than to t3, you will have the result
that
t1* < t2* < t3*, and
t2* is closer to t1* than to t3*.
The units of encoded SCLK are "ticks since the start of
the mission", where a "tick" is defined to be the
shortest time increment expressible by a particular
spacecraft's clock.
Each clock string without partition number represents
a certain number of ticks, but you need to include
partition information to determine the relative
position of that time in relation to the start of the
mission.
Since the end time of one partition is coincident
with the begin time of the next, there are two
different representations for this instant, and they
will both yield the same encoding.
For example, if partition 1 has an end time of t1, and
partition 2 has a begin time of t2, then if we executed
the code fragment
cspice_scencd, '1/t1', sc, x
cspice_scencd, '2/t2', sc, y
we would obtain x = y.
`sclkdp' returns with the same measure of vectorization (N)
as `sclkch'.
MXPART is the maximum number of spacecraft clock partitions
expected in the kernel file for any one spacecraft.
MXPART is currently set to 9999.
Any numerical results shown for these examples may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) Double precision encodings of spacecraft clock counts are used
to tag pointing data in the C-kernel.
In the following example, pointing for a sequence of images
from the CASSINI Imaging Science Subsystem (ISS) is requested
from the C-kernel using an array of character spacecraft clock
counts as input. The clock counts attached to the output are
then decoded to character and compared with the input strings.
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 scencd_ex1
;;
;; Local parameters.
;;
;; The instrument we want pointing for is the CASSINI
;; spacecraft. The reference frame we want is
;; J2000. The spacecraft is CASSINI.
;;
SC = -82L
INST = -82000L
REF = 'J2000'
CK = '04153_04182ca_ISS.bc'
SCLK = 'cas00071.tsc'
NPICS = 4L
CLKTOL = '1.0'
;;
;; Set the input SCLK strings.
;;
sclkin = ['1/1465644279.0', '1/1465644281.0', $
'1/1465644351.0', '1/1465644361.0']
;;
;; Load the appropriate files. We need
;;
;; 1. CK file containing pointing data.
;; 2. Spacecraft clock kernel file.
;;
cspice_furnsh, CK
cspice_furnsh, SCLK
;;
;; Convert the tolerance string to ticks.
;;
cspice_sctiks, SC, CLKTOL, tol
for i=0L, NPICS-1L do begin
cspice_scencd, SC, sclkin[i], timein
cspice_ckgp, INST, timein, tol, REF, cmat, timeout, found
print
print, format='(2A)', 'Input s/c clock count : ', sclkin[i]
if ( found ) then begin
cspice_scdecd, SC, timeout, sclkout
print, format='(2A)', 'Output s/c clock count: ', sclkout
print, format='(A)', 'Output C-Matrix:'
print, format='(3F21.15)', cmat
endif else begin
print, format='(A)', 'No pointing found.'
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 s/c clock count : 1/1465644279.0
No pointing found.
Input s/c clock count : 1/1465644281.0
Output s/c clock count: 1/1465644281.171
Output C-Matrix:
-0.335351455948710 0.864374440205611 0.374694846658341
-0.937887426812980 -0.343851965210223 -0.046184419961653
0.088918927227039 -0.366909598048763 0.925997176691424
Input s/c clock count : 1/1465644351.0
Output s/c clock count: 1/1465644351.071
Output C-Matrix:
-0.335380929397586 0.864363638262230 0.374693385378623
-0.937874292008090 -0.343889838107825 -0.046169163264003
0.088946301703530 -0.366899550417080 0.925998528787713
Input s/c clock count : 1/1465644361.0
No pointing found.
2) Convert a series of CASSINI encoded SCLK values to their
corresponding character representation of spacecraft clock
time, and convert back that SCLK string to double precision
form.
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 scencd_ex2
;;
;; Assign values for the spacecraft ID (CASSINI),
;; the SCLK kernel, and a double precision
;; encodings of SCLK strings
;;
SC = -82
SCLK = 'cas00071.tsc'
timein = 197483587237.d0
;;
;; Load the kernel file.
;;
cspice_furnsh, SCLK
;;
;; Convert the CASSINI encoded SCLK to an
;; SCLK string.
;;
cspice_scdecd, SC, timein, sclkch
;;
;; Convert the SCLK string to double precision form.
;; The output value should match the original for
;; encoded SCLKs that are integers, and be truncated
;; to an integer for encoded SCLKs that have a non-zero
;; fractional part.
;;
cspice_scencd, SC, sclkch, sclkdp
print, 'Scalar:'
print, format='(A10,F21.8)', 'Original: ', timein
print, 'SCLKCH : ', sclkch
print, format='(A10,F21.8)', 'Decoded : ', sclkdp
print
;;
;; Convert a vector of SCLK values.
;;
timein = [ 197483587237.D0, $
197483587250.D0, $
197485901583.201D0, $
197486447183.D0, $
198136032015.4D0]
;;
;; Convert the SCLK dps to the string representation,
;; then convert to the dp form. As before,
;; the output value should match the original for
;; encoded SCLKs that are integers, and be truncated
;; to an integer for encoded SCLKs that have a non-zero
;; fractional part.
;;
cspice_scdecd, SC, timein, sclkch
cspice_scencd, SC, sclkch, sclkdp
print, 'Vector:'
for i=0, n_elements(timein)-1 do begin
print, format='(A10,F21.8)', 'Original: ', timein[i]
print, 'SCLKCH : ', sclkch[i]
print, format='(A10,F21.8)', 'Decoded : ', sclkdp[i]
print
endfor
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_unload, SCLK
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Scalar:
Original: 197483587237.00000000
SCLKCH : 1/1465644281.165
Decoded : 197483587237.00000000
Vector:
Original: 197483587237.00000000
SCLKCH : 1/1465644281.165
Decoded : 197483587237.00000000
Original: 197483587250.00000000
SCLKCH : 1/1465644281.178
Decoded : 197483587250.00000000
Original: 197485901583.20098877
SCLKCH : 1/1465653322.015
Decoded : 197485901583.00000000
Original: 197486447183.00000000
SCLKCH : 1/1465655453.079
Decoded : 197486447183.00000000
Original: 198136032015.39999390
SCLKCH : 1/1468192894.015
Decoded : 198136032015.00000000
In general, it is difficult to compare spacecraft clock counts
numerically since there are too many clock components for a
single comparison. This routine provides a method of assigning a
single double precision number to a spacecraft's clock count,
given one of its character representations.
The routine cspice_scdecd performs the inverse operation of
cspice_scencd, converting an encoded double precision number to character
format.
To convert the string to ticks since the start of the mission,
cspice_scencd
1) Converts the non-partition portion of the string to
ticks, using the routine cspice_sctiks.
2) Determines the partition number for the clock time,
either by getting it directly from the input string, or
determining the default partition if none was specified.
3) Includes partition start and stop times, which are also
measured in ticks, to compute the number of ticks
from the beginning of the mission to the clock time.
1) If the number of partitions in the kernel file for spacecraft
`sc' exceeds the parameter MXPART, the error SPICE(TOOMANYPARTS)
is signaled by a routine in the call tree of this routine.
2) If any of the extracted clock components cannot be parsed as
integers, or the string has too many components, or the value
of one of the components is less than the offset value,
an error is signaled by a routine in the call tree of this
routine.
If a partition number is included in the SCLK string, the
following exceptions may occur:
3) If the partition number cannot be parsed as an integer, the
error SPICE(BADPARTNUMBER) is signaled by a routine in the
call tree of this routine.
4) If the partition number is not in the range of the number of
partitions found in the kernel pool, the error
SPICE(BADPARTNUMBER) is signaled by a routine in the call tree
of this routine.
5) If the clock count does not fall in the boundaries of the
specified partition, the error SPICE(NOTINPART) is
signaled by a routine in the call tree of this routine.
If a partition number is not included in the SCLK string, the
following exception may occur.
6) If the clock count does not fall in the boundaries of any
partition found in the kernel pool, the error
SPICE(NOPARTITION) is signaled by a routine in the call tree
of this routine.
7) If the partition delimiter (slash) is first found in the last
position of SCLKCH, the error SPICE(INVALIDSCLKSTRING) is
signaled by a routine in the call tree of this routine.
8) If any of the input arguments, `sc' or `sclkch', is undefined,
an error is signaled by the IDL error handling system.
9) If any of the input arguments, `sc' or `sclkch', is not of the
expected type, or it does not have the expected dimensions and
size, an error is signaled by the Icy interface.
10) If the output argument `sclkdp' is not a named variable, an
error is signaled by the Icy interface.
A kernel file containing spacecraft clock partition information
for the desired spacecraft must be loaded, using the routine
cspice_furnsh, before calling this routine.
None.
ICY.REQ
SCLK.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.1.2, 21-NOV-2021 (JDR)
Edited the header to comply with NAIF standard. Extended -I/O
section to provide further description of arguments. Added
complete examples; second one based on existing fragment using
CASSINI PDS archived data.
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.1.1, 05-FEB-2008 (EDW)
Edited -I/O section, replaced comment
"returns with the same order"
with
"returns with the same measure of vectorization"
Removed a superfluous -Version tag, edited -I/O section.
-Icy Version 1.1.0, 12-SEP-2004 (EDW)
Added capability to process 'sclkch' as vector
input returning vector 'sclkdp' on output.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
encode spacecraft_clock
|