Index Page
CKBRIEF User's Guide

Table of Contents 

   CKBRIEF User's Guide
      Abstract
      Summary
      Usage
      Helpful Hints for Those in a Hurry
      Ways to Provide File Names
      Default Summary Format
      Options Controlling Output Summary Format
         Displaying Interpolation Intervals (``-dump'')
         Displaying Segment Boundaries (``-nm'')
         Displaying Relative-to-Frames (``-rel'')
         Displaying Frames Associated with Structure IDs (``-n'')
         Displaying Summary in a Tabular Format (``-t'')
         Displaying Tabular Summary Grouped by Coverage (``-g'')
         Specifying Multiple Options Controlling Output Format
      Options Controlling Output Time Format
         Displaying Times in UTC Calendar Date Format (``-utc'')
         Displaying Times in UTC Day-of-Year Format (``-utcdoy'')
         Displaying Times as SCLK Strings (``-sclk'')
         Displaying Times as Encoded SCLKs (``-dpsclk'')
      Miscellaneous Options
         Filtering for a Specified Structure ID (``[ID]'')
         Summarizing Kernels Listed in a File (``-f [list]'')
         Displaying Help and Version (``-h'' and ``-v'')
      Troubleshooting


Top

CKBRIEF User's Guide




Last revised on 2008 FEB 12 by B. V. Semenov.



Top

Abstract



CKBRIEF is a command-line utility program that displays a contents and time coverage summary for one or more binary CK files.



Top

Summary



CKBRIEF is a command line program that displays a summary of the contents and time coverage for one or more binary CK files. The program displays a summary for each CK file listed on the command line, in a list file, and/or a meta-kernel. It can display coverage boundaries as ephemeris time (ET) in calendar format, as UTC time in ``year-month-day'' or ``day-of-year'' format, or as on-board clock (SCLK) time in string or encoded format. It can display the summary in a variety of formats, with or without showing the names of the frames associated with spacecraft or structure IDs or the names/IDs of the frames with respect to which orientation is provided.



Top

Usage



CKBRIEF is a command line program with the following usage: 

   ckbrief [-options] file [file ...]
where [file]s are binary CK files and text kernels needed to support time conversion (LSK and SCLKs), or containing frame definitions (FKs), provided in any order. The options are: 

   -dump        display interpolation intervals boundaries
   -nm          display segment boundaries
 
   -rel         display relative-to frames
   -n           display frames associated with structure IDs
 
   -t           display summary in a tabular format
   -g           display summary grouped by coverage
 
   -utc         display times in UTC calendar date format
   -utcdoy      display times in UTC day-of-year format
   -sclk        display times as SCLK strings
   -dpsclk      display times as SCLK ticks
 
   [ID]         display summary for structure with [ID]
 
   -f [list]    summarize kernels listed in the [list] file
 
   -h           display help
   -v           display version
The options can be provided in any order and can appear before, after, or intermixed with file names. The case of option keys is significant -- they must be lowercase as shown above. While any option can be provided together with any other option or a combination of options, some options will override others. For specific information on this refer to the sections of this document describing individual options in detail.

If the command line is blank, the program displays usage. If the command line contains a token that is not the name of an existing file or a recognized option, the program displays help.



Top

Helpful Hints for Those in a Hurry



This list contains a few quick suggestions about options that would be most appropriate for common summary tasks:

    -- use shell filename substitution capabilities to provide multiple file names on the command line, e.g. ``*.bc'' will be expanded into the list of all binary CK files in the current directory by most shells

    -- always provide LSK and SCLK files because they are required to display times in ET (default), UTC, and SCLK string formats

    -- use ``-dump'' to see boundaries of interpolation intervals -- the actual periods for which CK segments provide continuous coverage

    -- use ``-n'' to see the names of the frames associated with structure IDs for which CK files contain data; an FK file(s) defining these frames must be provided to the program

    -- use ``-rel'' to see the names of the frames with respect to which CK files contain data; an FK file(s) defining these frames must be provided to the program

    -- use both ``-n'' and ``-rel'' to see the frames associated with structure IDs and the frames with respect to which the CK files provide data in the same summary

    -- use ``-utc'' or ``-utcdoy'' and provide LSK and SCLK files to display times in UTC

    -- use ``-sclk'' and provide LSK and SCLK files to display times as SCLK strings

    -- use ``-t'' in combination with any other options for a more legible summary format

    -- use ``-f'' with a list file to summarize large sets of kernels, the names of which cannot be listed on the command line all at the same time



