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
Installation
(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.
Configuration
(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:
- The image is read in to the workspace by the'File_Opener' module.
- The raw image resolution, SNR and drift is quantified by the 'Hawkeye_Core' module.
- Horizontal scan-distortion is corrected by the 'Horizontal_Restoration_Module'.
- Vertical scan-distortion is corrected by the 'Vertical_Restoration_Module'.
- Drift is corrected using the 'Drift_Restoration_Module'.
- 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.
Content © 2012 Lewys Jones - layout & design by Vincent Chan