[Spice_announce] Release of Alpha-test Digital Shape Kernel Prototype

Acton, Charles H (343N) charles.h.acton at jpl.nasa.gov
Thu Jul 1 14:55:42 PDT 2010


Release of the Alpha Test DSK Prototype Toolkit 01-JUL-2010
===========================================================================

   Dear SPICE Users,

   Special SPICE Toolkits augmented with code and documentation for the
   ``alpha-test''prototype Digital Shape Kernel (DSK) subsystem are now
   available. The DSK subsystem provides a mechanism for storing and
   performing geometric computations with topography data. A "tutorial"
   outlining this extension to the SPICE shape modeling capability is
   available from the NAIF website at
   http://naif.jpl.nasa.gov/naif/tutorials.html
   with name 45_shape_model_preview.

   As alpha-test software, some of the provided module interfaces will
   change or will not be supported when the DSK subsystem becomes part of
   the official SPICE Toolkit. See the document dsk.req (included below) for
   details.

           **************************************************************
           The DSK file format supported by this software is NOT
           compatible with that used by previous versions of the
           DSK prototype subsystem.
           **************************************************************

   However the DSK file format supported by this software is now stable and
   will be supported by NAIF from now on: when the DSK subsystem is included
   in official SPICE Toolkits, those Toolkits will support this format.
   Future file format changes will take the form of support for additional
   data representations (analogous to new SPK or CK data types).

   The Alpha DSK Toolkit packages are on the NAIF server

           naif.jpl.nasa.gov

   in the path

           pub/naif/misc/alpha_dsk

   These Toolkits may be picked up via anonymous ftp.


Fortran and C versions

   Fortran and C versions of the software are available for all platforms on
   which Fortran or C SPICE Toolkits are supported.

   The C version of the software contains certain high-level geometry APIs
   that are not provided in the Fortran version: these APIs have name of the
   form

           *pl02.c


IDL version

   The IDL version of the software is available only for the platforms

           MacIntel_OSX_AppleC_32bit
           MacIntel_OSX_AppleC_64bit
           PC_Linux_GCC_32bit

   This software was written recently and has not undergone the
   multi-platform regression testing that has been applied to the C and
   Fortran versions of the Alpha DSK subsystem. However the underlying
   C-language "dsklib_c" code has been regression-tested on all platforms
   NAIF supports.


MATLAB version

   NAIF tentatively plans to develop a MATLAB version of this prototype, but
   this work has not yet started.


Documentation
----------------------------------------------------------

   A ``Required Reading'' technical reference document for the current DSK
   subsystem is included in the ``doc'' path of the Alpha DSK packages and
   is included at the end of this message.

   The two DSK-specific utility programs MKDSK and DSKBRIEF have user's
   guides; these are included in the packages.

   API routines in the Fortran and C packages have normal SPICE headers that
   include example code.

   Primary documentation for the IDL APIs is provided by the example
   programs in the path

           alpha_dsk_idl/src/dskcook_idl

   of these IDL packages. The IDL API routines correspond to routines in the
   C-language "dsklib_c" library; the headers of the corresponding C
   routines should be consulted for details. There currently is no
   IDL-specific header documentation for these APIs.



Data
----------------------------------------------------------

   Example DSK files that may be used for testing are located on the NAIF
   server under the path

           pub/naif/misc/alpha_dsk/data

   All of the files provided there are IEEE little-endian, suitable for use
   on PC/Windows, PC/Linux and modern (INTEL) Mac platforms.

           **************************************************************
           Unlike SPK files, non-native DSK files cannot be read by SPICE
           software.
           **************************************************************

   See dsk.req for information on moving these files to big-endian platforms
   (Sun and old PowerPC Mac platforms).




                "Required Reading" Technical Reference for
                  Alpha Test DSK Subsystem --- C Version
=========================================================================

   Last revised on 2010 JUN 09 by N. J. Bachman


Abstract
----------------------------------------------------------

   The Alpha Test DSK (``Digital Shape Kernel'') subsystem is a prototype
   software set that supports storage of and geometric computations using
   topography data.


Introduction
----------------------------------------------------------

   The SPICE DSK subsystem enables SPICE-based application software to
   easily ingest and perform geometric computations with topography data, or
   more generally, data representing surfaces of objects. The DSK subsystem
   also supports exchange and archival of such data.

   As with the existing SPICE kernel subsystems, the DSK subsystem comprises

            --   A file format

            --   Software

            --   Documentation

   This prototype SPICE DSK software set provides a subset of the
   capabilities that will be provided by the SPICE Toolkit version of the
   software. In particular, the current software set supports representation
   of surfaces only by collections of triangular plates; this representation
   is called ``type 2.''

   Capabilities absent from this prototype, but that will be provided by the
   official version of the DSK subsystem include:

            --   Support for DTMs (Digital Terrain Models)

            --   Support for multiple-segment DSK files

            --   Support for geometric computations involving data from
                 multiple loaded files

            --   Support for high-level geometry computations.

            --   Support for all DSK features in Fortran, C, IDL, and
                 MATLAB.

            --   Full documentation of all DSK capabilities


