ImageJ

Selective Plane Illumination Microscopy Registration (ImageJ)
Author	Stephan Preibisch, Stephan Saalfeld, Johannes Schindelin, Pavel Tomancak
Maintainer	Stephan Preibisch
File	SPIM_Registration.jar
Initial release	February 2010
Latest version	September 2011
Category	SPIM Registration
Website	Stephan Preibisch's homepage

Important Note

Please Note: This version of the software is outdated. It will be part of Fiji for the time being, but I highly recommend using the new Multiview Reconstruction Plugin. It is much more powerful, flexible and completely integrated with the BigDataViewer.

Citation

Please note that the SPIM registration plugin available through Fiji, is based on a publication. If you use it successfully for your research please be so kind to cite our work:

S. Preibisch, S. Saalfeld, J. Schindelin and P. Tomancak (2010) "Software for bead-based registration of selective plane illumination microscopy data", Nature Methods, 7(6):418-419. Webpage PDF Supplement

For technical details about the bead-based registration method and SPIM imaging see SPIM Registration Method.

Overview of the deprecated SPIM bead-based registration plugin

The SPIM Registration plugin reconstructs an image from several input images, called views. For this reconstruction process some parameters defining the input and output data are required. The user has to define the naming convention of the input images, an approximate bead-brightness as well as the strategies for creating the fused output image.

Creating a cropped output image

As the output images are typically very big (bounding box around all registered views) it is strongly recommended to define a cropping area where the imaged sample is positioned in the output image. As this is not possible in the first run, there is an option to first create a down-sampled version of the output image from which one can extract the cropping area. By running the plugin again and loading the previous registration parameters the cropped full-resolution output image can be created efficiently.

Downloading example dataset

There is a 7-angle SPIM dataset of Drosophila available here. The cropping parameters pre-set in the plugin fit this dataset, only the appropriate folder has to be defined.

System requirements

Multi-view SPIM datasets are typically rather large, therefore it is recommended to use the registration plugin on a computer with a lot of RAM. The minimal requirement for the example dataset is at least 4Gb of memory however we recommend an 8Gb system. You may need to increase the Fiji memory limit by going to Edit->Options->Memory & Threads.

Using the Plugins

There are three plugins which take those input parameters in different formats:

SPIM Registration: Allows the registration of SPIM data with a subset of necessary options presented in the graphical user interface
Multi-Channel SPIM Registration: Extends the SPIM Registration to multiple channels and allows to override the z-stretching saved in the input files.
Advanced SPIM Registration: Registration of SPIM data using all possible options via loading a configuration file

Processing a Time Lapse Acqusition

Processing a time lapse acquisition requires two steps. In the first step the registration for each individual timepoint has to be computed and will be automatically stored. Therefore, in the first pass, input the timepoints that should be processed in Time Points to process (e.g. 1-100), check Register only (no fusion) and uncheck Timelapse processing. After the registration is performed one timepoint has to be selected as reference timepoint, typically one with a low registration error. This timepoint should be fused to determine the correct cropping area which will afterwards be applied to all other timepoints.

After all individual timepoints are registered and the cropping area is defined the plugin has to be called again. This time check Timelapse Registration, insert the Reference Timepoint, uncheck Register only (no fusion) and insert the coordinates of the cropping area of the reference timepoint. The created output images can be viewed for example with Plugins->Image5D->Virtual Image 5D Opener [1].

deprecated SPIM bead-based registration

Shows the SPIM Registration Dialog.

SPIM Data Directory: Fill in the directory name that contains all the image files. You can either drag&drop the directory, browse for it or type the name directly.

Time Points to process: Define the timepoint(s) that should be processed. You can give single numbers (e.g. 18), enumerate (e.g. 1, 18, 19, 100), define ranges (e.g. 1-18) or combine all of them in any combination wanted (e.g. 1,2,10,20-50).

Pattern of SPIM files: Define the naming convention of the input files by explaining how the angle and the timepoint is encoded into the filename. For example the file names are named in following way
spim_tl1_angle0.lsm, spim_tl1_angle45.lsm ... spim_tl1_angle270.lsm
spim_tl2_angle0.lsm, ... spim_tl2_angle270.lsm
spim_tl100_angle0.lsm, ... spim_tl100_angle270.lsm.
That means the pattern of the file names corresponds to spim_tl{t}_angle{a}.lsm, where {t} is replaced with the current timepoint and {a} with the current angle. If the numbers contain leading zeros (e.g. 000, 045, 090, 135 instead of 0, 45, 90, 135), this can be encoded by simply adding more letters to the placeholder, in this case {aaa}.

