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.
![]() |
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
).
![]() |
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. |
![]() |
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 of1
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 thewavelength
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 thewavelength 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).
![]() |
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.
-
![]() |
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)
![]() |
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.
|