TMSB XML Schema Part 1: Overview

article by Ben Lincoln

This set of articles is intended for advanced users of The Mirror's Surface Breaks who want to modify the existing configurations, or create their own from scratch. A basic understanding of XML is assumed.

This first article describes conventions shared among all of the filetypes (as well as this documentation), and also the metadata "wrapper" which is present in all of the file types.

Common Features

The TMSB XML format includes a nonstandard <Import> tag. The reason for its use (as opposed to the standard mechanism) is that TMSB uses the following path search order for configuration files (including XML fragments referenced by this <Import> tag):

If the file path is specified using an absolute path, then that absolute path is used. Otherwise:

An attempt is made to locate a file with the relative path from TMSB_Config under the user's home directory (Documents / My Documents on Windows systems). If a match is found, that file is used.
If a match was not found, an attempt is made to locate a file with the relative path from TMSB_Config under the application directory (wherever TMSB.EXE or TMSBGUI.EXE is located). If a match is found, that file is used. Otherwise, the file is treated as not existing.

This allows users without administrative rights to override the "factory settings" by creating XML files in their own directory with the same names as the ones in the application directory, or for users on shared systems to customize settings without "stepping on the toes" of other users of that same system.

Processing of the <Import> tag occurs before the data is handed off to the .NET XML parser, so to .NET, it appears as if one monolithic XML file is being loaded. When the Export XML button in the GUI is used, it is that monolithic representation that is exported.

Using a standard import mechanism would make this behaviour extremely difficult to implement. In addition, the pre-handoff processing strips comments, because it would be extremely frustrating to have to determine if comments were nested (which violates the XML specification) across multiple files. No comment present in a TMSB XML file will make it as far as the .NET XML parsing engine.

The examples used in the XML documentation assume the monolithic representation.

Conventions

The following colour-coding is used throughout all of the articles on the TMSB XML schema:

Green text, blue text, and cyan text indicate blocks of code that must occur a maximum of one time. Unless otherwise indicated in the Notes section, they must be included.

Red text, yellow text, and magenta text indicate blocks of code that may occur multiple times. If there is a limit on the number of occurrences, or the code must occur at least once, it will be indicated in the Notes section.

Three colours are available for both types of text to (hopefully) provide clarity about where one block begins and another ends.

Whether a block can occur multiple times or not is indicated by the "parent node" of that block. For example, if a particular block can occur multiple times but a subsection of that block must occur only once within each instance of the block, the begin and end tags for that block will be coloured red, yellow, or magenta, but the tags for the subsection within it will be coloured green, blue, or cyan.

Grey text indicates a user-specified (or application-generated) value. For values which must be selected from a list, that list is defined in the Notes section.

If this is confusing, there are plenty of examples included with TMSB for you to look at.

Schema

<?xml version="1.0" encoding="utf-16" ?>

<TMSB>

The file type (see below)

</FileType>

1.0

</GeneratingVersion>

</ApplicationData>

<Name>

A short, descriptive name for the input configuration

</Name>

A detailed description of the input file to display to the user

</Description>

Cautionary text to display to the user

</Warnings>

The author's name

</Author>

The creation date (UTC) in XML dateTime format

</Created>

The modification date (UTC) in XML dateTime format

</LastModified>

</MetaData>

The type-specific XML code (see the articles for each type)

</TMSB>

Notes

The encoding parameter of the xml tag must always be utf-16, and the file must actually be encoded as UTF-16 (not ASCII/ANSI). It is very likely that the encoding must be little-endian UTF-16 specifically, but I don't have access to a big-endian system to test that theory on.^[1]

FileType may be one of the following values:

Input Configuration
Output Configuration
Colour Configuration
Processing Configuration
Transformation Profile List
Execution Options

GeneratingVersion should always be specified as 1.0 at this time.

Warnings is an optional field used to indicate information that is important for the user to consider. For example, if using the configuration file in question will result in an unusually large number of output files.

Example

<?xml version="1.0" encoding="utf-16" ?>

<TMSB>

Input Configuration

</FileType>

1.0

</GeneratingVersion>

</ApplicationData>

<Name>

NIR-R-G-B-UVA (TIFF - 3 Files)

</Name>

This input configuration uses up to five spectral bands (near-infrared, red, green, blue, and ultraviolet-A) in TIFF format.

The red, green, and blue bands should be contained in a single three-channel file ("RGB.TIF"), with the remaining bands in separate three-channel greyscale files ("NIR.TIF" and "UVA.TIF").

</Description>

Ben Lincoln

</Author>

2010-10-13T00:00:00

</Created>

2011-02-06T22:54:57.2379202Z

</LastModified>

</MetaData>

The type-specific XML code (see the articles for each type)

</TMSB>

Footnotes

The reason UTF-16 is forced is because it would have been very difficult (due to the way XML files are processed by TMSB, which is itself a consequence of the specific behaviour of the .NET Framework) to allow multiple encodings, and I wanted to ensure that international characters could be supported without additional hassle.