[ Beneath the Waves ]

TMSB Tutorial 1: Basic Use

article by Ben Lincoln

 

This article will walk you through processing your first set of images using The Mirror's Surface Breaks. These instructions are specifically for the GUI, but the command-line version is discussed at the end of the article.

You Will Need

Initial Set Up

You should only need to perform these steps once.

  1. Unzip TMSB to the location of your choice (e.g. C:\Program Files (x86)\TMSB on Windows®, or ~/TMSB on Linux).
  2. Windows® users should double-click on TMSBGUI.EXE.
  3. Users of Unix-like systems should open a terminal, switch to the directory where they unpacked TMSB, and execute mono ./TMSBGUI.exe.
  4. Switch to the Execution tab.
  5. In the Script Options section, click the Browse button to the right of the Script Processor Path.
  6. Windows® users should browse to either the DShadow32 or DShadow64 subdirectory of the location where they unpacked TMSB, and double-click on the dshadow.bat file inside. DShadow32 is for 32-bit versions of Windows®, and DShadow64 is for 64-bit versions.
    You can use the 32-bit version on 64-bit Windows® (but not vice-versa), although doing so will mean losing all of the benefits of using the 64-bit version (mostly the ability to work with much larger images).
    If you are unsure whether your version of Windows® is 32-bit or 64-bit, right-click on My Computer and choose Properties. 64-bit versions of Windows® will have the text "64-bit" somewhere in the window that appears.
  7. Users of Unix-like systems should browse to the dshadow executable that they compiled using instructions in the corresponding article.
  8. Close the TMSB window.

