[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