Supported Languages

   This prototype software is available in the C language.

   A limited subset of the software is available in Fortran.

   Some APIs will be made available in IDL as time permits (contact NAIF for
   details).


Future compatibility and support
----------------------------------------------------------

   This prototype SPICE DSK software set is an update of that provided to
   the DAWN and Rosetta missions in the 2006-2009 time frame.

   The file format supported by this version of the DSK subsystem is now
   ``official'': the SPICE system will continue to support this format in a
   backward-compatible fashion. Future changes to the format will consist
   only of addition of new data types (``data types'' are mechanisms for
   representing topography data).

   The software portion of this prototype subsystem is NOT official, and
   some of it will not be included in the SPICE Toolkit. The prospects for
   continued support of the software are expected to be as follows:

            1.   DLA subsystem routines: almost certainly will become
                 official with no interface changes

            2.   DSK ``type 2'' routines: most will become official with no
                 interface changes

            3.   ``Plate 02'' routines (having names of the form *pl02.c''):
                 these will NOT become part of the SPICE Toolkit

            4.   Lower-level, supporting routines: may be revised.

            5.   The DSK creation utility MKDSK will continue to be
                 supported and will later be enhanced to accept a wider
                 variety of input files and create a wider variety of output
                 files.

            6.   The DSKBRIEF utility will continue to be supported but
                 likely have its display contents revised.


DSK files
==========================================================================


DSK file characteristics
----------------------------------------------------------


DSK format

   The DSK file format is designed to efficiently handle large volumes of
   data. To make this possible, DSK files are in binary format and support
   direct access.

   The drawback of binary format is that DSK contents are not directly
   readable by (most) humans. DSK contents can be accessed only via
   subroutine interfaces and utility programs.


Comments in DSK files

   DSK files can hold an unlimited amount of documentation in a data
   structure called the ``comment area.'' This feature is analogous to that
   comment area capability provided by the SPK, CK, and binary PCK file
   formats. A DSK file's comment area can be accessed by the SPICE utility
   COMMNT. It also can be accessed using the SPICE DAS subsystem's comment
   area routines.


Porting DSK files

   DSK files can be moved between computer systems having incompatible
   binary file formats, but only with the help of SPICE porting tools.
   The easiest way to convert a DSK file between big- and little- endian
   binary file formats is to use the SPICE utility program BINGO. This
   program is not part of the SPICE Toolkit; is is available from the NAIF
   web site:

           http://naif.jpl.nasa.gov/naif

   DSK files also can be ported in ``transfer format''; the SPICE utilities
   TOXFR and TOBIN are used for this. See the Convert User's Guide in the
   doc path or the Porting Kernels tutorial on the NAIF web site for
   details.


Design

   The DSK format is designed to be extensible: as needed, new mathematical
   representations for topography data can be accommodated. These types of
   representations are called ``data types.''

   The DSK file format is based on two lower-level formats: the DSK format
   is a special case of the DLA (``DAS linked array'') format, and the DLA
   format is a special case of the DAS (``Direct Access, Segregated'')
   format. Because of this hierarchical relationship, some DSK functionality
   is provided by routines belonging to the DLA or DAS subsystems. This can
   be seen in the code examples provided with this sofware set.


DSK Software
==========================================================================


Overview
----------------------------------------------------------

   The DSK software set contains

            --   DSK utility programs

            --   DSK example programs

            --   DSK routines

   Documentation of the routines is provided by SPICE-style ``headers'' in
   the source code.

   The utility programs have user's guides; these are located in the ``doc''
   path.


Utility programs
----------------------------------------------------------


MKDSK

   The program MKDSK converts a triangular plate model data file to a DSK
   containing a single type 2 segment. MKDSK can accept as input a variety
   of files containing triangular plate data. See the MKDSK User's Guide for
   details.


DSKBRIEF

   The program DSKBRIEF displays a segment-by-segment summary of the
   coverage of a DSK file. See the DSKBRIEF User's Guide for details.