Top

Ways to Provide File Names



CKBRIEF supports three ways to provide the names of the CK files to be summarized:

    1. by listing them on the command line

    2. by getting them from a meta-kernel(s) provided on the command line and/or in a list file

    3. by listing them in a list file provided with the ``-f'' option (see ``Summarizing Kernels Listed in a File'' for more details)

In most cases CKBRIEF requires some text kernels to be provided in addition to the CK files to be summarized -- LSK and SCLK files to support time conversions, and FK files to provide frame definitions. The names of the text kernels may be provided in the same way as the names of the files to be summarized -- on the command line, in a list file, or in a meta-kernel(s).



Top

Default Summary Format



By default, when no options are specified, CKBRIEF displays summary information as a set of blocks, one for each CK file, in the order in which the files were provided on the command line and/or listed in the meta-kernels and/or the list file. Each block contains one or more tables showing the ``total'' coverage begin and end times for each of the structures for which data is provided in the file. The numeric ID of the structure is listed at the top of the table. The table header consists of the column heading line, indicating the time tag type, and a line of separating dashes. The table data consists of one or more coverage summary lines providing the begin and end times for coverage periods along with a flag indicating whether angular velocities are included in the file. These coverage periods are based on the segment descriptor information rather than on interpolation intervals from the file segments, meaning that there may be gaps within these coverage periods. The coverage begin and end times are displayed as calendar ET in the ``YYYY-MON-DD HR:MN:SC.DDD'' format. The angular velocity flag is set to ``Y'' if all segments for this ID contain angular velocity data. It is set to ``N'' if none of the segments for this ID contains angular velocity data. And it is set to ``*'' if some segments for this ID contain angular velocity while others don't.

The example below illustrates CKBRIEF's default output. This example should be used as a reference when examining the examples in later sections of this document discussing various options. The output summary lines in this example and all other examples in this document were truncated to 69 characters to fit in the maximum page width allowed for this User's Guide.

If CKBRIEF is run to display the default summary for two binary CK files -- ``m01_sc.bc'', containing orientation data for the 2001 Mars Odyssey (M01) spacecraft and ``m01_hga.bc'', containing orientation data for the M01 High Gain Antenna (HGA), -- with the LSK file ``naif0009.tls'' and the SCLK file ``m01.tsc'' files provided to support time conversions, it will generate the following summary: 

   > ckbrief m01_sc.bc m01_hga.bc m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_sc.bc
 
   Object:  -53000
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:08.296 2007-APR-01 00:01:01.564 Y
 
 
   Summary for: m01_hga.bc
 
   Object:  -53211
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y
 
   Object:  -53212
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y


Top

Options Controlling Output Summary Format



While the default summary format is adequate in many cases, the information provided in it is insufficient for requests concerning the segment or interpolation interval boundaries or frames associated with the structure IDs, or used as the reference for the CK data. To alter the type of coverage (``total'' vs. ``segments'' vs. ``intervals''), the format, and the order of records in the displayed summary, and to include frame information in the summaries, CKBRIEF provides a number of options described in this section.



Top

Displaying Interpolation Intervals (``-dump'')



