This document describes the output image files created by DIRSIG.

Format Overview

The output images generated by DIRSIG include both a binary image data file and an ASCII/Text "header" file that includes details about the binary image data file. This binary data and ASCII/Text header file pair follows the convention employed by the ENVI image exploitation software.

Note Although this image data/header file pair is commonly referred to as "ENVI format", the ASCII/Text header file is an excellent "cheat sheet" that can be used to read the binary image data into any tool.

The binary image data file is usually written to a file with a .img file extension (for example radiance.img). The ASCII/Text file is usually written to a file with a .img.hdr file extension (for example radiance.img.hdr).

Tip These data/header image file pairs can be loaded and displayed by the image viewer provided with DIRSIG, ENVI, Opticks and other commonly used image exploitation packages utilized by the remote sensing community.
Tip If you are a Matlab or Python user, several utilities exist that will simplify the reading of these data/header file pairs. Just search for "ENVI image reader" on your favorite search engine.

The Binary Data File

The output image is written to a binary data file. The format of the binary data is summarized below:

  • The data is written in the native endian (byte order) of the host machine.

  • There is no offset to the binary data (the first pixel starts at the first byte in the file).

  • The default data type is usually:

    • 64-bit double-precision floating-point radiance values (normal mode)

    • 64-bit double-precision floating-point truth values

    • 64-bit double-precision floating-point complex values (radar, DIRSIG4)

  • The pixel and band data is always organized as "band interleaved by pixel" (BIP).

The "band interleaved by pixel" (BIP) data order means a multi-band image file is written in the order:

     (X0, Y0, B0),     (X0, Y0, B1),     ... (X0, Y0, Bmax),
     (X1, Y0, B0),     (X1, Y0, B1),     ... (X1, Y0, Bmax),
     ...
     (Xmax, Y0, B0),   (Xmax, Y0, B1),   ... (Xmax, Y0, Bmax),
     (X0, Y1, B0),     (X0, Y1, B1),     ... (X0, Y1, Bmax),
     (X1, Y1, B0),     (X1, Y1, B1),     ... (X1, Y1, Bmax),
     ...
     (Xmax, Y1, B0),   (Xmax, Y1, B1),   ... (Xmax, Y1, Bmax),
     ...
     (Xmax, Ymax, B0), (Xmax, Ymax, B1), ... (Xmax, Ymax, Bmax),

where X is the X dimension (or "columns") in the image, Y is the Y dimension (or "rows") in the image and B is the Z dimension (or "bands") in the image.

The ASCII/Text Header File

Each binary image data file is accompanied by an ASCII/Text header file that describes the dimensionality of the binary image data. The format of this file follows the format used in the header files utilized by the ENVI image exploitation software (multiple resources for advanced features of this file can be found in the ENVI documentation). The file is composed of a series of "tag = value" assignments.

The official documentation for the ENVI header file is available here.

Minimal Header Tags

The following is a minimal set of tags written by DIRSIG and required by ENVI.

A minimal ENVI header file.
ENVI
bands = 1
byte order = 0
data type = 5
file type = Other
header offset = 0
interleave = bip
lines   = 128
samples = 128

The following is a brief description of these tags:

bands

The number of bands (Z dimension elements) in the image.

byte order

The byte order (endian) of the binary data. A value of 0 indicates Least Significant Byte First (LSF) or "little endian" data (Intel/AMD systems) and a value of 1 indicates Most Significant Byte First (MSF) or "big endian" data (all others including Sparc, UltraSparc, MIPS, etc.).

data type

This tag describes the data type user for each pixel/band value. The ENVI software supports nearly every pixel/band data size ranging from 8-bit integer to 64-bit, double-precision, float-point complex. By default, DIRSIG radiance and truth image pixels are written using 5 (64-bit double-precision, floating-point values).

  • 1 = 8-bit unsigned integer

  • 2 = 16-bit signed integer

  • 3 = 32-bit signed integer

  • 4 = 32-bit single-precision floating-point

  • 5 = 64-bit double-precision floating-point

  • 6 = 2 x 32-bit complex (real,imaginary) single-precision floating-point

  • 9 = 2 x 64-bit complex (real,imaginary) double-precision floating-point

  • 12 = 16-bit unsigned integer

  • 13 = 32-bit unsigned integer

  • 14 = 64-bit signed integer

  • 15 = 64-bit unsigned integer

file type

The "type" of file (used by ENVI for internal purposes).

header offset

The number bytes to skip in binary image data file before the pixel data begins. In DIRSIG image files, this value is usually 0.

interleave

This tag describes how the 3D image data cube is "unrolled" into the 1D data stream in the binary image data file. The ENVI software supports "band sequential" (BSQ), "band interleaved by line" (BIL) and "band interleaved by pixel" (BIP) interleaving. DIRSIG always writes data as "bip" or "band interleaved by pixel".

