This software system is designed to integrate the Integrated Software for Imagers and Spectrometers (ISIS) version 3 with Research Systems, INC Interactive Data Language (IDL) system. This software system is composed to two distinct parts. The first part is the Idl DLM toolkit, IdlDlm.

IdlDlm is a toolkit designed to manage the IDL DLM interface as an abstract layer. It hides all the complicated peculiarities inherent to writing an IDL DLM.

Note routines return 0 if successful, non-zero if it was unable to complete its designed operation. This is standard for all routines unless otherwise indicated.

ISIS_OPEN

Opens an ISIS cube or a PVL file. This routine accepts the name of a file and will open for READONLY or READWRITE access. It returns a unique ISIS IDentifier, IID, that can be used in other IsisDlm functions.

result = ISIS_OPEN(FILENAME, IID, [,/LABEL] [,/READONLY] [,/READWRITE])

ISIS_OPEN Parameters
Type	Name	I/O	Description
STRING	FILENAME	Input	Name of file to open for specified operations. The unique ISIS identifier is returned in the IID parameter. This file remains open until ISIS_CLOSE is called or the IDL session terminates, at which time all opened files are closed.
ULONG	IID	Output	IID returns the unique ISIS identifier for this file. It is to be used in other IsisDLM routines for subsequent access.

ISIS_OPEN Keywords
Type	Name	I/O	Description
BOOLEAN	LABEL	Input	This option should be used when the caller is only interested in the accessing the PVL label portion of the file. It can be used with ISIS cube files or for any file that conforms to PVL syntax. This option is know to work for version 2 ISIS files and PDS files.
BOOLEAN	READONLY	Input	IDL caller request the file be opened for read only access
BOOLEAN	READWRITE	Input	IDL caller request the file be opened for read and write access.

ISIS_CREATE

Creates and ISIS cube file or a PVL file. The default operation of this routine is to create an ISIS cube file. If no parameters are provided, the ISIS system provides the defaults.

