TMSB Tutorial 4A: Basic XML File Customization

article by Ben Lincoln

Making basic changes to The Mirror's Surface Breaks configuration files should be easy, especially for anyone who has worked with XML files before. When I designed TMSB, I did my best to come up with XML schemas that were straightforward and easy to understand. I've worked fairly extensively with Apache Tomcat configurations, and (although I think Apache Tomcat is a fine piece of server software) I really used that as a model for how not to handle the XML schema design.

There are only two major quirks that I deliberately introduced:

XML files for TMSB must be in UTF-16 format.
A nonstandard <Import> tag is used to include the contents of other files ("fragments").

UTF-16 seemed like the most straightforward Unicode encoding when I was designing TMSB. I wanted to use Unicode so users who wrote in a foreign language could use their own characters instead of having to Romanize the text. I needed to pick a particular Unicode character set because interally, TMSB juggles data around and giving it the ability to handle multiple character sets would have been really complicated, and I just didn't feel like it was worth the hassle (and potential bugs related to that functionality).

Speaking of juggling the data around, this is mostly related to the <Import> tag. There are a couple of more-or-less standard ways of doing this in XML, but this was another area where it seemed like they were more trouble than they were worth. So when TMSB loads an XML file, before it hands it off to the .NET XML processor, it performs all of the work related to the <Import> tag (as well as stripping out any comments^[1]).

Getting Started

There are two ways to get yourself an XML file to begin your modifications on:

Make a copy (in Windows Explorer, et cetera) of one of the files in the TMSB_Config directory underneath wherever you unpacked TMSB to. For example, if you want to customize the "No Funny Business" processing configuration, you can just copy and paste the Process-NFB.xml file. The TMSB GUI shows the full path to the configuration file selected on each tab. This is less than ideal for users who are new to customizing the files, because if the file in question makes use of the Import tag (which most of the included configuration files do), most of the content they're interested in will be located somewhere else.
In the TMSB GUI, select the configuration you want to customize, then click the Export XML button to the right of the drop-down. This will prompt for a location to save the file in, and the file that's saved will have all of the Import references resolved already (IE it will contain all of the content).

Either way, the best location (in most cases) to copy the file to is the TMSB_Config directory located underneath your own user profile directory (for example, C:\Users\blincoln\Documents\TMSB_Config on Windows 7) - not the TMSB_Config directory underneath where TMSB itself is located. There are a couple of reasons this is (generally) the preferred approach:

It is compliant with shared/multi-user systems design. You are not "stepping on the toes" of anyone else who happens to use TMSB on the same computer.
It doesn't require administrative access to the PC.
Your custom files are preserved from being overwritten if you install an updated version of TMSB which includes file(s) with the same name(s).

The one exception to this recommendation is on the off chance that you are maintaining a TMSB installation on a multi-user system, and want to make a custom configuration available for everyone that uses it. In that case, go right ahead and put them in the TMSB_Config directory underneath the TMSB installation directory.

When you create the copy, be sure to give it a distinctive filename, and don't put "Fragment" at the beginning of that name. When populating the drop-down menus, TMSB ignores any file whose name started with "Fragment", because the assumption is that those are incomplete files referenced by others.

Once you've created the copied file, you can customize it to your heart's content, as long as you use a text editor that is capable of handling UTF-16-encoded text files (for example, Notepad.exe, at least on newer versions of Windows).

Like all of the tutorial configuration files, complete (and tested) versions of the results below are included in the Tutorial subdirectory of TMSB_Config wherever you unpacked the software to (TMSB version 1.2 or later). These can be used to refer to if you run into trouble, or you can just copy them into your TMSB_Config directory if you would rather just use them instead of know how to create custom configurations.

Example 1: Ratio-Only Calculated Images Configuration

Let's start with an easy example: creating a custom "calculated images" processing configuration that only produces variations based on the ratio of each channel to every other channel.