Angles to process: Define the angles (at least 2) that should be processed (for each timepoint if applicable). You can enumerate angles (e.g. 0, 90, 180, 270), define ranges in steps (e.g. 0-270:45 which means use angle 0 to 270 in steps of 45, i.e. 0, 45, 90, 135, 180, 225, 270) or combine all of them in any combination wanted (e.g. 0, 45, 180-270:45).

Timelapse processing: Checked if a timelapse processing should be performed. In this case the pre-registered timepoints are re-registered to one reference timepoint which results in an aligned time series.

Reference Timepoint: Define the reference timepoint for timelapse processing if timelapse processing above is checked.

Load segmented beads: If the registration of the time point is carried out more than once (to recompute the registration) the initial segmentation of the beads can be loaded to speed up processing. Note: if Load registration is checked, Load segmented beads is implicitly checked as well.

Bead Brightness: Define the brightness of the used beads relative to the sample.

Load Registration: If the registration of the time point is carried out more than once (either to define the correct cropping area or to perform timelapse processing) the initial segmentation of the beads and the final affine matrices of the views can be loaded to speed up processing. Note: if Load registration is checked, Load segmented beads is implicitly checked as well and Display registration will be ignored.

Register only (no fusion): Checked if no fusion of the data should be performed.

Display registration: This will display an interactive window visualizing the global optimization process. Note: This slows down the optimization.

Fusion Method: There are three options available.
Fuse all images at once loads all the input images and computes the output image. This is the fastest method but it also needs significant amouts of RAM.
Fuse images sequentially loads one input image after the other and computes the contribution sequentially. This is significantly slower but typically uses less RAM. However, this methods needs to allocate the output image twice during the fusion process as it needs to store image content and weights separatetly.
Create independent registered images is a special output option where each view is transformed into a compatible bounding box and written as a separate file for further processing.

Fusion use Blending: Checked if blending at the edges of the overlapping views should be applied; this removes brightness differences at the hyperplanes where the overlapping images intersect. Note: If neither Blending nor Content based Weightening is selected, only averaging is performed for fusion.

Fusion use Content based Weightening: Checked if the content-based weightening should be used; this weights each pixel of each view by its local information content and thereby increases the contrast of the output image. Note: The content based weightening is rather fast but consumes a lot of RAM. If neither Blending nor Content based Weightening is selected, only averaging is performed for fusion.

Output Image Scaling: The factor defines the downsampling of the output image, e.g. 2 means that the output image will be half as big in each dimension and therefore need 8x less RAM than the full resolution output image. This is especially useful if the bounding box around the imaged sample (defined below) is not known yet as has to be determined.

Crop Offset Output Image X/Y/Z: Defines the cropping offset in the x/y/z-dimension of the output image relative to the uncropped image. A value of 0 means no cropping. Note: All the values are relative to the downsampling factor in Output Image Scaling.
Crop Size Output Image X/Y/Z: Defines the cropped size in the x/y/z-dimension of the output image relative to the uncropped image. A value of 0 means no cropping. Note: All the values are relative to the downsampling factor in Output Image Scaling.

Plugin Wishlist

When you find some features that you would like to be added to the plugin, please write them down here

Change Z-Stretching in Plugin
Automatic Timelapse processing
Preview (e.g. Max Projections of first angle) if register only checked and more than one timepoint

Multi-Channel SPIM Registration

The multi-channel SPIM Registration extends the normal registration by the ability to register multiple channels and to override the resolution (xy, z) stored in the files. Therefore two new options are available

Channels to process: Define the channel(s) to process. You can give single numbers (e.g. 0), enumerate (e.g. 1, 2), define ranges (e.g. 1-3) or combine all of them in any combination wanted (e.g. 1,3-4).

Override file dimensions: Check this box to override the axial and lateral resolution stored in the input files.

xy resolution (um/px): Define the xy-resolution in um per pixel, note that only the ratio between xy and z-resolution is used.

z resolution (um/px): Define the z-resolution in um per pixel, note that only the ratio between xy and z-resolution is used.

Advanced SPIM Registration

Shows the Advanced SPIM Registration Dialog.

For advanced SPIM registration all available parameters can be tuned using two configuration files (configuration.txt and VariablesAssignment.txt, see below). Contact the author for further details [2].

configuration.txt

### Configuration file for SPIM Registration
### ----------------------------------------
###
### The first line is the filename for the linkage from the entries in this file to the
### variable names in java. It is very important and you only need to change this
### if you change the source code.
###
### The rest of the file is divided into sections where you can change different
### types of parameters. Really important is the Input files section. Change it
### according to your experiment data.

<VariablesAssignment.txt>

###
### Section: General Parameters
###

