GDBIntChanIO -- Generic Database Integer Image Transfer

GDBIntChanIO() (Image Window Integer Image data I/O) allows access to the imagery data held on a generic database file. There are two functions: reading of a rectangular window of imagery from the file into an integer (int32) buffer; and writing of data from an integer (int32) buffer into a rectangular window of imagery on the file.

GDBIntChanIO() automatically performs shrinking/zooming between windows of different sizes, mapping between buffer and generic database channels, and data type conversions.

GDBIntChanIO() is similar to GDBByteChanIO(), except that the image data buffer consists of int32's. Please review the GDBByteChanIO() help for information on data interleaving, zooming and windowing.

See Also: GDBByteChanIO(), GDBRealChanIO()

CALL SEQUENCE

void GDBIntChanIO(fpGDB, nFunc, nXOff, nYOff, nXSize, nYSize,
                 panImgBuf, nBufXSize, nBufYSize,
                 nBufChanCount, panChanMap);

FILE    *fpGDB;
           File pointer of generic database file to access.

int     nFunc;
           Function to perform.  This should be GDB_READ, to read
           from the file into pabyImgBuf, or GDB_WRITE to write from
           pabyImgBuf into the file.

int     nXOff;
           X (pixel) offset to imagery window in file.

int     nYOff;
           Y (line)  offset to imagery window in file.

int     nXSize;
           X (pixel) size of imagery window in file.

int     nYSize;
           Y (line)  size of imagery window in file.

int32   *panImgBuf;
           Buffer of integer image data to read/write.

           On a read, this buffer receives  the  imagery data  read
           from  the file.  On a write,  this buffer  contains  the
           imagery  data to write into the file.  The image held in
           panImgBuf has dimensions nBufYSize lines, each line made
           up of nBufXSize pixels, each pixel having nBufChanCount
           channels.

int     nBufXSize;
           X (pixel) size of imagery window in buffer.

int     nBufYSize;
           Y (line)  size of imagery window in buffer.

int     nBufChanCount;
           Number of channel values in panImgBuf.

int     *panChanMap;
           Channel mapping buffer.  The list of channels to read,
           or write.  This array should contain nBufChanCount entries.

Data Conversion

Each channel of imagery data on a file can be one of the following four types: 8 bit unsigned integer (also called byte); 16 bit signed integer; 16 bit unsigned integer; and 32 bit real. A GeoGateway file may contain a mixture of these data types.

The caller of GDBIntChanIO() does not need know the type of data each channel on the file contains since GDBIntChanIO() automatically converts between int32 and other data types. This gives the appearance that all channels on the file are int32.

As a general rule, when one data type is converted to another, input values which are less than or greater than the minimum or maximum allowed output values are set to the minimum or maximum output value. Real values are truncated to integer values, where necessary. Scaling and rounding is NOT performed.

The following table shows how a pixel value N in the database is converted to and from a byte value in the buffer, for each of the four data types. 

+---------+--------------------------+--------------------------+
|         |           READ           |          WRITE           |
+---------+------------------+-------+------------------+-------+
| data    |      file        | buffer|     buffer       | file  |
| type    |      input       | output|     input        | output|
+---------+------------------+-------+------------------+-------+
| 8-bit   |                  |       |     0> N         |   0   |
| unsigned|     0<=N<=255    |   N   |     0<=N<=255    |   N   |
| integer |                  |       |        N >255    |  255  |
+---------+------------------+-------+------------------+-------+
| 16-bit  |                  |       | -32678> N        |-32768 |
| signed  | -32768<=N<=32767 |   N   | -32768<=N<=32767 |   N   |
| integer |                  |       |         N >32767 | 32767 |
+---------+------------------+-------+------------------+-------+
| 16-bit  |                  |       |      0> N        |   0   |
| unsigned|      0<=N<=65535 |   N   |      0<=N<=65535 |   N   |
| integer |                  |       |         N >65535 | 65535 |
+---------+------------------+-------+------------------+-------+
| 32-bit  |                  |       |                  |       |
| real    | -2147483648<=N<= | int(N)|  any integer N   |real(N)|
|         |  2147483647      |       |                  |       |
+---------+------------------+-------+------------------+-------+

EXAMPLE

A window of data, offset (123 pixels, 111 lines), size (128 pixels, 128 lines), is to be read off a PCIDSK file and shrunk to a size of 32 pixels by 64 lines. In addition only the three channels 7, 3 and 5 are required off disk. 

             . . .
    FILE          *fp;
    int           chnmap[3],window[4];
    char          dbname[64];
    int32         img[6144];             | 6144=32*64*3
             . . .
    fp = GDBOpen(dbname,"r+");           | Open the PCIDSK file 
    window[0] = 123;                     | X offset
    window[1] = 111;                     | Y offset
    window[2] = 128;                     | X size
    window[3] = 128;                     | Y size
    chnmap[0] = 7;
    chnmap[1] = 3;
    chnmap[2] = 5;
    CheckChan (fp,"CHNMAP",CHNMAP,3);
                |  Check that window is valid and channels exist
    CheckWin (fp,"WINDOW",window,chnmap);

    GDBIntChanIO(fp,GDB_READ,window[0],window[1],window[2],
                 window[3],img,32,64,3,chnmap);
                            | Get the window off the database
             . . .
About PCI Help Gateway