Lewys Jones's Research

Features - Download - User Manual - Support

This user guide contains the information on how to install, configure and run the Jitterbug distortion correction code. Jitterbug is continually being improved based on user feedback so please check the support page for update notifications and changelogs.

User Manual Quick Links:

Installation    -    Configuration    -    Running Jitterbug    -    Results


(return to top)

Jitterbug Componant Files

As Jitterbug is being activley developed and improved small updates may be distributed frequently. To facilitate this it is built from several modules each of which can be updated seperatly. The table below outlines the files that you should have in your installation, their purpose and the most current version. Before running Jitterbug for the first time users should check all these files are present in the same folder along with the image file to be processed.

File Purpose Current Version Release Date
Jitterbug_Wrapper Sets up the user variables for the image restoration. 3.6 20th September 2013
Jitterbug_Core Coordinates the image handling and restoration. Calls the horizontal, vertical and drift restoration modules as required. 3.6 20th September 2013
Jitterbug_license_check Check the validity of the current version. 1.0 20th September 2013
File_Opener Opens image files of various types and passes image data to "Jitterbug_Core". 1.5.3 12th September 2013
Horizontal_Restoration_Module Perfroms the horizontal restoration. Called once for each processing iteration. 1.8.3 20th September 2013
Vertical_Restoration_Module Contains the code to perform vertical distortion correction. 1.6 22nd April 2013
Drift_Restoration_Module Performs the drift correction. 0.6 22nd April 2013
Hawkeye_Core Performs the image resolution & SNR quantification. 1.3 20th September 2013
Ranger Core Performs the peak-finding. 2.2 13th September 2013
ReadDM3* Allows "File_Opener" to handle Gatan .dm3 files. - 19th March 2010
serReader* Allows "File_Opener" to handle FEI .ser files. - 6th August 2009
HodPres_filter* Used to smooth the determined probe-offset data. - -
peakdet* Used to identify spectrum peaks and line profile positions. 3.4.05 -

In addition to the above the Matlab Image-processing, Statistics and Curve-fitting Toolboxes are required to use Jitterbug.

Example Installation

The image below shows a typical installation of Jitterbug (ordered alphabetically). All the componant files must be in the same folder as each other. The image to be processed may be in any folder.

Typical Jitterbug Installation


(return to top)

Setting the Restoration Variables

The Jitterbug wrapper file sets up all the input variables needed to process the image to the user’s specification. Before running the code each of the variables should be verified. Once verified however these will only need modifying rather than entireley resetting each time. The following table defines the action of each input variable.

Variable Purpose Default / Recommended Value Input Restrictions Notes
correct_horizontal_distortion Selects which distortion types to correct and hence which restoration modules to run. 1 1 - for Yes, or 0 - for No. -
correct_vertical_distortion 1 -
correct_drift 1 For low SNR images automatic correction can return an invalid restoration. For low SNR images specify manual drift parameters below or disengage this correction.
correct_AFM_STM_height 0 This should onlt be used with AFM / STM data exhibiting horizontal banding from tip height errors.
use_fast_mode Reduces run-time when accurate instability spectrum is not required. 0 -
number_iterations The number of times the horizontal distortion will be iteratively analysed and corrected. 3 Positive integers only. Apart from initial and terminal image quantification proecssing time scales linearly with this variable. Additional iterations will not necessarily give any improvement in SNR or resolution.
pixel_dwell_time Used to calibrate the distortion frequency spectrum axis. No default, user must enter value. Can usually befound in the digiscan tags saved in the images. Positive non-zero numbers only. Units of micro-seconds.
bright_field Used to calibrate the distortion frequency spectrum axis. 0 0 for normal dark-field 1 for bright-field (experimental feature). -
auto_detect_drift Select between automatic and manual drift correction 1 1 - for automatic, or 0 - for manual. For low SNR images drift should be specified manually if known, or if unknown drift correction should not be used.
shear_orientation The direction of the drift vector. Not applicable. Positive non-zero numbers only. North or 12 noon is zero degrees.
shear_strength The magnitude of the drift vector. Has units of degrees equivalent shear.
Variable Purpose Default / Recommended Value Input Restrictions Notes
best_size_override Allows the size of the quantification searh windown and restoration test-band to be overridden. 0 0 - for automatic, or 1 - for manual. This option is useful if a very rigourous comparison of two images is needed but the manually selected variables must be carefully chosen as they will affect the restoration results greatly.
manual_best_size Specifies the manual size of the image quantification search window. Not applicable. Positive non-zero odd numbers only. If specified manually this (odd) number should be just less than the number of pixels between atomic columns.
manual_testband_size Specifies the manual size of the restoration neighbour inspection test-band. If specified manually this (odd) number should be around half the number of pixels between horizontally adjacent features.
angle_steps Specifies the angular sensitivity when searching for lattice planes / direction. 180 Positive non-zero numbers only. The number of test angles per 180 degrees. A value of 180 corresponds to nearest whole degree accuracy, 360 corresponds to nearest 0.5 degrees. Will affect the image quantification process run-time approximately linearly.
directions Specifies the number of lattice plane directions the code should search for. 4 / 6 Any positive non-zero integer but usually 3, 4, 6 or 8. This should be specified as either 4 or 8 for cubic symmetry materials / projection and 3 or 6 for hexagonal. The choices of 8 or 6 will require a higher SNR image in order to return valid answers.
repeats_per_direction Specifies the number of real-space line profiles to collect from each lattice plane orientation for SNR measurement. 5 Positive non-zero integers. This number multiplied by the number of directions will give the total number of line-profiles to be used for SNR determination.
Variable Purpose Default / Recommended Value Input Restrictions Notes
quantify_images Allows the user to select whether or not to quantify before and after images. 1 0 - for no, or 1 - for yes. This process will add a couple of minutes to the start and end of the main restoration.
overide_features Allows the user to overide the total number or atoms used for resolution measurment. 1 0 - for automatic, or 1 - for manual. On automatic (0) the code will use ever atom available to calculate the average resolution. If there are many hundred this will take excessive time.
survey_features Allows the number of features for resolution measurement to be specified. 25 Positive non-zero integers. Must also be less than the number of atoms present in the image.
show_progress Allows the user to specify whether image quantification progress is displayed. 1 1 - for Yes, or 0 - for No. As these options cause figures to be redrawn during processing they will add a small time overhead to the overall restoration. They are however useful in optimising restoration variable or bug fixing. Experienced users may benefit from a slight speed improvement from disabling the display outputs.
display_results Allows the user to specify whether image restoration progress is displayed. 1
display_large Gives the user the choice of displaying large versions of raw and processed images and FTs upon completion. 1 -
export_image Gives the user the choice to save the restored image as .bin, .txt, .bmp and .mat file formats. 1 -

