TMSB XML Schema Part 2: Input Configuration

article by Ben Lincoln

Input configuration files control which files TMSB looks for in each input directory, and if they are present, how to treat them at a basic level. If one or more files are missing, processing proceeds without them, unless the total number of bands found in the directory is less than the minimum configured in the application (3 by default).

Note: the FileType value in the metadata section of the file must be Input Configuration.

Schema

A short string to reference the band by (see notes below)

</BandName>

The name of the file (without a directory name/path) which contains the greyscale image for the band

</FileName>

<Plane>

The plane/channel in the file which contains the image

</Plane>

</DataSource>

</DataSources>

A band category (see below)

</BandCategory>

The special band name (see below) if there is one

</SpecialBandName>

A boolean (true/false) value

</UseAsLuminanceChannel>

A boolean (true/false) value

</UseAsThreeChannelChannel>

The name of a band which should not be used in any of the same images as this band.

</MutuallyExclusiveBand>

The name of a transformation profile to apply to this image before it is used in any other way.

</InputTransformation>

</SpectralBand>

</SpectralBands>

</InputConfig>

Notes

The SpectralBand blocks should be specified in order from longest-wavelength to shortest, because that is how TMSB determines that order for generating permutations. For example, if your source data includes far infrared, near infrared, and blue data, the XML should define them in that order. For source images which do not actually have a wavelength (e.g. elevation), include them before or after the actual spectral bands depending on your preference for their frequency of use in permutations.

BandName will be used in output filenames, as well as if the band is referenced by name in other configuration files, so I highly recommend using something short.