In the TMSB GUI, switch to the Processing Configuration tab.
In the drop-down menu, select Focused: Calculated Images. This is the configuration to start with, because it generates ratio-based variations (as well as difference, and normalized difference).
Click the Export XML button.
In the File name field, enter Process-Focused-Calculated_Images-Ratio_Only.xml. Before you click Save, make a note of the directory the file is being saved in (e.g. C:\Users\blincoln\Documents\TMSB_Config). After you've made a note, click Save.
Launch the UTF-16-supporting text editor of your choice, and in that editor, open the file you just saved.
Near the beginning of the file, you should see the <Metadata> and </Metadata> blocks which define the portion of the configuration file related to what it is and who made it (among other things) as opposed to the actual configuration. Every type of TMSB configuration file has one of these.
In the <Name> section, change the text to read Focused: Calculated Images - Ratio Only. It's important to pick a name that's not already in use by another TMSB file of the same type, because this is the name that's displayed in the drop-down menu.
In the <Description> section, change the text to read Generates ratio variations, as well as three-channel false colour based on those variations. (or whatever you think is appropriate).
If you like, replace my name in the <Author> section with your own.
If you like, enter the date/time, in XML format in the <Created> and/or <LastModified> sections.
Scroll down until you see (or search for) the <CalculatedChannelSets> tag.
Unsurprisingly, the next line down should contain the first <CalculatedChannelSet> tag, which defines the beginning of an individual calculated channel set definition (in this case, the one that generates the Ratio output, which is the only one we want to keep in this example). Keep going until you find the corresponding </CalculatedChannelSet> tag, which delineates the end of the Ratio block.
The next line after that should contain another <CalculatedChannelSet> tag - this one for the Difference combination method. Make a note of where this line is - it's the first line you'll be deleting.
Keep scrolling down in the file until you locate the last </CalculatedChannelSet> tag (the one that marks the end of the ND_(Neg) block). This is the last line you'll be deleting. Click and drag to select everything between the line you found in the previous step and this line (including the beginning and ending lines themselves) and delete them. Important: make sure not to delete the </CalculatedChannelSets> tag after the last </CalculatedChannelSet> tag (the one that marks the end of the entire block of calculated channel sets), or TMSB won't read your file correctly.
Save the file and exit.
If you closed out of TMSB previously, launch the GUI again. Otherwise, from the Tools menu, select Reload Configuration Files. In the Processing Configuration tab, the drop-down should now contain a new entry (named Focused: Calculated Images - Ratio Only, if you followed all of the instructions correctly).
If you like, give the new configuration a try.

Example 2: Making an R72-Only Filter Emulation Configuration

Let's say that you like the "Classic R72" false colour image generated by the Focused: Filter Emulation processing configuration, but don't like any of the others that it produces. To create a custom processing configuration that only generates that one result, you will need to customize two sub-sections of that configuration.

In the TMSB GUI, switch to the Processing Configuration tab.
In the drop-down menu, select Focused: Filter Emulation.
Click the Export XML button.
In the File name field, enter Process-Custom-R72_Emulation.xml, then click Save.
Launch your text editor and open the file you just saved.
In the <Metadata> section:
1. In the <Name> section, change the text to read Custom: Classic R72 Filter Emulation.
2. In the <Description> section, change the text to read Generates the "Classic R72" variation that is based on sample images from an Olympus C-2020Z provided by Steve Smeed. (or whatever you think is appropriate).
3. If you like, enter the date/time, in XML format in the <Created> and/or <LastModified> sections.
Scroll down to the the <CustomGreyscaleChannels> section. This is where the three greyscale channels (red, green, and blue) that make up the final colour image are defined. Conveniently, the three needed for the "Classic R72" variation are the first in the list (Custom-R72_Classic-Red, Custom-R72_Classic-Green, and Custom-R72_Classic-Blue).
Delete all of the other <CustomGreyscaleChannel> blocks in this section, leaving only the three entire blocks mentioned in the previous step. That is, when you are done, your <CustomGreyscaleChannels> block should look like this:

<CustomGreyscaleChannels>

<CustomGreyscaleChannel>

<ChannelName>

Custom-R72_Classic-Red