Time Point Pattern = "18"
Acquisition Angle Pattern = "0-270:45"
# The input files can be in any format that Fiji can read.
# They need to be 3D stacks with correct calibration, though.
Input File Pattern = "spim_TL{t}_Angle{a}.lsm"
Input Directory = "F:\Stephan\dros\"
Output Directory = "F:\Stephan\dros\output"
Registration File Directory = "F:\Stephan\dros\registration\"
Debug Level = "DEBUG_MAIN"
Show ImageJ Window = true

###
### Section: Time Lapse 
###

Time Lapse Registration = false
Reference Time Point = 1

###
### Section: Data Structures, Access and Paging
###

Factory for Images during Segmentation = ArrayContainerFactory()
Factory for Recursive Gauss = ArrayContainerFactory()
Factory for Images during Fusion = ArrayContainerFactory()
#Factory for Output Images = ArrayContainerFactory()
Factory for Entropy = ArrayContainerFactory()
Factory for Scale Space = ArrayContainerFactory()

#Factory for Images during Segmentation = CubeContainerFactory(16)
#Factory for Recursive Gauss = CubeContainerFactory(16)
#Factory for Images during Fusion = CubeContainerFactory(16)
Factory for Output Images = CubeContainerFactory( 256 )
#Factory for Entropy = CubeContainerFactory(16)
#Factory for Scale Space = CubeContainerFactory(35)

Paging Temporary Directory = null

Out of Bounds Strategy for Fusion = OutsideStrategyValueFactory(0)
Out of Bounds Strategy for Gauss = OutsideStrategyMirrorFactory()
Interpolator for Output Image = LinearInterpolatorFactory()

###
### Section: Main Switches
###

Write Output Image = true
Show Output Image = true
Segmentation Use Scale Space = true
Fusion Use Entropy = false
Fusion Use Gauss = false
Fusion Use Blending = false

Fuse all Images at once = false
Fuse Images sequentially = false
Number of Paralell Views = 4
Create multiple registered Output Images = true    

Register Only = false
Display Registration = false
Read Segmentation = true
Write Segmentation = true
Read Registration = false
Write Registration = true

###
### Section: Image Parameters
###

Override Z-Stretching of Image = true

# 20x, 2um z spacing ( 2.0 / 0.73 )
Image Z-Stretching = 2.739726027397260273972602739726

Image Background = 0

###
### Section: Threshold Bead Segmentation
###

Bead Segmentation Threshold = 0.9
Bead Segmentation Fixed Threshold = 0.02
Bead Segmentation Use Fixed Threshold = true 
Bead Segmentation Circularity Factor = 0.5
Bead Segmentation Minimum Black Border around Bead = 1
Bead Segmentation Minimum Bead Size = 10
Bead Segmentation Maximum Bead Size = 13375
Bead Segmentation Use Center of Mass = false

###
### Section: Scale Space Bead Segmentation
###

Bead Scale Space Minimum Peak Value = 0.01
Bead Scale Space Minimum Initial Peak Value = 0.005
Bead Scale Space Identity Radius = 3.0
Bead Scale Space Maxima Tolerance = 0.01
Bead Scale Space Image Sigma = 0.5
Bead Scale Space Initial Sigma = 1.4
Bead Scale Space Steps per Octave = 4
Bead Scale Space Steps = 3
Bead Scale Space Number of Threads = 0

###
### Section: Point Descriptor and Global Optimization
###

Point Descriptor Difference Threshold = 50
Point Descriptor Ratio of Distance = 10
Point Descriptor Number of Neighbors = 3
Point Descriptor Use Associated Beads = false   
Point Descriptor Use RANSAC = true

RANSAC Maximum Epsilon = 5
RANSAC Minimum Inlier Ratio = 0.1  
RANSAC Number of Iterations = 1000

# p__ = ( 1 - r^n ) ^ k
# k = log(p__) / log ( 1 - r^n )

# p__ ... probability that ransac fails
# r   ... min inlier ratio
# n   ... minimal number of points needed to create model
# k   ... number of iterations 

###
### Section: Output Image
###

Output Image Scale = 1

Output Image Crop Offset X = 0
Output Image Crop Offset Y = 0
Output Image Crop Offset Z = 0
Output Image Crop Size X = 0
Output Image Crop Size Y = 0
Output Image Crop Size Z = 0


Output Image Number of Threads = 0

###
### Section: Volume Injection
###

Volume Injection Sigma = 0.25
Volume Injection Cut Off Radius = 2

###
### Section: Entropy
###

Entropy Histogram Bins = 256
Entropy Window Size X = 25
Entropy Window Size Y = 25

###
### Section: Blending
###

Blending Alpha = 1.5