Running Jitterbug

(return to top)

Once the above parameters have been selected in the Jitterbug_Wrapper file simply press run (or F5).

The restoration then proceeds in the folloing stages which are described in turn below:

  1. The image is read in to the workspace by the'File_Opener' module.
  2. The raw image resolution, SNR and drift is quantified by the 'Hawkeye_Core' module.
  3. Horizontal scan-distortion is corrected by the 'Horizontal_Restoration_Module'.
  4. Vertical scan-distortion is corrected by the 'Vertical_Restoration_Module'.
  5. Drift is corrected using the 'Drift_Restoration_Module'.
  6. After all restoration is complete the process image is quantified again.

1 - File Reading

If a .DM3 file was selected the greyscale image will be extracted from the fil by the 'ReadDM3' function.

2 - Raw Image Quantification

If "quantify_images" was set to 1, then the raw image signal-noise ratio and resolution will be determined. This process will take an additional two - four minutes depending on system speed. As part of this stage a peak-finding algorithm will run which requires the user to select a background grey level. Instructions for the peak-finding are described here

3 - Horizontal Distortion Correction

Next the horizontal scan distortion will be analysed and corrected throughout the image working from top to bottom. As this progresses a frequency spectrum will be shown below the image indicating the most likely determined contributions to the distortion in the image. These identified frequencies may be useful in determining sources of distortion in the microscope suite.

4 - Vertical Distortion Correction

After horizontal distortions have been corrected the vertical distortion will be determined and compensated for on a feature-by-feature basis (atom-by atom). Once this is complete, if the user selected more than a single iteration to be performed, a reference image will be returned to run stages three and four again.

5 - Image Drift Measurement and Correction

Once the target number of iterations has been completed drift in the image will be determined and then corrected via a 2D image transformation.

6 - Restored Image Quantification

Once all image restoration is complete, the largest possible square area will be cropped form the data and then passed to the image quantification module once more.

Jitterbug Results

(return to top)

After completion the workspace will be cleared. However, Jitterbug can save the restored image as a .bin, .txt, .bmp or .mat file. These formats can then be imported into other packages such as Digital Micrograph. To enable this option just set "export_image" equal to 1.

* MatLab function files available from MatLab Central.

  • "ReadDM3" was developed by Fred Sigworth and Liguo Wang at Yale University.
  • "serReader.m" was developed by Peter Ercius at the National Center for Electron Microscopy (NCEM).
  • "HodPres_filter" was developed by Wilmer Henao.
  • "peakdet" was developed by Eli Billauer.

  • Content © 2012 Lewys Jones - layout & design by Vincent Chan