The ``-dump'' option tells CKBRIEF to display a summary of interpolation interval boundaries -- the actual time periods for which the file provides data -- for each of the segments in the file, as seen in this example: 

   > ckbrief -dump m01_sc.bc m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_sc.bc
 
   Segment No.: 1
 
   Object:  -53000
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:08.296 2007-JAN-01 06:35:52.430 Y
     2007-JAN-01 06:40:16.430 2007-JAN-01 12:54:46.269 Y
     2007-JAN-01 12:58:16.269 2007-JAN-03 06:27:52.809 Y
     2007-JAN-03 06:28:58.809 2007-JAN-03 06:30:46.808 Y
     2007-JAN-03 06:35:16.808 2007-JAN-03 06:42:04.803 Y
   ...
 
   Segment No.: 18
 
   Object:  -53000
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-MAR-29 04:20:23.895 2007-MAR-29 18:36:23.126 Y
     2007-MAR-29 19:17:35.110 2007-MAR-29 20:32:13.677 Y
     2007-MAR-29 20:34:05.075 2007-APR-01 00:01:01.564 Y


Top

Displaying Segment Boundaries (``-nm'')



The ``-nm'' option tells CKBRIEF to display a summary of segment boundaries for each of the structures in the file, as seen in this example: 

   > ckbrief -nm m01_hga.bc m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_hga.bc
 
   Object:  -53211
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:57.468 2007-MAR-15 11:53:47.032 Y
     2007-MAR-15 11:53:47.032 2007-MAR-31 23:58:58.431 Y
 
   Object:  -53212
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:57.468 2007-MAR-15 11:53:47.032 Y
     2007-MAR-15 11:53:47.032 2007-MAR-31 23:58:58.431 Y
As with the default summary, the coverage displayed in this summary is based on segment descriptor information rather than on interpolation intervals from the file segments, meaning that there may be gaps within these coverage periods.



Top

Displaying Relative-to-Frames (``-rel'')



The ``-rel'' option tells CKBRIEF to display, in the additional right-hand column, frames with respect to which the orientation is given in the CK segments. For frames known to SPICE -- built-in or defined in the FK files provided to the program along with CK, LSK, and SCLK files -- the program displays names; for unrecognized frames, the program displays IDs, as seen in these examples, only one of which loads the M01 FK file ``m01.tf'' defining M01 HGA frames: 

   > ckbrief -rel m01_hga.bc m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_hga.bc
 
   Object:  -53211
     Interval Begin ET        Interval End ET          AV  Relative to F
     ------------------------ ------------------------ --- -------------
     2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y   -53210
 
   Object:  -53212
     Interval Begin ET        Interval End ET          AV  Relative to F
     ------------------------ ------------------------ --- -------------
     2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y   -53211
 
   > ckbrief -rel m01_hga.bc m01.tsc naif0009.tls m01.tf
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_hga.bc
 
   Object:  -53211
     Interval Begin ET        Interval End ET          AV  Relative to F
     ------------------------ ------------------------ --- -------------
     2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y   M01_HGA_BOOM
 
   Object:  -53212
     Interval Begin ET        Interval End ET          AV  Relative to F
     ------------------------ ------------------------ --- -------------
     2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y   M01_HGA_INNER
If a CK file contains segments that provide data for the same structure but with respect to different frames, the word ``MIXED'' is displayed in the right column instead of the frame name or ID.



Top

Displaying Frames Associated with Structure IDs (``-n'')



The ``-n'' option tells CKBRIEF to display frame names associated with the structure IDs instead of the numeric structure IDs. For frames known to SPICE -- defined in the FK files provided to the program -- the program displays names; for unrecognized frames, the program displays IDs with the prefix ``NO FRAME FOR <id>'', as seen in these examples, only one of which loads the M01 FK file ``m01.tf'' defining M01 HGA frames: 

   > ckbrief -n m01_hga.bc m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_hga.bc
 
   Frame:   NO FRAME FOR -53211
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y
 
   Frame:   NO FRAME FOR -53212
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y
 
 
   > ckbrief -n m01_hga.bc m01.tsc naif0009.tls m01.tf
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_hga.bc
 
   Frame:   M01_HGA_INNER_GIMBAL
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y
 
   Frame:   M01_HGA_OUTER_GIMBAL
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y


Top

Displaying Summary in a Tabular Format (``-t'')



