dskmi2_c |

Table of contents## Proceduredskmi2_c ( DSK, make spatial index for type 2 segment ) void dskmi2_c ( SpiceInt nv, ConstSpiceDouble vrtces[][3], SpiceInt np, ConstSpiceInt plates[][3], SpiceDouble finscl, SpiceInt corscl, SpiceInt worksz, SpiceInt voxpsz, SpiceInt voxlsz, SpiceBoolean makvtl, SpiceInt spxisz, SpiceInt work [][2], SpiceDouble spaixd [], SpiceInt spaixi [] ) ## AbstractMake spatial index for a DSK type 2 segment. The index is returned as a pair of arrays, one of type SpiceInt and one of type SpiceDouble. These arrays are suitable for use with the DSK type 2 writer dskw02_c. ## Required_ReadingDAS DSK ## KeywordsDAS DSK FILES PLATE TOPOGRAPHY ## Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- nv I Number of vertices. vrtces I Vertices. np I Number of plates. plates I Plates. finscl I Fine voxel scale. corscl I Coarse voxel scale. worksz I Workspace size. voxpsz I Voxel-plate pointer array size. voxlsz I Voxel-plate list array size. makvtl I Vertex-plate list flag. spxisz I Spatial index integer component size. work I-O Workspace. spaixd O Double precision component of spatial index. spaixi O Integer component of spatial index. ## Detailed_Inputnv is the number of vertices belonging to the input set of plates. vrtces is an array of coordinates of the vertices. Vertex indices, also called "vertex numbers," are 1-based in all languages supported by SPICE, and range from 1 to `nv'. The ith vertex occupies elements [i-1][0:2] of this array. np is the number of plates in the input plate set. plates is an array representing the triangular plates of a shape model. 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 [i-1][0:2] of this array. finscl is the fine voxel scale. 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 is the coarse voxel scale. 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 the -Parameters section below). worksz is the second dimension of the workspace array `work'. `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 is the size of the fine voxel-plate pointer array. 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 is the size of the fine voxel-plate list array. 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 is a logical flag that, when set to SPICETRUE, indicates that a vertex-plate association list is to be constructed. 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 is the declared size of the output array `spaixi'. 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 ) work is the workspace array. The array should be declared with dimensions (2, worksz) See the description of `worksz' above. ## Detailed_Outputwork is the workspace array, modified by the operations performed by this routine. spaixd, spaixi are, respectively, the double precision and integer components of the spatial index of the segment. `spaixd' must be declared with size at least SPICE_DSK02_IXDFIX. `spaixi' must be declared with size at least `spxisz'. ## ParametersSee the header file SpiceDSK.h for declarations of DSK data type 2 (plate model) parameters. See the header file SpiceDLA.h for declarations of DLA descriptor sizes and documentation of the contents of DLA descriptors. See the header file SpiceDSK.h for declarations of DSK descriptor sizes and documentation of the contents of DSK descriptors. ## Exceptions1) 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' 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' 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 -Detailed_Input 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 -Detailed_Input 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 -Detailed_Input 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. ## FilesNone. ## ParticularsUsers 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 dskw02_c 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 SpiceDSK.h). 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 functions 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. ## ExamplesThe numerical results shown for this example may differ across platforms. The results depend on the SPICE kernels used as input, the compiler and supporting libraries, 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 vertex data. The selected input file has one segment. phobos_3_3.bds Example code begins here. /. Program dskmi2_ex1 Example program for dskw02_c, ## RestrictionsNone. ## Literature_ReferencesNone. ## Author_and_InstitutionN.J. Bachman (JPL) J. Diaz del Rio (ODC Space) ## Version-CSPICE Version 1.0.1, 10-AUG-2021 (JDR) Edited the header to comply with NAIF standard. Fixed I/O type of arguments "work", "spaixd" and "spaixi" in -Brief_I/O table. Added example's output. -CSPICE Version 1.0.0, 13-DEC-2016 (NJB) ## Index_Entriesmake spatial index for type 2 DSK segment |

Fri Dec 31 18:41:04 2021