Example programs
----------------------------------------------------------

   The programs listed here illustrate use of the higher-level geometry
   routines in this software set.

              illum_pl02_ex1        Demonstrate computation of
                                    ``illumination angles'' (phase,
                                    solar incidence, and
                                    emission) at specified points on a
                                    surface represented by a type 2 DSK
                                    segment.

              limb_pl02_ex1         Demonstrate computation of limb points
                                    on a surface represented by a type 2 DSK
                                    segment. Note that this limb computation
                                    is suitable only for objects whose shape
                                    is well approximated by a triaxial
                                    ellipsoid.

              llgrid_pl02_ex1       Demonstrate computation of a grid of
                                    surface points at specified
                                    latitude/longitude coordinates on a
                                    surface represented by a type 2 DSK
                                    segment.

              subpt_pl02_ex1        Demonstrate computation of a
                                    sub-observer point on a surface
                                    represented by a type 2
                                    DSK segment.

              subsol_pl02_ex1       Demonstrate computation of a sub-solar
                                    point on a surface represented by a type
                                    2 DSK segment.

              term_pl02_ex1         Demonstrate computation of terminator
                                    points on a surface represented by a
                                    type 2 DSK segment. Note that this limb
                                    computation is suitable only for objects
                                    whose shape is well approximated by a
                                    triaxial ellipsoid.


Subroutines
----------------------------------------------------------


Top-level geometry routines

              dskx02_c       Determine the plate ID and body-fixed
                             coordinates of the intersection of a specified
                             ray with the surface defined by a (Type 2) DSK
                             plate model.

              illum_pl02     Compute the illumination angles---phase, solar
                             incidence, and emission---at a specified point
                             on a target body at a particular epoch,
                             optionally corrected for light time and stellar
                             aberration. The target body's surface is
                             represented by a triangular plate model
                             contained in a (Type 2) DSK segment.

              limb_pl02      Compute a set of points on the limb of a
                             specified target body, where the target body's
                             surface is represented by a triangular plate
                             model contained in a (Type 2) DSK segment.

              llgrid_pl02    Given the planetocentric longitude and latitude
                             values of a set of surface points on a
                             specified target body, compute the
                             corresponding rectangular coordinates of those
                             points. The target body's surface is
                             represented by a triangular plate model
                             contained in a (Type 2) DSK segment.

              subpt_pl02     Compute the rectangular coordinates of the
                             sub-observer point on a target body at a
                             particular epoch, optionally corrected for
                             light time and stellar aberration. The target
                             body's surface is represented by a triangular
                             plate model contained in a (Type 2) DSK
                             segment. Return the sub-observer point's
                             coordinates expressed in the body-fixed frame
                             associated with the target body. Also, return
                             the observer's altitude above the target body.

              subsol_pl02    Compute the rectangular coordinates of the
                             sub-solar point on a target body at a
                             particular epoch, optionally corrected for
                             light time and stellar aberration. The target
                             body's surface is represented by a triangular
                             plate model contained in a (Type 2) DSK
                             segment. Return the sub-solar
                             point's coordinates expressed in the body-fixed
                             frame associated with the target body. Also,
                             return the observer's distance from the
                             sub-solar point.

              term_pl02      Compute a set of points on the umbral or
                             penumbral terminator of a specified target
                             body, where the target body's surface is
                             represented by a triangular plate model
                             contained in a (Type 2) DSK segment.


Bulk readers

   These routines allow an application to rapidly read all of the plate data
   from a DSK segment.

              dskp02_c   Fetch plates from a type 2 DSK segment.

              dskv02_c   Fetch vertices from a type 2 DSK segment.


Supporting APIs

              dascls_c   Close a DSK file, or more generally any DAS file.

              dasopr_c   Open a DSK file, or more generally any DAS file,
                         for read access.

              dlabfs_c   Begin a forward search for segments in a DSK file,
                         or more generally, any DLA file.

              dlafns_c   Find the next segment in a DSK file, or more
                         generally, any DLA file.

              dskb02_c   Look up model parameters and other bookkeeping data
                         from a type 2 DSK segment.

              dskd02_c   Look up double precision data from a type 2 DSK
                         segment.

              dski02_c   Look up integer data from a type 2 DSK segment.

              dskn02_c   Compute the normal vector associated with a
                         specified plate in a type 2 DSK segment.

              dskw02_c   Write a type 2 DSK segment. User applications
                         should not call this routine directly (it's
                         permissible but quite difficult to do correctly);
                         instead use MKDSK to create DSK files.

              dskz02_c   Fetch vertex and plate counts from a type 2 DSK
                         segment.


Converted Fortran routines

   These routines have names lacking the ``_c'' or ``_pl02'' suffixes. They
   should not be called directly by user applications.


Header files
----------------------------------------------------------

   Declarations required by the DSK APIs are provided in the header files

           dla_proto.h (new)
           dsk_proto.h (new)
           f2c_proto.h (new)
           pl02.h      (new)
           SpiceDLA.h  (new)
           SpiceDSK.h  (new)
           SpiceZpr.h  (updated CSPICE header)
           SpiceZfc.h  (updated CSPICE header)

   Of these, the files

           SpiceDLA.h
           SpiceDSK.h

   will become part of CSPICE.

   The files providing prototypes will be subsumed in other CSPICE header
   files, and so will not be provided in the official DSK subsystem.





More information about the Spice_announce mailing list