The ``-t'' option tells CKBRIEF to use the tabular display format in which coverage information for all structures from each file is presented in a single table with the structure IDs provided in the left column rather than in the table headers, as seen in this example: 

   > ckbrief -t m01_hga.bc m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_hga.bc
 
   Objects  Interval Begin ET        Interval End ET          AV
   -------- ------------------------ ------------------------ ---
   -53211   2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y
   -53212      -- same --               -- same --            Y


Top

Displaying Tabular Summary Grouped by Coverage (``-g'')



The ``-g'' option tells CKBRIEF to use the grouping display format, in which information for structures with the same coverage is grouped together into blocks with the coverage begin and end time shown first, and the list of structure IDs shown below them, as seen in this example: 

   > ckbrief -g m01_hga.bc m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_hga.bc
 
   Begin ET: 2007-JAN-01 00:01:57.468  End ET: 2007-MAR-31 23:58:58.431
   Objects: -53211
            -53212


Top

Specifying Multiple Options Controlling Output Format



When ``-dump'', ``-nm'', ``-rel'', ``-n'', ``-t'', and ``-g'' are provided together, their effects are combined, resulting in a large variety of display formats. They can be provided in any combination and, in general, don't conflict, except in these cases:

    -- ``-nm'' and ``-g'' are ignored when ``-dump'' is specified,

    -- ``-rel'' is ignored when ``-g'' is specified

    -- ``-g'' is ignored when ``-t'' is specified



Top

Options Controlling Output Time Format



