This document describes the output image files created by DIRSIG. These image files are created by the following components:

  • The Raw and Basic capture methods (normal mode)

  • The Raw and Basic capture methods (preview mode)

  • Truth image collections (normal and preview modes)

Format Details

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.

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 data type is one of the following:

    • 32-bit signed integer values (preview mode)

    • 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)

  • The pixel and band data is 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.

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 "variable = value" assignments.

Minimal Header File

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

ENVI
description = {
    Generated by DIRSIG 4.5.0 (r10171) using Simple capture method
    Image opened at simulation time: 2009-09-01T10:09:60.0000-05:00.}
samples = 128
lines   = 128
bands   = 1
header offset = 0
file type = Other
data type = 5
interleave = bip
sensor type = Unknown
byte order = 0

The following is a brief description of these variables:

samples

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

lines

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

bands

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

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.

file type

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

data type

This variable 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

interleave

This variable 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".

sensor type

The "sensor" used to collect the data (used by ENVI for internal purposes).

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.).

Example Single-Band Radiance Header

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

  • The band names variable is a list of "names" for each band in

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

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

ENVI
description = {
    Generated by DIRSIG 4.5.0 (r10171) using Simple capture method
    Image opened at simulation time: 2009-09-01T10:09:60.0000-05:00.}
samples = 128
lines   = 128
bands   = 1
header offset = 0
file type = Other
data type = 5
interleave = bip
sensor type = Unknown
byte order = 0
wavelength units = Microns
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 variable is assigned a value of 3. The band names and wavelength variable lists indicate which bands are the red, green and blue.

ENVI
description = {
    Generated by DIRSIG 4.5.0 (r10171) using Simple capture method
    Image opened at simulation time: 2009-09-01T10:09:60.0000-05:00.}
samples = 128
lines   = 128
bands   = 3
header offset = 0
file type = Other
data type = 5
interleave = bip
sensor type = Unknown
byte order = 0
wavelength units = Microns
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.

ENVI
description = {
    Generated by DIRSIG 4.4.1b (r7585) using Simple capture method
    Image opened at simulation time: 2008-04-01T10:00:01.0000-05:00.}
samples = 256
lines   = 256
bands   = 32
header offset = 0
file type = Other
data type = 5
interleave = bip
sensor type = Unknown
byte order = 0
wavelength units = Microns
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}

This file includes the following optional variables:

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

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" variable indicates the number of different truth "values" available in each pixel and the band names indicate what truth value is stored in that "band".

ENVI
description = {
    Truth image generated by DIRSIG}
samples = 256
lines   = 256
bands   = 27
header offset = 0
file type = Other
data type = 5
interleave = bip
sensor type = Unknown
byte order = 0
wavelength units = Microns
band names = {
    First Material (Top ID),
    First Material (Unique IDs),
    First Material (Top Fraction),
    ...
    [lines deleted for documentation purpose]
    ...
    Avg. X Hit Coordinate [m],
    Avg. Y Hit Coordinate [m],
    Avg. Z Hit Coordinate [m],
    ...
    [lines deleted for documentation purpose]
    ...
    Var. GSD [m]}

Radiometric Units

The units for the values in the output image files produced by DIRSIG vary depending on if the model was run in "preview mode" or "normal mode".

Preview Image Files

The "preview mode" images are used as a visualization aid and do not have radiometric units. The individual pixel value in a "preview mode" image is the material ID for the given pixel.

Radiance Image Files

Pixel values in output radiance image files produced during a "normal mode" simulation are currently "aperture reaching radiances". The exact radiometric units vary depending on how the user configured the "capture method" assigned to the focal plane array (FPA).

Note Even though the user defines the focal length, pixel pitches (sizes) and relative spectral and spatial responses, this information is used to project the focal plane array onto the aperture and the radiance values reflect the radiance at that point in the optical path.

Raw Capture Method

If the user configured the Raw Capture Method for a given focal plane, then the image radiance values are spectral radiances:

  • If the spectral bandpass was in wavenumbers, then the pixel units are Watts/(cm3 steradian)

  • If the spectral bandpass was in microns, then the pixel units are Watts/(cm2 steradian micron)

  • If the spectral bandpass was in nanometers, then the pixel units are Watts/(cm2 steradian nanometer)

Basic Capture Method

The radiance units for the file generated by the Basic Capture Method can be sorted into two groups:

  • Integrated radiances

    • The user selected the Output integrated radiance button (the default) on the Normalization tab for the respective channel.

  • Spectral radiances

    • The user selected the Output spectral radiance button on the Normalization tab for the respective channel.

Note The radiance normalization can be selected on a channel-by-channel basis. Therefore, it is possible for some bands in the image to have "integrated radiance" units and others to have "spectral radiance" units.
Integrated Radiance

If the user selected the Output integrated radiance option (the default), then the spectral dimension is integrated out and the resulting units are always Watts/(cm2 steradian). The units for these default flux (Watts) and area (cm2) units can now be overriden in the capture method options.

Spectral Radiance

If the user selected the Output spectral radiance option, then the integrated radiance is normalized by dividing by the integral of the spectral response. This introduces a "per spectral unit" term into the radiance:

  • If the spectral bandpass was in wavenumbers, then the pixel units are Watts/(cm3 steradian)

  • If the spectral bandpass was in microns, then the pixel units are Watts/(cm2 steradian micron)

  • If the spectral bandpass was in nanometers, then the pixel units are Watts/(cm2 steradian nanometer)

Important These defined units assume that the gain on the Amplification tab for a given channel is 1 (the default value). If the gain is changed, then the units change respectively. The user can employ the gain as a mechanism to change the output to desired units. For example, setting the gain to 10000 will change the output radiances from per cm2 to per m2.