example Documentation

example - Illustrates how to access ISIS cube from IDL


PRO EXAMPLE, file, sfrom=sfrom
;
;	-----------------------
;	|    E X A M P L E    |
;	-----------------------
;
;_Title	EXAMPLE - Access ISIS cube file from IDL
;
;_Args	Type	Variable	I/O	Description
;	string	file		I	Input cube file name
;	string	sfrom		I	SFROM to select the part of
;					  the input cube file to
;					  be processed
;
;_Desc	This is an example program that illustrates how to use
;	the CALL_EXTERNAL routines to access an ISIS cube file.
;	This includes reading label keyword values, reading
;	the core of the cube, and reading a backplane of the
;	cube into a LONG array (which would be the appropriate
;	data type for a Region of Interest (ROI) backplane
;	created with "cv").
;
;
;	There are a number of additional ISIS routines that can
;	be called from IDL using CALL_EXTERNAL.  The source files
;	for these routines (which include documentation for the
;	caller) are contained in $ISIS/idl/externals.  Many of
;	these are simply interfaces that call the corresponding
;	ISIS C or Fortran routine, but there are some that do more
;	complicated things.
;
;	Note the following concerning the example program:
;
;	1. The isislib string variable contains the name and
;	location of the isis2idl.so file that contains the
;	compiled library of the CALL_EXTERNAL routines.
;
;	2. Normally the location of isis2idl.so is obtained from the
;	ISISIDLLIB environment variable, which is set to
;	/usgs/isisr/exe by the standard ISIS user initialization.
;	(This location might be different on a different ISIS
;	installation.)
;
;	3. When you supply the name of a variable in a CALL_EXTERNAL
;	call, the variable must already exist - it will not be
;	created if it is to receive a value.
;
;	4. All integer variables in CALL_EXTERNAL calls must be LONGs.
;
;	5. When string (or string array) values are to be returned
;	by a CALL_EXTERNAL routine, the argument supplied should be
;	an IDL byte array rather than an IDL string.  The STRING
;	function can be used to convert a returned byte array to an
;	IDL string.
;
;	6. A NULL IDL string ('') should not be passed as an input
;	string value to a CALL_EXTERNAL routine.  In particular, when
;	calling a routine such as I_p_get_dbl_key (illustrated below)
;	to fetch a keyword value from a cube label, if the keyword
;	is not within a group or object, then the parameter should
;	be specified as a string containing a single blank character
;	(' ') rather than as a NULL string.
;
;_Hist	Apr 17 2000 Jim Torson, USGS, Flagstaff - Original version
;	Dec 25 2000 JMT - Updated to be compatible with updated I_getspecial
;	Jun  5 2001 JMT - Added more explanation in the description
;	Dec  6 2001 JMT - Clarified the description of passing strings
;		to CALL_EXTERNAL routines 
;
;_End