N IF
Navigation and Ancillary Information Facility

Digital Shape Kernel Subsystem(DSK)

April 2023

N IFTopics
Navigation and Ancillary Information Facility••••••••DSK subsystem overview
DSK shape representations
N67 version of DSK subsystem
DSK APIs and graphical depictions
DSK API example
DSK utility programs
DSK concepts
Writing and using DSK files

Digital Shape Kernel2

N IF

DSK Subsystem Overview
Navigation and Ancillary Information Facility• The DSK subsystem– enables SPICE-based applications toconveniently make use of high fidelity surface
shape (topographic) data in geometry
computations– serves as a format for transmission and archivalof surface shape data
– consists of SPICE software, DSK file format
specifications, and documentation

Digital Shape Kernel

3

N IF

DSK Shape Representations
Navigation and Ancillary Information Facility• The DSK subsystem handles two representationsof shape data
– Tessellated plate model (Type 2)– Digital elevation model (development not yet finished) (Type 4)

Digital Shape Kernel

4

N IF

Tessellated Plate Model – Type 2
Navigation and Ancillary Information Facility• The surface of the object is represented as a collection oftriangular plates• More flexible than digital elevation model: any arbitrary 3-D
surface can be modeled– Surface could be a complicated shape with multiple surface points
having the same latitude and longitude» Examples: “dumbbell”-shaped asteroid, caves, arches• Less efficient than digital elevation model (DSK Type 4) ofsimilar resolution in terms of storage and computational
speedPhobos
Digital Shape Kernel

Itokowa

Churyumov-Gerasimenko
5

N IF

Digital Elevation Model – Type 4
Navigation and Ancillary Information Facility• Maps longitude/latitude to “elevation”– Elevation of a surface point can be defined as distance from the origin ofa body-fixed reference frame or height above a reference ellipsoid• Example: rendering of a piece of DSK data created from MGS
laser altimeter (MOLA) Mars DEM

Digital Shape Kernel

6

N IF

N67 Toolkit with DSKNavigation and Ancillary Information Facility• Supports only the tessellated plate model data type(Type 2 DSK)• Support for Digital Elevation Model (DEM) (Type 4DSK) will be added in a future Toolkit version

Digital Shape Kernel

7

N IF

Some DSK Features
Navigation and Ancillary Information Facility• Supports multi-segment, multi-file DSK data sets
– Up to 5000 DSK files can be loaded simultaneously– Up to 10,000 DSK segments can be loaded simultaneously• Supports run-time data translation: big-endian DSK
files can be read on little-endian platforms, and viceversa
• Pre-DSK era SPICE Toolkit geometry APIs will
support DSK shape data, where applicable

Digital Shape Kernel

8

N IF

APIs Available in N66 Toolkits -1
Navigation and Ancillary Information Facility• Kernel load/unload/info:– FURNSH, UNLOAD, KCLEAR, KTOTAL, KINFO, KDATA• Geometry:– Ray-surface intercept: SINCPT, DSKXV, DSKXSI– Sub-observer point: SUBPNT– Sub-solar point: SUBSLR– Illumination angles at surface point: ILLUMF, ILLUMG, ILUMIN– Longitude-latitude pairs to surface points: LATSRF– Find occultation state at a given time: OCCULT– Find occultation or transit of point target behind/across DSK
shape: GFOCLT– Generate limb points: LIMBPT– Generate terminator points: TERMPT– Compute outward normal vector at surface point: SRFNRM

Digital Shape Kernel

9N IF

APIs Available in N66 Toolkits -2Navigation and Ancillary Information Facility• Low-level access:– DLA segment traversal: DLABFS, DLABBS, DLAFNA, DLAFPA– Fetch type 2 counts/plates/vertices/normals: DSKZ02, DSKP02,DSKV02, DSKN02– Fetch all type 2 data structure contents: DSKI02, DSKD02– Fetch DSK segment descriptor: DSKGD• Plate utilities:– PLTVOL, PLTAR, PLTEXP, PLTNP, PLTNRM• Create DSK files:– DSKOPN, DSKW02, DSKCLS, DSKMI2, DSKRB2• Summary routines:– DSKOBJ, DSKSRF• Surface name-code translation:– SRFS2C, SRFSCC, SRFC2S, SRFCSS

Digital Shape Kernel

10

N IF

Graphic Depictions
Navigation and Ancillary Information Facility• In the next several charts we provide graphic
depictions of the high-level APIs that should be ofinterest to many users

Digital Shape Kernel

11

N IF

Plate Model Surface Intercept
Navigation and Ancillary Information Facility

API: SINCPTIntercept nearest toobserver’s location
Additional intercepts ---not computed

Input rayObserver’s location
Observer is external to objectDigital Shape Kernel