</ChannelName>

<Type>

CustomScriptCode

</Type>

<CustomScriptCode>

= (pow((((%SpecialBand:NearInfraredNonspecific% * 0.8) + (%SpecialBand:Red% * 0.2))), 0.65) - 0.10) * 1.30

</CustomScriptCode>

<UseAsLuminanceChannel>

false

</UseAsLuminanceChannel>

<UseAsThreeChannelChannel>

false

</UseAsThreeChannelChannel>

<OutputTransformation>

Clip: 0.0 - 1.0

</OutputTransformation>

</CustomGreyscaleChannel>

<CustomGreyscaleChannel>

<ChannelName>

Custom-R72_Classic-Green

</ChannelName>

<Type>

CustomScriptCode

</Type>

<CustomScriptCode>

= pow(((%SpecialBand:NearInfraredNonspecific% - 0.06) / 1.02), 0.97)

</CustomScriptCode>

<UseAsLuminanceChannel>

false

</UseAsLuminanceChannel>

<UseAsThreeChannelChannel>

false

</UseAsThreeChannelChannel>

<OutputTransformation>

Clip: 0.0 - 1.0

</OutputTransformation>

</CustomGreyscaleChannel>

<CustomGreyscaleChannel>

<ChannelName>

Custom-R72_Classic-Blue

</ChannelName>

<Type>

CustomScriptCode

</Type>

<CustomScriptCode>

= pow(((%SpecialBand:NearInfraredNonspecific% - 0.01) / 0.91), 0.87) - 0.04

</CustomScriptCode>

<UseAsLuminanceChannel>

false

</UseAsLuminanceChannel>

<UseAsThreeChannelChannel>

false

</UseAsThreeChannelChannel>

<OutputTransformation>

Clip: 0.0 - 1.0

</OutputTransformation>

</CustomGreyscaleChannel>

</CustomGreyscaleChannels>
Not far beyond the end of the giant text block you just deleted, you should see the beginning of the <CustomThreeChannelImages> block. This is where the custom greyscale channels defined in the previous block are combined into colour images.
Again, notice that the first <CustomThreeChannelImage> block defines the one that you want to keep (for purposes of this example) - the FC-3C-Custom-R72_Classic image. Leave that block alone, but delete all of the other <CustomThreeChannelImage> blocks. That is, your <CustomThreeChannelImages> block should look like this:

<CustomThreeChannelImages>

<CustomThreeChannelImage>

<UserDefinedName>

FC-3C-Custom-R72_Classic

</UserDefinedName>

<RedChannelName>

Custom-R72_Classic-Red

</RedChannelName>

<GreenChannelName>

Custom-R72_Classic-Green

</GreenChannelName>

<BlueChannelName>

Custom-R72_Classic-Blue

</BlueChannelName>

<IncludeInSecondOrderImages>

true

</IncludeInSecondOrderImages>

<OutputTransformation>

Normalize: Standard

</OutputTransformation>

</CustomThreeChannelImage>

</CustomThreeChannelImages>
Save the file and exit.
If you closed out of TMSB previously, launch the GUI again. Otherwise, from the Tools menu, select Reload Configuration Files. In the Processing Configuration tab, the drop-down should now contain a new entry (named Focused: Calculated Images - Ratio Only, if you followed all of the instructions correctly).
If you like, give the new configuration a try.

Example 3: Creating and Mapping a Custom Tinting Colour

If you like the idea of tinting your greyscale ultraviolet-A images, but don't like the particular shade of neon pink I chose to include in the Photography - Moderate processing configurations, here's how you can replace it with one more to your liking. This requires editing the Global-Colours.xml configuration file, so you'll need write access to the TMSB_Config directory underneath the installation directory (not just your own personal TMSB_Config directory). If (like most people) you are running Windows® and are an administrator on the machine, you already have write access to that location.

Note that because of that requirement, this example is not included in the Tutorial directory. You'll need to make these customizations yourself.

