DAT file manipulation Isis software documentation

DAT file manipulation

This library contains two levels of functionality for manipulating DAT file format files. The higher level reads and writes Isis images in DAT format, and the lower level provides raw DAT file access and manipulation routines.

Reading and writing Isis image buffers

The objects defined below may be used to read and write images to and from two-dimensional DAT files. All image buffers that you pass to the objects must have a step factor of [1 imagewidth]. For this reason, you should never pass sub-image buffers to the objects--only buffers that have been newly allocated with new-standard-image or new-image. The reason for this restriction is that the DAT library is slow when dealing with non-contiguous buffers. Error checking is minimal in all of the routines. Dataset counting starts at 0.

Reading DAT files into Isis image buffers

(set idf (input-image-datfile filename)) input-image-datfile creates an object that may be used to read Isis images from the specified DAT file. You can perform different operations on the object by calling the returned procedure with different kinds of arguments. (idf) # return next dataset in new buffer (idf dataset) # return specified dataset in new buffer Calling the object with no arguments returns a new image buffer that is the next dataset in the DAT file. Calling the object with a single integer argument returns a new image buffer containing the specified dataset of the DAT file. (idf ibuf) # return next frame in old buffer (must be right size) (idf dataset ibuf) # return specified dataset in old buffer Calling the object with a single image buffer argument loads the next dataset of the DAT file into that image buffer. The same image buffer is returned. Calling the object with two arguments, an integer and an image buffer, loads that dataset into that buffer. The image buffer must be the correct size--no error checking is performed! (idf 'k' keyword) # retrieve descriptor key value (as string) Calling the object with the character 'k' and a string keyword will return the string value of the specified key from the DAT file's descriptor, or Null if it doesn't exist. (idf 'd') # get number of datasets (idf 'c') # get number of channels (idf 's') # get image size (idf 't') # get DAT file sample type Calling the object with the character 'd' returns the number of datsets in the file. 'c' returns the number of channels, and 's' returns image size (as a list of two integers). 't' will return the sample type (matches one of the memory types defined in the memory manipulation library). (idf 'q') # close file Calling the procedure with the character 'q' closes the DAT file. Do not attempt further operations after closing.

The following example opens and displays the first dataset in a DAT file in an X window:

Writing Isis image buffers to DAT files

(set odf (output-image-datfile filename datasets channels [xsize ysize])) ouput-image-datfile creates a new object that may be used to write Isis images to a DAT file. You must pass four arguments: the filename, number of datasets, number of channels, and image size [xsize ysize]. An optional fifth argument is the sample type of the images to be outputted (one of the types constants from the memory manipulation library). If this fifth argument is not given, the default is c-byte. You can perform different operations on the object by calling the returned procedure with different kinds of arguments. (odf ibuf) # output image to next dataset (odf dataset ibuf) # output image to specifed dataset Calling the object with a single image buffer argument outputs that image to the current position in the DAT file. The same image buffer is returned. The image buffer must be the correct size--no error checking is performed! Calling the object with two arguments, an integer and an image buffer, outputs the image into the specified dataset in the file. Note that you cannot write to points that do not exist yet--you must fill the DAT file with data first and then you can go back and randomly jump around. (odf dataset) # reposition write pointer to specified dataset Calling the object with a single integer argument repositions the file pointer so that the next write will take place at that dataset. The same integer is returned. (odf 'k' keyword str) # set descriptor key value (must be string) Calling the object with the character 'k', a string keyword, and a string value will set the value of that key in the DAT file's descriptor. (odf 'd') # get number of datasets (odf 'c') # get number of channels (odf 's') # get image size (odf 't') # get image buffer sample type Calling the object with the character 'd' returns the number of datsets the file can hold. 'c' returns the number of channels, and 's' returns image size (as a list of two integers). 't' will return the sample type (matches one of the memory types defined in the memory manipulation library). All of these attributes are set when the object is created. (odf 'q') # close file Calling the object with the character 'q' closes the DAT file. Do not attempt further operations after closing.

The following example writes an Isis image buffer to a DAT file, and includes a comment in the descriptor:

Long Example

An X-window DAT file viewer utility.

Raw DAT file manipulation

The following routines access and manipulate DAT files at a lower level than the image objects defined above. Use these when you need more control or when you need to manipulate data that has more than two dimensions. For more info on the specific operation of these routines, see the datio and datsubs man pages.

Opening and closing DAT files

(dat-open filename mode) # mode = "r" or "w" (dat-close dfile) dat-open opens a DAT file with the specified mode: "r" for reading or "w" for writing. The return is a file handle that should be used in all subsequent operations, or Null if there was a problem opening the file. dat-close closes an open DAT file.

Getting and setting file attributes

(dat-set-dim dfile [dsets chans dim0 dim1 ...]) (dat-get-dim dfile) # returns [dsets chans dim0 dim1 ...] (dat-set-type dfile type) # type is a DAT type character (dat-get-type dfile) (dat-set-key dfile keyword string) (dat-get-key dfile keyword) dat-set-dim sets the dimensions of a DAT file open for writing. The dimensions should be given as a list of integers [dsets chans dim0 dim1 ...]. dat-get-dim returns the dimensions of the DAT file in the same format.

dat-set-type and dat-get-type get and set the sample type of the DAT file. The type is given as a character--see the man pages for a list of accepted types and their corresponding characters.

dat-set-key and dat-get-key get and set key values in the DAT file's descriptor. Keywords and values must be passed as strings. dat-get-key returns a string or Null if the given keyword doesn't exist.

Reading and writing data

(dat-write dfile buf n-elements buf-type) # write data (dat-read dfile buf n-elements buf-type) # read data (dat-seek dfile [dsets chans dim0 dim1 ...]) # go to absolute position (dat-seek-relative [dsets chans dim0 dim1 ...]) # go to relative position dat-write accepts a DAT file handle, an address of a buffer, an integer number of elements to write, and the sample type of the buffer (a character as in dat-set-type. It transfers the specified number of elements from the buffer into the file. dat-read takes the same arguments but transfers data from the file to the buffer. Both functions return the actual number of elements transferred.

dat-seek moves the internal pointer of the DAT file to the specified absolute position so that the next read or write will take place there. dat-seek-relative seeks from the current position instead of the beginning of the file. Both functions accepts a DAT file handle and a list of integers specifying the position offset. Any ommited dimensions in the list are assumed to be zero. The same position list is returned. For example, to go to the 10th dataset, 0th channel, 50th line, and 75th pixel on that line:

Requirements:

Scripts: (load "image-datfile.isis")
Libraries: -lisis_datio -ldat
Headers: isis_datio.h
Binders: bind_datio_library(script);

written by: Ann Bui and Stefan Agamanolis

Scripts:	`(load "image-datfile.isis")`
Libraries:	`-lisis_datio -ldat`
Headers:	`isis_datio.h`
Binders:	`bind_datio_library(script);`