PRO WRITEISIS, FILE, DATA, SPECIAL=special

;	---------------------------
;	|    W R I T E I S I S    |
;	---------------------------
;
;  This procedure creates a new ISIS cube file with the name specified
;  by the string parameter FILE.  The 2D or 3D data array supplied in
;  the DATA parameter is written into the core of the new cube file.
;  DATA must be a floating point array.  The output file will contain
;  32-bit floating point pixels and will be in BSQ physical storage
;  order.
;
;  The optional keyword parameter SPECIAL allows translating one or five
;  pixel values into ISIS special pixel values in the output file.  If
;  SPECIAL is not specified, then no translation is performed.  If a
;  single value is specified, then any pixel values in the DATA array
;  that match the value are translated into ISIS NULL pixel values before
;  being written to the file.  If needed, the supplied value is converted
;  to floating point format.  (Note that the values in the input DATA 
;  array are changed by this operation.)  If five SPECIAL values are
;  specified, then the five values are translated into the five ISIS
;  special pixel values.  The order of the values is: NULL,
;  LOW_REPR_SATURATION, LOW_INSTR_SATURATION, HIGH_INSTR_SATURATION, and
;  HIGH_REPR_SATURATION.

;
;  Written by Jim Torson, U.S. Geological Survey, Flagstaff, AZ
;
;  History:
;	Jan. 29, 1996 - Original version
;	Apr.  1, 1996 - Changed to use ISISIDLLIB environment variable;
;		Fixed bug in checking for floating point input array
;	Apr.  2, 1996 - Added SPECIAL keyword parameter
;	Dec.  3, 2001 - Updated the Version Date (it hadn't been updated
;		previously)

isislib = getenv('ISISIDLLIB')
if strlen(isislib) EQ 0 then begin
    print, 'Before running WRITEISIS, you must set the environment variable ISISIDLLIB'
    print, '  to the directory that contains the "isis2idl.so" file'
    return
endif else isislib = isislib + '/isis2idl.so'

prgnam = 'WRITEISIS'
version = '2001-12-03'
sftwdesc = 'Write array into new ISIS cube'
result = call_external(isislib, 'I_init', prgnam,version,sftwdesc)

n_spec = n_elements(special)
if (n_spec NE 0L) AND (n_spec NE 1L) AND (n_spec NE 5L) then begin
    print, 'WRITEISIS - SPECIAL parameter must specify 1 or 5 values'
    goto, alldone
endif

s_info = size(data)
if (s_info(0) LT 2) OR (s_info(0) GT 3) then begin
    print, 'WRITEISIS - Data array must be 2D or 3D'
    goto, alldone
endif
if s_info(0) EQ 2 then typecode = s_info(3) else typecode = s_info(4)
if typecode NE 4 then begin
    print, 'WRITEISIS - Data array must be floating point'
    goto, alldone
endif

fid = 0L
access = 3L
sfrom = ' '
ptype = 3L
scale = [0.0,1.0]
ns = s_info(1)
nl = s_info(2)
if s_info(0) EQ 2 then nb = 1L else nb = s_info(3)
result = call_external(isislib, 'I_cube_open', fid,file, access,sfrom,ptype, $
	scale, ns,nl,nb)
if result NE 0 then begin
    print, 'WRITEISIS - Error creating new cube file'
    goto, alldone
endif

if n_spec NE 0L then begin
; Translate some values to special pixel values
    spec_vals = fltarr(7)
    result = call_external(isislib, 'I_getspecial', 3L, spec_vals)
    oldspec = float(special)
    result = call_external(isislib, 'I_cleandata', 3L, n_spec, oldspec, $
	spec_vals, ns*nl*nb, data)
endif

iomode = 2L
cnvt = 0L
limits = [[1,ns],[1,nl],[1,nb]]
sats = [0L,0L]
result = call_external(isislib, 'I_cube_cbrick', fid,iomode,cnvt,limits, $
	data, sats)
if result NE 0 then begin
    print, 'WRITEISIS - Error writing data to new cube file'
    goto, alldone
endif

result = call_external(isislib, 'I_qclose', fid)

alldone:
result = call_external(isislib, 'I_exit')
return
end