Launch your text editor and open the Global-Colours.xml file that's located in the TMSB_Config directory underneath the directory where you unpacked TMSB.
In the <TintingColours> section, copy and paste one of the existing <TintingColour> blocks to create a copy of it.
In the new <TintingColour> block you just created:
1. Change the <Name> value to Joan_Jett_Blazer_Pink (Kristen_Stewart_as_Joan_Jett_Blazer_Pink would be more accurate, but is a little too long to be ideal).
2. Change the <Red> value to 52428
3. Change the <Green> value to 13107
4. Change the <Blue> value to 26214
That is, the new block should look like this:

<TintingColour>

<Name>

Joan_Jett_Blazer_Pink

</Name>

<Format>

UnsignedInteger16

</Format>

<Red>

52428

</Red>

<Green>

13107

</Green>

<Blue>

26214

</Blue>

</TintingColour>

This example uses 16-bit unsigned integer values for the colour levels (numbers between 0 and 65535). If you would prefer to use 8-bit integer values (0-255, like most image-editing software), or 32-bit floating-point values, you can use those instead, by changing the <Format> value.

The same block but configured to use 8-bit colour values:

<TintingColour>

<Name>

Joan_Jett_Blazer_Pink

</Name>

<Format>

Byte8

</Format>

<Red>

204

</Red>

<Green>

51

</Green>

<Blue>

102

</Blue>

</TintingColour>

The same block but configured to use 32-bit colour values:

<TintingColour>

<Name>

Joan_Jett_Blazer_Pink

</Name>

<Format>

Float32

</Format>

<Red>

0.8

</Red>

<Green>

0.2

</Green>

<Blue>

0.4

</Blue>

</TintingColour>

You should only include one of these, because each tinting colour name must be unique in the file.
Save the file and exit.
In the TMSB GUI, switch to the Processing Configuration tab.
In the drop-down menu, select Photography - Moderate - 01.
Click the Export XML button.
In the File name field, enter Process-Photography-Moderate-01-Custom_UVA_Pink.xml, then click Save.
Launch your text editor and open the file you just saved.
In the <Metadata> section:
1. In the <Name> section, change the text to read Photography - Moderate - 01 (Custom UVA Pink Tint).
2. In the <Description> section, change the text to read The same as Photography - Moderate - 01, but with a customized pink tint for ultraviolet-A. (or whatever you think is appropriate).
3. If you like, enter the date/time, in XML format in the <Created> and/or <LastModified> sections.
Locate the <TintMapping> section.
Within that section, locate the <TintedChannel> block which maps the Neon_Pink colour to the UltravioletA special band (it should be the only block which references the Neon_Pink colour).
Replace the Neon_Pink text with Joan_Jett_Blazer_Pink.
Save the file and exit.
If you closed out of TMSB previously, launch the GUI again. Otherwise, from the Tools menu, select Reload Configuration Files. In the Processing Configuration tab, the drop-down should now contain a new entry (named Photography - Moderate - 01 (Custom UVA Pink Tint), if you followed all of the instructions correctly).
If you like, give the new configuration a try.

In Closing

That wasn't so hard, was it? Who wants a stupid GUI configuration editor anyway?^[2] If you're interested in some more advanced customizations (creating input and processing configurations from scratch), you can proceed on to the rest of the articles in this section.

Footnotes

For reasons I haven't bothered to research (but which are no doubt questionable), part of the XML specification is that comments cannot be nested. This is one of those decisions that seems to me to have been made offhand by a developer or two many years ago without realizing the countless frustrations they were laying on the shoulders of future generations.
For example, a common troubleshooting technique is to comment out large blocks of code to narrow down where a problem is occuring. With XML, anyone who does this has to either inspect those large blocks with a fine-toothed comb to make sure there are no nested comments inside, or divide it up into chunks based on the location of the nested comments.
This becomes particularly annoying when dealing with content being referenced in other files. By removing anything contained within comment tags before the XML is handed off to the .NET XML processor, the entire problem is avoided. It doesn't matter if comments are nested, because everything contained within the highest level of comment tag is removed.

Everyone who uses the software, including me, that's who.