User Guide
- Launching MIST
- Installation Validation Test
- MIST Graphical User Interface
- Input Parameters
- Output Parameters
- Subgrid Parameters
- Advanced Parameters 1. Java Execution 2. FFTW Execution 3. CUDA Execution
- Help
- MIST Status Frame
- Docker Execution of MIST
- Command-line Execution of MIST
- Start Fiji.
- Click through the menus: Plugins >> Stitching >> MIST
- Click: MIST
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.
- Download test images: Cy5_ImageTiles.zip ~ 54 MB
- Extract Cy5_ImageTiles.zip into a directory
- Launch MIST plugin from Fiji
- Select Load Params and open '[extractionPath]/Small_Fluorescent_Test_Dataset/stitching-params.txt'
- To manually enter parameters (avoiding Load Params) enter the following values into the Input Tab
- Filename Pattern Type: 'Row-Column'
- Filename Pattern: 'img_r{rrr}_c{ccc}.tif'
- Starting Point: 'Upper Left'
- Grid Width: '5'
- Grid Height: '5'
- Modify Image Directory to '[extractionPath]/Small_Fluorescent_Test_Dataset/image-tiles'
- Select the Output tab and update Output Directory to define where the output files are to be saved
- Set Blending Mode: to 'Overlay'
- Update Display Stitched Image and Save Full Stitched Image to selected/enabled
- To check the parameters defining the image grid, select Preview (0% overlap) which should generate and display a zero percent overlap tiling of the input images
- Click Begin Stitching to launch
- Compare the newly generated stitched image to the reference stitched image shipped with the test dataset
- Open '[extractionPath]/Small_Fluorescent_Test_Dataset/stitched-image/img-stitched-0.tif' in Fiji.
- Check that the new stitched image has the same dimensions as the reference
- Perform a pixel-wise comparison between the stitched images 1. Fiji>>Process>>Image Calculator 2. The operation new stitched image "Difference" reference stitched image should produce an image containing all zeros when using the correct parameters
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.
Save Params Button - Saves all parameters in MIST to a file.
Preview (0% overlap) Button - Opens the image mosaic into Fiji assuming 0% overlap.
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.
* Filename Pattern Type - Used to specify the type of filename pattern used in the acquired images. Possible options: Sequential and Row-Column.
Sequential:
Sequential pattern images have a single number representing their position within the image grid. Example: img_pos001_c01.tif = img_pos{ppp}_c01.tif {ppp} - Special text that represents position numbering between 0 and 999. Increase the number of p's to represent larger numbers.Row-Column:
Row-Column pattern images have a pair of numbers representing their position within the image grid. Example: img_r01_c01.tif = img_r{rr}_c{cc}.tif {rr} - Special text that represents row numbering between 0 and 99. Increase the number of r's to represent larger numbers. {cc} - Special text that represents column numbering between 0 and 99. Increase the number of c's to represent larger numbers.
* Starting Point - The starting point of the microscope scan. Possible options: Upper Left, Upper Right, Lower Left, and Lower Right. This specifies the origin for the grid of images.
* Direction - The direction and pattern of the microscope motion during acquisition. Possible options: Vertical Combing, Vertical Continuous, Horizontal Combing, and Horizontal Continuous.
* 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.
Discover Width/Height Button - Attempts to automatically discover the width and height of a row-column filename pattern type acquisition given a valid filename pattern and image directory.
* Filename Pattern - Used to load images from a directory. Changes based on the Filename Pattern Type. Important: the character "%" cannot be used as part of a filename pattern.
- If the Filename Pattern Type = Sequential, then the Filename Pattern expects sequential style numbering. We support all filename types that ImageJ supports. For a list of supported types, please refer to ImageJ User Guide
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 Filename Pattern Type = Row-Column, then the Filename 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.
Assemble from metadata - Generates the image mosaic using metadata from a previous run. Important: You must specify the global-positions file to use in the Global Positions File field. If your Filename Pattern has a time slice iterator "{tt}" then the global-positions file specified must also.
Global Positions File - The filepath to the global-positions file to use in assembling from metadata. Note: this must be the filepath of an individual global-positions file, not the directory containing a global-positions file. Note: If you Filename Pattern has a time slice iterator "{tt}" then the global-positions file specified must also.
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-{#}.tif
- **{namePrefix}**statistics.txt
- **{namePrefix}**log.txt
- {namePrefix}global-positions-{#}.txt
- {namePrefix}relative-positions-{#}.txt
- {namePrefix}relative-positions-no-optimization-{#}.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.
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.
Warning: Large image grids can cause out of memory errors. If the number of pixels in the output stitched image exceeds 2147483647 (231-1), then the stitched image must be exported using an alternative method. (imagePixelWidth*imagePixelHeight < 2147483647)
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.
Suppress SubGrid Warning Dialog Box - suppress the warning dialog box that gets displayed when stitching a subgrid. The warning dialog is useful if you infrequently stitch subgrids to prevent inadvertently stitching a subgrid.
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. This value is specified in pixels.
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. This value is specified in percent. The value must be between 0 and 100.
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. This value is specified in percent. The value must be between 0 and 100.
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. This value is specified in percent. The value must be between 0 and 100. This value should generally not exceed 10. (Default: 5)
Use BioFormats Image Reader? - Specifies whether to use the BioFormats image reader as opposed to the ImageJ image reader. The ImageJ reader supports most common image file types and is faster than BioFormats. If the ImageJ reader cannot read an image being stitched, try using BioFormats as it supports more image types.
Use Double Precision Math? - Specifies whether the FFTs and other stitching computation is done using 32bit floats of 64bit doubles. The default is 32bit, but if you are not getting a satisfactory stitching try using double precision.
Translation Refinement Method - Specifies the type of translation refinement that is performed. Once the translations between images have been computed, the stage model is built to constrain the translations to reasonable values. Within the search space defined by the stage model an optimization of the pairwise translations takes place. The method of translation optimization/refinement is selected here. The default is a single hill climbing starting at the computed/estimated translation. This is the fastest option. If this proves ineffective for your dataset, multipoint hill climbing is available where, in addition to performing a hill climbing starting at the computed/estimated translation, n starting points are randomly selected within the search bounds and allowed to converge to local maxima. The number of starting points is user selected (default of 16). This is more robust than the single hill climb, but more computationally intensive. The final option, Exhaustive, checks every possible translation within the stage model bounds. This is extremely slow.
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)
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.
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.
CPU worker threads - Number of parallel workers to spawn (should not exceed number of CPU cores)
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.
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.
Open Local Help Documentation - Opens this document without an Internet connection.
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
To use MIST outside of Fiji, you need to obtain a copy of the jar file with all the dependencies built in (as opposed to relying on Fiji). The easiest way to do so is to use the Docker container.
https://hub.docker.com/r/wipp/mist
Setting up docker on your system will likely be easier than downloading the java code, configuring the project, and compiling a jar file with all of the required dependencies.
Once you have docker installed, you can use the docker run example script in the repo to run MIST outside of Fiji.
https://github.com/usnistgov/MIST/blob/master/docker_example.sh
The valid args for the command line tool are included in that example script.
In order to use MIST from the command-line you will need to follow these installation instructions to build the executable Jar file: https://github.com/usnistgov/MIST/wiki/Install-Guide#compilation-from-source.
Required parameters (note some parameters change depending on if the pattern is row-column or sequential):
1. --filenamePattern <string containing filename pattern>
2. --filenamePatternType <ROWCOL/SEQUENTIAL>
3a. --gridOrigin <UL/UR/LL/LR> -- Required only for ROWCOL or SEQUENTIAL
3b. --numberingPattern <VERTICALCOMBING/VERTICALCONTINUOUS/HORIZONTALCOMBING/HORIZONTALCONTINUOUS> -- Required only for SEQUENTIAL
4. --gridHeight <#>
5. --gridWidth <#>
6. --imageDir <PathToImageDir>
7a. --startCol <#> -- Required only for ROWCOL
7b. --startRow <#> -- Required only for ROWCOL
7c. --startTile <R> -- Required only for SEQUENTIAL
8. --programType <AUTO/JAVA/FFTW> -- Highly recommend using FFTW
9. --fftwLibraryFilename libfftw3f.dll -- Required for FFTW program type
9a. --fftwLibraryName libfftw3f -- Required for FFTW program type
9b. --fftwLibraryPath <path/to/library> -- Required for FFTW program type
Example execution:
java.exe -jar MIST_-2.1-jar-with-dependencies.jar --filenamePattern img_r{rrr}_c{ccc}.tif --filenamePatternType ROWCOL --gridHeight 5 --gridWidth 5 --gridOrigin UR --imageDir C:\Users\user\Downloads\Small_Fluorescent_Test_Dataset\image-tiles --startCol 1 --startRow 1 --programType FFTW --fftwLibraryFilename libfftw3f.dll --fftwLibraryName libfftw3f --fftwLibraryPath C:\Users\user\apps\Fiji.app\lib\fftw
Example execution uses dataset: https://github.com/usnistgov/MIST/wiki/testdata/Small_Fluorescent_Test_Dataset.zip