12

N IF

Plate Model Sub-observer Point
Navigation and Ancillary Information Facility

API: SUBPNT
Reference ellipsoid
Sub-observer point(nadir definition)

Outward normal toreference ellipsoid

Sub-observer point(target center definition)
Observer to subobserver point vector(target center definition)
Digital Shape Kernel

Observer to subobserver point vector(nadir definition)
Observer location
13

N IF

Plate Model Sub-solar Point
Navigation and Ancillary Information Facility

API: SUBSLR
Reference ellipsoid
Sub-solar point (targetcenter definition)

Observer to subobserver point vector(target center definition)
Observer location

Sub-solar point (nadirdefinition)

Outward normal toreference ellipsoid
Observer to subobserver point vector(target center definition)
Sun location

Digital Shape Kernel

14

N IF

Plate model Illumination Angles
Navigation and Ancillary Information Facility
Direction to illumination source

API: ILLUMF
Outward surface normal
Phase angle
Direction to observer
Emission angle

Incidence
angle

Also returned:- target epoch (corrected for light time),- observer visibility flag,- illumination source visibility flag
Digital Shape Kernel

15

N IF

Plate Model Surface Point Grid
Navigation and Ancillary Information Facility

API: LATSRF
Ray emanating fromsphere point, pointing
toward center of bodyfixed, body-centeredreference frame

Exterior bounding
sphere for target object•

Point on bounding
sphere, specified byplanetocentriclongitude andlatitude, and by
radius of exterior
bounding sphere.
This grid contains 9such points.
Digital Shape Kernel

••

•

•

•

•

•

•

Surface intercept
point corresponding
to point on bounding
sphere:planetocentriclongitude andlatitude of intercept
match those of thesphere point. Anintercept iscomputed for each
input sphere point.
16

N IF

Plate Model Limb-1
Navigation and Ancillary Information Facility

API: LIMBPTLimb point---lies on atangent ray in theselected half-plane (forsome shapes, multiple
tangents will exist for a given
axis and half-plane)

Ray emanating fromobserver and tangent totarget bodySpecified half-planebounded by observertarget center line
(axis): contains ray

Limb point angle relative to axis
Observer location
Axis: observer-target center vector
Digital Shape Kernel

17

N IF

Plate Model Limb-2
Navigation and Ancillary Information Facility

API: LIMBPTRays emanating fromobserver, lying in halfplane, and tangent totarget body

Limb points---each istangent point of a rayin the selected halfplane

Specified half-planebounded by observertarget center line
(axis): contains ray

Observer location
Axis: observer-target
center vector
Digital Shape Kernel

Angular search step
must be less than
this angle

18

N IF

Plate Model Terminator-Umbral
Navigation and Ancillary Information Facility

API: TERMPTRay tangent to sun
and target bodySpecified half-planebounded by sun centertarget center line (axis):
contains ray

Umbral terminator
point: lies on a tangent
ray in the specified
half-plane (for someshapes, multiple tangents will
exist for a given axis and halfplane). Terminator point

and ray vertex are on
same side of axis.

•Sun center

Axis: sun center-target center vector
Digital Shape Kernel

19

N IF Plate Model Terminator-Penumbral
Navigation and Ancillary Information Facility

API: TERMPT
Axis: sun center-target
center vector
Ray tangent to sun
and target body

Penumbral terminator
point: lies on a tangent
ray in the specified
half-plane (for some•Sun center
Specified half-plane boundedby sun center-target centerline (axis): contains semiinfinite portion of ray

shapes, multiple tangents will
exist for a given axis and halfplane). Terminator pointlies in half-space on
opposite side of axis
from ray’s vertex.

Terminator tangent ray angle
relative to axis

Digital Shape Kernel

20

N IF

Example of API Using DSK - 1
Navigation and Ancillary Information Facility• Find ray intercept point on target surface:– CALL SINCPT ( METHOD, TARGET, ET, FIXREF, ABCORR,OBSRVR, DREF, DVEC, SPOINT, TRGEPC,SRFVEC, FOUND)e
codnarFort plemexa– SINCPT is a high-level SPICE API.
– The input string argument METHOD indicates the surface model touse.
» To model the target body shape using an ellipsoid, set
METHOD to ‘ellipsoid’» To model the target body shape using DSK data, set METHOD
to one of the forms• ‘DSK/UNPRIORITIZED’– If all DSK segments for the body designated by TARGET areapplicable• ‘DSK/UNPRIORITIZED/SURFACES = <surface name or ID 1>, …’– If only DSK segments for the specified surfaces associated with thebody designated by TARGET are applicable» For the DSK case, the keyword UNPRIORITIZED is currently required.
This keyword indicates that no applicable segment can mask another.

