Parent Topic: Supported File Formats

Raw Binary Image Format (RAW)

The GDB library has a facility for reading and writing imagery in user described raw files. Some applications (such as ImageWorks) include interactive dialogs for describing the layout of the data. This description is then saved to a .aux file in the same directory as the raw data, allowing automatic use of the same file in the future without redescribing it.

Users can also prepare .aux files by hand, or with scripts. Furthermore, much of the image layout information that can be provided in the .aux file can also be supplied via a complex file naming convention if so desired.

Export of Raw Binary files is supported. These files are exported with a type of "RAW".

The default image interleaving is band sequential, but this can be overridden with the following option values during creation:

Georeferencing (or Projection), and file layout information will be written to an auxiliary file, which has the same name as the data file but with the extension ``.aux''.

The generated files may contain any image data types, but may not contain LUTs, PCTs, vectors, or bitmaps.

See Also: IMAGERD, PCIADD2, FEXPORT

Raw .aux Format
The .aux file is a simple ASCII file used to store a variety of information about an associated target file. It is used to store all information about raw files (other than the image data itself). The following is an example of a fairly simple .aux file that would be called ``test.aux''. 

 AuxilaryTarget: test.raw
 RawDefinition: 300 300 2
 ChanDefinition-1: 16U 512 2 600 Swapped
 ChanDefinition-2: 16U 180512 2 600 Swapped
 ChanDesc-1: Original DEM
 ChanDesc-2: Edited DEM
 MapUnits: UTM    11 S E000
 UpLeftX: 428720
 UpLeftY: 3734400
 LoRightX: 444080
 LoRightY: 3719040
 ProjParms: 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 METADATA_IMG_2_NO_DATA_VALUE: 100
First, an .aux file describing a file must be in the same directory as the target file, have the same basename, but the extension .aux. In the above example a selection of the file test.raw would case GeoGateway to check for the associated test.aux file. If it finds it, the name of the raw file (test.raw) is checked against the AuxilaryTarget line in the .aux file. If the filenames are different, then the .aux file is ignored.

Therefore, the first line of any .aux file must be the AuxilaryTarget: entry with the value being the name (not including directory path) of the target file. Now imagine that there was a directory with the files test.001, test.002, and test.003. There can only be one test.aux in that directory so it is not possible to associate an .aux file with each of the files.

The .aux file consists of a series of entry names, and values. The entry name is the portion of a line before the first colon, and the value is everything after the colon. So above we see several entries including RawDefinition, ChanDefinition-1, and ChanDefinition-2. 

 RawDefinition: pixels lines bands
The RawDefinition entry has three items as its value. They are the number of pixels, lines, and bands. They must be separated by white space, but otherwise the formatting is free form. If no ChanDefinition entries are provided, then the file is assumed to have zero header bytes, and to be band interleaved. 

 ChanDefinition-n: data_type start_offset pixel_offset line_offset swap_flag
The ChanDefinition entry describes the data layout of a single channel, or band. The -n in the entry name indicates which band this description applies to. The data_type must be one of 8U, 16S, 16U, or 32R. The start offset is the offset in bytes to the first byte of data of the first pixel for this channel. The pixel_offset is the offset between the first byte of one pixel on a scanline, and the next pixel. The line_offset is the offset in bytes between the first pixel of one scanline and the first pixel of the next scanline. Lastly, the swap flag can either be Swapped (Intel/LSB) or Unswapped (Motorola/MSB). 

 ChanDesc-n: description
The ChanDesc entry associates a channel description with a particular channel. 

 MapUnits: projection_name
The MapUnits entry associates a projection/georeferencing system name with the file. It must contain at most 16 characters. Its interpretation is further described in the general projections description. 

 UpLeftX, UpLeftY, LoRightX, LoRightY
These entries are used to provide the upper left and lower right corner coordinates in the indicated MapUnits. 

 ProjParms: n1 n2 ... n17
This entry is used to supply additional parameters needed to define complex projections. The meaning of these parameters is not described here, but can be deduced by editing the projection parameters of a raw file and inspecting the values written to the .aux file. 

 METADATA_layertype_layer#_metaitem: value
The METADATA entry can be used to associate the value ``value'' with the metadata item ``metaitem'' on the layer ``layer#'' of type ``layertype''.

See Also: Projections

Describing via Filename
Sometimes it is helpful to be able to describe the entire layout of a raw imagery filename via the filename. This allows any GeoGateway based utility to work with the raw image, whether it has interactive dialogs for raw describing the file or not. This also avoids the need to write an associated .aux file, which is impossible if the raw file is in a read-only directory, such as on a CDROM.

However, describing raw files via this filenaming syntax is not generally intended for interactive use. It is mainly useful in a scripting environment.

The naming convention for raw files is: 

 RAW:::filename xsize ysize bands [offset {8U/16U/16S/32R} {PIXEL/LINE/BAND}]
   [*CHANNEL chan_num {8U/16U/16S/32R} offset pixel_off line_off
                                               [swapped/unswapped]]*
The absolute simplest file description would describe a band sequential file of 8-bit data that is tightly packed with no header. For example, the following would describe the file ``raw.dat'' as being three bands, 512 pixels by 512 lines. 

 RAW:::raw.dat 512 512 3
A slightly more complex form can be used to define any file that could be read with IMAGERD. This adds the offset to the first byte of imagery, the data type and the interleaving mode. The following description defines the same file as the previous one, but it explicitly states that the offset to the first byte of imagery is zero; the data is 8-bit unsigned, band interleaved. 

 RAW:::raw.dat 512 512 3 0 8U BAND
Many file organizations cannot be described this way. For instance, files with more than one data type, or files with spaces between bands or byte swapped multi-byte data, cannot be described this way. In these cases, it is possible to describe the layout of each channel. The following description defines the same raw.dat files as in the previous two descriptions. For each channel a data type, image offset, and swapping capability is provided. 

 RAW:::raw.dat 512 512 3 *Channel 1 8U 0      1 512 unswapped
                         *Channel 2 8U 262144 1 512 unswapped
                         *Channel 3 8U 524288 1 512 unswapped
The offset is to the first byte of data in the channel, therefore channel two data starts at byte 262144 in the file. The second offset is from one pixel of data on the same scanline to the next pixel of data on the same scanline. The third offset is the offset from the beginning of one scanline to the beginning of the next. The swap flag indicates whether the data is in little endian order or not. Little endian byte order has the least significant byte of the word first, and is found on Intel and VAX machines. This is considered `swapped'. Big endian machines such as the Motorola and Sun are considered `unswapped'. The default is the native byte order of the current machine.

A more interesting example might be a 300x400 one-band file with little endian 16-bit unsigned data starting after a one block (512-byte) header. 

 RAW:::testi2.dat 300 400 1 *Channel 1 16U 512 2 1024 swapped
Parent Topic: Supported File Formats
About PCI Help Gateway