TMSB Troubleshooting and Optimization

article by Ben Lincoln

These are some basic guidelines for troubleshooting issues with The Mirror's Surface Breaks. TMSB is a complex application (especially if you are using a custom configuration), so this is not a comprehensive discussion. If you get stuck, feel free to get in touch with me using the Contact form, although I can't guarantee that I'll be able to solve your problem.

Like so many other pieces of technology, if you encounter a minor error (such as a single failed image out of a set), the first thing you should try doing is rerunning the processing of that set after the rest of the images are generated. If you are using any of the configurations included with TMSB, images that were created successfully the first time will not be generated again, so the processing of the one or two that failed should take place immediately.

If no images out of a set are generated, you should verify that in the Execution tab, the Script Processor Path is set to a valid location of davinci.bat from the DaVinci's Shadow script processor. By default, it is located in the DaVinci sub-directory of wherever you unzipped TMSB to.

If you are running TMSB on Linux or BSD, and no images are generated, make sure you followed the instructions marked IMPORTANT in the DaVinci's Shadow Build Process - Linux, DaVinci's Shadow Build Process - BSD, and TMSB on Unix-like Operating Systems articles about editing library_linux.dvrc to update certain paths!

Another good general-purpose troubleshooting option in the GUI version is to reset to the default execution options (Tools -> Reset Execution Options To Default).

Make sure you are running the current version of the software (1.3 as of this writing), and that if your operating system is 64-bit, that you have selected a 64-bit version of the DaVinci's Shadow script processor - especially if you are processing high-resolution images.

Memory Use

The following table includes the amount of memory used by each instance of the DaVinci's Shadow script processor when processing an image set of the given size. Except for statistical images, the number of spectral bands is not relevant to the amount of memory used.

The sizes are given in megapixels, because this is the factor of importance when estimating memory use by this application - all data is internally up-converted to 32-bit floating-point format, so using different bit-depths of input or output image will not change the amount of memory consumed during processing (only the quality of the result).

For example, a 4000x2000 image set (8 megapixels) will consume the same amount of memory during processing as an 8000 x 1000 image set (also 8 megapixels).

These tests were performed using the 64-bit version of the DaVinci's Shadow script processor on the 64-bit version of Windows 7. Memory use should be virtually identical under 64-bit versions of Linux.

	8 MP	16 MP	32 MP	64 MP (5 spectral bands)	64 MP (6 spectral bands)	64 MP (9 spectral bands)
Most greyscale image types	550 MB	1 GB	2 GB	3.7 GB	3.7 GB	3.7 GB
Most colour image types	600 MB	1.1 GB	2.1 GB	4.1 GB	4.1 GB	4.1 GB
Statistical greyscale images	900 MB	1.6 GB	3.1 GB	6.8 GB	7 GB	7.8 GB
Luminance/colour images	950 MB	1.7 GB	3.4 GB	6.8 GB	6.8 GB	6.8 GB
DCS images	950 MB	1.8 GB	3.5 GB	7 GB	7 GB	7 GB

The effective limit for the 32-bit version of DaVinci's Shadow is about 13 megapixels (for example, source images of 5500 x 2360 or 5000 x 2600 in size) for complex processing. The effective limit for the 64-bit version has not been determined, due to limitations on the amount of RAM in the test system, but should be well above 64 megapixels (assuming enough physical memory is installed).

For very high-resolution images (such as the 64 megapixel test set), the TMSB GUI will display incorrect thumbnails for images, but the full-size image files will contain accurate results.

Using the information in this table, users of multi-core systems can determine the safe level to which they can allow TMSB to process images concurrently.

For example, with image sets of 8 MP in resolution, the maximum amount of memory consumed by each instance of DaVinci's Shadow will be about 1 GB. If the system where the processing is occurring has 12GB of physical memory, then about 8 instances of DaVinci's Shadow can be run at the same time without overly impacting system performance. However, if the image resolution is doubled to 16 MP, the maximum amount of memory per instance jumps to almost 2 GB of RAM, so it would be unwise to allow more than 3 or 4 instances to run at the same time.

The number of instances in use is limited by the Maximum Simultaneous Directories and Maximum Simultaneous Images settings in the Execution tab of TMSB, as discussed in the TMSB Tutorial 1: Basic Use article. For example, on a system with 4 CPU cores, both of those values could be safely set to 4, and the speed at which the image sets were processed would increase by about four times.

Troubleshooting Options

This section refers to these options using their names in the GUI. The same options are available in the command-line interface. See the list at the bottom of the TMSB Tutorial 1: Basic Use article.

All of these options are located within the Execution tab.

Collect and Display Performance Data - this option is disabled by default (in the GUI - the reverse is true in the CLI), but if it's turned on, it will give you some idea of whether TMSB is putting too much of a load on your system in terms of CPU and/or RAM.
Log Level - if you are running into trouble, you can set this option to something other than None (and specify a full path in the Log File Path field) and see if helpful information shows up in the log file. If you are running into unexpected behaviour (such as TMSB not even attempting to generate a permutation that you think it should be), this is the best place to start. I recommend only using the Debug log level if all else fails, because it is extremely verbose. The other levels are manageable.
Log Mode - if this value is set to Append, and the log file specified by the Log File Path value already exists, then the file will be appended to. Otherwise, it will be overwritten.
Continue Processing Even When Errors Occur - This option is enabled by default, and causes TMSB to attempt to process the rest of the images in a set even if one or more fail. As noted above, it is not uncommon for one or two images to fail to be generated. If you encounter many errors, you may wish to disable this option while troubleshooting to prevent TMSB from attempting to launch numerous instances of DaVinci's Shadow.
Do Not Delete Temporary Files - if this option is enabled, it will cause TMSB to not delete the numerous .dv script files and log output that are generated as it performs its work. If you are getting to the point of stepping through the script to see why it's failing, or DaVinci's Shadow is crashing and no master log file is being generated, this is a good option to turn on.
Write Script Code Even When No Images Will Be Generated - by default, TMSB does not generate large blocks of script code when those blocks would not generate output images (for improved efficiency). If you expect to see an image that does not show up in the output directory and can't find a reference to it in the generated script, try turning on this option.
Display Thumbnails - this option is enabled by default. If it is turned off, the sliding thumbnail display in the GUI is disabled. If you are having trouble with the GUI (or just want to improve efficiency), you are probably better off using the CLI, but this option is still provided in case it is useful for someone.

Advanced Troubleshooting

Expert users can examine the tmsb_script.dv script generated in the image directory and try stepping through it in the DaVinci's Shadow script processor to see where the failure is occurring and hopefully discern why.