mag_distortion_estimate and correct
mag_distortion_estimate is used to estimate magnification distortions in electron micrographs using images of polycrystalline samples such as gold shadowed diffraction gratings. The measured distortion at a particular magnification can then be corrected in images of the sample using mag_distortion_correct. Both programs read images that are stored in MRC/CCP4 format. They were written by Timothy Grant and are described in [1]. This software is subject to Janelia Research Campus Software Copyright 1.1. For support, feedback and bug reports, please use the Magdistortion forum.
Please note that mag_distortion_correct currently reads and writes unsigned bytes when images/movies are stored as MRC files with Mode 0. The convention for Mode 0 MRC files has recently changed and signed integers are now used. Newer versions of IMOD's tif2mrc tool now write Mode 0 MRC files with the new convention and therefore, mag_distortion_correct will read these files incorrectly. Until this incompatibility is resolved users have the following options when using IMOD:
- Set an environment variable WRITE_MODE0_SIGNED to 0.
- Use the program newstack with the "-byte 0" option. Newstack can be used instead of tif2mrc.
- Use the clip program for converting or processing data with the option "-m ubyte".
- As of IMOD 4.8.53, there will be a "-B 0" option for tif2mrc.
- Use an older version of tif2mrc.
Alternatively, MRC files can be converted to a different mode, for example Mode 2 (float), using tools such as label (part of the MRC processing suite).
Installation instructions
Both mag_distortion_estimate and mag_distortion_correct are provided as compressed tar archives. Each archive contains a binary which should work on most modern 64-bit linux systems, and the src archive enabling the programs to be recompiled using the Intel fortran compiler.
Extracting the archives
The archives can be extracted using the following command on a linux system:
tar xfz mag_distortion_estimate_1.0.1.tar.gz
and
tar xfz mag_distortion_correct_1.0.1.tar.gz
which will create directories “mag_distortion_estimate_1.0.1” and “mag_distortion_correct_1.0.1”.
Using the binaries
Inside each of these directories is a sub-directory named “bin”, containing a pre-compiled binary which should work on most modern 64-bit linux systems. In most cases the program can be run using this directory by simply executing it, e.g.
./mag_distortion_estimate_openmp_8_18_15.exe
The programs prompt for input interactively, and help for each prompt can be obtained by typing a “?”.
Compiling from src
The full src archive is provided, enabling users to recompile from source if the binary will not run on their system. The code is written and tested using the Intel Fortran compiler, and we therefore recommend this compiler is used to compile the source. The package is an autotools managed system, and makefile can be generated with the following command:
./configure FC=ifort F77=ifort –enable-optimizations –enable-openmp
This command will run the configure script which will attempt to setup the compilation based on the current system, and will attempt to locate any required dependencies. If a required dependency is not found the script will throw an error, and the dependency must be installed and the configure re-run.
Once the configure script executes without error, the code can be compiled by typing
make
If the compilation finishes without error, the compiled binary will be located in the "src" directory.
