 
BRIEF User's Guide
===========================================================================
 
   Last revised on 2021 SEP 17 by B. V. Semenov.
 
 
Abstract
--------------------------------------------------------
 
   BRIEF is a command-line utility program that displays a contents and
   time coverage summary for one or more binary SPK or binary PCK files.
 
 
Summary
--------------------------------------------------------
 
   BRIEF is a command line program that displays summary of the contents
   and time coverage for one or more binary SPK or binary PCK files. The
   program can display a summary for each individual file listed on the
   command line, in a list file, and/or a meta-kernel, or for all files as
   if they were combined into a single file. It can display coverage
   boundaries as Ephemeris Times (ET) in calendar format, if requested
   rounded to the nearest second, minute, hour, or day, as ET seconds past
   J2000, as UTC times in ``year-month-day'' format , or as UTC times in
   ``day-of-year'' format. BRIEF can restrict summary display to only
   specified bodies or frames and/or specified centers-of-motion or
   relative-to-frames and/or for a specified time or time interval. It can
   display the summary in a variety of formats, ordered by body or frame
   names or numeric IDs, with or without showing centers-of-motion or
   relative-to-frames.
 
 
Usage
--------------------------------------------------------
 
   BRIEF is a command line program with the following usage:
 
      > brief [-options] file [file ...]
 
   where [file]s are binary SPK or PCK files, and possibly text kernels
   needed to support some of the display types. The options are:
 
      -c           display centers-of-motion/relative-to-frames
      -t           display summary in a tabular format
      -a           treat all files as a single file
 
      -s           display summary sorted by start time for each body
      -g           display summary grouped by coverage
      -n           display bodies/frames using only numeric id-codes
      -o           display summary ordered by body/frame name
 
      -utc         display times in UTC calendar date format
      -utcdoy      display times in UTC day-of-year format
      -etsec       display times as ET seconds past J2000
 
      -sec         display times ``rounded inward'' to second
      -min         display times ``rounded inward'' to minute
      -hour        display times ``rounded inward'' to hour
      -day         display times ``rounded inward'' to day
 
      -<bod>       display summary for body [bod]
      -sb<bod>     display summary for body [bod]
      -sc<cen>     display summary for center/relative-to-frame [cen]
      -at <time>   display summary if coverage contains epoch [time]
      -from <beg>  display summary if coverage contains interval [beg]:
      -to <end>    display summary if coverage contains interval :[end]
 
      -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.
 
 
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. ``*.bsp'' will be
            expanded into the list of all binary SPK files in the current
            directory by most shells
 
       --   use ``-t'' in combination with any other options for more a
            legible summary format
 
       --   use ``-c'' to see centers-of-motion when you need to identify
            those for which a SPICE error message reported lack of
            ephemeris data
 
       --   use ``-t -c -s'' to see when/if a body switches its
            center-of-motion
 
       --   use ``-a'' for a set of kernels that are to be used together
 
       --   use ``-a'' when summarizing SPK files in a meta-kernel to see
            the combined set of ephemeris data available to an application
            that loads that meta-kernel
 
       --   use ``-utc'' or ``-utcdoy'' and provide an LSK file to display
            times in UTC
 
       --   provide FK files with body name-ID mappings and frame
            definitions to display names of bodies/frames not built into
            SPICE
 
       --   use ``-etsec'' to display times as ET seconds past J2000
 
       --   use ``-sb'' to find out which kernels from a set contain data
            for the body of interest
 
       --   use ``-at'' or ``-from''/``-to'' to find out which kernels from
            a set provide coverage for the time or the time interval of
            interest
 
       --   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
 
 
Ways to Provide File Names
--------------------------------------------------------
 
   BRIEF supports three ways to provide names of 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 section ``Summarizing Kernels Listed in a File'' for more
            details)
 
   While each of these methods by itself or any combination of them may be
   used, the following two restrictions apply:
 
       1.   BRIEF cannot summarize binary SPK files and binary PCK files in
            the same run. If you attempt to do so BRIEF responds with an
            error message.
 
       2.   BRIEF summarizes only SPK files included in a meta-kernel(s).
            If binary PCK files are provided in a meta-kernel(s), BRIEF
            ignores them in all cases, even if a meta-kernel(s) lists just
            PCK files and no SPK files.
 
   In some cases BRIEF requires text kernels to be provided in addition to
   the files to be summarized. Such cases include providing an LSK file
   when times are to be displayed as UTC and providing an FK file when
   names need to be displayed in addition to numeric IDs for bodies/frames
   not built into SPICE. The names of text kernels may be provided in the
   same ways as the names of the files to be summarized -- on the command
   line, in a list file, or in a meta-kernel(s).
 
 
