MIST User Guide

Contents

1. MIST User Guide
   1. Launching MIST
   2. Installation Validation Test
   3. MIST Graphical User Interface
      1. Input Parameters
      2. Output Parameters
      3. Subgrid Parameters
      4. Advanced Parameters (optional)
      5. Java Execution
      6. FFTW Execution
      7. CUDA Execution
      8. Help
   4. MIST Status Frame
2. Installing MIST
   1. Update Site Installation
   2. Manual Installation
3. Installing FFTW
4. Installing CUDA

Launching MIST

1. Start Fiji.
2. Click through the menus: Plugins >> Stitching >> MIST
3. Click: MIST

Installation Validation Test

In this section, we will walk through setting up running MIST on one of the 5x5 image tile datasets in order to validate that the plugin is installed correctly.

1. Download test images: Cy5_ImageTiles.zip ~ 54 MB
2. Extract Cy5_ImageTiles.zip into a directory
3. Launch MIST plugin from Fiji
4. Select Load Params and open '[extractionPath]/Small_Fluorescent_Test_Dataset/stitching-params.txt'
5. To manually enter parameters (avoiding Load Params) enter the following values into the Input Tab
   1. Filename Pattern Type: 'Row-Column'
   2. Filename Pattern: 'img_r{rrr}_c{ccc}.tif'
   3. Starting Point: 'Upper Left'
   4. Grid Width: '5'
   5. Grid Height: '5'
6. Modify Image Directory to '[extractionPath]/Small_Fluorescent_Test_Dataset/image-tiles'
7. Select the Output tab and update Output Directory and Metadata Directory to define where the output files are to be saved
8. Update Display Stitched Image and Save Full Stitched Image to selected/enabled
9. To check the parameters defining the image grid, select Preview Mosaic With No Overlap which should generate and display a zero percent overlap tiling of the input images
10. Click Begin Stitching to launch
11. Compare the newly generated stitched image to the reference stitched image shipped with the test dataset
    1. Open '[extractionPath]/Small_Fluorescent_Test_Dataset/stitched-image/img-stitched-0.tif' in Fiji.
    2. Check that the new stitched image has the same dimensions as the reference
    3. Perform a pixel-wise comparison between the stitched images
    4. Fiji>>Process>>Image Calculator
    5. The operation new stitched image "Difference" reference stitched image should produce an image containing all zeros when using the correct parameters

MIST Graphical User Interface

The MIST plugin consists of five tabs. Below, we outline each tab and discuss all of the parameters. All options labeled with an * are required in order to start stitching. Each tab contains a ? button that, when clicked, generates a local copy of this documentation.

Input Parameters

Save Params Button - Saves all parameters in MIST to a file.

Begin Stitching Button - Launches the stitching experiment.

Load Params Button - Loads parameters from a file. Note: Supports loading the statistics file that is generated after each experiment.

* File Pattern Type - Used to specify the type of file pattern. Possible options: Sequential and Row-Column.

* File Pattern - Used to load images from a directory. Changes based on the File Pattern Type

• If the File Pattern Type = Sequential, then the File Pattern expects sequential style numbering.

    Example 1: Img_pos0001_c01.tif = Img_pos{pppp}_c01.tif
    Examples 2: Img_pos001_time001.tif = Img_pos{ppp}_time{ttt}.tif
    {ppp} - Special text that represents position numbering between 0 and 999. Increase the number of p's to represent larger numbers.
    {ttt} - Special text that represents timeslice number between 0 and 999. Each value of {ttt} will be stitched independently. Increase the number of t's to represent larger numbers. Specifying time slices is optional.

• If the File Pattern Type = Row-Column, then the File Pattern expects row-column style numbering.

    Example 1: Img_r1_c1.tif = Img_r{r}_c{c}.tif
    Example 2: Img_row01_col01_time01.tif = Img_row{rr}_col{cc}_time{tt}.tif
    {rr} - Special text for row numbering between 0 and 99. Increase the number of r's to represent larger numbers.
    {cc} - Special text for column numbering between 0 and 99. Increase the number of c's to represent larger numbers.
    {ttt} - Special text that represents timeslice number between 0 and 999. Each value of {ttt} will be stitched independently. Increase the number of t's to represent larger numbers. Specifying time slices is optional.

* Image Directory - The directory where the source images are located. Select browse to open a directory browser.

* Starting Point - The starting point of the microscope scan. Possible options: Upper Left, Upper Right, Lower Left, and Lower Right.

* Direction - The direction the microscope moves. Possible options: Vertical Combing, Vertical Continuous, Horizontal Combing, and Horizontal Continuous.

Assemble from metadata - Generates the image mosaic using metadata from a previous run. Important:You must specify the metadata directory in the output tab to refer to the metadata directory of your previous run.

* Grid Width - The number of images in a row (The number of columns, the width of the image grid)

* Grid Height - The number of images in a column. (The number of rows, the height of the image grid)

Timeslices - The number of timeslices to stitch. Leave this field blank to stitch all timeslices. To stitch timeslices you must add the spcial format text {ttt} to the File Pattern. This input supports a comma separated list and/or a range using a '-'. Example: "1-25,35,45" stitches timeslices 1 through 25, 35, and 45.

