Table of contents
CSPICE_DSKMI2 makes spatial index for a DSK type 2 segment. The index is
returned as a pair of arrays, one of type integer and one of type
double. These arrays are suitable for use with the DSK type 2 writer
cspice_dskw02.
Given:
vrtces an array of coordinates of the vertices.
help, vrtces
DOUBLE = Array[3,NV]
The Ith vertex occupies elements [0:2,I-1] of this array.
plates an array representing the triangular plates of a shape model.
help, plates
LONG = Array[3,NP]
The elements of `plates' are vertex indices; vertex indices, as
well as plate indices, are 1-based in all languages supported by
SPICE. The vertex indices of the Ith plate occupy elements
[0:2,I-1] of this array.
finscl the fine voxel scale.
help, finscl
DOUBLE = Scalar
This scale determines the edge length of the cubical
voxels comprising the fine voxel grid: the edge length
`voxsiz' is approximately
finscl * {average plate extent}
where the extents of a plate are the respective
differences between the maximum and minimum
coordinate values of the plate's vertices.
The relationship between `voxsiz' and the average plate
extent is approximate because the `voxsiz' is adjusted
so that each dimension of the fine voxel grid is an
integer multiple of the coarse voxel scale.
See the -Particulars section below for further
information on voxel scales.
corscl the coarse voxel scale.
help, corscl
LONG = Scalar
This integer scale is the ratio of the edge length of coarse
voxels to that of fine voxels. The coarse scale must be large
enough so that the total number of coarse voxels does not exceed
SPICE_DSK02_MAXCGR (see IcyDSK.pro).
worksz the second dimension of the workspace array `work'.
help, worksz
LONG = Scalar
`worksz' must be at least as large as the greater of
- the number of fine voxel-plate associations
This number is equal to
np * {average number of fine voxels
intersected by each plate}
- the number of vertex-plate associations, if
the vertex-plate mapping is constructed.
This number is equal to
nv + ( 3 * np )
voxpsz the size of the fine voxel-plate pointer array.
help, voxpsz
LONG = Scalar
This array maps fine voxels to lists of plates that
intersect those voxels. `voxpsz' must be at least as
large as
3
corscl * {number of non-empty coarse voxels}
voxlsz the size of the fine voxel-plate list array.
help, voxlsz
LONG = Scalar
This array contains, for each non-empty fine voxel, the
count of plates that intersect that voxel and the
IDs of those plates. `voxlsz' must be at least as large
as
`np' * {average number of fine voxels
intersected by each plate}
+ {number of non-empty fine voxels}
makvtl a logical flag that, when set to True, indicates that a
vertex-plate association list is to be constructed.
help, makvtl
BOOLEAN = Scalar
The amount of workspace that is needed may depend on
whether a vertex-plate association list is
constructed. When this list is constructed, the size
of the integer component of the spatial index is
increased by the size of the list and the size of a
vertex-plate pointer array; the total of these sizes
is
( 2 * nv ) + ( 3 * np )
spxisz the declared size of the output array `spaixi'.
help, spxisz
LONG = Scalar
This size must be at least as large as the sum of
- the fixed-size part of the integer component of
the index, which includes the coarse voxel grid;
this value is
SPICE_DSK02_IXIFIX
- the size `voxpsz' of the voxel-plate pointer array
- the size `voxlsz' of the voxel-plate association
list
plus, if the vertex-plate association list is
constructed,
- the size `nv' of the vertex-plate pointer array
- the size of the vertex-plate association list;
this size is
nv + ( 3 * np )
the call:
cspice_dskmi2, vrtces, plates, finscl, corscl, worksz, voxpsz, $
voxlsz, makvtl, spxisz, spaixd, spaixi
returns:
spaixd,
spaixi respectively, the double precision and integer components of the
spatial index of the segment.
help, spaixd
DOUBLE = Array[SPICE_DSK02_IXDFIX]
help, spaixi
LONG = Array[spxisz]
`spaixd' must be declared with size at least
SPICE_DSK02_IXDFIX.
`spaixi' must be declared with size at least `spxisz'.
See the parameter definitions file
IcyDSK.pro
for declarations of DSK data type 2 (plate model) parameters.
See the parameter definitions file
IcyDLA.pro
for declarations of DLA descriptor sizes and documentation of the
contents of DLA descriptors.
See the parameter definitions file
IcyDSK.pro
for declarations of DSK descriptor sizes and documentation of the
contents of DSK descriptors.
Any numerical results shown for this example may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) Create a three-segment DSK file using plate model data for
Phobos. Use latitudinal, rectangular, and planetodetic
coordinates in the respective segments. This is not a
realistic example, but it serves to demonstrate use of
the supported coordinate systems.
Use the DSK kernel below to provide, for simplicity, the input
plate and vertices data. This file has one segment only.
phobos_3_3.bds
Example code begins here.
PRO dskmi2_ex1
;;
;; IcyUser globally defines DSK parameters.
;; For more information, please see IcyDSK.pro.
;;
@IcyUser
SPICETRUE = 1L
NSEG = 3
cornam = ['radius', 'Z-coordinate', 'Z-coordinate', 'altitude']
;;
;; Assign names of input and output DSK files.
;;
indsk = 'phobos_3_3.bds'
dsk = 'phobos_3_3_3seg.bds'
if ( cspice_exists(dsk) ) then begin
file_delete, dsk
endif
;;
;; Open input DSK for read access; find first segment.
;;
cspice_dasopr, indsk, inhan
cspice_dlabfs, inhan, dladsc, found
;;
;; Fetch vertices and plates from input DSK file.
;;
;; Note that vertex and plate indices are 1-based.
;;
print, 'Reading input data...'
cspice_dskv02, inhan, dladsc, 1, SPICE_DSK02_MAXVRT, vrtces
cspice_dskp02, inhan, dladsc, 1, SPICE_DSK02_MAXPLT, plates
print, 'Done.'
;;
;; Set input array sizes required by cspice_dskmi2.
;;
voxpsz = SPICE_DSK02_MAXVXP
voxlsz = SPICE_DSK02_MXNVLS
worksz = SPICE_DSK02_MAXCEL
spaisz = SPICE_DSK02_SPAISZ
makvtl = SPICETRUE
;;
;; Set fine and coarse voxel scales. (These usually
;; need to determined by experimentation.)
;;
finscl = 5.D
corscl = 4
;;
;; Open a new DSK file.
;;
cspice_dskopn, dsk, dsk, 0, handle
for segno=1, NSEG do begin
;;
;; Create spatial index. We won't generate a
;; vertex-plate mapping, so we set the flag
;; for creating this map to "false."
;;
print, 'Creating segment ', segno
print, 'Creating spatial index...'
cspice_dskmi2, vrtces, plates, finscl, corscl, $
worksz, voxpsz, voxlsz, makvtl, $
spaisz, spaixd, spaixi
print, 'Done.'
;;
;; Set up inputs describing segment attributes:
;;
;; - Central body: Phobos
;; - Surface ID code: user's choice.
;; We use the segment number here.
;; - Data class: general (arbitrary) shape
;; - Body-fixed reference frame
;; - Time coverage bounds (TBD)
;;
center = 401
surfid = segno
dclass = SPICE_DSK_GENCLS
frame = 'IAU_PHOBOS'
first = -50.D * cspice_jyear()
last = 50.D * cspice_jyear()
;;
;; Set the coordinate system and coordinate system
;; bounds based on the segment index.
;;
;; Zero out the coordinate parameters to start.
;;
corpar = dblarr(SPICE_DSK_NSYPAR)
case segno of
1 : begin
;;
;; Use planetocentric latitudinal coordinates. Set
;; the longitude and latitude bounds.
;;
corsys = SPICE_DSK_LATSYS
mncor1 = -cspice_pi()
mxcor1 = cspice_pi()
mncor2 = -cspice_halfpi()
mxcor2 = cspice_halfpi()
end
2 : begin
;;
;; Use rectangular coordinates. Set the
;; X and Y bounds.
;;
;; The bounds shown here were derived from
;; the plate data. They lie slightly outside
;; of the range spanned by the plates.
;;
corsys = SPICE_DSK_RECSYS
mncor1 = -1.3D
mxcor1 = 1.31D
mncor2 = -1.21D
mxcor2 = 1.2D
end
3 : begin
;;
;; Set the coordinate system to planetodetic.
;;
corsys = SPICE_DSK_PDTSYS
mncor1 = -cspice_pi()
mxcor1 = cspice_pi()
mncor2 = -cspice_halfpi()
mxcor2 = cspice_halfpi()
;;
;; We'll use equatorial and polar radii from
;; pck00010.tpc. These normally would be fetched
;; at run time, but for simplicity, we'll use
;; hard-coded values.
;;
re = 13.D0
rp = 9.1D
f = ( re - rp ) / re
corpar = [ re, f ]
end
else: message, 'Icy(BUG)'
endcase
;;
;; Compute plate model radius bounds.
;;
print, 'Computing ' + cornam[corsys-1] +' bounds of plate set...'
cspice_dskrb2, vrtces, plates, corsys, corpar, mncor3, mxcor3
print, 'Done.'
;;
;; Write the segment to the file.
;;
print, 'Writing segment...'
cspice_dskw02, handle, $
center, $
surfid, $
dclass, $
frame, $
corsys, $
corpar, $
mncor1, $
mxcor1, $
mncor2, $
mxcor2, $
mncor3, $
mxcor3, $
first, $
last, $
vrtces, $
plates, $
spaixd, $
spaixi
end
;;
;; Close the input DSK.
;;
cspice_dskcls, handle, SPICETRUE
cspice_dascls, inhan
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Reading input data...
Done.
Creating segment 1
Creating spatial index...
Done.
Computing radius bounds of plate set...
Done.
Writing segment...
Creating segment 2
Creating spatial index...
Done.
Computing Z-coordinate bounds of plate set...
Done.
Writing segment...
Creating segment 3
Creating spatial index...
Done.
Computing altitude bounds of plate set...
Done.
Writing segment...
Note that after run completion, a new DSK exists in the output
directory.
Users planning to create DSK files should consider whether the
SPICE DSK creation utility MKDSK may be suitable for their needs.
This routine supports use of the DSK type 2 segment writer cspice_dskw02
by creating the "spatial index" arrays required as inputs to that
routine.
A spatial index is a group of data structures that facilitates
rapid high-level computations involving sets of plates. The data
structures created by this routine are aggregated into arrays
of type SpiceInt and type SpiceDouble.
Voxel grids
===========
A key geometric computation---probably the most important, as it
serves as a foundation for other high-level computations---is
finding the intersection of a ray with the plate set. DSK type 2
segments use data structures called "voxel grids" as part of
their indexing mechanism. There is a "coarse grid": a box that
completely encloses a DSK type 2 segment's plate set, and which
is composed of identically-sized cubes called "coarse voxels."
Each coarse voxel in composed of smaller cubes called "fine
voxels." When the term "voxel" is used without qualification, it
refers to fine voxels.
Type 2 DSK segments contain data structures that associate plates
with the fine voxels intersected by those plates. These
structures enable the type 2 DSK software to rapidly find plates
in a given region of space.
Voxel scales
============
There are two voxel scales:
- The coarse voxel scale is the integer ratio of the
edge length of a coarse voxel to the edge length of
a fine voxel
- The fine voxel scale is the double precision ratio
of the edge length of a fine voxel to the average
extent of the plates in the input plate set. "Extents"
of a plate are the absolute values of the differences
between the respective maximum and minimum X, Y, and Z
coordinates of the plate's vertices.
Voxel scales determine the resolution of the voxel grid.
Voxel scales must be chosen to satisfy size constraints and
provide reasonable plate lookup performance.
The following considerations apply to spatial indexes of
type 2 DSK segments:
1) The maximum number of coarse voxels is fixed at
SPICE_DSK02_MAXCGR (declared in IcyDSK.pro).
2) If there are too few fine voxels, the average number of
plates per fine voxel will be very large. This largely
negates the performance improvement afforded by having an
index. Also, the number of plates per voxel may exceed
limits imposed by DSK subroutines that use static arrays.
3) If there are too many fine voxels, the average number of
voxels intersected by a given plate may be too large for
all the plate-voxel associations to be stored. In
addition, the time needed to examine the plate lists for
each voxel (including the empty ones) may become quite
large, again negating the value of the index.
In many cases, voxel scales yielding optimum performance must be
determined by experiment. However, the following heuristics can
provide reasonable starting values:
Let `np' be the number of plates. Let `fs' be the fine voxel
scale. Then a reasonable value of `fs' may be
(0.25)
fs = np / 8.
In general, `fs' should not smaller than 1.
1) If the fine voxel scale is non-positive, the error
SPICE(BADFINEVOXELSCALE) is signaled by a routine in the call
tree of this routine.
2) If the coarse voxel scale is less than 1, the error
SPICE(BADCOARSEVOXSCALE) is signaled by a routine in the call
tree of this routine.
3) If `nv', the number of vertices, is less than 3 or greater
than SPICE_DSK02_MAXVRT, the error SPICE(BADVERTEXCOUNT) is
signaled by a routine in the call tree of this routine.
4) If `np', the number of plates, is less than 1 or greater than
SPICE_DSK02_MAXPLT, the error SPICE(BADPLATECOUNT) is signaled
by a routine in the call tree of this routine.
5) If the workspace size `worksz' is less than np+1, the error
SPICE(WORKSPACETOOSMALL) is signaled by a routine in the call
tree of this routine. This is merely a sanity check; normally
the workspace will need to be substantially larger than this
reference value. See the description of `worksz' in the header
section -I/O above.
6) If the voxel-plate pointer array size `voxpsz' is less than 1,
the error SPICE(PTRARRAYTOOSMALL) is signaled by a routine in
the call tree of this routine. This is merely a sanity check;
normally this pointer array will need to be substantially
larger than this reference value. See the description of
`voxpsz' in the header section -I/O above.
7) If the voxel-plate list array size `voxlsz' is less than np+1,
the error SPICE(PLATELISTTOOSMALL) is signaled by a routine in
the call tree of this routine. This is merely a sanity check;
normally this array will need to be substantially larger than
this reference value. See the description of `voxlsz' in the
header section -I/O above.
8) If the size `spxisz' of the integer array `spaixi' is too small
to contain its constituent structures, where the sizes
of these structures are derived from the inputs
nv, np, voxpsz, voxlsz
the error SPICE(INTINDEXTOOSMALL) is signaled by a routine in
the call tree of this routine.
9) If there is insufficient room to create any of the data
structures contained in the spatial index, an error is
signaled by a routine in the call tree of this routine.
10) If any of the input arguments, `vrtces', `plates', `finscl',
`corscl', `worksz', `voxpsz', `voxlsz', `makvtl' or `spxisz',
is undefined, an error is signaled by the IDL error handling
system.
11) If any of the input arguments, `vrtces', `plates', `finscl',
`corscl', `worksz', `voxpsz', `voxlsz', `makvtl' or `spxisz',
is not of the expected type, or it does not have the expected
dimensions and size, an error is signaled by the Icy
interface.
12) If any of the output arguments, `spaixd' or `spaixi', is not a
named variable, an error is signaled by the Icy interface.
None.
None.
DAS.REQ
DSK.REQ
ICY.REQ
None.
J. Diaz del Rio (ODC Space)
M. Liukis (JPL)
E.D. Wright (JPL)
-Icy Version 1.0.1, 31-MAY-2021 (JDR)
Edited the header to comply with NAIF standard.
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added arguments' type and size information in the -I/O section.
-Icy Version 1.0.0, 13-DEC-2016 (ML) (EDW)
make spatial index for type 2 DSK segment
|