result = ISIS_CREATE(FILENAME, IID, [,DIMS=[ns,nl,nb] [,PROPID=pid]
                     [,/LABEL] [,/DETACHED] [,/BSQ] [,/FLOAT] [,/SHORT]
                     [,/BYTE])

ISIS_CREATE Parameters
Type	Name	I/O	Description
STRING	FILENAME	Input	Name of file to create. The unique ISIS identifier is returned in the IID parameter. This file remains open until ISIS_CLOSE is called or the IDL session terminates, at which time all opened files are closed.
ULONG	IID	Output	IID returns the unique ISIS identifier for this newly created file. It is to be used in other IsisDLM routines for subsequent access.

ISIS_CREATE Keywords
Type	Name	I/O	Description
INT	DIMS	Input	If creating an ISIS cube file, this parameter specifies the dimensions of the ISIS cube data. This should be a 3 element array where the first element is the number of SAMPLES (ns), the second is LINES (nl) and the third elements is the number of BANDS (nl).
ULONG	PROPID	Input	The caller can provide the Isis identifier of a file that is already opened by IsisDlm from which to propagate labels from. This is useful for creating files from existing files whilst preserving label content. Note this option really only pertains to ISIS cubes and is therefore ignored when the LABEL option is specified and when the PROPID is not opened as an ISIS cube file. Note this option is not currenly implemented for this release!
BOOLEAN	LABEL	Input	IsisDlm provides the capability to create PVL files. This is useful for creating custom PVL files. Operations are restricted to label reading and writing operations if a file is created in this mode.
BOOLEAN	DETACHED	Input	ISIS files can either have their labels and data objects created as a single file or the labels can be detached from the data. If the caller provides this option, then a label file will be created with a .cub extension and the data is created with a .dat extension. The default is to create an attached ISIS file.
BOOLEAN	BSQ	Input	ISIS 3 cube files use a tiling scheme to physically store cube data. The creator of ISIS cubes may choose to create Band SeQuential (BSQ) core data objects in the same fashion of version 2 ISIS cubes. This is useful when access by external methods are anticipated where the BSQ form is more easily supported. The default is determined by the ISIS system and will typically be tiled data organization. This organization has shown to be efficient for map projections within the ISIS system.
BOOLEAN	FLOAT	Input	Specifies the raw core data values to be stored in Real format. See this table for ISIS pixel types.
BOOLEAN	SHORT	Input	Specifies the raw core data values to be stored in SignedWord format. See this table for ISIS pixel types.
BOOLEAN	BYTE	Input	Specifies the raw core data values to be stored in UnsignedByte format. See this table for ISIS pixel types.

The implementation of this routine in ISISDLM::isis_create.

ISIS_CLOSE

This routine closes an ISIS cube file or a PVL file that was opened or created by other routines in the IsisDlm toolkit. See also ISIS_OPEN ISIS_CREATE.

result = ISIS_CLOSE(IID)

ISIS_CLOSE Parameters
Type	Name	I/O	Description
ULONG	IID	Input	Specifies the ISIS identifier of the file to close.

The implementation of this routine in ISISDLM::isis_close.

ISIS_QUERY

Provides a programmable interface to files that are currently open and maintained by the IsisDlm.

result = ISIS_QUERY([IID=iid] [,FILENAME=filename] [,DIMS=[ns,nl,nb]]

[,DTYPE=dtype] [,BASE=base] [,MULT=mult] [,/SHOWALL])

ISIS_QUERY Keywords (No Parameters!)

Type

Name

I/O

Description

ULONG

IID

Input

Isis Identifier associated with an open file. If provided, the information requested in other keywords will be characteristics of this file.

STRING

FILENAME

Output

Returns the name of the file if IID is specified by the caller. This file may have been opened by ISIS_OPEN or some other IsisDLM routine.

LONG

DIMS

Output

Returns the dimensions of the ISIS cube core data associated with the file refered to by IID. It will a 3-dimensional array where the first array element is SAMPLES, the second is LINES and the third is BANDS in the ISIS cube file core.

STRING

DTYPE

Output

Returns the type of data stored in the ISIS core. Possible return values are listed in the following table:

ISIS Core Data Types
Value	Description
None	No type or invalid
UnsignedByte	8-bit Unsigned Byte/Integer (BYTE)
SignedByte	8-bit Signed Byte/Integer (BYTE)
SignedWord	16-bit Signed Integer (INT)
SignedWord	16-bit Unsigned Integer (UINT)
SignedInteger	32-bit Signed Integer (LONG)
UnsignedInteger	32-bit Unsigned Integer (ULONG)
Real	32-bit Float (FLOAT)
Double	64-bit Double Float (DOUBLE)

DOUBLE

BASE

Output

Returns the base offset added to the stored core data value after the MULT value is applied to it. This value is used in the following equation to compute the double representation of a pixel value:

value = ((stored core value) * MULT) + BASE

DOUBLE

MULT

Output

Returns the multiplier value applied to the stored core data value and the BASE value to compute the actual pixel value. This value is used in the following equation to compute the double representation of a pixel value:

value = ((stored core value) * MULT) + BASE

SWITCH

SHOWALL

Input

This switch will result in the information for the file specified in IID being printed to the screen. This is mainly used for the interactive IDL user to see the state of the file or files currently open and accessable in the IsisDLM system.

If IID is not provided, it lists information about all the files currently open. If a valid IID is given, only information for that particular file is printed.

The implementation of this routine in ISISDLM::isis_query.

ISIS_READ

ISIS_READ provides access to core data within an ISIS cube file. It will read the entire core, all bands in either DOUBLE or raw format. Raw format is either 8-bit unsigned integer, 16-bit signed integer, or 32-bit floating point data.

The general form of the call is:

result = ISIS_READ(FILE, DATA, [,OID=oid] [,/RAW])

ISIS_READ Parameters
Type	Name	I/O	Description
STRING	FILE	Input	Name of file to open and read the core from. If OID is given, a unique identifier is returned in OID and the file remains open for further access by data I/O routines or label routines. If OID is not provided, the file is closed prior to returning from this routine.
DOUBLE, FLOAT, INT, BYTE	DATA	Output	The core data is returned in this parameter. This parameter will either be 2-dimensional if there is only one band, or 3-dimensional if there is more than one band in the cube. If /RAW is specified, then the return type will be FLOAT, INT or BYTE if the raw storage data type of the cube is 32-bit float, 16-bit signed integer, or 8-bit unsigned integer, respectively.

ISIS_READ Keywords
Type	Name	I/O	Description
ULONG	OID	Output	If specified by the caller (i.e., oid=oid), this parameter will return a unique identifier for FILE. The file will remain open. If this parameter is not provided by the caller, the file will be closed prior to returning to the calling IDL environment. See also ISIS_CLOSE.
SWITCH	RAW	Input	If the caller provides /RAW in the calling list, the data will be returned in the actual storage type. See the DATA parameter for a description of possible types

The implementation of this routine is found at ISISDLM::isis_read.

ISIS_READ_IMAGE

ISIS_READ_IMAGE provides access to individual core plane data within an ISIS cube file. It will read a singal plane from the core, in either DOUBLE or raw format. Raw format is either 8-bit unsigned integer, 16-bit signed integer, or 32-bit floating point data.

The general form of the call is:

result = ISIS_READ_IMAGE(DATA, [,FILE=filename] [,IID=iid] [,BAND=band]

[,/RAW] [,OID=oid])

ISIS_READ_IMAGE Parameters
Type	Name	I/O	Description
DOUBLE, FLOAT, INT, BYTE	DATA	Output	The core plane is returned in this parameter. This parameter will be a 2-dimensional array of the data in the requested format - either DOUBLE or RAW. If /RAW is specified, then the return type will be FLOAT, INT or BYTE if the raw storage data type of the cube is 32-bit float, 16-bit signed integer, or 8-bit unsigned integer, respectively.

ISIS_READ_IMAGE Keywords
Type	Name	I/O	Description
STRING	FILE	Input	Name of file to open and read the core plane from. This keyword provides the option of reading a single band from a file that is not yet opened. If OID is provided, the band is read, a unique ISIS identifier is returned in OID and the file remains open upon return. If OID is not provided, only the requested band is read and the file is closed prior to returning to the IDL caller.
ULONG	IID	Input	Isis Identifier associated with an open file. If provided, the requested BAND is read in from the file.
INT	BAND	Input	Specifies the band number to read in from the cube. It should range from 1 to the number of bands in the cube core.
SWITCH	RAW	Input	If the caller provides /RAW in the calling list, the data will be returned in the actual storage type. See the DATA parameter for a description of possible types
ULONG	OID	Output	If specified by the caller (i.e., OID=oid), this parameter will return a unique identifier for FILE. The file will remain open. If this parameter is not provided by the caller, the file will be closed prior to returning to the calling IDL environment. This parameter should be used in conjunction with the FILE keyword. See also ISIS_CLOSE.

The implementation of this routine is found at ISISDLM::isis_read_image.

ISIS_READ_BRICK

ISIS_READ_BRICK provides access to a 3-dimensional section of the ISIS core data within an ISIS cube file. It will read datae from the core in either DOUBLE or raw format. Raw format is either 8-bit unsigned integer, 16-bit signed integer, or 32-bit floating point data.

The general form of the call is:

result = ISIS_READ_BRICK(DATA, [,FILE=filename] [,IID=iid] 
                         [,SBAND=sband] [,NBANDS=nbands]
                         [,SSAMP=ssamp] [,NSAMPS=nsamps]
                         [,SLINE=sline] [,NLINES=nlines]
                         [,/RAW] [,OID=oid])

ISIS_READ_BRICK Parameters
Type	Name	I/O	Description
DOUBLE, FLOAT, INT, BYTE	DATA	Output	The core section is returned in this parameter. This parameter will be a 2-dimensional array if the net number of bands or NBANDS is 1. It will return a 3-dimensional array if the number of bands is more than 1. The data will be return in the requested format - either DOUBLE or RAW. If /RAW is specified, then the return type will be FLOAT, INT or BYTE if the raw storage data type of the cube is 32-bit float, 16-bit signed integer, or 8-bit unsigned integer, respectively.

ISIS_READ_BRICK Keywords
Type	Name	I/O	Description
STRING	FILE	Input	Name of file to open and read the core section from. This keyword provides the option of reading a from a file that is not yet opened. If OID is provided, the requested core section is read, a unique ISIS identifier is returned in OID and the file remains open upon return. If OID is not provided, only the requested section of the core is read and the file is closed prior to returning to the IDL caller. Note it is in error to provide both FILE and IID. Only one of these keywords should be specified.
ULONG	IID	Input	Isis Identifier associated with an open file. If provided, the requested section of the core data is read in from a previously opened file via one of the IsisDlm routines (ISIS_OPEN for example).
LONG	SBAND	Input	Specifies the starting band to read from the cube. It should range from 1 to the number of bands in the cube core. If this value is not provided, the default is 1.
LONG	NBANDS	Input	Specifies the number of bands to read from the cube. The number of bands specified is subject to the starting band as specified in SBAND. SBAND + NBANDS - 1 cannot exceed the total number of bands in the ISIS cube core. If this keyword is not provided, the default is to read all bands from SBAND to the maximum number of bands in the cube core.
LONG	SSAMP	Input	Specifies the starting sample to read from the cube. It should range from 1 to the number of samples in the cube core. If this value is not provided, the default is 1.
LONG	NSAMPS	Input	Specifies the number of samples to read from the cube. The number of samples specified is subject to the starting sample as specified in SSAMP. SSAMP + NSAMPS - 1 cannot exceed the total number of samples in the ISIS cube core. If this keyword is not provided, the default is to read all samples from SSAMP to the maximum number of samples in the cube core.
LONG	SLINE	Input	Specifies the starting line to read from the cube. It should range from 1 to the number of lines in the cube core. If this value is not provided, the default is 1.
LONG	NLINES	Input	Specifies the number of lines to read from the cube. The number of lines specified is subject to the starting line as specified in SLINE. SLINE + NLINES - 1 cannot exceed the total number of lines in the ISIS cube core. If this keyword is not provided, the default is to read all samples from SSAMP to the maximum number of samples in the cube core.
SWITCH	RAW	Input	If the caller provides /RAW in the calling list, the data will be returned in the actual storage type. See the DATA parameter for a description of possible types
ULONG	OID	Output	If specified by the caller (i.e., OID=oid), this parameter will return a unique identifier for FILE. The file will remain open. If this parameter is not provided by the caller, the file will be closed prior to returning to the calling IDL environment. This parameter should be used in conjunction with the FILE keyword. See also ISIS_CLOSE.

The implementation of this routine is found at ISISDLM::isis_read_brick.

ISIS_READ_BLOB

ISIS_READ_BLOB will read the a field from a Binary Large OBject (BLOB) that is contained within an ISIS cube. The caller must know the name of the table the BLOB is contained and the name of the field within that table.

The general form of the call is:

result = ISIS_READ_BLOB(IID, TABLE, FIELD, DATA)

ISIS_READ_BLOB Parameters
Type	Name	I/O	Description
ULONG	IID	Input	Isis Identifier associated with an open file.
STRING	TABLE	Input	This is the name of a TABLE object within an ISIS file. This will be the value of the NAME keyword in the object.
STRING	FIELD	Input	This is the name of a FIELD group within a TABLE object in the ISIS file. This will be the value of the NAME keyword in the group
DOUBLE, LONG, STRING	DATA	Output	This will return the requested FIELD from the BLOB. It will typically be a vector containing the data.

There is no real distinct way to determine if an ISIS file contains a particular BLOB. There is a way using the ISIS_GET_KEY routine. This IDL code will determine the names of the BLOBS in an ISIS cube file:

;  Now lets see how many tables are in the file and then their names
occurs = 0
kspec = 'Table/Name'
status = 0
while (status eq 0) do begin
  status = isis_get_key(iid, kspec, name, occurs=occurs)
  if (status eq 0) then begin
    print, '  Table Name: ', name
  endif
  occurs = occurs + 1
endwhile

Note that the kspec string contains a "path" to the Table OBJECT and the keyword Name within that OBJECT. All ISIS BLOBs are in Table OBJECTs and the name of the BLOB is in the Name keyword within that OBJECT.

ISIS_WRITE

ISIS_WRITE will create a new ISIS file and write a 2-D or 3-D array of data to the ISIS core object.

The general form of the call is:

result = ISIS_WRITE(FILE, DATA, [,OID=oid] [,PROPID=iid])

ISIS_WRITE Parameters
Type	Name	I/O	Description
STRING	FILE	Input	Name of file to create and write the core to. If OID is given, a unique identifier is returned in OID and the file remains open for further access by data I/O routines or label routines. If OID is not provided, the file is closed prior to returning from this routine.
DOUBLE, FLOAT, INT, BYTE	DATA	Output	The core data is provided by the caller in this parameter. This parameter can be either be 2-dimensional if there is only one band, or 3-dimensional if there is more than one band to write to the ISIS cube specified by FILE. If the array is not DOUBLE, then it must be FLOAT (32-bit float), INT (16-bit signed integer) or BYTE (8-bit unsigned integer). It is written in RAW format.

ISIS_WRITE Keywords
Type	Name	I/O	Description
ULONG	OID	Output	If specified by the caller (i.e., OID=oid), this parameter will return a unique identifier for FILE. The file will remain open. If this parameter is not provided by the caller, the file will be closed prior to returning to the calling IDL environment. See also ISIS_CLOSE.
ULONG	PROPID	Input	If specified by the caller, this is taken to be the Isis Identifier of an open file where the label content will be propagated from it to the file created by this routine.

ISIS_WRITE_IMAGE

ISIS_WRITE_IMAGE will optionally create a new ISIS file or use an existing file and write a 2-D or 3-D array of data to the ISIS core object at a specified starting band.

The general form of the call is:

result = ISIS_WRITE_IMAGE(DATA, FILE=filename | IID=iid [,BAND=bandno] [,OID=oid])

NOTE There has been a bug fix provided in the ISIS 3.4.7 release that fixed a problem with keeping a file open when IID is provided. Also, the BAND specified was not being considered and would only write to the first band. This has been fixed. (KJB 2014-08-27)

ISIS_WRITE_IMAGE Parameters
Type	Name	I/O	Description
DOUBLE, FLOAT, INT, BYTE	DATA	Input	The core data is provided by the caller in this parameter. This parameter can be either be 2-dimensional if there is only one band, or 3-dimensional if there is more than one band to write to the ISIS cube specified by FILE or IID. If the array is not DOUBLE, then it must be FLOAT (32-bit float), INT (16-bit signed integer) or BYTE (8-bit unsigned integer). It is written in RAW format.
STRING	FILE	Input	Name of file to create and write the core to. If OID is given, a unique identifier is returned in OID and the file remains open for further access by data I/O routines or label routines. If OID is not provided, the file is closed prior to returning from this routine. In this case, the size of the output cube file is determined by the dimensions of the DATA array. Note that FILE cannot be specified if IID is provided.
ULONG	IID	Input	Isis Identifier associated with an open file to write the DATA array to. If IID is specified, FILE cannot be specified since this would indicate a second source of output. The DATA array size is expected to be no greater than the dimensions of the cube file associated with the IID cube. The cube associated with IID can be opened using ISIS_OPEN or created using ISIS_CREATE.

ISIS_WRITE_IMAGE Keywords
Type	Name	I/O	Description
LONG	BAND	Input	If specified by the caller, it specifies the starting band to write the image to in the FILE or IID cube file. If it is not provided, BAND=1 is implied. Note that if the DATA array is 3-dimensional, the number of bands in DATA starting at BAND cannot exceed the size of the given file if IID is given.
ULONG	OID	Output	If specified by the caller (i.e., OID=oid), this parameter will return a unique identifier for FILE. The file will remain open. If this parameter is not provided by the caller, the file will be closed prior to returning to the calling IDL environment. See also ISIS_CLOSE.

See also ISIS_CREATE, ISIS_OPEN, ISIS_WRITE,

The implementation of this routine is found at ISISDLM::isis_write_image.