DataSource must be specified at least once for each spectral band. Its only use at present is to specify a second image which is to be used instead of the first when the band is used as the luminance channel in luminance/colour images (see Luminance/Colour Images. Specifying more than two will have no effect in the current version of TMSB. If the second source is specified, but only the first file is present in a given input directory, then the first file will be used for both purposes.

FileName should never contain directory/path information. It is always relative to the working directory where the raw image files are located. The following file formats are supported, with the file type being automatically determined based on the content:

PNG (8-bit-per-channel and 16-bit-per-channel)
TIFF (8-bit-per-channel, 16-bit-per-channel, and 32-bit-per-channel)
JPEG (8-bit-per-channel)

Plane is the numeric plane/channel number in an image file which contains the greyscale image data to be used for the spectral band. If the file has only one channel (IE it is a greyscale file), this should be 1. If, for example, the file is a red/green/blue image, and the spectral band is located in the blue channel, the value would be 3.

BandCategory is an optional value which may be one of the following strings, and may be specified multiple times for a single spectral band (although there is little reason to specify multiple values at this time). The main use of this value at this time is in defining custom greyscale channels (see TMSB XML Schema Part 4: Processing Configuration).

Radio
Microwave
FarInfrared
MidInfrared
NearInfrared
HumanVisible
Ultraviolet
XRay
GammaRay

SpecialBandName is optional, and may be any one of the following values. This value is used by processing configuration entries such as the vegetation indices (see Calculated Greyscale Images and Gradient-Mapped False Colour Images). For example, the NDVI formula references the bands assigned the "special names" NearInfraredNonspecific and Red, regardless of filename or the name assigned to the band ("R", "Red", "650nm", et cetera). This is so that TMSB can apply the same processing configuration to multiple different input configurations (e.g. photography versus satellite imagery), as long as they both contain the required type of image data.

RadioELF
RadioSLF
RadioULF
RadioVLF
RadioLF
RadioMF
RadioHF
RadioVHF
RadioUHF
RadioSHF
RadioEHF
RadioNonSpecific
Radar
MicrowavePBand
MicrowaveLBand
MicrowaveSBand
MicrowaveCBand
MicrowaveXBand
MicrowaveKBand
MicrowaveQBand
MicrowaveVBand
MicrowaveWBand
MicrowaveNonspecific
Terahertz
ThermalInfrared
FarInfraredNonspecific
MidInfrared2220nm
MidInfrared1625nm
MidInfraredNonspecific
NearInfrared700nm
NearInfrared825nm
NearInfrared950nm
NearInfraredNonspecific
Red
Orange
Yellow
Green
Blue
Violet
UltravioletA
UltravioletB
UltravioletC
ExtremeUltraviolet
SoftXRay
HardXRay
GammaRay
Elevation
Sonar
Proton
Neutron
Electron
Neutrino
Quark
UserDefined1
UserDefined2
UserDefined3
UserDefined4
UserDefined5
UserDefined6
UserDefined7
UserDefined8
UserDefined9

(I have realized that both of these lists would be best defined in a configuration file instead of the source code, and plan to include that change in a future release).

UseAsLuminanceChannel is either true or false, and controls whether this band will be used as the luminance channel in luminance/colour images (assuming the processing configuration includes that type of variation).

UseAsThreeChannelChannel is either true or false, and controls whether this band will be used as one of the three channels in three-channel false colour images (assuming the processing configuration includes that type of variation).

For example, if I would like to use an elevation map as a luminance channel, but not as the red/green/blue channel in three-channel false colour images, I would set its UseAsLuminanceChannel value to true, but its UseAsThreeChannelChannel value to false

Note that setting UseAsThreeChannelChannel to false also prevents the band from being used in calculated channels.

MutuallyExclusiveBand is an optional value which can occur multiple times. It indicates that the band being defined must never be used in combination with the other named band. For example, the OnEarth input configuration uses this to prevent the "ThL" and "ThH" (low- and high-gain thermal imagery) from being used together, because those data sets are identical except that one has had its values boosted by a fixed amount.

InputTransformation is an optional value which can occur multiple times. This is a reference (by name) to one of the transformation profiles defined in the global transformation configuration file (see TMSB XML Schema Part 6: Transformation Profiles for a discussion of this file). For example, if the value Normalize: Standard is used here, then the image will be normalized using the settings in the transformation profile of that name before being used for any other purpose. The OnEarth input configuration file makes use of this feature as well.

If multiple InputTransformation blocks are present, they are applied in the order they appear in the input configuration file.

Example

This configuration defines five input spectral bands (near infrared, red, green, blue, and ultraviolet-A). All five will be used in three-channel false colour images, but only near infrared and ultraviolet-A will be used as the luminance channel in luminance/colour images. All five are also assigned their corresponding "special band names", so that processing configurations which include e.g. NDVI-style calculated images will make use of them. In the specific case of the photography-related processing configurations, assigning the "special band" names for near infrared and ultraviolet-A also ensures that the tinted greyscale versions of those bands will be generated as output images.

The use of the names "NIR", "R", "G", "B", and "UVA" ensures that e.g. a three-channel false colour image made up of the near infrared, red, and blue bands will be named "FC-3C-NIR-R-B". If the names "NearInfrared", "Red", "Green", "Blue", and "Ultraviolet-A" had been used instead, such an output image would be named e.g. "FC-3C-NearInfrared-Red-Blue".

In all five cases, secondary filenames are specified, so that an "optimized for use as the luminance channel" variation of each band can be used.

NIR

</BandName>

NIR.TIF

</FileName>

<Plane>

</Plane>

</DataSource>

NIR2.TIF

</FileName>

<Plane>

</Plane>

</DataSource>

</DataSources>

NearInfrared

</BandCategory>

NearInfraredNonspecific

</SpecialBandName>

true

</UseAsLuminanceChannel>

true

</UseAsThreeChannelChannel>

</SpectralBand>

</BandName>

RGB.TIF

</FileName>

<Plane>

</Plane>

</DataSource>

RGB2.TIF

</FileName>

<Plane>

</Plane>

</DataSource>

</DataSources>

HumanVisible

</BandCategory>

Red

</SpecialBandName>

false

</UseAsLuminanceChannel>

true

</UseAsThreeChannelChannel>

</SpectralBand>

</BandName>

RGB.TIF

</FileName>

<Plane>

</Plane>

</DataSource>

RGB2.TIF

</FileName>

<Plane>

</Plane>

</DataSource>

</DataSources>

HumanVisible

</BandCategory>

Green

</SpecialBandName>

false

</UseAsLuminanceChannel>

true

</UseAsThreeChannelChannel>

</SpectralBand>

</BandName>

RGB.TIF

</FileName>

<Plane>

</Plane>

</DataSource>

RGB2.TIF

</FileName>

<Plane>

</Plane>

</DataSource>

</DataSources>

HumanVisible

</BandCategory>

Blue

</SpecialBandName>

false

</UseAsLuminanceChannel>

true

</UseAsThreeChannelChannel>

</SpectralBand>

UVA

</BandName>

UVA.TIF

</FileName>

<Plane>

</Plane>

</DataSource>

UVA2.TIF

</FileName>

<Plane>

</Plane>

</DataSource>

</DataSources>

Ultraviolet

</BandCategory>

UltravioletA

</SpecialBandName>

true

</UseAsLuminanceChannel>

true

</UseAsThreeChannelChannel>

</SpectralBand>

</SpectralBands>

</InputConfig>