Volume Electron Microscopy Registration (vEMreg) is a python (3.8 to 3.11) and java (11) library to automatically register/align stacks of images acquired using a focused ion beam scanning electron microscope (FIB-SEM).
This library uses an algorithm that is a stochastic version of TurboReg.





1 - Installation

vEMreg is pip installable, so open a terminal, preferably create a dedicated environment, and run:

$ pip install vEMreg

If vEMreg is already installed and you wish to upgrade it, then run:

$ pip install --upgrade vEMreg





2 - Quick start and examples

vEMreg can be executed/run using a command line or from a python script. Here is a quick example to check that everything is working fine.

This example contains:
  • A tiny dataset composed of 10 images of dimensions 6K x 4K in the directory "Data".
  • The registered/aligned result images in the directory "Data - Registered".
  • A directory name "Check" that will contain check / side view images to check the results quality.
  • A Python scrip "Registration.py" to reproduce the results
  • A command line that is identical to the Python script to reproduce the results.

So to reproduce the results, then run:

 $ cd /The/Path/To/The/Script/
$ python Registration.py

Or the following command line:

 $ cd /The/Path/To/The/Data/
$ vEMreg --dataDir="./Data/" --resultsDir="./Data - Registered/" &

Based on the example above, a directory named "Data - Registered" will be automatically created and will contain the registered results along with the validation/check images.





3 - Keywords / parameters

  • 'dataDir' (string, required): The path to the raw (not yet registered) data/images.

  • 'imName' (string): The name of the reference/target image. It's the first image that will be used as reference to register the others, so usually the central image. Default to null, so the central image will be automatically used.

  • 'nIterations' (int): The number of transformations to compute for each pair of images to register. Default to 7 (minimum recommended), cannot be smaller than 5, and the higher the slower the registration but more stable.

  • 'transformation' (string): The type of transformation to use among Affine (default) and Bilinear.

  • 'aggressive' (boolean): Are the points picked up with an aggressive way? If true, then they are picked up closer to the images border. Default to false. The closer to the image border the points are, the more stable the registration is, but it would become an issue if the stage drifted significantly during acquisition, in which case the points might end up in the transformed/empty border.

  • 'safetyLevel' (int): 0 means no checking during registration, 1 means basic checking, 2 means advanced checking. Default to 2 and highly recommended.

  • 'resultsDir' (string): The path to the directory where the aligned/registered images will be saved. Default to "./Registered/".

  • 'nCores' (int): The number of cpu cores to use. Default to 6.

  • 'debug' (boolean): Use debugging mode? If true more outputs will be displayed and the transformation matrices will be saved. Default to true, recommended.

  • '
  • ' (string): the amount of memory (RAM) allocated to the Java part of the software at start. It's the Xms JVM option. Default to 8G.

  • 'Java_Xmx' (string): the maximum amount of memory (RAM) allocated to the Java part of the software. It's the Xmx JVM option. Default to 32G.





Acknowledgement: the images used in the example above were acquired by Jessica Riesterer at OHSU.