This tool is used to generate, manipulate and interact with DIRSIG emissivity files.

General usage message.
$ ems_tool -h
Usage: ems_tool [options] <command> ...

Options:
  -h/--help
	Display this help and exit.
  --log_level string
	Sets the minimum logging level. Values are: debug, info, warning, error, critical, off

Commands:
  generate
  export
  expand

For subcommand help: ems_tool <command> -h

The Export Tool

The export tool strips some of the formatting from the input file and writes a two-column, ASCII/Text file that can be easily plotted in Gnuplot (or any other plotting package) to visualize it. The format of the exported data is:

  • Two column (wavelength and value), one pair per line, tab-separated.

  • At the start of each curve is a "comment" line (e.g., # Curve #2).

    • Gnuplot ignores lines that begin with #.

  • After each curve is an empty line

    • Gnuplot will break a plot line when it encounters an empty line.

Usage for the export tool.
$ ems_tool export -h
Usage: ems_tool ... export [options] input_filename

Positional Arguments:
  input_filename (required!)
	The input DIRSIG emissivity file to export.

Options:
  -h/--help
	Display this help and exit.
  -o/--output string
	The ASCII/Text output file containing the exported data.
  --as_reflectance
	The output file will contain reflectance rather than emissivity data.

Example Usage

Exporting the emissivity data to a simple ASCII/Text file.
$ ems_tool export --output_filename=example.txt example.ems

If you want to convert the data from emissivity to reflectance during the export, you can add the (optional) --as_reflectance option:

Exporting the emissivity data as reflectance a simple ASCII/Text file.
$ ems_tool export --as_reflectance --output_filename=example.txt example.ems

And this file can be easily plotted in GNUplot with the following command:

Plotting the simple ASCII/Text file.
gnuplot> plot "example.txt" using 1:2 with lines
Tip If you want to export an emissivity file to a an ENVI Spectral Library file, use the "convert" tool in the sli_tool utility.

The Expand Tool

The expand tool is used to take a small emissivity database file (limited number of curves) and generate a new file that contains many curves. The input is an existing DIRSIG emissivity file and the number of curves to generate.

Usage for the expand tool.
$ ems_tool expand -h
Usage: ems_tool ... expand [options] input_filename output_filename

Positional Arguments:
  input_filename (required!)
	The input DIRSIG emissivity file to expand.
  output_filename (required!)
	The output DIRSIG emissivity file containing the expanded curve set.

Options:
  -h/--help
	Display this help and exit.
  -c/--curve_count uint
	The number of curves to generate in the output file.

Example Usage

Generating a 100 curve emissivity file using another emissivity file as input.
$ ems_tool --log_level=debug expand --curve_count=100 --output_filename=out.ems in.ems
[debug] ExpandTool
[debug] Reading emissivity file 'in.ems'
[debug]   File contains 6 curve(s)
[debug] Computing multivariate stats for curve set
[debug]   Computing the mean vector
[debug]   Computing the covariance matrix
[debug] Computing the eigen values
[debug] Checking if eigen matrix is singular
[debug] Computing the inverse eigen matrix
[debug] Generating 100 new curves
[debug]   Generating curve #0
[debug]   Generating curve #1
...
[debug]   Generating curve #99
[debug] Writing emissivity file 'out.ems'

Important Notes:

  • The input emissivity file should contain data for a single material, represented by a uni-modal distribution.

  • The input emissivity file should contain enough curves to capture the spectral mean, variance and covariance of the material.

The Generate Tool

The generate tool is similar to the expand tool except that is takes a binary ENVI statistics file as the primary input to generate a new multi-curve database.

Usage for the generate tool.
$ ems_tool generate -h
Usage: ems_tool ... generate [options] input_filename output_filename

Positional Arguments:
  input_filename (required!)
	The input ENVI statistics file (.sta) used to generate the curve set.
  output_filename (required!)
	The output DIRSIG emissivity file containing the generated curve set.

Options:
  -h/--help
	Display this help and exit.
  -c/--curve_count uint
	The number of curves to generate in the output file.

Example Usage

Generating a 100 curve emissivity file using an ENVI statistics file as input.
$ ems_tool --log_level=debug generate --sta_filename=grass.sta --curve_count=100 --output_filename=grass.ems
[debug] GenerateTool
[debug] Reading ENVI statistics file 'grass.sta'
[debug]   ID = 1313426753 (new format, non-native endian)
[debug]   sampleCount = 1688
[debug]   lineCount   = 2034
[debug]   bandCount   = 272
[debug]   dataType    = 4
[debug]   ROI index   = -1
[debug]   ROI Box     = [273,529] -> [1473,2007]
[debug]   ROI name    = '[/Users/dirsig//raw_9088_rd_rf_or]^[]^[b]'
[debug]   File contains 272 wavelength(s)
[debug]   Wavelengths scalar = 0.001
[debug] Extracting spectral mean data
[debug] Extracting spectral covariance data
[debug] Computing the eigen values
[debug] Checking if eigen matrix is singular
[debug] Computing the inverse eigen matrix
[debug] Generating 10 new curves
[debug]   Generating curve #0
[debug]   Generating curve #1
[debug]   Generating curve #2
...
[debug]   Generating curve #99
[debug] Writing emissivity file 'grass.ems'

Important Notes:

  • The input statistics file should contain data for a single material, represented by a uni-modal distribution.

Spectral Curve Generation

The spectral curve generation algorithm is based on starting with the statistics of a single land cover class that is assumed to be well defined by a uni-modal, spectral distribution. Using the spectral mean and covariance for that class, the corresponding eigen matrix can be used to transform the statistics into a spectrally non-correlated space. Conversely, randomly distributed (non-correlated) values that are back transformed through the inverse of that eigen matrix will be spectrally correlated. Hence, a method to synthesize spectral curves with a defined mean, variance and covariance is possible. The details of this method are described below.

The spectral statistics of a land cover class is expected to be a uni-modal distribution characterized by:

\[\vec{\mu}^t = \left[ \begin{array}{*{4}{c}} \mu_o & \mu_1 & \cdots & \mu_n \end{array} \right]\]
\[\vec{\Sigma} = \left[ \begin{array}{*{4}{c}} \sigma_{0,0} & \sigma_{0,1} & \cdots & \sigma_{0,n} \\ \sigma_{1,0} & \sigma_{1,1} & \cdots & \sigma_{1,n} \\ \vdots & \vdots & \ddots & \vdots \\ \sigma_{n,0} & \sigma_{n,1} & \cdots & \sigma_{n,n} \end{array} \right]\]

where \$\vec{\mu}\$ and \$\vec{\Sigma}\$ are the respective mean and covariance of an individual class.

One can compute the eigenvalues and eigenvectors for the covariance matrix, \$\vec{\Sigma}\$ to obtain the following:

\[\vec{\lambda}^t = \left[ \begin{array}{*{4}{c}} \lambda_o & \lambda_1 & \cdots & \lambda_n \end{array} \right]\]
\[\vec{e} = \left[ \begin{array}{*{4}{c}} e_{0,0} & e_{0,1} & \cdots & e_{0,n} \\ e_{1,0} & e_{1,1} & \cdots & e_{1,n} \\ \vdots & \vdots & \ddots & \vdots \\ e_{n,0} & e_{n,1} & \cdots & e_{n,n} \end{array} \right]\]

where \$\lambda_{0} \ge \lambda_{1} \ge \cdots \ge \lambda_{n} \ge 0\$ and the columns of \$\vec{e}\$ contain the normalized eigenvectors corresponding to the eigenvalues, \$\vec{\lambda}\$, for that land cover class.

We know that if the zero-centered original data was transformed via its eigenvector matrix, \$\vec{e}\$, as:

\[\vec{Y} = \vec{e^t} \left( \vec{X} - \vec{\mu} \right)\]

where

\[\vec{X} = \left[ \begin{array}{*{4}{c}} x_o & x_1 & \cdots & x_n \end{array} \right]\]

are the original spectral curves, one would obtain a data set, \$\vec{Y}\$, which was spectrally non-correlated. This non-correlated data set would be distributed \$N_n \left( \vec{\mu}, \vec{\Lambda} \right)\$ where the covariance matrix, \$\vec{\Lambda}\$, has the form:

\[\vec{\Lambda} = \vec{e^t}~\vec{\Sigma}~\vec{e} = \left[ \begin{array}{*{4}{c}} \lambda_0 & 0 & \cdots & 0 \\ 0 & \lambda_1 & \cdots & 0 \\ \vdots & \vdots & \ddots & \vdots \\ 0 & 0 & \cdots & \lambda_n \end{array} \right]\]

This non-correlated covariance matrix is used to generate multivariate random variables distributed as \$N_n \left( \vec{\mu}, \vec{\Sigma} \right)\$. To do this, we generate a set of Gaussian-distributed random numbers, \$y_i\$, distributed as \$N_n \left( 0, \lambda_{i} \right)\$ for \$(i = 0, 1, \cdots, n)\$ to form the vector:

\[\hat{\vec{Y}} = \left[ \begin{array}{*{4}{c}} y_o & y_1 & \cdots & y_n \end{array} \right]\]

This vector is then back transformed through the inverse of eigen transform as:

\[\hat{\vec{X}} = \left( \vec{e} \right)^{-1} \hat{\vec{Y}} + \vec{\mu}\]

to yield a multivariate random variable distributed as which could be used to represent a reflectance curve from a population with these multivariate statistics (note that any negative values are truncated to zero).

The expand and generate tools use this general method to generate large curve sets. In the case of the expand tool, the spectral mean and covariance is computed from the input curve set. In the case of the generate tool, the spectral mean and covariance from the input ENVI statistics file is used directly.

Important The input curve database must be suitably diverse for this synthesis algorithm to work. In some cases, the inputs will result in an eigen matrix that cannot be inverted (usually indicating that the inputs are too correlated) and the algorithm will fail.