---

Output Parameters

Use Image Directory as Output Directory - Sets the output directory to be the same as the input directory.

Output Directory - Specifies the location to save images and run statistics.

Files that are saved:

• {namePrefix}stitched-{#}.tiff

• {namePrefix}statistics.txt

    {namePrefix} - the prefix used in "Filename Prefix"
    {#} - The timeslice number (0 if no timeslices are used)

Filename Prefix - The prefix given to output files.

Metadata Directory - The directory where metadata is written.

Files that are saved:

• global-positions-{#}.txt
• relative-positions-{#}.txt
• relative-positions-no-optimization-{#}.txt

• hillclimb-startings-positions-{#}.txt

    {#} - The timeslice number (0 if no timeslices are used)

Blending mode - Selects the blending mode to be used for computing the mosaic image. Blending Types:

• Overlay - Choose only one pixel from overlapping pixels based on highest accuracy
• Linear - Smoothly alters the intensity of the overlapping area between images. Smoothness is determined by alpha. Value should be between (0, 5]
• Average - Computes the average intensity

Warning:: RGB images may cause out of memory issues for linear and average blending. When generating the mosaic of RBG images it is recommended to use overlay images.

Display Stitched Image - Opens the blended image mosaic into Fiji.

Save Full Stitched Image - Writes the blended image mosaic to the Output Directory.

Update Button - Updates the estimated stitched image file size.

Preview Mosaic With No Overlap - Opens the image mosaic into Fiji assuming 0% overlap.

Warning: Large image grids can cause out of memory errors. If the number of pixels in the image exceeds 2147483647 (2³¹-1), then the mosaic image must be exported using an alternative method. (imagePixelWidth*imagePixelHeight < 2147483647)

Subgrid Parameters

Use full grid - Updates the subgrid to use the full grid of images.

Start Col - The start column for the subgrid.

Start Row - The start row for the subgrid.

Extent Width- The width for the subgrid.

Extent Height - The height for the subgrid.

Advanced Parameters (optional)

Number of FFT Peaks - Specifies the number of peaks to check when computing the phase correlation image alignment method. We have determined that modifying this value can yield more accurate pre-optimization displacements. This value should not exceed 10. (Default: 2)

Stage Repeatability - Sets the stage repeatability variable when computing the global optimization. This value is used to represent the repeatability of the microscope stage movement. It is used for determining the search space of the hill climbing algorithm.

Horizontal overlap - Sets the horizontal overlap variable when computing the global optimization. This value is used to filter translations as good or bad. Good translations are used to identify the optimal starting position for the hill climbing algorithm. Setting this value can improve the accuracy of the image mosaic.

Vertical overlap - Sets the vertical overlap variable when computing the global optimization. This value is used to filter translations as good or bad. Good translations are used to identify the optimal starting position for the hill climbing algorithm. Setting this value can improve the accuracy of the image mosaic.

Overlap uncertainty - Sets the overlap uncertainty variable when computing the global optimization. This value is used to specify the range when filtering translations as good or bad. It is used in conjunction with the horizontal and vertical overlap variables.

Stitching Program - Selects which type of program to execute.

• Auto - Determine which program to use. First checks if FFTW is available, if it is not then it falls back to Java.
• Java - Uses the pure java implementation. This version uses single precision values, but is not as accurate as FFTW and CUDA.
• FFTW - Uses FFTW libraries.
• CUDA - Uses NVIDIA CUDA GPUs.

Java Execution

CPU worker threads - Number of parallel workers to spawn (should not exceed number of CPU cores)

FFTW Execution

CPU worker threads - Number of parallel workers to spawn (should not exceed number of CPU cores)

FFTW Plan Type - The type of FFTW plan to generate

• Measure - Default, short creation time, usually ideal runtimes
• Patient - Long planning time, more robust runtimes
• Exhaustive - Very long planning time, most robust runtimes

Note: FFTW plans can be saved and reused to eliminate planning time.

Save Plan? - Saves the FFTW plan that is generated to file.

Load Plan? - Loads the FFTW plan from file.

FFTW Library File - Specifies the FFTW library file to load. Example Files:

• Windows: libfftw3.dll (this library is packaged with MIST in the "Fiji.app/lib/fftw" directory)
• Linux: libfftw3.so (default installation location "/usr/local/lib")
• Mac OSX: libfftw3.dylib (default installation location "/usr/local/lib")

Plan Location (or file) - The location to load FFTW plans. If a file is specified, the file will be used when loading the plan. This path is also used for saving plans.

Note: FFTW installation instructions

CUDA Execution

CPU worker threads - Number of parallel workers to spawn (should not exceed number of CPU cores)

Execute Device Query - Queries for all GPUs installed on the system and prints the information to the log.

Refresh Device Table - Forces the table to re-query all GPUs and repopulate the table.

GPU Table - Displays all available GPUs found on the machine. To use one (or more) GPUs, click the check box in the Selected? column. Note: GPUs have limited memories, it is recommended to use GPUs with at least 1 GB of graphics memory depending on the size of the image grid.

Note: CUDA Installation instructions

Help

Log Level - Sets the log level for the user interface and the stitching execution. Possible Options:

• None - No logging
• Mandatory - Logs important information
• Helpful - Logs helpful information
• Info - Logs informative information
• Verbose - Logs all information

Note: The lower logging stack includes the logging levels above. Example: Helpful, includes Mandatory.

Debug Level - Sets the debug level for the user interface and the stitching execution. Possible Options:

• None - No debug logging
• Mandatory - Logs important debug information
• Helpful - Logs helpful debug information
• Info - Logs informative debug information
• Verbose - Logs all debug information

Note: The lower logging stack includes the logging levels above. Example: Helpful, includes Mandatory.

Open Help (PDF) - Opens this document in PDF format.

MIST Status Frame

Progress - If timeslices are used, shows the current timeslice, total timeslices, and number of groups (if entered as a comma separated list in the input parameters).

Progress bar - Shows the % progress made for the current experiment.

Log Level - Sets the log level for the user interface and the stitching execution. Possible Options:

• None - No logging
• Mandatory - Logs important information
• Helpful - Logs helpful information
• Info - Logs informative information
• Verbose - Logs all information

Note: The lower logging stack includes the logging levels above. Example: Helpful, includes Mandatory.

Debug Level - Sets the debug level for the user interface and the stitching execution. Possible Options:

• None - No debug logging
• Mandatory - Logs important debug information
• Helpful - Logs helpful debug information
• Info - Logs informative debug information
• Verbose - Logs all debug information

Note: The lower logging stack includes the logging levels above. Example: Helpful, includes Mandatory.

Cancel Execution - Safely stops execution and releases used resources.

* - required in order to start stitching

MIST Plugin Installation

Installing the plugin into Fiji is simplified using Fiji's update site manager. If the machine is not configured for the network then please refer to the manual installation.

Update Site Installation

1. Open Fiji
2. Help >> Update Fiji
3. Manage update sites
4. Activate MIST by selecting check box
5. Close and Apply Changes
6. Plugin is installed in Plugin >> Stitching >> MIST

Or

1. Open Fiji
2. Help >> Update Fiji
3. Manage update sites
4. Click "Add"
5. Enter Name: "MIST" and URL: http://sites.imagej.net/NIST-ISG-MIST/
6. Close and Apply Changes
7. Plugin is installed in Plugin >> Stitching >> MIST

Manual Installation

1. Download the latest version of the MIST plugin from MIST Plugin Download
2. Extract the contents of the zip file into your Fiji.app folder
3. Restart Fiji
4. Plugin is installed in Plugins >> Stitching >> MIST

FFTW Installation

FFTW (Fastest Fourer Transform in the West, http://fftw.org ) is a C implementation out of MIT that computes the discrete Fourier transform. The plugin loads the library at run-time and uses the high performance FFTW functions in Java.

Requirements:

1. Fiji (64-bit version)

Note: 64-bit Windows systems should be able to run the FFTW version without additional setup.

FFTW Installation on Unix (64-bit Mac OSX/Linux)

1. Download fftw-3.3.4.tar.gz from http://www.fftw.org/download.html
2. Extract source code to directory (tar xzvf fftw-3.3.4.tar.gz)
3. From a terminal locate source code and run the following commands:

    ./configure --enable-shared
    make
    sudo make install

(If configure fails, additional compilers and/or libraries may be needed)

1. Launch the Fiji MIST plugin
2. Specify the FFTW library file in the Advanced FFTW Options FFTW options user guide (default FFTW installation location is in /usr/local/lib)
   1. Linux library name example: libfftw3.so (or similar)
   2. MacOSX library name example: libfftw3.dylib (or similar)
3. You should now be able to launch MIST using FFTW

FFTW Installation using MacPorts

1. From the command-line: sudo port install fftw-3
2. Launch the Fiji MIST plugin
3. Specify the FFTW library file in the Advanced FFTW Options FFTW options user guide (default FFTW installation location is in /usr/local/lib)
   1. Linux library name example: libfftw3.so (or similar)
   2. MacOSX library name example: libfftw3.dylib (or similar)
4. You should now be able to launch MIST using FFTW

CUDA Installation

CUDA is the Compute Unified Device Architecture and is a language developed by NVIDIA. It is used to execute code on NVIDIA GPUs to obtain high performance.

Requirements:

1. NVIDIA GPU installed on your system
2. CUDA toolkit version 6.5
3. Fiji 64-bit

Once the CUDA toolkit is installed a computer restart might be required before stitching can take advantage of your GPU.

CUDA Toolkit v6.5 installation on Windows/Linux/MacOSX

1. Download CUDA toolkit v6.5 for the appropriate operating system version CUDA Toolkit 6.5
2. Install the CUDA Tookit
   1. For Windows: Launch the executable and complete the installation
   2. For MacOSX: Toolkit MacOSX installation guide
   3. For Linux: Toolkit Linux installation guide
3. Restart your computer
4. Open Fiji and run MIST plugin
5. CUDA option should be available in the MIST plugin.