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 define and store information about raw files (other than the image data itself). In previous releases of GDB, GDB also used this .aux file to store metadata. CATALYST Professional now uses a .pox file to store metadata. It has an advantage of having an extra extension rather than a replacement extension. In the example below, there can be test.001.pox and test.002.pox. A pox file is a special type of PCIDSK file. In addition to metadata, it stores any non-native overviews for the file. The metadata can be accessed and viewed as the text segment of the .pox file.

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 GDB 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 file names 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".