Default Summary Format
--------------------------------------------------------
 
   By default, when no options are specified, BRIEF displays summary
   information as a set of blocks, one for each SPK or PCK file, in the
   order in which the files were provided on the command line. Each block
   contains one or more tables showing coverage begin and end times for a
   set of bodies/frames with the same coverage provided by the file. The
   names and/or numeric IDs of the bodies/frames are listed at the top of
   each table in one or more columns, ordered by body/frame numeric ID down
   the columns. The coverage table itself, consisting of the column heading
   line indicating the time tag type, the line with separating dashes, and
   the coverage begin and end time, is provided below the body/frame list.
   The coverage begin and end times are displayed as calendar ET in the
   ``YYYY MON DD HR:MN:SC.DDD'' format while the body/frame name and
   numeric ID are displayed in the `NAME (ID)'' format, if numeric IDs can
   be mapped to names, or in the ``ID'' format, if numeric IDs cannot be
   mapped to names.
 
   Two examples below illustrate BRIEF's default output for SPK and PCK
   files. These examples should be used as a reference when examining the
   examples in the later sections of this document discussing various
   options. To fit in the maximum page width allowed for this User's Guide
   lines in these examples and all other examples in this document were
   truncated at 69 characters.
 
   If BRIEF is run to display the default summary for three binary SPK
   files
 
       --   ``stardust.bsp'' containing trajectory data for Stardust
            covering from 2003-DEC-01 to 2004-JAN-10, ephemerides for Solar
            System barycenters, Sun, Mercury, Venus, Moon, Earth and Mars
            covering from 1959-DEC-10 to 2020-JAN-16, and ephemerides for
            comet Wild 2 covering from 2002-JAN-01 to 2007-APR-05,
 
       --   ``tempel1.bsp'' containing ephemerides for comet Tempel 1
            covering from 2000-JAN-01 to 2050-JAN-01, and
 
       --   ``dss_17_prelim_itrf93_161110.bsp'' containing location data
            for the DSN tracking station DSS-17 covering from 1950-JAN-01
            to 2050-JAN-01
 
   it will generate the following report:
 
      > brief stardust.bsp tempel1.bsp dss_17_prelim_itrf93_161110.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      Body: SDU (-29)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2003 DEC 01 00:01:04.183            2004 JAN 10 01:00:00.000
 
      Bodies: MERCURY BARYCENTER (1)  SATURN BARYCENTER (6)   MERCURY (199)
              VENUS BARYCENTER (2)    URANUS BARYCENTER (7)   VENUS (299)
              EARTH BARYCENTER (3)    NEPTUNE BARYCENTER (8)  MOON (301)
              MARS BARYCENTER (4)     PLUTO BARYCENTER (9)    EARTH (399)
              JUPITER BARYCENTER (5)  SUN (10)                MARS (499)
              Start of Interval (ET)              End of Interval (ET)
              -----------------------------       -------------------------
              1959 DEC 10 00:00:00.000            2020 JAN 16 00:00:00.000
 
      Body: WILD 2 (1000107)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2002 JAN 01 00:00:00.000            2007 APR 05 00:00:00.000
 
 
      Summary for: tempel1.bsp
 
      Body: TEMPEL 1 (1000093)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2000 JAN 01 00:00:00.000            2050 JAN 01 00:00:00.000
 
 
      Summary for: dss_17_prelim_itrf93_161110.bsp
 
      Body: DSS-17 (399017)*
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            1950 JAN 01 00:00:00.000            2050 JAN 01 00:00:00.000
 
 
   Note that ``*'' following the DSS-17 ID indicates that its data is
   provided in a non-inertial frame.
 
   If BRIEF is run to generate the default summary for a binary PCK file
   called ``moon_pa_de418.bpc'' containing orientation data for the
   ``MOON_PA_DE418'' frame with the frame class ID 31004, it will generate
   the following summary:
 
      > brief moon_pa_de418.bpc
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: moon_pa_de418.bpc
 
      Frame: 31004
             Start of Interval (ET)              End of Interval (ET)
             -----------------------------       --------------------------
             1950 JAN 01 00:00:00.000            2050 DEC 31 00:00:00.000
 
 
 
Options Controlling Output Summary Format
--------------------------------------------------------
 
   While the default summary format is adequate in many cases, it starts
   looking rather cumbersome when many files need to be summarized in one
   run, or when the file(s) to be summarized contain data for many
   bodies/frames with varying coverages. Moreover, the default file format
   does not include one additional summary item that BRIEF is capable of
   displaying -- centers-of-motion/relative-to-frames for the bodies/frames
   covered by the file(s). To alter the format and the order of records in
   the displayed summary BRIEF provides a number of options described in
   this section.
 
 
Displaying Centers-of-Motion/Relative-to-Frames (``-c'')
 
   The ``-c'' option tells BRIEF to display bodies/frames in the format
   that shows their centers-of-motion (for SPKs) or relative-to-frames (for
   binary PCKs), as seen in this example for an SPK file:
 
      > brief -c stardust.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      Body: SDU (-29) w.r.t. SUN (10)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2003 DEC 01 00:01:04.183            2004 JAN 10 01:00:00.000
 
      Bodies: MERCURY BARYCENTER (1) w.r.t. SOLAR SYSTEM BARYCENTER (0)
              VENUS BARYCENTER (2) w.r.t. SOLAR SYSTEM BARYCENTER (0)
              EARTH BARYCENTER (3) w.r.t. SOLAR SYSTEM BARYCENTER (0)
              MARS BARYCENTER (4) w.r.t. SOLAR SYSTEM BARYCENTER (0)
              JUPITER BARYCENTER (5) w.r.t. SOLAR SYSTEM BARYCENTER (0)
              SATURN BARYCENTER (6) w.r.t. SOLAR SYSTEM BARYCENTER (0)
              URANUS BARYCENTER (7) w.r.t. SOLAR SYSTEM BARYCENTER (0)
              NEPTUNE BARYCENTER (8) w.r.t. SOLAR SYSTEM BARYCENTER (0)
              PLUTO BARYCENTER (9) w.r.t. SOLAR SYSTEM BARYCENTER (0)
              SUN (10) w.r.t. SOLAR SYSTEM BARYCENTER (0)
              MERCURY (199) w.r.t. MERCURY BARYCENTER (1)
              VENUS (299) w.r.t. VENUS BARYCENTER (2)
              MOON (301) w.r.t. EARTH BARYCENTER (3)
              EARTH (399) w.r.t. EARTH BARYCENTER (3)
              MARS (499) w.r.t. MARS BARYCENTER (4)
              Start of Interval (ET)              End of Interval (ET)
              -----------------------------       -------------------------
              1959 DEC 10 00:00:00.000            2020 JAN 16 00:00:00.000
 
      Body: WILD 2 (1000107) w.r.t. SUN (10)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2002 JAN 01 00:00:00.000            2007 APR 05 00:00:00.000
 
 
   When ``-c'' is used each distinct body and center-of-motion, or frame
   and relative-to-frame, combination present in the file segments is
   treated as a separate entity for the purpose of summarizing coverage.
   Knowing the centers-of-motion is usually needed to find out whether an
   SPK file, or a set of SPK files, contains data for all objects required
   to compute position of one body of interest with respect to another body
   of interest.
 
   The ``-c'' option changes the default format for bodes/frames from
   ``NAIF (ID)'' to ``NAME (ID) w.r.t. NAME (ID)''.
 
 
Treating All Files as a Single File (``-a'')
 
   The ``-a'' option tells BRIEF to display combined summary for all files
   as if all data from these files were merged into a single file, as seen
   in this example:
 
      > brief -a stardust.bsp tempel1.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for all files.
 
      Body: SDU (-29)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2003 DEC 01 00:01:04.183            2004 JAN 10 01:00:00.000
 
      Bodies: MERCURY BARYCENTER (1)  SATURN BARYCENTER (6)   MERCURY (199)
              VENUS BARYCENTER (2)    URANUS BARYCENTER (7)   VENUS (299)
              EARTH BARYCENTER (3)    NEPTUNE BARYCENTER (8)  MOON (301)
              MARS BARYCENTER (4)     PLUTO BARYCENTER (9)    EARTH (399)
              JUPITER BARYCENTER (5)  SUN (10)                MARS (499)
              Start of Interval (ET)              End of Interval (ET)
              -----------------------------       -------------------------
              1959 DEC 10 00:00:00.000            2020 JAN 16 00:00:00.000
 
      Body: TEMPEL 1 (1000093)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2000 JAN 01 00:00:00.000            2050 JAN 01 00:00:00.000
 
      Body: WILD 2 (1000107)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2002 JAN 01 00:00:00.000            2007 APR 05 00:00:00.000
 
 
   When ``-a'' is used the output display includes the ``Summary for all
   files'' heading to indicate that the displayed summary is for all files.
 
 
Display Summary in a Tabular Format (``-t'')
 
   The ``-t'' option tells BRIEF to use a tabular display format in which
   all coverage information for each file is presented in a single table
   with bodies/frames provided in the left column rather than in the table
   header, as seen in this example:
 
      > brief -t stardust.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      Bodies                Start of Interval (ET)          End of Interval
      -------               -----------------------------   ---------------
      -29 SDU               2003 DEC 01 00:01:04.183        2004 JAN 10 01:
      1 MERCURY BARYCENTER  1959 DEC 10 00:00:00.000        2020 JAN 16 00:
      2 VENUS BARYCENTER                Same coverage as previous object
      3 EARTH BARYCENTER                Same coverage as previous object
      4 MARS BARYCENTER                 Same coverage as previous object
      5 JUPITER BARYCENTER              Same coverage as previous object
      6 SATURN BARYCENTER               Same coverage as previous object
      7 URANUS BARYCENTER               Same coverage as previous object
      8 NEPTUNE BARYCENTER              Same coverage as previous object
      9 PLUTO BARYCENTER                Same coverage as previous object
      10 SUN                            Same coverage as previous object
      199 MERCURY                       Same coverage as previous object
      299 VENUS                         Same coverage as previous object
      301 MOON                          Same coverage as previous object
      399 EARTH                         Same coverage as previous object
      499 MARS                          Same coverage as previous object
      1000107 WILD 2        2002 JAN 01 00:00:00.000        2007 APR 05 00:
 
   The records in the table are ordered by body/frame numeric ID and
   bodies/frames are shown in ``ID NAME'' format. The ``Same coverage as
   previous object'' string is shown for any body/frame that has the same
   coverage as the body/frame immediately above it.
 
 
Displaying Tabular Summary Sorted by Start Time (``-s'')
 
   The ``-s'' option tells BRIEF to re-order records in the tables of the
   tabular output in such way that the records for a particular body or
   frame are grouped together and sorted by the start time within each
   group. This option is particularly useful for the output including the
   centers-of-motion (for SPKs) or relative-to-frames (for binary PCKs)
   because it shows in chronological order when/if a body switches its
   center-of-motion or a frame switches its relative-to-frame. This option
   supersedes ``-g'' and has no effect without ``-t''.
 
   In this example ``-s'' is used to produce a summary of the CASSINI inner
   cruise SPK file, which provides CASSINI spacecraft trajectory relative
   to different centers-of-motion during different time intervals:
 
      > brief -c -t -s cas_inner_cruise.bsp
 
      BRIEF -- Version 4.0.0, September 8, 2010 -- Toolkit Version N0064
 
 
      Summary for: cas_inner_cruise.bsp
 
      Bodies                                 Start of Interval (ET)    End
      -------                                ------------------------  ----
      -82 CASSINI w.r.t. 10 SUN              1997 NOV 15 00:00:00.000  1998
      -82 CASSINI w.r.t. 2 VENUS BARYCENTER  1998 APR 25 10:37:10.235  1998
      -82 CASSINI w.r.t. 10 SUN              1998 APR 27 16:54:58.844  1999
      -82 CASSINI w.r.t. 2 VENUS BARYCENTER  1999 JUN 24 02:37:43.459  1999
      -82 CASSINI w.r.t. 10 SUN              1999 JUN 25 14:24:23.301  1999
                                             1999 JUL 06 16:01:04.183  1999
      -82 CASSINI w.r.t. 399 EARTH           1999 AUG 17 11:38:55.368  1999
      -82 CASSINI w.r.t. 10 SUN              1999 AUG 18 19:20:02.623  1999
 
 
Displaying Tabular Summary Grouped by Coverage (``-g'')
 
   The ``-g'' option tells BRIEF to re-order records in the tables of the
   tabular output such that all records with the same coverage are grouped
   together. This option has no effect without ``-t''.
 
   No example for ``-g'' is provided in this section because if it were
   used to summarize ``stardust.bsp'' it would produce the same output as
   ``-t'' by itself, in which, by chance, records are already grouped by
   coverage.
 
 
Displaying Bodies/Frames Using Only Numeric IDs (``-n'')
 
   The ``-n'' option tells BRIEF to display bodies/frames using numeric IDs
   (``ID'') rather than the default name/ID combinations (``NAME (ID)''),
   as seen in this example:
 
      > brief -n stardust.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      Body: -29
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2003 DEC 01 00:01:04.183            2004 JAN 10 01:00:00.000
 
      Bodies: 1       3       5       7       9       199     301     499
              2       4       6       8       10      299     399
              Start of Interval (ET)              End of Interval (ET)
              -----------------------------       -------------------------
              1959 DEC 10 00:00:00.000            2020 JAN 16 00:00:00.000
 
      Body: 1000107
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2002 JAN 01 00:00:00.000            2007 APR 05 00:00:00.000
 
 
 
Displaying Summary Ordered by Body/Frame Name (``-o'')
 
   The ``-o'' option tells BRIEF to order bodies/frames in the table
   headers in the default display, or in the left columns in the tabular
   display, by name rather than by numeric ID, as seen in this example:
 
      > brief -o stardust.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      Bodies: EARTH (399)             MERCURY (199)           SATURN BARYCE
              EARTH BARYCENTER (3)    MERCURY BARYCENTER (1)  SUN (10)
              JUPITER BARYCENTER (5)  MOON (301)              URANUS BARYCE
              MARS (499)              NEPTUNE BARYCENTER (8)  VENUS (299)
              MARS BARYCENTER (4)     PLUTO BARYCENTER (9)    VENUS BARYCEN
              Start of Interval (ET)              End of Interval (ET)
              -----------------------------       -------------------------
              1959 DEC 10 00:00:00.000            2020 JAN 16 00:00:00.000
 
      Body: SDU (-29)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2003 DEC 01 00:01:04.183            2004 JAN 10 01:00:00.000
 
      Body: WILD 2 (1000107)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2002 JAN 01 00:00:00.000            2007 APR 05 00:00:00.000
 
 
   For the default format ``-o'' also changes the order in which the tables
   are displayed by ordering them by the name of the first body/frame
   appearing in the table headers.
 
 
Specifying Multiple Options Controlling Output Format
 
   When ``-c'', ``-a'', ``-t'', ``-o'', ``-n'', ``-g'', and ``-s'' are
   provided together their effects are combined, resulting in a large
   variety of display formats (see ``Appendix 1: Matrix of Output
   Formats''). They can be provided in any combination and, in general,
   don't depend on each other, except in these cases:
 
       --   ``-o'' is ignored when ``-n'' is specified,
 
       --   ``-g'' has effect only when provided together with ``-t''
 
       --   ``-s'' has effect only when provided together with ``-t''
 
       --   ``-s'' supersedes ``-g''
 
       --   ``-g'' regroups tabular display tables already ordered by name
            (``-o'') or by numeric ID (no ``-o'')
 
       --   ``-s'' re-sorts tabular display tables already ordered by name
            (``-o'') or by numeric ID (no ``-o'')
 
 
Options Controlling Output Time Format
--------------------------------------------------------
 
   By default, BRIEF displays coverage time tags as calendar ET in the
   ``YYYY MON DD HR:MN:SC.DDD'' format. This section describes options that
   change this behavior.
 
   The first category of options affecting displayed time tags are the
   options that tell BRIEF to display time tags in a different time system
   and/or format. These options are ``-etsec'', ``-utc'', and ``-utcdoy''.
 
   The second category of options affecting displayed time tags are the
   options that tell BRIEF to round the default calendar ET time tags
   inwards. These options are ``-sec'', ``-min'', ``-hour'', and ``-day''.
   The ``rounding inwards'' performed by these options adjusts both ends of
   a coverage interval toward the even second, minute, hour, or day
   boundary nearest to the interval center. For example, the interval
   ``2007 JAN 12 12:05:06.333 .. 2007 JAN 13 22:45:23.765'' rounded inward
   to hour becomes ``2007 JAN 12 13:00:00.000 .. 2007 JAN 13
   22:00:00.000''.
 
 
Displaying Times as ET Seconds Past J2000 (``-etsec'')
 
   The ``-etsec'' option tells BRIEF to display time tags as ET seconds
   past J2000 in the ``SSSSSSSSSSSS.DDDDDD'' format, as seen in this
   example:
 
      > brief -etsec tempel1.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: tempel1.bsp
 
      Body: TEMPEL 1 (1000093)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
                       -43200.000000                   1577880000.000000
 
 
 
Displaying Times in UTC Calendar Date Format (``-utc'')
 
   The ``-utc'' option tells BRIEF to display time tags as UTC in the
   ``YYYY-MON-DD HR:MN:SC.DDD'' format, as seen in this example:
 
      > brief -utc naif0008.tls tempel1.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: tempel1.bsp
 
      Body: TEMPEL 1 (1000093)
            Start of Interval (UTC)             End of Interval (UTC)
            -----------------------------       ---------------------------
            1999-DEC-31 23:58:55.816            2049-DEC-31 23:58:54.816
 
 
   An LSK file must be provided to BRIEF in order to display times tags in
   this format because LSK data are required to convert ET times stored in
   binary SPK and PCK files to UTC. An LSK file may 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.
 
 
Display Times in UTC Day-of-Year Format (``-utcdoy'')
 
   The ``-utcdoy'' option tells BRIEF to display time tags as UTC times in
   the ``YYYY-DOY // HR:MN:SC.DDD'' format, as seen in this example:
 
      > brief -utcdoy naif0008.tls tempel1.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: tempel1.bsp
 
      Body: TEMPEL 1 (1000093)
            Start of Interval (UTC)             End of Interval (UTC)
            -----------------------------       ---------------------------
            1999-365 // 23:58:55.816            2049-365 // 23:58:54.816
 
 
   An LSK file must be provided to BRIEF in order to display times tags in
   this format because LSK data are required to convert ET times stored in
   binary SPK and PCK files to UTC for output. An LSK file may 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.
 
 
Display Times ``Rounded Inward'' to Second (``-sec'')
 
   The ``-sec'' option tells BRIEF to display default calendar ET time tags
   ``rounded inward'' to the nearest second, as seen in this example:
 
      > brief -sec stardust.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      Body: SDU (-29)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2003 DEC 01 00:01:05.000            2004 JAN 10 01:00:00.000
 
      ...
 
   When this option is applied to a coverage window shorter than one second
   it produces a singleton interval with the interval's begin time equal to
   its end time. When such a short interval spans a second boundary, the
   times are set to the time of that boundary. When such a short interval
   does not span a second boundary, the times are set to the un-rounded end
   time of the interval.
 
 
Display Times ``Rounded Inward'' to Minute (``-min'')
 
   The ``-min'' option tells BRIEF to display default calendar ET time tags
   ``rounded inward'' to the nearest minute, as seen in this example:
 
      > brief -min stardust.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      Body: SDU (-29)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2003 DEC 01 00:02:00.000            2004 JAN 10 01:00:00.000
 
      ...
 
   When this option is applied to a coverage window shorter than one minute
   it produces a singleton interval with the interval's begin time equal to
   its end time. When such a short interval spans a minute boundary, the
   times are set to the time of that boundary. When such a short interval
   does not span a minute boundary, the times are set to the un-rounded end
   time of the interval.
 
 
Display Times ``Rounded Inward'' to Hour (``-hour'')
 
   The ``-hour'' option tells BRIEF to display default calendar ET time
   tags ``rounded inward'' to the nearest hour, as seen in this example:
 
      > brief -hour stardust.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      Body: SDU (-29)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2003 DEC 01 01:00:00.000            2004 JAN 10 01:00:00.000
 
      ...
 
   When this option is applied to a coverage window shorter than one hour
   it produces a singleton interval with the interval's begin time equal to
   its end time. When such a short interval spans ah hour boundary, the
   times are set to the time of that boundary. When such a short interval
   does not span an hour boundary, the times are set to the un-rounded end
   time of the interval.
 
 
Display Times ``Rounded Inward'' to Day (``-day'')
 
   The ``-day'' option tells BRIEF to display default calendar ET time tags
   ``rounded inward'' to the nearest day, as seen in this example:
 
      > brief -day stardust.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      Body: SDU (-29)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2003 DEC 02 00:00:00.000            2004 JAN 10 00:00:00.000
 
      ...
 
   When this option is applied to a coverage window shorter than one day it
   produces a singleton interval with the interval's begin time equal to
   its end time. When such a short interval spans a day boundary, the times
   are set to the time of that boundary. When such a short interval does
   not span a day boundary, the times are set to the un-rounded end time of
   the interval.
 
 
Specifying Multiple Options Controlling Time Format
 
   If more than one of the ``-etsec'', ``-utc'', ``-utcdoy'' options is
   specified, the one provided last on the command line takes precedence.
 
   If more than one of the ``-sec'', ``-min'', ``-hour'', and ``-day''
   options is specified, the one providing the ``highest'' time resolution
   takes precedence, e.g. when ``-min'' and ``-day'' are specified the
   times are rounded to minute independently of the placement of these
   options on the command line.
 
   The ``rounding'' options ``-sec'', ``-min'', ``-hour'', and ``-day''
   have no effect when time tags are displayed in a format other than
   calendar ET, i.e. when either of the ``-etsec'', ``-utc'', or
   ``-utcdoy'' options is specified.
 
 
Options Filtering Summary
--------------------------------------------------------
 
   In some cases rather than displaying the full summary of data from a
   single binary SPK or PCK file, or a set of binary SPK or PCK files, it
   is more desirable to check if the file or files contain data for a
   specified body/frame or at a specified epoch. To filter summary
   information based on such criteria BRIEF provides a number of options
   described in this section.
 
 
Filtering for a Specified Body/Frame (``-sb[bod]'' or ``-[bod]'')
 
   The ``-sb'' option followed by a body/frame name or numeric ID ``bod''
   tells BRIEF to display summary information only for the specified
   body/frame. While ``sb'' can be omitted from the option key permitting
   one to use just ``-'' followed by the body/frame name or numeric ID,
   including ``-sb'' is the preferred method as it is slightly more clear.
   In this example ``-sb'' is used to display data for only the Earth:
 
      > brief -sbEARTH stardust.bsp tempel1.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      Body: EARTH (399)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            1959 DEC 10 00:00:00.000            2020 JAN 16 00:00:00.000
 
 
      Summary for: tempel1.bsp
 
 
      There is no data:
        for body 'EARTH'
 
 
   The body/frame name or numeric ID must immediately follow ``-sb'', i.e.
   ``-sbEARTH'', ``-sb-29'', or ``-sb301'' not ``-sb EARTH'', ``-sb -29'',
   or ``-sb 301''. If the body/frame name contains spaces, these spaces
   must be replaced with underscores (``_''), i.g.
   ``-sbMERCURY_BARYCENTER'' must be used instead of ``-sbMERCURY
   BARYCENTER''.
 
   A range of numeric IDs in the form ``-sb[min:max]'' may be used instead
   of a single name or numeric ID. For example, ``-sb[500:598]'' may be
   used to see if a given SPK file contain data for any satellites of
   Jupiter. The range can be open on either end, producing a summary for
   all numeric IDs greater than the specified value (``-sb[min:]'') or less
   than the specified value (``-sb[:max]''). For example, ``-sb[11:]'' may
   be used to see if a given SPK file(s) contains data for any natural
   bodies while ``-sb[:-1]'' may be used to see if a given SPK file(s)
   contains data for any spacecraft. In some Unix shells the options
   providing ranges must be quoted with single or double quotes to avoid
   errors from parsing ``['' and ``]'' as special shell characters.
 
   When a file does not contain any data for the specified body/frame name,
   numeric ID, or range of numeric IDs, BRIEF displays the ``There is no
   data: ...'' message instead of the summary table as seen in the example
   above.
 
 
Filtering for a Specified Center/Relative-to-Frame (``-sc[cen]'')
 
   The ``-sc'' option followed by a body/frame name or numeric ID ``cen''
   tells BRIEF to display summary information only for the specified
   center-of-motion/relative-to-frame. In this example ``-sc'' is used to
   display data only for the bodies that have ephemeris data with respect
   to the Solar System Barycenter:
 
      > brief -sc0 stardust.bsp tempel1.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      Bodies: MERCURY BARYCENTER (1)  JUPITER BARYCENTER (5)  PLUTO BARYCEN
              VENUS BARYCENTER (2)    SATURN BARYCENTER (6)   SUN (10)
              EARTH BARYCENTER (3)    URANUS BARYCENTER (7)
              MARS BARYCENTER (4)     NEPTUNE BARYCENTER (8)
              Start of Interval (ET)              End of Interval (ET)
              -----------------------------       -------------------------
              1959 DEC 10 00:00:00.000            2020 JAN 16 00:00:00.000
 
 
      Summary for: tempel1.bsp
 
 
      There is no data:
        w.r.t. center 'SOLAR SYSTEM BARYCENTER'
 
 
   All formatting rules for the ``-sb'' option described in the previous
   section apply to the ``-sc'' option.
 
 
Filtering for a Specified Epoch (``-at [time]'')
 
   The ``-at'' option followed by a calendar ET time ``time'' tells BRIEF
   to display summary information only for the bodies/frames whose coverage
   intervals contains the specified time. In this example ``-at'' is used
   to display data only for the bodies that have coverage at ``2030-JAN-01
   12:00'' ET:
 
      > brief -at 2030-JAN-01/12:00 stardust.bsp tempel1.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      There is no data:
        covering ET '2030 JAN 01 12:00:00.000'
 
 
      Summary for: tempel1.bsp
 
      Body: TEMPEL 1 (1000093)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2000 JAN 01 00:00:00.000            2050 JAN 01 00:00:00.000
 
 
   The time specified after ``-at'' must be separated from ``-at'' by one
   or more spaces, i.e. ``-at TIME'' not ``-atTIME''. The time can be
   provided in any format supported by SPICE's TPARSE routine (see
   TIME.REQ) as long as it doesn't contain spaces. A few of the acceptable
   time formats are ``YYYY-MM-DD/HR:MN:SC.DDD'', ``YYYY-DOY/HR:MN:SC.DDD'',
   and ``JDNNNNNNNNN.DDDDDD''.
 
   When a file does not contain any data for the specified time BRIEF
   displays the ``There is no data: ...'' message instead of the summary
   table as seen in the example above.
 
 
Filtering for a Specified Interval (``-from [beg]'' and ``-to [end]'')
 
   The options ``-from'' and ``-to'' followed by calendar ET times ``beg''
   and ``end'' tell BRIEF to display summary information only for the
   bodies/frames whose coverages contain the specified time interval. In
   this example ``-from'' and ``-to'' are used to display data only for the
   bodies with coverage that contains the interval from ``2025-01-01 ET''
   to ``2025-02-01 ET''
 
      > brief -from 2025-01-01 -to 2025-02-01 stardust.bsp tempel1.bsp
 
      BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0062
 
 
      Summary for: stardust.bsp
 
      There is no data:
        covering from ET '2025 JAN 01 00:00:00.000' to ET '2025 FEB 01 00:
 
 
      Summary for: tempel1.bsp
 
      Body: TEMPEL 1 (1000093)
            Start of Interval (ET)              End of Interval (ET)
            -----------------------------       ---------------------------
            2000 JAN 01 00:00:00.000            2050 JAN 01 00:00:00.000
 
 
   All formatting rules for the ``-at'' option described in the previous
   section apply to the ``-from'' and ``-at'' options. If either ``-from''
   or ``-to'' is specified by itself it has the same effect as the ``-at''
   option.
 
 
Specifying Multiple Filtering Options
 
   Up to 100 individual ``-sb'', ``-'', and ``-sc'' constraints can be
   specified at the same time. BRIEF combines them using logical ``OR'' and
   displays a summary for all bodies/frames and
   centers-of-motion/relative-to-frames specified by these constraints.
 
   ``-at'' specified together with ``-from''/``-to'' overrides them. When
   multiple ``-at'', ``-from'', or ``-to'' are provided, for each of them
   the one provided last on the command line takes precedence. If the time
   provided with ``-from'' is later than the time provided with ``-to''
   BRIEF re-orders them internally.
 
   Constraints from body/frame and time groups can be provided at the same
   time. BRIEF combines them using logical ``AND'' and displays summary for
   the specified bodies/frames only if they have coverage at the specified
   time or time interval.
 
 
Miscellaneous Options
--------------------------------------------------------
 
   BRIEF also provides a number of miscellaneous options; they are
   described in this section.
 
 
Summarizing Kernels Listed in a File (``-f [list]'')
 
   The ``-f'' option tells BRIEF to display a summary for the files whose
   names are listed in the text file ``list''. For example, when a text
   file named ``spk_list.txt'' with the following contents
 
      stardust.bsp
      tempel1.bsp
 
   is provided to BRIEF using this option, the program displays a summary
   for these two SPKs as if they were provided on the command line.
 
   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 BRIEF's command
   line buffer. In such cases a simple listing of these files can be made
   and provided to BRIEF 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
   must include only the names of binary SPK files and text kernels or the
   names of binary PCK 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. 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.
 
 
Displaying Help and Version (``-h'' and ``-v'')
 
   When run with a blank command line BRIEF displays a short usage message
   listing only the most useful options.
 
   The ``-h'' option tells BRIEF 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, BRIEF
   ignores any other options and/or file names specified on the command
   line.
 
   The ``-v'' option tells BRIEF to display just the version line that is
   normally displayed at the top of every summary produced by the program.
   When this option is specified, BRIEF ignores any other options,
   including ``-h'', and/or file names specified on the command line.
 
 
Troubleshooting
--------------------------------------------------------
 
   In most cases of incorrect usage BRIEF 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 BRIEF 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 BRIEF coverage information buffers overflow due to too many
   bodies/frames present in a file, or too many intervals for a body/frame,
   or too many intervals for all bodies/frames, BRIEF displays the
   ``SPICE(WINDOWEXCESS)'', ``SPICE(NAMETABLEFULL)'', or
   ``SPICE(VALUETABLEFULL)'' error. If this happens when the program is run
   with a single file, the user must contact NAIF because the situation
   cannot be fixed by the user.
 
 
Appendix 1: Matrix of Output Formats
--------------------------------------------------------
 
   This table lists the output format variations for all combinations of
   the ``-t'', ``-n'', ``-c'' and ``-o'' options. When ``-a'' is not
   specified these formats are used for each summarized file; when ``-a''
   is specified these formats are used for the combined summary. The time
   format options ``-utc'', ``-utcdoy'', and ``-etsec'' and the time
   rounding options ``-sec'', ``-min'', ``-hour'', and ``-day'' affect only
   the time tags included in the summary reports, not any other aspect of
   the report formats.
 
      ------------------------------------------------------------
      Options     | Output Format
      ------------------------------------------------------------
      -t -n -c -o | body/frame format, location, N of tables,
                  | ordering
      ------------------------------------------------------------
                  |
      Y  .  .  .  | ``ID NAME'', left column, one table, ordered
                  | by ID
                  |
      Y  Y  .  .  | ``ID'', left column, one table, ordered by ID
                  |
      Y  Y  Y  .  | ``ID w.r.t ID'', left column, one table,
                  | ordered by ID
                  |
      Y  Y  Y  Y  | same as -t/-n/-c NO -o
                  |
      Y  Y  .  Y  | same as -t/-n NO -c/-o
                  |
      Y  .  Y  .  | ``ID NAME w.r.t. ID NAME'', left column, one
                  | table, ordered by ID
                  |
      Y  .  Y  Y  | ``NAME (ID) w.r.t. NAME (ID)'', in left
                  | column, one table, ordered by name
                  |
      Y  .  .  Y  | ``NAME (ID)'', left column, one table,
                  | ordered by name
                  |
      .  Y  .  .  | ``ID'', table header, multiple tables
                  | with the same coverage ordered by ID,
                  | within table headers bodies/frames ordered
                  | by ID
                  |
      .  Y  Y  .  | ``ID w.r.t ID'', table header, multiple
                  | tables with the same coverage ordered by
                  | ID, within table headers bodies/frames
                  | ordered by ID
                  |
      .  Y  Y  Y  | same as -n/-c NO -t/-o
                  |
      .  Y  .  Y  | same as -n NO -t/-c/-o
                  |
      .  .  Y  .  | ``NAME (ID) w.r.t. NAME (ID)'', table
                  | header, multiple tables with the same
                  | coverage ordered by name, within table
                  | headers bodies/frames ordered by name
                  |
      .  .  Y  Y  | ``NAME (ID) w.r.t. NAME (ID)'', in table
                  | header, multiple tables with the same
                  | coverage ordered name, within table headers
                  | bodies ordered by name
                  |
      .  .  .  Y  | ``NAME (ID)'', table header, multiple
                  | tables with the same coverage ordered
                  | by name, within table headers
                  | bodies/frames ordered name
                  |
      .  .  .  .  | ``NAME (ID)'', table header, multiple
                  | tables with the same coverage ordered
                  | by ID, within table headers
                  | bodies/frames ordered by ID
      ------------------------------------------------------------
 