(This is to make sure that TMSB is using the correct path for the DaVinci's Shadow script processor)

GUI Use

There are screenshots of the major steps in this process, below the written instructions.

  1. Place the source images for an image set in their own directory. For example, if you are using the files from the TMSB_Example-01-African_Violet example file at the bottom of this page, create a directory named TMSB_Example-01-African_Violet and unzip the five TIFF files from the zip file into it.
  2. If you wish to process multiple image sets in one pass, create separate directories for each image set and place their files in them.
  3. In the directory where you unzipped TMSB itself, double-click on TMSBGUI.EXE
  4. In the Input Configuration tab (which is selected by default), click the drop-down menu and select NIR-R-G-B-UVA (TIFF - 3 Files).
  5. Switch to the Processing Configuration tab. If this is your first time using TMSB, select a simple configuration (such as No Funny Business) in the drop-down. Otherwise, feel free to experiment with the various configurations included with the software. The Description field will give you a rough estimate of how many output files will be generated by the selected configuration (although you may need to scroll down to see it if the rest of the description is lengthy).
    Keep in mind that the ones which have "Satellite Imagery" in their name will not produce good results with the sample image sets from this page, because those sets don't include mid-infrared or thermal infrared bands. See TMSB Tutorial 2: OnEarth Satellite Imagery for information on satellite imagery.
  6. Switch to the Output Configuration tab. For purposes of this tutorial, select 16-Bit-Per-Channel TIFF and 8-Bit-Per-Channel JPEG Output in the drop-down menu.
  7. Switch to the Execution tab.
  8. Don't be intimidated by the number of options here - most of them are for advanced users or troubleshooting/debugging only. If this is your first time using TMSB, or you just don't care about advanced options, ignore all of these. Otherwise, see the Options For Intermediate Users section, below. If you ever set these options to different values and it breaks something, go to TMSB's Tools menu and select Reset Execution Options To Default.
  9. In Windows Explorer, navigate to the parent directory of the directory (or directories) where your source image sets are located. For example, if my source image set is in C:\Users\blincoln\Documents\TMSB_Examples\TMSB_Example-01-African_Violet, I would navigate to C:\Users\blincoln\Documents\TMSB_Examples.
  10. Drag and drop one or more of the source image set directories from Windows Explorer into the queue area in the lower left corner of the TMSB window (see the screenshots below if this is unclear).
  11. You should see a new entry in the queue for each directory that you just dropped onto it. If not, try again.[2]
  12. Click the Begin Processing button in the middle of the window. Unless you missed one of the previous steps, the TMSB processing window should appear.
  13. The concept behind the processing window is a combination of a photographic thumbnail/contact sheet and an industrial assembly line. As TMSB generates each output image, it will appear on the right side of the screen, and slide to the left as subsequent images are created. The speed with which the sliding occurs increases as more images "back up" to the right of the display.
  14. While images are visible on the sliding display, they can be double-clicked to open the "most likely to be useful for preview purposes" version in the default image viewer. If you followed the directions above and chose an output configuration which included JPEGs, then double-clicking a thumbnail will open the JPEG version in the default image viewer on your PC. See the Options For Intermediate Users section for other methods that can be used to make use of the output images while they are sliding on the display.
    Note that while you have your mouse cursor "hovered" over one of the sliding displays, the sliding is paused. This can cause a large number of images to "back up" to the right side of the queue, so try not to leave your mouse cursor there unless you really are opening images by double-clicking on them.
  15. When the processing completes successfully, the Directory bar above the sliding thumbnail display will turn blue. If an error occurs, the bar will turn red instead. See the TMSB Troubleshooting and Optimization article for a discussion of how to handle errors.
  16. Once all image sets have been processed, the Close button in the lower-right corner of the window will become enabled. Click it to close the TMSB processing window.
  17. Once you have closed the processing status window, you can either select a different Processing Configuration for the same image set and run that, or remove the image set from the queue, add a different one, and process that instead.
  18. Once you are done working in TMSB, close the TMSB window.
  19. Browse to the output location in Windows Explorer or your favourite image viewer/editor and examine the results.
  20. If you don't need the high-quality TIFFs (or just want to save disk space), and don't plan on processing the same image set again with a different configuration, you can delete all of the TIFF versions and retain only the JPEGs. You shouldn't delete the TIFFs until you're done running all processing on a given image set, because if you do, TMSB will have to regenerate all of the intermediate images instead of using ones that are already there.
Basic Use Screenshots
[ Source image set directory ]
Source image set directory
[ Directory structure for multiple source image sets ]
Directory structure for multiple source image sets
[ Input configuration ]
Input configuration
[ Processing configuration ]
Processing configuration
[ Output configuration ]
Output configuration
[ Execution options ]
Execution options
[ Where to drag and drop directories into ]
Where to drag and drop directories into
[ What the source window for the drag and drop operation should look like ]
What the source window for the drag and drop operation should look like
[ An advanced illustration of the drag-and-drop operation ]
An advanced illustration of the drag-and-drop operation
[ What the queue should look like after adding a source directory ]
What the queue should look like after adding a source directory
[ Beginning processing ]
Beginning processing
[ Finished processing ]
Finished processing
     

Illustrations for the steps above.

 

Options For Intermediate Users

TMSB has numerous options available for users who are interested in taking advantage of them (although it is not necessary to do so).

Intermediate/Advanced Use Screenshots
[ The queue with multiple source directories ]
The queue with multiple source directories
[ Multiple image sets being processed simultaneously ]
Multiple image sets being processed simultaneously
[ More multiple image-set processing ]
More multiple image-set processing
[ Errors have occurred! Better consult the troubleshooting article! ]
Errors have occurred! Better consult the troubleshooting article!
[ Eight image sets being processed simultaneously ]
Eight image sets being processed simultaneously

Illustrations for the steps above. I confess that the main reason I allowed the queue pane to be resized (as in the final screenshot) was that I was hoping it would cause TMSB to show up on a computer screen in the background on a film or TV show looking awesome and high-tech as eight or more rows of fancy thumbnails slid along simultaneously.

 

Notes On Using Your Own Image Sets

The process for using image sets you created yourself is identical to the example images, with the following exceptions:

  1. Your images should be saved in either TIFF or PNG format, and ideally in 16-bit-per-channel ("48-bit") variations of those formats. You should avoid using images which have been saved as JPEGs (or other lossy formats) at any point in their existence, because the type of processing TMSB performs will greatly magnify the flaws that JPEG compression introduces.
  2. If you are using PNG source files instead of TIFFs, then in the Input Configuration tab, use the NIR-R-G-B-UVA (PNG - 3 Files) option.
  3. It is also possible to use other file formats supported by DaVinci's Shadow/DaVinci. For example, TIFFs that use 32-bit floating-point values, HDF5 files, and so on. You will need to create your own input configuration XML file to do this, as files for other formats are not included with TMSB. See TMSB XML Schema Part 2: Input Configuration, TMSB Tutorial 4B: Dual-Band Ultraviolet-A XML File Customization, and TMSB Tutorial 4F: Yellow Filter Processing, as well as ASU's page on the read() function, for a list of supported formats. Note that some of them (e.g. VICAR) are not supported in DaVinci's Shadow unless you make a custom build that includes those optional components.
  4. Once you are more familiar with the application, you may use other Output Configuration options, but it is highly recommended that you always use one of the options which includes either 16-bit-per-channel TIFF or PNG output. This is because TMSB creates final output based on at least one (and often more than one) iteration of processing, and using and 8-bit-per-channel format will reduce the quality of the final images.[1]
  5. Custom output configurations that use more esoteric file formats are also possible, but again, you should always make sure to include 8-bit-per-channel JPEG or PNGs as the last file type in such a configuration, unless you don't care about thumbnails being displayed.
  6. If you only have near infrared or ultraviolet-A exposures in addition to human-visible-light, that's OK. TMSB will process what it can with the source files it has available, although obviously there will be fewer permutations as a result. Do not include "dummy" files named for the missing spectral band(s)!
  7. You may notice that in some of the example sets, there are files named NIR2.TIF and/or UVA2.TIF in addition to NIR.TIF and/or UVA.TIF. These are not additional spectral bands. They make use of a niche function which allows a different version of each band to be specified for use when that band is used as the luminance channel in a luminance/colour image (see Luminance/Colour Images). This is useful if the band looks best "blown-out" in three-channel false colour images, but with a more subtle curve when used as the luminance channel. This feature also applies to tinted greyscale versions of bands, since those are created by the same method. Again, if you don't want to make use of this feature, just don't put files with those names in the source directory - TMSB works with what is made available to it.
  8. Processing options are much more limited if you have only red, green, and blue images to work with (IE you shot the photo with a conventional DSLR), but you can still experiment with the various DCS configurations (see Decorrelation Stretch Images), and also the Example: Exponential Scaling configuration, which only operates on those channels even if more are available. You can use the statistical configurations too, but you probably won't get very interesting results.

Where To Go From Here

At this point, you can use any of the configurations that are included with TMSB, as long as you're interested in processing photos of the same general type that I shoot. If you're interested in learning about some of the other types of images that can be processed using the "out-of-the-box" configuration files, see TMSB Tutorial 2: OnEarth Satellite Imagery and TMSB Tutorial 3: Mars Rover PanCam Images. If you'd like to get your feet wet with creating customized configurations, see TMSB Tutorial 4: XML File Customization. For very advanced users, TMSB has the ability to execute arbitrary DaVinci scripts in a multiprocess manner, as long as they are written in a specific format - see TMSB Tutorial 5: Custom Scripts for information on that.

Sooner or later, you are also probably going to have to make use of the information in the TMSB Troubleshooting and Optimization article.

Command-Line Use

TMSB includes a full command-line implementation (TMSB.EXE) in addition to the GUI, for advanced users who want to create wrapper scripts, or simply squeeze as much performance as possible out of the system (since the CLI version does not use even minimal system resources for things like the sliding thumbnail display that are unique to the GUI).

If you don't know (or care) what a "command-line implementation" is, you can ignore this section entirely.

If you wish to make use of the command-line TMSB, I highly recommend adding the directory where you unzipped TMSB to your system-level PATH environment variable, so that you can call TMSB.EXE without using the full path.

The syntax for the command-line version (which is also available by running TMSB.exe -help or TMSB.exe -?) is:

TMSB.exe -i [input configuration file] -p [processing configuration file] -o [output configuration file] -m [minimum number of source bands] -r -x -ise -d [script processor path] -da [script processor arguments] -gn -gi -pri [script process priority] -td [maximum simultaneous directories to process] -tt [maximum number of simultaneous images to process] -kt -ol [output verbosity level] -tl [subscript execution time limit in milliseconds] -log [log file path] -al -nco -dec -npd -aw [-fow or -fou] [source directory path 1] [source directory path 2] ... [source directory path n]

With the individual options being:

-i [input configuration file] (required) - the name (if located in TMSB_Config under your personal directory or the TMSB installation directory) or full path of a TMSB input configuration XML file.

-p [processing configuration file] (required) - the name (if located in TMSB_Config under your personal directory or the TMSB installation directory) or full path of a TMSB processing configuration XML file.

-o [output configuration file] (required) - the name (if located in TMSB_Config under your personal directory or the TMSB installation directory) or full path of a TMSB output configuration XML file.

-m [minimum number of source bands] (optional) - the minimum number of source spectral bands that must be found in a directory for that directory to be processed. Defaults to 3 if not explicitly specified.

-r (optional) - enables recursion through each of the source directories. This is functionally similar to the Add Directories Recursively When Dropped Onto The Queue option in the GUI, but is conceptually different because it causes the command-line TMSB to recurse through the directories at execution time instead of when queueing the directories. The difference is mostly academic, but may be important in unusual cases.

-x (optional) - execute scripts after generating them. If this flag is omitted, then TMSB will only generate .dv scripts in each source directory and not pass them to the DaVinci's Shadow script processor.

-ise (optional) - ignore script errors. If this flag is specified, then TMSB will attempt to process the remaining images for a particular directory even when one or more failures occur. If it is not specified, then processing of the entire set is aborted.

-d [script processor path] (required if the -x flag is specified) - the full path to the davinci.bat file from DaVinci's Shadow. Note: you must specify the path to the .bat file, not the actual .exe file.

-da [script processor arguments] (optional, but should be specified if the -x flag is specified or you won't get the results you expect) - these are the command-line arguments to pass to DaVinci's Shadow. In virtually all cases, this value should be "-f".

-gn (optional) - never generate scripts. This is an advanced option for users who want to create their own custom .dv scripts and have TMSB execute them. See TMSB Tutorial 5: Custom Scripts for a discussion.

-gi (optional) - only generate scripts if they are not already present. This is an advanced option for users who want to create their own custom .dv scripts and have TMSB execute them, unless the source directory does not contain a script, in which case TMSB should generate and execute a script using the specified configuration. See TMSB Tutorial 5: Custom Scripts for a discussion.

-pri [script process priority] (optional) - the priority the operating system should assign to instances of DaVinci's Shadow. This value should be one of the following, with the recommended value being BelowNormal or Normal. If this value is not explicitly specified, it defaults to Normal.

Idle
BelowNormal
Normal
AboveNormal
High
RealTime

-td [maximum simultaneous directories to process] (optional) - the maximum number of directories to process simultaneously. If this value is not explicitly specified, it defaults to 1. It must be less than or equal to the value specified for the -tt option.

-tt [maximum number of simultaneous images to process] (optional) - the maximum number of images to process simultaneously. If this value is not explicitly specified, it defaults to 1.

-kt (optional) - "keep temporary files". This is a debugging option which cases TMSB to not delete the numerous temporary .dv scripts and log files it generates as it performs its work.

-ol [output verbosity level] (optional) - a number from 0 to 4 which specifies how much text to echo to the display (and the log file, if logging is enabled), with 0 being "none" and 4 being "debug". If this value is not specified explicitly, it defaults to 2.

-tl [subscript execution time limit in milliseconds] (optional) - a number from 0 to 2147483648, which specifies the maximum amount of time that a subscript is allowed to execute. If 0 is specified, no limit will be used. If this value is not specified explicitly, it defaults to 172800000 (48 hours).

-log [log file path] (optional) - the full path to a log file to write results to in addition to echoing them to console output. Specifying this path implicitly enables the logging functionality.

-al (optional) - if logging is enabled, causes an existing log file to be appended to, rather than overwritten.

-nco (optional) - do not echo any output to the console.

-dec (optional) - represent memory/disk space using SI/decimal values instead of powers of two.

-npd (optional) - do not collect or display performance data.

-aw] (optional) - a debugging option that forces generation of script code sections that will not result in any images being created.

[-fow or -fou] (optional) - debugging options that force TMSB to behave as though it were being executed on Windows® (-fow) or Unix/Linux (-fou) instead of its default behaviour of automatically determining the operating system.

[source directory path 1] [source directory path 2] ... [source directory path n] (required) - one or more paths that contain source image sets. If the -r option is specified, these paths may also be to directories which contain (in one or more subdirectories at any level below them) source image sets.

For example, if I want to execute the CLI using these criteria:

...the command-line syntax would be:

TMSB.exe -i "Input-NIR_R_G_B_UVA-TIFF-3F.xml" -p "Process-Photography-Moderate-01.xml" -o "Output-TIFF_16-JPG_8.xml" -x -ise -d "C:\Program Files (x86)\TMSB\DaVinci\davinci.bat" -da "-f" -tt 2 "C:\Users\blincoln\Documents\TMSB_Examples\TMSB_Example-02-Phalaenopsis_Orchid" C:\Users\blincoln\Documents\TMSB_Examples\TMSB_Example-04-Yellowstone_Hotspring

Obviously, if you use the CLI frequently, you are going to be writing some wrapper scripts.

The syntax on Unix-like operating systems is the same, except you will need to call the executable via mono, and also specify the -f argument for the script processor. For example:

mono ./TMSB.exe -i "Input-NIR_R_G_B_UVA-TIFF-3F.xml" -p "Process-Photography-Conservative-01.xml" -o "Output-TIFF_16-JPG_8.xml" -x -d "/home/blincoln/dshadow-2.9.2-linux/dshadow" -da "-f" -ol 4 -ise -log "Debug_Log-Console.txt"

Please note that on Unix-like systems, you cannot use the ~ shorthand for the home directory of the current user. Mono doesn't expand it. Sorry. So in the previous example, I used /home/blincoln/dshadow-2.9.2-linux/dshadow as the script processor path, not ~/dshadow-2.9.2-linux/dshadow

 
Download
File Size Version Release Date Author
African Violet 6 MiB 1.0 2011-02-21 Ben Lincoln
A sample image set for use with the TMSB tutorials. This set will generate output images that occupy about 2.5 MiB on disk for each variation in the selected processing configuration.
 
Download
File Size Version Release Date Author
Phalaenopsis Orchid 4 MiB 1.0 2011-02-21 Ben Lincoln
A sample image set for use with the TMSB tutorials. This set will generate output images that occupy about 2.5 MiB on disk for each variation in the selected processing configuration.
 
Download
File Size Version Release Date Author
Big Bend Plants 5 MiB 1.0 2011-02-21 Ben Lincoln
A sample image set for use with the TMSB tutorials. This set will generate output images that occupy about 2.5 MiB on disk for each variation in the selected processing configuration.
 
Download
File Size Version Release Date Author
Yellowstone Hotspring 5 MiB 1.0 2011-02-21 Ben Lincoln
A sample image set for use with the TMSB tutorials. This set will generate output images that occupy about 2.5 MiB on disk for each variation in the selected processing configuration.
 
Download
File Size Version Release Date Author
Blood-Stained Shirt 4 MiB 1.0 2011-02-21 Ben Lincoln
A sample forensic image set for use with the TMSB tutorials. Note: the blood is mine, and was drawn by a nurse for purposes of creating this test image. This set will generate output images that occupy about 2.5 MiB on disk for each variation in the selected processing configuration.
 
Download
File Size Version Release Date Author
Blood-Stained Gloves 3 MiB 1.0 2011-02-21 Ben Lincoln
A sample forensic image set for use with the TMSB tutorials. Note: the blood is mine, and was drawn by a nurse for purposes of creating this test image. This set will generate output images that occupy about 2.5 MiB on disk for each variation in the selected processing configuration.
 
Download
File Size Version Release Date Author
Writing On White Paper 6 MiB 1.0 2011-02-21 Ben Lincoln
A sample forensic image set for use with the TMSB tutorials. This set will generate output images that occupy about 4 MiB on disk for each variation in the selected processing configuration.
 
Download
File Size Version Release Date Author
Charred Paper With Writing 7 MiB 1.0 2011-02-21 Ben Lincoln
A sample forensic image set for use with the TMSB tutorials. This set will generate output images that occupy about 4 MiB on disk for each variation in the selected processing configuration.
 
Footnotes
1. Expert users will notice that there are no output configurations included with TMSB in which the primary output format is JPEG. This is because using lossy compression on the intermediate images would be many times worse than just using an 8-bit-per-channel format for this purpose.
2. If you can't get the drag-and-drop functionality to work, or are using an interface that makes it difficult, you can also use the Add buttons to the right of the queue or in the File menu and browse to the directory. On the off chance that you are running TMSB in debugging mode within Visual Studio on a newer version of Windows® which has UAC enabled, you will probably not be able to use the drag-and-drop functionality (because Visual Studio is operating in an administrative context and Windows Explorer is not) and will need to use one of these other methods.
 
[ Page Icon ]