Table of contents
CSPICE_DSKGD returns the DSK descriptor from a DSK segment identified
by a DAS handle and DLA descriptor.
Given:
handle the handle of a DSK file that is open for read access.
help, handle
LONG = Scalar
dladsc the DLA segment descriptor corresponding to a DSK segment.
help, dladsc
LONG = Array[SPICE_DLA_DSCSIZ]
the call:
cspice_dskgd, handle, dladsc, dskdsc
returns:
dskdsc the DSK segment descriptor of the segment designated by the
input handle and DLA descriptor.
help, dskdsc
DOUBLE = Array[SPICE_DSK_DSCSIZ]
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 these examples may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) Dump the DSK descriptor of the first segment of a DSK file.
Example code begins here.
PRO dskgd_ex1
@IcyUser
;;
;; Local variables
;;
dsk = ''
;;
;; Prompt for the name of the DSK file.
;;
read, dsk, PROMPT='Enter name of DSK file > '
cspice_dasopr, dsk, handle
;;
;; Search for the first segment in the file; obtain
;; the segment's DLA descriptor.
;;
cspice_dlabfs, handle, nxtdsc, found
while ( found ) do begin
dladsc = nxtdsc
cspice_dskgd, handle, dladsc, dskdsc
print, 'DSK descriptor contents:'
print, ' '
print, ' Surface ID: ', $
long( dskdsc[SPICE_DSK_SRFIDX] )
print, ' Center ID: ', $
long( dskdsc[SPICE_DSK_CTRIDX] )
print, ' Data class: ', $
long( dskdsc[SPICE_DSK_CLSIDX] )
print, ' Data type: ', $
long( dskdsc[SPICE_DSK_TYPIDX] )
print, ' Frame ID: ', $
long( dskdsc[SPICE_DSK_FRMIDX] )
print, ' Coordinate system: ', $
long( dskdsc[SPICE_DSK_SYSIDX] )
print, ' Parameters: ', dskdsc[SPICE_DSK_PARIDX]
for i = 1, SPICE_DSK_NSYPAR-1 do begin
print, ' ', dskdsc[SPICE_DSK_PARIDX+i]
endfor
print, ' Coordinate 1 min: ', dskdsc[SPICE_DSK_MN1IDX]
print, ' Coordinate 1 max: ', dskdsc[SPICE_DSK_MX1IDX]
print, ' Coordinate 2 min: ', dskdsc[SPICE_DSK_MN2IDX]
print, ' Coordinate 2 max: ', dskdsc[SPICE_DSK_MX2IDX]
print, ' Coordinate 3 min: ', dskdsc[SPICE_DSK_MN3IDX]
print, ' Coordinate 3 max: ', dskdsc[SPICE_DSK_MX3IDX]
print, ' Start time: ', dskdsc[SPICE_DSK_BTMIDX]
print, ' Stop time: ', dskdsc[SPICE_DSK_ETMIDX]
;;
;; Fetch next DLA descriptor.
;;
cspice_dlafns, handle, dladsc, nxtdsc, found
endwhile
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, using the DSK file named phobos512.bds, the output
was:
Enter name of DSK file > phobos512.bds
DSK descriptor contents:
Surface ID: 401
Center ID: 401
Data class: 1
Data type: 2
Frame ID: 10021
Coordinate system: 1
Parameters: 0.0000000
0.0000000
0.0000000
0.0000000
0.0000000
0.0000000
0.0000000
0.0000000
0.0000000
0.0000000
Coordinate 1 min: -3.1415927
Coordinate 1 max: 3.1415927
Coordinate 2 min: -1.5707963
Coordinate 2 max: 1.5707963
Coordinate 3 min: 8.0496322
Coordinate 3 max: 13.940940
Start time: -1.5778800e+09
Stop time: 1.5778801e+09
2) Again, dump the DSK descriptors of a DSK file, this time
interpreting the descriptor information and displaying
it in a user-friendly form. This display is a simplified
version of that created by the utility DSKBRIEF.
This program requests the name of an optional meta-kernel.
The meta-kernel can be used to define surface name-ID
associations. If no meta-kernel is needed, the user can
enter a carriage return at the prompt for this file.
Example code begins here.
PRO dskgd_ex2
;;
;; IcyUser is a file that makes certain variables global.
;; You must call IcyUser to have access to the parameters used
;; in this example.
;;
;; To use the variables in IcyUser, add the 'src/icy' directory
;; to your IDL path by doing the following in which /path/to is the
;; local path to Icy.
;;
;; pref_set, 'IDL_PATH', '/path/to/icy/src/icy:<IDL_DEFAULT>', $
;; /COMMIT
;;
@IcyUser
;;
;; Local constants
;;
clsnms = ['Single-valued surface', 'General surface']
sysnms = ['Latitudinal', 'Cylindrical', $
'Rectangular', 'Planetodetic']
;;
;; Local variables
;;
dsk = ''
meta = ''
;;
;; Prompt for the name of the DSK and meta-kernel files.
;;
read, dsk, PROMPT = 'Enter DSK name > '
read, meta, PROMPT = 'Enter meta-kernel name > '
if ( ( meta ne ' ' ) && ( meta ne '' ) ) then begin
cspice_furnsh, meta
endif
;;
;; Open the DLA file and begin a forward search
;; for segments.
;;
cspice_dasopr, dsk, handle
segno = 0
cspice_dlabfs, handle, nxtdsc, found
while ( found ) do begin
segno += 1
;;
;; Make the DLA descriptor we just fetched
;; the current one.
;;
dladsc = nxtdsc;
cspice_dskgd, handle, dladsc, dskdsc
bodyid = long( dskdsc[SPICE_DSK_CTRIDX] )
surfid = long( dskdsc[SPICE_DSK_SRFIDX] )
framid = long( dskdsc[SPICE_DSK_FRMIDX] )
dtype = long( dskdsc[SPICE_DSK_TYPIDX] )
dclass = long( dskdsc[SPICE_DSK_CLSIDX] )
cspice_bodc2s, bodyid, bodnam
cspice_srfc2s, surfid, bodyid, srfnam, isname
cspice_frmnam, framid, frame
if ( frame eq ' ' ) then begin
frame = STRING( format='(%"%d")', framid )
endif
cspice_etcal, dskdsc[SPICE_DSK_BTMIDX], btime
cspice_etcal, dskdsc[SPICE_DSK_ETMIDX], etime
corsys = long( dskdsc[SPICE_DSK_SYSIDX] )
sysnam = sysnms[corsys-1]
print, '===================================='
print, ' DSK descriptor for segment ', segno
print, ' Body: ', bodnam
print, ' Surface: ', srfnam
print, ' Frame: ', frame
print, ' Start time (TDB): ', btime
print, ' Stop time (TDB): ', etime
print, ' Data type: ', dtype
print, ' Data class: ', clsnms[ dclass-1 ]
print, ' Coordinate System: ', sysnam
if ( corsys eq SPICE_DSK_PDTSYS ) then begin
re = dskdsc[SPICE_DSK_PARIDX]
f = dskdsc[SPICE_DSK_PARIDX+1]
rp = re * (1.0 - f);
print, format='(A,F22.14)', ' Equatorial radius (km):', re
print, format='(A,F22.14)', ' Polar radius (km):', rp
endif
print, ' Segment boundaries:'
if ( corsys eq SPICE_DSK_LATSYS ) then begin
print, format='(A,2F22.14)', ' Longitude (deg): ', $
dskdsc[SPICE_DSK_MN1IDX] * cspice_dpr(), $
dskdsc[SPICE_DSK_MX1IDX] * cspice_dpr()
print, format='(A,2F22.14)', ' Latitude (deg): ', $
dskdsc[SPICE_DSK_MN2IDX] * cspice_dpr(), $
dskdsc[SPICE_DSK_MX2IDX] * cspice_dpr()
print, format='(A,2F22.14)', ' Radius (km): ', $
dskdsc[SPICE_DSK_MN3IDX], $
dskdsc[SPICE_DSK_MX3IDX]
endif else if ( corsys eq SPICE_DSK_CYLSYS ) then begin
print, 'Coordinate system was Cylindrical.'
return
endif else if ( corsys eq SPICE_DSK_RECSYS ) then begin
print, format='(A,2F22.14)', ' X-coordinate (km):', $
dskdsc[SPICE_DSK_MN1IDX], $
dskdsc[SPICE_DSK_MX1IDX]
print, format='(A,2F22.14)', ' Y-coordinate (km):', $
dskdsc[SPICE_DSK_MN2IDX], $
dskdsc[SPICE_DSK_MX2IDX]
print, format='(A,2F22.14)', ' Z-coordinate (km):', $
dskdsc[SPICE_DSK_MN3IDX], $
dskdsc[SPICE_DSK_MX3IDX]
endif else if ( corsys eq SPICE_DSK_PDTSYS ) then begin
print, format='(A,2F22.14)', ' Longitude (deg): ', $
dskdsc[SPICE_DSK_MN1IDX] * cspice_dpr(), $
dskdsc[SPICE_DSK_MX1IDX] * cspice_dpr()
print, format='(A,2F22.14)', ' Latitude (deg): ', $
dskdsc[SPICE_DSK_MN2IDX] * cspice_dpr(), $
dskdsc[SPICE_DSK_MX2IDX] * cspice_dpr()
print, format='(A,2F22.14)', ' Altitude (km): ', $
dskdsc[SPICE_DSK_MN3IDX], $
dskdsc[SPICE_DSK_MX3IDX]
endif
;;
;; Find the next segment, if it exists.
;;
cspice_dlafns, handle, dladsc, nxtdsc, found
endwhile
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_kclear
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, using the DSK file named phobos512.bds and an empty
string instead of the meta-kernel name, the output was:
Enter DSK name > phobos512.bds
Enter meta-kernel name >
====================================
DSK descriptor for segment 1
Body: PHOBOS
Surface: 401
Frame: IAU_PHOBOS
Start time (TDB): 1950 JAN 01 00:00:41.183
Stop time (TDB): 2050 JAN 01 00:01:06.183
Data type: 2
Data class: Single-valued surface
Coordinate System: Latitudinal
Segment boundaries:
Longitude (deg): -180.00000000000000 180.00000000000000
Latitude (deg): -90.00000000000000 90.00000000000000
Radius (km): 8.04963224872155 13.94093983212395
3) Again, dump the DSK descriptors of a DSK file, using the
program from example 2, but this time reading the DSK file
phobos_3_3_3seg.bds
which can be created by running an example program from
cspice_dskw02. Use the meta-kernel shown below to demonstrate surface
name-ID mapping.
KPL/MK
File: dskgd_ex3.tm
This meta-kernel is intended to support operation of SPICE
example programs. The file contents shown here should not be
assumed to contain adequate or correct versions of data
required by SPICE-based user applications.
\begindata
NAIF_SURFACE_NAME += ( 'Phobos example surface 1',
'Phobos example surface 2',
'Phobos example surface 3' )
NAIF_SURFACE_CODE += ( 1, 2, 3 )
NAIF_SURFACE_BODY += ( 401, 401, 401 )
\begintext
End of meta-kernel
When Example #2 was executed on a Mac/Intel/IDL8.x/64-bit
platform, using the DSK file named phobos_3_3_3seg.bds and the
meta-kernel dskgd_ex3.tm, the output was:
Enter DSK name > phobos_3_3_3seg.bds
Enter meta-kernel name > dskgd_ex3.tm
====================================
DSK descriptor for segment 1
Body: PHOBOS
Surface: Phobos example surface 1
Frame: IAU_PHOBOS
Start time (TDB): 1950 JAN 01 00:00:00.000
Stop time (TDB): 2050 JAN 01 00:00:00.000
Data type: 2
Data class: General surface
Coordinate System: Latitudinal
Segment boundaries:
Longitude (deg): -180.00000000000000 180.00000000000000
Latitude (deg): -90.00000000000000 90.00000000000000
Radius (km): 8.22529807597397 14.01176814562576
====================================
DSK descriptor for segment 2
Body: PHOBOS
Surface: Phobos example surface 2
Frame: IAU_PHOBOS
Start time (TDB): 1950 JAN 01 00:00:00.000
Stop time (TDB): 2050 JAN 01 00:00:00.000
Data type: 2
Data class: General surface
Coordinate System: Rectangular
Segment boundaries:
X-coordinate (km): -1.30000000000000 1.31000000000000
Y-coordinate (km): -1.21000000000000 1.20000000000000
Z-coordinate (km): -9.45293235778800 9.63817977905300
====================================
DSK descriptor for segment 3
Body: PHOBOS
Surface: Phobos example surface 3
Frame: IAU_PHOBOS
Start time (TDB): 1950 JAN 01 00:00:00.000
Stop time (TDB): 2050 JAN 01 00:00:00.000
Data type: 2
Data class: General surface
Coordinate System: Planetodetic
Equatorial radius (km): 13.00000000000000
Polar radius (km): 9.10000000000000
Segment boundaries:
Longitude (deg): -180.00000000000000 180.00000000000000
Latitude (deg): -90.00000000000000 90.00000000000000
Altitude (km): -3.72866868360370 1.37201579108146
This is a convenience routine intended for use by low-level routines
that read DSK segments. This routine may also be called by user
applications that must access DSK files at the segment level.
1) If the size of the double precision component of the segment
is smaller than that of a DSK descriptor, the error
SPICE(INVALIDFORMAT) is signaled by a routine in the call tree
of this routine.
2) If the input handle is invalid, an 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 any DAS read error is detected, the error is signaled by a
routine in the call tree of this routine.
5) If any of the input arguments, `handle' or `dladsc', is
undefined, an error is signaled by the IDL error handling
system.
6) If any of the input arguments, `handle' or `dladsc', is not of
the expected type, or it does not have the expected dimensions
and size, an error is signaled by the Icy interface.
7) If the output argument `dskdsc' is not a named variable, an
error is signaled by the Icy interface.
See input argument `handle'.
1) See Exception #3.
DAS.REQ
DSK.REQ
ICY.REQ
NAIF_IDS.REQ
None.
J. Diaz del Rio (ODC Space)
M. Liukis (JPL)
E.D. Wright (JPL)
-Icy Version 1.0.1, 17-JUN-2021 (JDR)
Edited the header to comply with NAIF standard. Updated
code example to prompt for the input DSK file and reformatted
example's output. Added second and third examples.
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)
return DSK segment_descriptor
|