IMOD Library libiwarp

The libiwarp library contains routines used for working with nonlinear transformations, referred to as warping transforms. These warping transforms are an extension of image distortion fields. Current versions of warping files can contain multiple transforms (e.g., one per section). Each transform consists of a linear component and a warping component. The latter can consist either of an array of X and Y displacements on a regular grid, or of a list of arbitrarily located points an X/Y displacement at each (referred to as control points).

Calls from Fortran take the identical arguments, except as noted (string lengths are omitted from Fortran calls). Sections are numbered from 1 instead of zero when calling from Fortran.

Header to include: warpfiles.h

Warping File Format

Functions for Manipulating Warping Files

LIST FUNCTIONS FROM warpfiles.c

Utility Functions for Warping Transformations

LIST FUNCTIONS FROM warputils.c

Warping Interpolation Function

LIST FUNCTIONS FROM warpinterp.c

Functions for Magnification Gradients

LIST FUNCTIONS FROM maggradfield.c

Warping File Format

The library outputs files in version 3 and can read files in versions 1, 2, or 3. Version 3 files start with the header lines:
   3
   nx   ny  nz  binning  pixelSize flags
Here nx and ny are the sizes of the images on which a warping or distortion field was measured,
binning is relevant only for distortion fields, and is the absolute binning of the images, including any binning on the camera
pixelSize is the pixel size in Angstroms of the images, corresponding to the pixel spacing reported by the standard header output.
flags is an OR of a set of bit flags:
1 if the warping component is an inverse transform
2 if the warping specified by control points instead of a regular grid
For a regular grid, each transformation then has the following lines
   xStart  xInterval   nxGrid  yStart  yInterval  nyGrid
   a11  a12  a21  a22  dx  dy
   deltaX deltaY deltaX deltaY ...
   ...
Here,
xStart, yStart are coordinates of the lower left point of the grid
xInterval, yInterval are the spacing between grid points in X and Y
nxGrid, nyGrid are the number of grid points in X and Y
a11, a12, a21, a22, dx, dy specify a forward linear transform in the usual way, i.e.
   x' = a11 * (x - xci) + a12 * (y - yci) + xco
   y' = a21 * (x - xci) + a22 * (y - yci) + yco
where (x, y) and (x', y') are positions in the input and output images, and (xci, yci) and (xco, yco) are the centers of the input and output images. Finally,
deltaX, deltaY are the displacement vectors at the grid points, in order by increasing X for one Y, then by increasing Y. There may be variable numbers of entries per line (up to 50), but vectors at a new Y value should start a new line.

The vectors and positions describe an inverse transform: a point at a grid position in a transformed image corresponds to that position plus its displacement vector in the original image.

For a warping file with control points, each transformation has the following lines after the header:

   nControl
   a11  a12  a21  a22  dx  dy
   xControl yControl deltaX deltaY
   xControl yControl deltaX deltaY
   ...
where
nControl is the number of control points, which can be zero,
a11, a12, a21, a22, dx, dy specify a forward linear transform as above,
xControl, yControl are the coordinates of one control point in the warped image
deltaX, deltaY is the displacement vector at that point, which is added to the control point position to get the corresponding position in the original image.

Version 2 files could contain multiple grids of displacements, which are assumed to be inverse transforms, and no linear transforms. Its form was:

   2
   nx   ny  nz  binning    pixelSize
   xStart  xInterval   nxGrid  yStart  yInterval  nyGrid
   deltaX deltaY deltaX deltaY ...
   ...
   xStart  xInterval   nxGrid  yStart  yInterval  nyGrid
   deltaX deltaY deltaX deltaY ...
   ...
Here one grid follows another, starting with a line specifying the parameters for that grid

Version 1 files contained only a single grid of displacements, again assumed to be an inverse transform, and no linear transformations. Its form was:

   1
   nx   ny   binning    pixelSize
   xStart  xInterval   nxGrid  yStart  yInterval  nyGrid
   deltaX deltaY deltaX deltaY ...

Functions for Manipulating Warping Files

DESCRIBE FUNCTIONS FROM warpfiles.c

Utility Functions for Warping Transformations

DESCRIBE FUNCTIONS FROM warputils.c

Warping Interpolation Function

DESCRIBE FUNCTIONS FROM warpinterp.c

Functions for Magnification Gradients

DESCRIBE FUNCTIONS FROM maggradfield.c