Table of contents
CSPICE_DSKV02 fetches vertices from a type 2 DSK segment.
Given:
handle the handle of a DSK file containing a type 2 segment from which
data are to be fetched.
help, handle
LONG = Scalar
dladsc the DLA descriptor associated with the segment from which data
are to be fetched.
help, dladsc
LONG = Array[SPICE_DLA_DSCSIZ]
start the ID of the first vertex to be fetched from the segment
designated by `handle' and `dladsc'.
help, start
LONG = Scalar
The ID of a vertex is its ordinal position within the segment.
Vertex IDs range from 1 to `nv', where `nv' is the number of
vertices in the segment.
Note that Fortran-style 1-based indexing is used for
vertex IDs because these IDs must be consistent with
the IDs used in DSK files, across all languages
supported by SPICE.
room the maximum number of vertices to return.
help, room
LONG = Scalar
the call:
cspice_dskv02, handle, dladsc, start, room, vrtces
returns:
vrtces the array representing a contiguous set of `n' vertices, where
`n' is between 1 and `room' inclusive.
help, vrtces
DOUBLE = Array[3,N]
The returned vertices are arranged in order of increasing
vertex ID. The IDs of the returned vertices range from
start
to
start + n - 1
Each vertex is a 3-vector. The correspondence of elements
of `vrtces' with the elements of the set of vertices
contained in the segment is:
vrtces[0,0] segment_vertex_set[0, start]
vrtces[1,0] segment_vertex_set[1, start]
vrtces[2,0] segment_vertex_set[2, start]
... ...
vrtces[0,n-1] segment_vertex_set[0, start+n-1]
vrtces[1,n-1] segment_vertex_set[1, start+n-1]
vrtces[2,n-1] segment_vertex_set[2, start+n-1]
The vertices are expressed in the body-fixed
reference frame of the segment designated by
`handle' and `dladsc'. The center of this frame is the
origin of the Cartesian coordinate system in which
the vertices are expressed. Note that the frame
center need not coincide with the central body of
the segment. Units are km.
If an error occurs on the call, `vrtces' is
undefined.
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.
See the parameter definitions file
IcyDSK.pro
for declarations of DSK data type 2 (plate model) parameters.
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 dskv02_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.
This routine enables SPICE-based user applications to rapidly
fetch the vertex data from a specified type 2 DSK segment. Using
a large output array generally improves efficiency.
1) If the input handle is invalid, an error is signaled by a
routine in the call tree of this routine.
2) If a file read error occurs, the error is signaled by a
routine in the call tree of this routine.
3) If the input DLA descriptor is invalid, the effect of this
routine is undefined. The error *may* be diagnosed by
routines in the call tree of this routine, but there are no
guarantees.
4) If `room' is non-positive, the error SPICE(VALUEOUTOFRANGE)
is signaled by a routine in the call tree of this routine.
5) If `start' is less than 1 or greater than the number of
vertices in the segment, the error SPICE(INDEXOUTOFRANGE) is
signaled by a routine in the call tree of this routine.
6) If any of the input arguments, `handle', `dladsc', `start' or
`room', is undefined, an error is signaled by the IDL error
handling system.
7) If any of the input arguments, `handle', `dladsc', `start' or
`room', is not of the expected type, or it does not have the
expected dimensions and size, an error is signaled by the Icy
interface.
8) If the output argument `vrtces' is not a named variable, an
error is signaled by the Icy interface.
See input argument `handle'.
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, and
completed -Particulars section.
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, 04-APR-2017 (ML) (EDW)
return specified vertices from type 2 DSK segment
|