NRRD Mosaics

From NRIMS External Wiki
Jump to: navigation, search

Large mosaic images can be constructed from many smaller images captured by the Cameca NanoSIMS 50 prototype & 50L mass spectrometers. The individual images that make up the mosaic can either be acquired manually or as part of a chain analysis. Once a mosaic image has been constructed, it can be opened with the OpenMIMS plugin and processed just like any other image.

Mosaic image.
An example of a mosaic image. (White lines have been added for illustrative purposes only)



In order to construct and view mosaic images, the following requirements must be met:

The unu binary should be located somewhere in the users PATH such that the user can gets the following output when typing unu at the command line:

>> unu
          --- unu: Utah Nrrd Utilities command-line interface ---
     unu about ... Information about this program and its use
       unu env ... List relevant environment variables and their values
      unu make ... Create a nrrd (or nrrd header) from scratch
      unu head ... Print header of one or more nrrd files
      unu data ... Print data segment of a nrrd file
   unu convert ... Convert to another type (as if by cast, w/ optional clamp)

The mosaic_nrrd script should also be in the users PATH such the the user gets the following output when typing mosaic at the command line:

>> mosaic_nrrd -h
Usage: mosaic_nrrd [options] file1.nrrd file2.nrrd ...
    -t, --type mosaic_type           Choose type of mosaic to create ('grid' or 'fluid').
    -p, --prototype                  Data from prototype, reverse x-axis ('fluid' mode only).
    -c, --[no-]compress              Compress each input file to a single-plane image.
    -s, --[no-]scale                 Scale counts by number of planes in each input file.
    -l, --layout layout_filename     Specify grid layout file.
                                       (A text file containg input nrrd filenames; columns tab-separated, rows newline-separated)
    -o, --output output_filename     Specify output nrrd file.
    -h, --help                       Show this help message.


Step 1: Convert .im files to .nrrd files.
In order to construct mosaic images, the first thing that need to be done is to convert the image files from the .im format to .nrrd[1] format. This can be done in a batch job by the OpenMIMS plugin. Go to Utilies >> "Batch convert to NRRD" and select the images to convert. It is generally advisable to set the converter to auto track on the files by selecting the "Auto track" check box and typing in the number mass to track on. Generally the mass with the highest counts is the best mass to track against. Auto tracking is not required but will generally produce high quality images.

Once all the .nrrd files have been generated, the next step is to construct the mosaic using the mosaic_nrrd script. The next section provides instructions and example on how to do this.


The -t fluid option instructs the program to assemble the mosaic based on the position parameter specified in the .im which was carried over to the .nrrd file. This option is used by default

The -t grid option instructs the program to assemble the mosaic based on a layout file. This layout file must contain the file names with columns tab separated and rows line separated. When using this option, the -l filename option, specifying the layout file name, must also be used. An example layout file is provided below.

image1.nrrd	image2.nrrd
image4.nrrd	image3.nrrd

The -p or --prototype option is only to be used in certain cases where the NanoSIMS mass spectrometer x-axis is reversed. If you images appear to align in the y-axis but not the -x-axis than this option should be used. It only mork when in fluid mode.

The -c or --compress option instructs the program to compress the image into a signle plane mosaic. Using this option speeds up the runtime of the program and is therefore the default setting. If the user wishes to leave the final mosaic uncompressed (meaning it will have the same number fo planes as the individual tiles) then the user should use the --no-compress option. This option can not be used while in grid mode.

The -s or --scale option instructs the program to scale the intensity if the individual tiles. This option is useful in cases where one tile may more planes (and there for much higher counts) than other tiles in the mosaic. By default the --no-scale option is used.

The -l filename or --layout filename option is used only when in grid mode. It specifies the name of the layout file to be used to construct the mosaic. Uses grid.txt if none specified.

The -o or --output option tells the program what name to assign to the out file. If theis option is not specified than the output file will be named mosaic.nrrd.

The -h or --help option shows the help message.


Migrate to the directory with nrrd image files and make sure the unu binary and mosaic_nrrd script are in the PATH.

The following examples all produce the same output, a single plane mosaic image with filename mosaic.nrrd:

>> mosaic_nrrd *.nrrd
>> mosaic_nrrd -t fluid *.nrrd
>> mosaic_nrrd -t fluid -compress *.nrrd
>> mosaic_nrrd -t fluid -compress -o mosaic.nrrd *.nrrd

The following examples will generate a multi-plane mosaic image with filename mosaic_uncompressed.nrrd:

>> mosaic_nrrd -t fluid --no-compress -o mosaic_uncompressed.nrrd *.nrrd

The following example will consrtuct a single plane mosaic image with filename mosaic_uncompressed.nrrd according to layout file:

>> mosaic_nrrd -t grid -l layout_file.txt -o mosaic_uncompressed.nrrd *.nrrd