###
### Section: Gauss Fusion
###

Gauss Fusion Sigma 1 = 20
Gauss Fusion Sigma 2 = 40

VariablesAssignment.txt

Input File Pattern = String inputFilePattern
Time Point Pattern = String timepointPattern 
Acquisition Angle Pattern = String anglePattern
Input Directory = String inputdirectory 
Output Directory = String outputdirectory
Registration File Directory = String registrationFiledirectory
Debug Level = String debugLevel
Show ImageJ Window = boolean showImageJWindow

Time Lapse Registration = boolean timeLapseRegistration
Reference Time Point = int referenceTimePoint

Factory for Images during Segmentation = ContainerFactory imageFactory
Factory for Recursive Gauss = ContainerFactory recursiveGaussFactory
Factory for Images during Fusion = ContainerFactory imageFactoryFusion
Factory for Output Images = ContainerFactory outputImageFactory
Factory for Entropy = ContainerFactory entropyFactory
Factory for Scale Space = ContainerFactory scaleSpaceFactory

Paging Temporary Directory = String tempDir

Out of Bounds Strategy for Fusion = OutsideStrategyFactory strategyFactoryOutput	
Out of Bounds Strategy for Gauss = OutsideStrategyFactory strategyFactoryGauss
Interpolator for Output Image = InterpolatorFactory interpolatorFactorOutput

Write Output Image = boolean writeOutputImage
Show Output Image = boolean showOutputImage
Segmentation Use Scale Space = boolean useScaleSpace
Fusion Use Entropy = boolean useEntropy
Fusion Use Gauss = boolean useGauss
Fusion Use Blending = boolean useLinearBlening

Fuse all Images at once = boolean paralellFusion    
Fuse Images sequentially = boolean sequentialFusion
Number of Paralell Views = int numParalellViews  
Create multiple registered Output Images = boolean multipleImageFusion    

Register Only = boolean registerOnly
Display Registration = boolean displayRegistration
Read Segmentation = boolean readSegmentation
Write Segmentation =  boolean writeSegmentation
Read Registration = boolean readRegistration
Write Registration = boolean writeRegistration   

Override Z-Stretching of Image = boolean overrideImageZStretching
Image Z-Stretching = double zStretching
Image Background = int background
	
Bead Segmentation Threshold = float threshold
Bead Segmentation Fixed Threshold = float fixedThreshold
Bead Segmentation Use Fixed Threshold = boolean useFixedThreshold 
Bead Segmentation Circularity Factor = double circularityFactor
Bead Segmentation Minimum Black Border around Bead = int minBlackBorder
Bead Segmentation Minimum Bead Size = int minSize
Bead Segmentation Maximum Bead Size = int maxSize
Bead Segmentation Use Center of Mass = boolean useCenterOfMass

Bead Scale Space Minimum Peak Value = float minPeakValue
Bead Scale Space Minimum Initial Peak Value = float minInitialPeakValue
Bead Scale Space Identity Radius = float identityRadius
Bead Scale Space Maxima Tolerance = float maximaTolerance
Bead Scale Space Image Sigma = float imageSigma
Bead Scale Space Initial Sigma = float initialSigma
Bead Scale Space Steps per Octave = int stepsPerOctave
Bead Scale Space Steps = int steps
Bead Scale Space Number of Threads = int scaleSpaceNumberOfThreads

Point Descriptor Difference Threshold = double differenceThreshold
Point Descriptor Ratio of Distance = double ratioOfDistance
Point Descriptor Number of Neighbors = int neighbors
Point Descriptor Use Associated Beads = boolean useAssociatedBeads    
Point Descriptor Use RANSAC = boolean useRANSAC

RANSAC Maximum Epsilon = float max_epsilon
RANSAC Minimum Inlier Ratio = float min_inlier_ratio   
RANSAC Number of Iterations = int numIterations

Output Image Scale = int scale
Output Image Crop Offset X = int cropOffsetX
Output Image Crop Offset Y = int cropOffsetY
Output Image Crop Offset Z = int cropOffsetZ
Output Image Crop Size X = int cropSizeX
Output Image Crop Size Y = int cropSizeY
Output Image Crop Size Z = int cropSizeZ
Output Image Number of Threads = int numberOfThreads

Volume Injection Sigma = float sigma
Volume Injection Cut Off Radius = int cutOffRadiusGauss

Entropy Histogram Bins = int histogramBins
Entropy Window Size X = int windowSizeX
Entropy Window Size Y = int windowSizeY

Blending Alpha = float alpha

Gauss Fusion Sigma 1 = float fusionSigma1
Gauss Fusion Sigma 2 = float fusionSigma2