Digital Shape Kernel

21

N IF

Example of API Using DSK - 2Navigation and Ancillary Information Facility» Other inputs: target body name, epoch, body-fixed reference
frame, aberration correction, observer name, reference framefor direction vector, direction vector.
» Outputs: ray-surface intercept in Cartesian coordinates,
expressed in the body-fixed frame associated with the target--evaluated at the optionally light-time corrected epoch
TRGEPC, TRGEPC itself, observer-to-intercept vector
expressed in body-fixed frame, and found flag indicating
whether intercept exists.

Digital Shape Kernel

22

N IF

DSK Utility Programs
Navigation and Ancillary Information Facility• Create DSK files: MKDSK– Creates a DSK file containing a single type 2 segment• Export DSK data to text format files: DSKEXP– Writes data from Type 2 DSK segments to one or more text files– Supports simple output formats such as “obj”• Summarize DSK files: DSKBRIEF• Modify DSK segment attributes: DSKMOD• Merge DSK files: DLACAT– Concatenates segments from multiple DSK files into a single DSK file• Transform binary architecture of DSK file: TOXFR, TOBIN,BINGO (BINGO not part of standard SPICE Toolkit)• Read/write comment area: COMMNT• DSKMOD, DLACAT, and BINGO are provided on the NAIF Web
site (https://naif.jpl.nasa.gov/naif/utilities.html)

Digital Shape Kernel

23

N IF

DSK Concepts-1
Navigation and Ancillary Information Facility• Surface– "Surface" is a second identifier, in addition to the central body
» A “surface” has a name and an integer ID code
• Surfaces occupy a name space distinct from that of bodies• APIs are provided for surface name/ID conversion– Used to distinguish different versions of data for a given body
» Allows use of different versions without loading and unloading kernels• High-frequency kernel loading and unloading is too inefficient for DSK applications• Data class– Data class is a “hook” to differentiate kinds of data for differentapplications» Distinct from concept of “data type”– Existing classes indicate geometric characteristics of surface data
» Class 1: shape is single-valued function of domain coordinates.
Example, for latitudinal coordinates:• Every ray emanating from the origin of the body-fixed reference frame
associated with the body passes through the surface once
• Such surfaces cannot have features such as cliffs or caves• DEMs can represent class 1 surfaces» Class 2: arbitrary shape

Digital Shape Kernel• Not required to be convex, closed, or connected• Plate models are the only DSK data type that can be used for class 2surfaces

24

N IF

DSK Concepts-2
Navigation and Ancillary Information Facility• Kernel priority– Unlike SPK, CK, and binary PCK files, the concept of segment “priority” does not
apply to all DSK applications» Not applicable to data sets including segments of class 2• Concept simply doesn’t make sense when multiple heights can correspond to a single
longitude/latitude coordinate pair

» Can apply to data sets containing only class 1 segments• Coordinate systems– Associated with segments» Segment coverage is described in terms of a coordinate system associatedwith that segment– Can be any of» Planetocentric (latitudinal)» Planetodetic» Cartesian• Segment coverage– The spatial “coverage” of a segment is a region of space within which the segmentprovides valid surface data
» Characterized by three coordinate ranges• For example: min, max longitude; min, max latitude; min, max radius» “Padding” data may be provided outside of a segment’s coverage region

Digital Shape Kernel25

N IF

Writing Shape and Orientation Kernels
Navigation and Ancillary Information FacilityLAT/LON and height
above ellipsoid ordistance from centerof frame (N66 or later)

DSKMKDSK
Programor SPICE
Routines

Lists of platemodel vertices
and associatedplates

Axes dimensions
for tri-axial
ellipsoid

Some source ofrotation state
information (poleRA/DEC andprime meridianlocation)
Digital Shape Kernel

Digitalshape kernel
Digital Terrain
Shape Model(SPICE Toolkit)

Tessellated Plates
Shape Model

Text editor(Usually done byNAIF)

Triaxial Ellipsoid
Shape ModelZ

Text editor(Usually done byNAIF)

XY

Orientation

Text PCK
Planetary constants
kernel containing
rotation data for thebody, and possibly
tri-axial shape

26

N IF

Using Shape and Orientation Kernels
Navigation and Ancillary Information FacilityDSKDigital
shape kernel
Digital Terrain
Shape Model
Pick oneshape modelYour Application Program

Shape

Tessellated Plates
Shape Model
SPICEmodules

Triaxial Ellipsoid
Shape Modelntiotanie
OrZXYOrientation
Digital Shape Kernel

PCK
Planetary constants
kernel containing
rotation data for thebody, and possibly
tri-axial shapeYour otherdata, asneededSPICE modules for
obtaining rotation
state and shape,and thencomputing derivedquantities

27