CKBRIEF provides a number of options that can be used to change the default output time tag format -- calendar ETs formatted as `YYYY-MON-DD HR:MN:SC.DDD'' -- to another format. These options are ``-utc'' for UTC times in the year-month-day day format, ``-utcdoy'' for UTC times in the day-of-year format, ``-sclk'' for SCLK times in string format, and ``-dpsclk'' for SCLK times in encoded format. The format chosen using any of these options applies to all summaries -- default, interval dump, grouped, etc.

In order for the program to display times in the default format or any other format (except encoded SCLK), both an LSK file and an SCLK file containing required time correlation data must be provided on the command line, in a list file (specified with the option ``-f'' described later in this document), or in a meta-kernel file given on the command line or in the list file.

When multiple options controlling the output time format are given at the same time, the option specified last on the command line takes precedence.



Top

Displaying Times in UTC Calendar Date Format (``-utc'')



The ``-utc'' option tells CKBRIEF to display time tags as UTC in the ``YYYY-MON-DD HR:MN:SC.DDD'' format, as seen in this example: 

   > ckbrief -utc m01_sc.bc m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_sc.bc
 
   Object:  -53000
     Interval Begin UTC       Interval End UTC         AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:00:03.112 2007-MAR-31 23:59:56.378 Y
Note the UTC tag format is identical to the format of ET times; the fact that the tags are UTCs is reflected in the table header.



Top

Displaying Times in UTC Day-of-Year Format (``-utcdoy'')



The ``-utcdoy'' option tells CKBRIEF to display time tags as UTC times in the ``YYYY-DOY // HR:MN:SC.DDD'' format, as seen in this example: 

   > ckbrief -utcdoy m01_sc.bc m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_sc.bc
 
   Object:  -53000
     Interval Begin UTC/DOY   Interval End UTC/DOY     AV
     ------------------------ ------------------------ ---
     2007-001 // 00:00:03.112 2007-090 // 23:59:56.378 Y


Top

Displaying Times as SCLK Strings (``-sclk'')



The ``-sclk'' option tells CKBRIEF to display time tags as SCLK strings, as seen in this example: 

   > ckbrief -sclk m01_sc.bc m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_sc.bc
 
   Object:  -53000
     Interval Begin SCLK      Interval End SCLK        AV
     ------------------------ ------------------------ ---
     2/0852077102.124         2/0859853107.255         Y


Top

Displaying Times as Encoded SCLKs (``-dpsclk'')



The ``-dpsclk'' option tells CKBRIEF to display time tags as encoded SCLKs (ticks), as seen in this example: 

   > ckbrief -dpsclk m01_sc.bc m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_sc.bc
 
   Object:  -53000
     Interval Begin TICKS     Interval End TICKS       AV
     ------------------------ ------------------------ ---
       218131739502.            220122396913.          Y


Top

Miscellaneous Options



CKBRIEF also provides a number of miscellaneous options; they are described in this section.



Top

Filtering for a Specified Structure ID (``[ID]'')



One or more (up to 100) structure IDs may be listed on the command line to tell BRIEF to display summary information only for the specified structure(s), as seen in this example: 

   > ckbrief -53000 m01_sc.bc m01_hga.bc m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_sc.bc
 
   Object:  -53000
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:08.296 2007-APR-01 00:01:01.564 Y
 
 
   No data for specified objects in m01_hga.bc


Top

Summarizing Kernels Listed in a File (``-f [list]'')



The ``-f'' option tells CKBRIEF to display a summary for the files whose names are listed in the text file ``list''. For example, when a text file named ``ck_list.txt'' with the following contents 

   m01_sc.bc
   m01_hga.bc
is provided to CKBRIEF using this option, the program displays a summary for these two CKs as if they were provided on the command line: 

   > ckbrief -f ck_list.txt m01.tsc naif0009.tls
 
   CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0062
 
 
   Summary for: m01_hga.bc
 
   Object:  -53211
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y
 
   Object:  -53212
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:57.468 2007-MAR-31 23:58:58.431 Y
 
 
   Summary for: m01_sc.bc
 
   Object:  -53000
     Interval Begin ET        Interval End ET          AV
     ------------------------ ------------------------ ---
     2007-JAN-01 00:01:08.296 2007-APR-01 00:01:01.564 Y
This option is useful when there is a need to produce a summary for a large number of files whose names, if put all together on the command line, may overflow either the terminal shell buffer or CKBRIEF's command line buffer. In such cases a simple listing of these files can be made and provided to CKBRIEF using the ``-f'' option.

The list file name specified after ``-f'' must be separated from ``-f'' by one or more spaces, i.e. ``-f FILE'' not ``-fFILE''. The list file may include only the names of binary CK files and text kernels. The file names can be provided one-per-line or a few-per-line separated by one or more spaces. The file may include blank lines. IMPORTANT: All lines in the list file, including the last line, must be terminated with the line terminators native to the computer platform on which the program is run.

When a list file is provided to the program, additional files to be summarized can still be listed on the command line.

If ``-f'' is provided more than once, only the list file provided using the last occurrence of this option is considered and all earlier ones are ignored.



Top

Displaying Help and Version (``-h'' and ``-v'')



When run with a blank command line CKBRIEF displays a short usage message listing only the most useful options.

The ``-h'' option tells CKBRIEF to display a more complete usage message listing all options. This display is similar to the text provided in the ``Usage'' section of this document. When ``-h'' is specified, CKBRIEF ignores any other options and/or file names specified on the command line.

The ``-v'' option tells CKBRIEF to display just the version line that is normally displayed at the top of every summary produced by the program. This option is ignored if ``-h'' or any file names are provided.



Top

Troubleshooting



In most cases of incorrect usage CKBRIEF displays an error message or an information message indicating what went wrong. The exceptions are cases of the command line buffer overflow and coverage data buffer overflow.

The CKBRIEF command line buffer can hold up to 25,000 characters. If the command line is longer than 25,000 characters it gets truncated. The truncation most frequently happens in the middle of a file name resulting in the ``SPICE(FILENOTFOUND)'' error being signaled. To fix this situation the number of files provided on the command line should be reduced, or a list file listing all required files should be created and provided with the ``-f'' option.

When CKBRIEF coverage information buffers overflow due to too many segments present in a file (for any summary run) or too many intervals present in a single segment (for summaries with ``-dump''), CKBRIEF displays the ``SPICE(BUFFEROVERRUN1/2)'' or the ``SPICE(WINDOWEXCESS)'' error. If this happens, the user must contact NAIF because the situation cannot be fixed by the user.