lines

The number of lines (Y dimension elements) in the image.

samples

The number of samples (X dimension elements) in the image.

Common Optional Header Tags

The following is a list of commonly used but optional tags:

  • The acquisition time tag contains when the image was acquired using the ISO-8601 format.

  • The description tag describing the image or the processing performed. DIRSIG sensor plugins typically populate this string with the version of DIRSIG and the sensor plugin that generated the image file.

  • The band names tag is a list of "names" for each band in the image file.

  • The fwhm tag contains a list of the "Full-Width at Half Max" values for each band in the file. The units for these values follow that provided to the wavelength units tag.

  • The geo points tag is a list of geographic corners (latitude and longitude) for non-georeferenced files.

  • The wavelength tag is a list of the centers for each band in the file.

  • The wavelength units tag describes the spectral units used for the wavelength tag.

DIRSIG Specific Header Tags

The following is a list of tags added by DIRSIG (primarily by the BasicPlatform sensor plugin) to assist in downstream processing:

  • The data units tag specifies what the radiometric units are of the data.

  • The integration time tag specifies what the integration time of the focal plane in seconds.

Example Single-Band Radiance Header

The following is an example of the header for a single-band radiance image. In addition to the minimal tags, the following optional tags are included:

An example ENVI header file produced by DIRSIG for a single-band image.
ENVI
description = {
  Image data generated by DIRSIG 2023.44 (ae0ff2f) 'BasicInstrument' plugin (SimpleCapture)}
samples = 128
lines   = 128
bands   = 1
header offset = 0
file type = Other
data type = 5
interleave = bip
byte order = 0
wavelength units = Micrometers
data units = watts/(cm^2 sr)
band names = {
    Pan Channel}
wavelength = {
    0.600}

Example Multi-Band Radiance Header

The following is a header file for a RGB (multi-band) image file. The bands tag is assigned a value of 3. The band names and wavelength tag lists indicate which bands are the red, green and blue.

An example ENVI header file produced by DIRSIG for a multi-band image.
ENVI
description = {
  Image data generated by DIRSIG 2023.44 (ae0ff2f) 'BasicInstrument' plugin (SimpleCapture)}
samples = 128
lines   = 128
bands   = 3
header offset = 0
file type = Other
data type = 5
interleave = bip
byte order = 0
wavelength units = Micrometers
data units = watts/(cm^2 sr)
band names = {
    Red Channel,
    Green Channel,
    Blue Channel}
wavelength = {
    0.65,
    0.55,
    0.45}

Example Spectral Radiance Header

The following header file was created from a 32-channel spectrometer. The channels are evenly spaced on 0.010 micron (10 nanometer) centers with 0.010 micron (10 nanometer) widths.

An example ENVI header file produced by DIRSIG for a hyperspectral image.
ENVI
description = {
  Image data generated by DIRSIG 2023.44 (ae0ff2f) 'BasicInstrument' plugin (SimpleCapture)}
samples = 256
lines   = 256
bands   = 32
header offset = 0
file type = Other
data type = 5
interleave = bip
byte order = 0
wavelength units = Micrometers
data units = watts/(cm^2 sr um)
band names = {
    Channel #1,
    Channel #2,
    ...
    [lines deleted for documentation purpose]
    ...
    Channel #32}
wavelength = {
    0.4,
    0.41,
    ...
    [lines deleted for documentation purpose]
    ...
    0.71}
fwhm = {
    0.01,
    0.01,
    ...
    [lines deleted for documentation purpose]
    ...
    0.01}

Example Truth Image Header

DIRSIG also uses this binary data and text header image pair system to generate truth images. In these application, each "band" in the image file contains a unique piece of data. For example, the material ID of the most frequently hit material within a pixel. Or the Scene ENU coordinate of each pixel (stored in 3-bands, one each for the X, Y and Z values). The example below shows how similar these files are to the radiance image files. The only notable change is that the bands tag indicates the number of different truth "values" available in each pixel and the band names indicate what truth value is stored in that "band".

An example ENVI header file produced by DIRSIG containing raster truth data.
ENVI
description = {
  Truth data generated by DIRSIG 2023.44 (ae0ff2f) 'BasicPlatform' plugin}
samples = 256
lines   = 256
bands   = 9
header offset = 0
file type = Other
data type = 5
interleave = bip
byte order = 0
band names = {
  Dominant Material Index,Dominant Optical Property Index,X Hit Coordinate [m],Y Hit Coordinate [m],Z Hit Coordinate [m],Distance [m],View Angle Cosine [],U Texture Coordinate [],V Texture Coordinate []}