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

int newWarpFile(int nx, int ny, int binning, float pixelSize, int flags)
int readWarpFile(char *filename, int *nx, int *ny, int *nz, int *binning, float *pixelSize, int *version, int *flags)
int writeWarpFile(const char *filename, int skipBackup)
int setCurrentWarpFile(int index)
int clearWarpFile(int index)
void warpFilesDone()
int getWarpFileSize(int *nx, int *ny, int *nz, int *ifControl)
int setLinearTransform(int iz, float *xform, int rows)
int setWarpGrid(int iz, int nxGrid, int nyGrid, float xStart, float yStart, float xInterval, float yInterval, float *dxGrid, float *dyGrid, int xdim)
int setWarpPoints(int iz, int nControl, float *xControl, float *yControl, float *xVector, float *yVector)
int addWarpPoint(int iz, float xControl, float yControl, float xVector, float yVector)
int removeWarpPoint(int iz, int index)
int getLinearTransform(int iz, float *xform, int rows)
int getNumWarpPoints(int iz, int *nControl)
int getWarpPoints(int iz, float *xControl, float *yControl, float *xVector, float *yVector)
int getWarpPointArrays(int iz, float **xControl, float **yControl, float **xVector, float **yVector)
int getWarpGridSize(int iz, int *nxMax, int *nyMax, int *prodMax)
int getGridParameters(int iz, int *nxGrid, int *nyGrid, float *xStart, float *yStart, float *xInterval, float *yInterval)
int setGridSizeToMake(int iz, int nxGrid, int nyGrid, float xStart, float yStart, float xInterval, float yInterval)
int controlPointRange(int iz, float *xmin, float *xmax, float *ymin, float *ymax)
int controlPointSpacing(int iz, float percentile, float *spacing)
int gridSizeFromSpacing(int iz, float percentile, float factor, int fullExtent)
int getWarpGrid(int iz, int *nxGrid, int *nyGrid, float *xStart, float *yStart, float *xInterval, float *yInterval, float *dxGrid, float *dyGrid, int xdim)
int separateLinearTransform(int iz)

Utility Functions for Warping Transformations

void interpolateGrid(float x, float y, float *dxGrid, float *dyGrid, int ixgDim, int nxGrid, int nyGrid, float xGridStart, float yGridStart, float xGridIntrv, float yGridIntrv, float *dx, float *dy)
void findInversePoint(float x, float y, float *dxGrid, float *dyGrid, int ixgDim, int nxGrid, int nyGrid, float xGridStart, float yGridStart, float xGridIntrv, float yGridIntrv, float *xnew, float *ynew, float *dx, float *dy)
void invertWarpGrid(float *dxGrid, float *dyGrid, int ixgDim, int nxGrid, int nyGrid, float xGridStart, float yGridStart, float xGridIntrv, float yGridIntrv, float *xform, float xcen, float ycen, float *dxInv, float *dyInv, float *xfInv, int rows)
int multiplyWarpings(float *dxGrid1, float *dyGrid1, int ixgDim1, int nxGrid1, int nyGrid1, float xStart1, float yStart1, float xIntrv1, float yIntrv1, float *xform1, float xcen, float ycen, float *dxGrid2, float *dyGrid2, int ixgDim2, int nxGrid2, int nyGrid2, float xStart2, float yStart2, float xIntrv2, float yIntrv2, float *xform2, float *dxProd, float *dyProd, float *xfProd, int useSecond, int rows)
int extractLinearXform(float *xPos, float *yPos, float *xVector, float *yVector, int nPoints, float xcen, float ycen, float *newXvec, float *newYvec, float *xfinv, int rows)
int extrapolateGrid(float *dxGrid, float *dyGrid, char *solved, int xdim, int nxGrid, int nyGrid, float xInterval, float yInterval, int reuse)
void extrapolateDone()
int expandAndExtrapGrid(float *dxGrid, float *dyGrid, int xdim, int ydim, int *nxGrid, int *nyGrid, float *xStart, float *yStart, float xInterval, float yInterval, float xBigStr, float yBigStr, float xBigEnd, float yBigEnd, int ixmin, int ixmax, int iymin, int iymax)
int readCheckWarpFile(char *filename, int needDist, int needInv, int *nx, int *ny, int *nz, int *ibinning, float *pixelSize, int *iflags, char *errString, int lenString)
int findMaxGridSize(float xmin, float xmax, float ymin, float ymax, int *nControl, int *maxNxg, int *maxNyg, char *errString, int lenString)
int getSizeAdjustedGrid(int iz, float xnbig, float ynbig, float xOffset, float yOffset, int adjustStart, float warpScale, int iBinning, int *nxGrid, int *nyGrid, float *xGridStrt, float *yGridStrt, float *xGridIntrv, float *yGridIntrv, float *fieldDx, float *fieldDy, int ixgdim, int iygdim, char *errString, int lenString)

Warping Interpolation Function

void warpInterp(float *array, float *bray, int nxa, int nya, int nxb, int nyb, float amat[2][2], float xc, float yc, float xt, float yt, float scale, float dmean, int linear, int linFirst, float *dxGrid, float *dyGrid, int ixgDim, int nxGrid, int nyGrid, float xGridStrt, float yGridStrt, float xGridIntrv, float yGridIntrv)

Functions for Magnification Gradients

void makeMagGradField(float *idfDx, float *idfDy, float *gradDx, float *gradDy, int lmGrid, int imageNx, int imageNy, int *nxGrid, int *nyGrid, float *xGridStrt, float *yGridStrt, float *xGridIntrv, float *yGridIntrv, float xcen, float ycen, float pixelSize, float axisRot, float tilt, float dmagPerUm, float rotPerUm)
void magGradientShift(float xx, float yy, int imageNx, int imageNy, float xcen, float ycen, float pixelSize, float axisRot, float tilt, float dmagPerUm, float rotPerUm, float *dx, float *dy)

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

int newWarpFile(int nx, int ny, int binning, float pixelSize, int flags)

Initialize for a new warp file based on image dimensions nx, ny at the given binning, with the pixel size in Angstroms in pixelSize and flags containing the sum of 1 for inverse warping and 2 for control points. Returns the index of the new file, or -1 for a memory error.

int readWarpFile(char filename, int nx, int ny, int nz, int binning, float pixelSize, int version, int flags)

Reads in a warping file whose name is in filename. Returns the X and Y sizes given in the file in nx and ny, the number of sections of warpings in nz, the binning factor into binning, the pixel size in Angstroms into pixelSize, the original file version into version, and the sum of 1 for inverse warpings and 2 for control points into flags. The return value is the index of the warp file, or -1 for failure to open the file, -2 for an error reading values from the file, -3 for the wrong number of values on the first line or nothing following that line, -4 for a version number out of range or an error reading values or the wrong number of values on the header line, -5 for nz, ny, nz, or binning out of range, -6 for memory errors, or -7 for an error or inconsistency reading warpings. version will be -1 for errors -1, -2, or -3, or 0 if the error is -3 and there are 6 values on the first line, which is a signal that the file contains ordinary transforms.

int writeWarpFile(const char *filename, int skipBackup)

Writes the current warping file as a version 3 file to filename. Backs up an existing file to filename~ unless skipBackup is non-zero. Returns -1 for no filename or failure to open the file, or 1 for an error backing up an existing file.

int setCurrentWarpFile(int index)

Set the index of the current warping file to index. Returns -1 for error.

int clearWarpFile(int index)

Deletes all data for the warp file at index and marks it as unused. Returns 1 for index out of range or 2 for a warp file not in use.

void warpFilesDone()

Deletes all warp file data and resets pointers and indices; also calls extrapolateDone.

int getWarpFileSize(int nx, int ny, int nz, int ifControl)

For the current warp file, returns the image size in nx and ny, number of sections in nz, and 1 in ifControl if it has control points. Return value is 1 if there is no current warp file.

int setLinearTransform(int iz, float *xform, int rows)

Sets the linear transform for section iz in the current warp file to xform; rows specifies the number of rows (2 or 3) in the xform array. When calling from Fortran, omit rows; it is assumed to be 2.

int setWarpGrid(int iz, int nxGrid, int nyGrid, float xStart, float yStart, float xInterval, float yInterval, float dxGrid, float dyGrid, int xdim)

Sets a warping grid for section iz in the current warp file. The grid consists of nxGrid by nyGrid points, starting at xStart, yStart and at intervals of xInterval, yInterval. The vectors are in 2D arrays dxGrid, dyGrid, and xdim is the X dimension of the arrays. This call can replace an existing warping grid but not eliminate a grid. Returns 1 for all errors.

int setWarpPoints(int iz, int nControl, float xControl, float yControl, float xVector, float yVector)

Sets control points for section iz of the current warp file. The number of points is in nControl, their locations are in xVector, yVector, and the displacements at the points are in xVector, yVector. This call can replace an existing set of control points or eliminate them. Returns 1 for errors.

int addWarpPoint(int iz, float xControl, float yControl, float xVector, float yVector)

Adds one control point specified by position xControl, yControl and displacement xVector, yVector to section iz of the current warp file. Returns -1 for no current warp file, not a control point file, iz out of range, or memory errors.

int removeWarpPoint(int iz, int index)

Removes the control point at index from section iz of the current warp file. Returns 1 for iz or index out of range.

int getLinearTransform(int iz, float *xform, int rows)

Returns the linear transform for section iz of the current warp file into xform, which has rows rows (2 or 3). Returns 1 for iz out of range or no warp file. When calling from Fortran, omit rows; it is assumed to be 2.

int getNumWarpPoints(int iz, int *nControl)

Returns in nControl either the number of warp points on section iz if iz >= 0, or the maximum number of points over all sections, if iz < 0. Returns 1 if there is no current warp file or iz is out of range.

int getWarpPoints(int iz, float xControl, float yControl, float xVector, float yVector)

Returns control points for section iz in the current warp file, with positions placed into xControl, yControl and displacements placed into xVector, yVector. Returns 1 for iz out if range or no warp file.

int getWarpPointArrays(int iz, float xControl, float yControl, float xVector, float yVector)

Returns pointers to control point arrays for section iz in the current warp file, with positions pointers placed into xControl, yControl and displacement pointers placed into xVector, yVector. Returns 1 for iz out if range or no warp file.

int getWarpGridSize(int iz, int nxMax, int nyMax, int *prodMax)

Returns the size of the warping grid for section iz of the current warp file, or the maximum size of all grids in the file if iz < 0. Returns the size in X and Y into nxMax, nyMax, and the total number of elements in the grid in prodMax. Returns 1 for iz out of range or no warping file.

int getGridParameters(int iz, int nxGrid, int nyGrid, float xStart, float yStart, float xInterval, float yInterval)

Returns all positional parameters of the warping grid for section iz of the current warp file: number of elements in nxGrid and nyGrid, starting coordinate in xStart, yStart, and spacing between points in xInterval and yInterval. Returns 1 for no warp file or iz out of range.

int setGridSizeToMake(int iz, int nxGrid, int nyGrid, float xStart, float yStart, float xInterval, float yInterval)

Sets the parameters for a grid to be interpolated from a set of control points for section iz of the current warp file. nxGrid, nyGrid set the number of elements in X and Y, xStart, yStart set the starting position, and xInterval, yInterval set the intervals between points. Returns 1 if iz is out of range, there is no warping file, or the warping file does not contain control points.

int controlPointRange(int iz, float xmin, float xmax, float ymin, float ymax)

Returns the range of the control points for section iz of the current warp file, with the X range in xmin and xmax and the Y range in ymin and ymax. Returns 1 if iz is out of range, there is no warping file, or the warping file does not contain control points.

int controlPointSpacing(int iz, float percentile, float *spacing)

Computes a spacing between the control points on section iz of the current warp file. Finds the distance to the nearest neighboring point for each point, then finds the percentile point of this distribution requested in percentile (a value between 0 and 1), and returns that distance in spacing. If percentile is < 0, a value of 0.5 will be used to obtain the median. Returns 1 for no warp file, a warp file not containing control points, iz or percentile out of range, or fewer than 2 control points.

int gridSizeFromSpacing(int iz, float percentile, float factor, int fullExtent)

Sets the grid size for an interpolated grid from the spacing between control points for section iz of the current warp file. Calls controlPointSpacing to find the given percentile value of the spacing between nearest neighboring control points, and multiplies this spacing by the value in factor to get the interval of the grid. If percentile is < 0, a value of * 0.5 will be used to obtain the median. If factor <0, a default value of 0.25 will be used. The grid is set up over the range of the control points unless fullExtent is nonzero, * in which case it is set up over the full extent of the image. Returns 1 for an error: iz out of range, no current warp file or no control points, percentile > 1, or factor is not < 0 or between 0.05 and 2.

int getWarpGrid(int iz, int nxGrid, int nyGrid, float xStart, float yStart, float xInterval, float yInterval, float dxGrid, float dyGrid, int xdim)

Returns a warping grid for section iz of the current warp file. The size of the grid is returned into nxGrid, nyGrid, the starting position in xStart, yStart, and the intervals in xInterval, yInterval. The vectors are returned into the 2D arrays dxGrid, dyGrid using the X dimension given in xdim. If xdim is <= 0, it will be set to nxGrid and data will be packed sequentially. For a file of warping grids, the grid is returned directly; for a file of control points, the grid is found by interpolation. Returns 1 for error if iz is out of range, there is no warping file, or, for a file of control points, the grid parameters are not defined, there are fewer than 3 control points, or a memory allocation fails.

int separateLinearTransform(int iz)

Extracts the linear transform embedded in the warping for section iz of the current warp file, modifies the vectors to remove this transform, and combines the transform with the linear transform for this section. Returns 1 for no warp file, section out of range, not an inverse warp file, fewer than 3 control or grid points, or a memory error.

Utility Functions for Warping Transformations

void interpolateGrid(float x, float y, float dxGrid, float dyGrid, int ixgDim, int nxGrid, int nyGrid, float xGridStart, float yGridStart, float xGridIntrv, float yGridIntrv, float dx, float dy)

Returns a value from one position in a 2D warping grid.
x, x is the position in the grid
dxGrid, dyGrid are the grid arrays, with first dimension ixgDim
nxGrid, nyGrid are the number of grid points in X and Y
xGridStart, yGridStart are coordinates at which the grid starts
xGridIntrv, yGridIntrv are the spacing between grid points in X and Y
dx and dy are returned with the interpolated values at the given position.

void findInversePoint(float x, float y, float dxGrid, float dyGrid, int ixgDim, int nxGrid, int nyGrid, float xGridStart, float yGridStart, float xGridIntrv, float yGridIntrv, float xnew, float ynew, float dx, float dy)

Finds the point that a grid maps to x, y by iteration. Returns the coordinates of that point in xnew, ynew (which can be the same as x, y) and the interpolated grid values at that point in dx and dy. Grid parameters are the same as in interpolateGrid.

void invertWarpGrid(float dxGrid, float dyGrid, int ixgDim, int nxGrid, int nyGrid, float xGridStart, float yGridStart, float xGridIntrv, float yGridIntrv, float xform, float xcen, float ycen, float dxInv, float dyInv, float xfInv, int rows)

Finds the inverse of a warping consisting of a linear transform in xform followed by a grid of inverse warp displacements in dxGrid, dyGrid. The center of transform is specified in xcen, ycen. The linear component of the inverse is returned in xfInv and the inverse warp displacements of the inverse are returned in dxInv, dyInv. rows specifies the number of rows of the transform (2 or 3; omitted when calling from Fortran). Grid parameters are the same as in interpolateGrid.

int multiplyWarpings(float dxGrid1, float dyGrid1, int ixgDim1, int nxGrid1, int nyGrid1, float xStart1, float yStart1, float xIntrv1, float yIntrv1, float xform1, float xcen, float ycen, float dxGrid2, float dyGrid2, int ixgDim2, int nxGrid2, int nyGrid2, float xStart2, float yStart2, float xIntrv2, float yIntrv2, float xform2, float dxProd, float dyProd, float *xfProd, int useSecond, int rows)

Multiply two warp transforms together. Each warping is specified by a linear transform applied first, and the inverse of warp displacement vectors. The warp transform applied first has its linear component in xform1 and has displacements in arrays dxGrid1 and dyGrid1, with nxGrid1 by nyGrid1 elements and an X dimension of ixgDim1. The grid starts at xStart1, yStart1 and has intervals in X and Y of xIntrv1 and yIntrv1. The warp transform applied second is specified by the corresponding arguments ending in 2. The center of transformation is given by xcen, ycen. Set useSecond nonzero to make an output grid whose parameters match that of the second input grid rather than the first. The number of rows of the linear transforms is specified in rows (2 or 3, omit when calling from Fortran). The output warp grid is returned in dxProd, dyProd and the linear transform is returned in xfProd. The second warp grid may be omitted by setting nxGrid to zero, but the first warp grid must exist. Returns 1 for memory or other errors.

int extractLinearXform(float xPos, float yPos, float xVector, float yVector, int nPoints, float xcen, float ycen, float newXvec, float newYvec, float *xfinv, int rows)

Extracts the linear transform embedded in a set of positions and vectors, and modifies the vectors to remove the transform. The positions of nPoints points are in xPos, yPos and the X and Y displacements are in xVector and yVector. The center for transformations is xcen, ycen. The modified vectors are returned in newXvec and newYvec, which can be the same as xVector and yVector. The inverse of the embedded transform is returned in xfinv with the number of rows specified in rows. Returns 1 for a memory allocation error, fewer than 3 points, or rows not 2 or 3.

int extrapolateGrid(float dxGrid, float dyGrid, char *solved, int xdim, int nxGrid, int nyGrid, float xInterval, float yInterval, int reuse)

Extrapolates a grid from locations marked as solved to those not marked. The grid of X and Y displacements is in dxGrid and dyGrid. solved is an corresponding array with 0 for a location to be fille din, and 1 for a location with a vector. The X dimension of dxGrid, dyGrid, and solved is given by xdim. solved must be six times the size of this array (6 * xdim * nyGrid) in order to be used for temporary storage. The number of grid elements in X and Y is given by nxGrid and nyGrid; the intervals between grid points in X and Y are given by xInterval and yInterval. If reuse is non-zero, it uses stored information about how to extrapolate from the last grid analyzed; this should only be done if the the last grid had the identical pattern of solved locations. Some of this information is stored in the solved array and the rest is stored in arrays that are always kept, until extrapolateDone is called. Returns 1 for a memory allocation error or an attempt to reuse when there is no stored data.

void extrapolateDone()

Frees the arrays used by extrapolateGrid

int expandAndExtrapGrid(float dxGrid, float dyGrid, int xdim, int ydim, int nxGrid, int nyGrid, float xStart, float yStart, float xInterval, float yInterval, float xBigStr, float yBigStr, float xBigEnd, float yBigEnd, int ixmin, int ixmax, int iymin, int iymax)

Expand a grid to a larger area by shifting it and then extrapolating it with extrapolateGrid.
dxGrid, dyGrid - grid arrays with displacements in X and Y
xdim, ydim - X and Y dimensions of arrays
nxGrid, nyGrid - call with original number of grid points in X and Y, returned with new number
xStart, yStart - Starting X and Y coordinates of grid, returned with new values
xInterval, yInterval - Spacing between points in X and Y
xBigStr, yBigStr - Starting X and Y coordinates of larger area
xBigEnd, yBigEnd - Ending X and Y coordinates of larger area
ixmin, ixmax - limiting coordinates in X; grid will not go outside this
iymin, iymax - limiting coordinates in X; grid will not go outside this
The new area covered by the grid will be at least as large as the larger area, unless that would make a grid point be out of bounds. Returns 1 for memory error.

int readCheckWarpFile(char filename, int needDist, int needInv, int nx, int ny, int nz, int ibinning, float pixelSize, int iflags, char errString, int lenString)

Attempts to open a transform file in filename as a warping file and performs basic checks on it. Set needDist to 1 if the file must be a distortion field file with an inverse transform grid, or needInv to 1 if a warping file must contain inverse transforms. The return value is a warping file index, -1 for a linear transform file, or -2 for an error. In case of an error, errString is filled with an error message; lenString is the size of errString (omitted when calling from Fortran). For a warping file, returns the image size in nx, ny. number of sections in nz, binning of images in ibinning, pixel size in pixelSize, and flags in iflags.

int findMaxGridSize(float xmin, float xmax, float ymin, float ymax, int nControl, int maxNxg, int maxNyg, char errString, int lenString)

Determines the maximum grid size needed in X and Y for all of the transforms in the current warping file. Set the needed minimum and maximum X and Y coordinates to be composed in xmin, xmax, ymin, and ymax. The number of control points, or 4 for a grid, is returned in nControl, which must be allocated before calling. The maximum grid sizes in X amd Y are returned in maxNxg and maxNyg. Returns -2 for an error and places an error message in errString; lenString is the size of errString (omitted when calling from Fortran).

int getSizeAdjustedGrid(int iz, float xnbig, float ynbig, float xOffset, float yOffset, int adjustStart, float warpScale, int iBinning, int nxGrid, int nyGrid, float xGridStrt, float yGridStrt, float xGridIntrv, float yGridIntrv, float fieldDx, float fieldDy, int ixgdim, int iygdim, char *errString, int lenString)

Gets a warping grid for section iz of the current warping file, expanded to fill the needed area and adjusted for size changes and offsets.
xnbig, ynbig - Size of the needed area, in warp file coordinates
xOffset, yOffset - Offset of needed area from the image used to get the warping
adjustStart - Set to 1 to have starting coordinates adjusted for difference in size and for the offset, and to have the grid vectors adjusted for the offset too
warpScale - Scaling between input image pixel size and warp file pixel size
iBinning - Binning of pixels for output. Vectors, starts, and intervals will be all be multiplied by warpScale / iBinning
nxGrid, nyGrid - Number of positions in returned grid in X and Y
xGridStrt, yGridStrt - Returned starting coordinate of grid
xGridIntrv, yGridIntrv - Returned interval between grid points
fieldDx, fieldDy - Grid of displacements in X and Y
ixgDim, iygDim - Dimensions of grid arrays in X and Y
Returns -2 for an error and places an error message in errString, whose size should be supplied in lenString (but not when calling from Fortran).

Warping Interpolation Function

void warpInterp(float array, float bray, int nxa, int nya, int nxb, int nyb, float amat[2][2], float xc, float yc, float xt, float yt, float scale, float dmean, int linear, int linFirst, float dxGrid, float dyGrid, int ixgDim, int nxGrid, int nyGrid, float xGridStrt, float yGridStrt, float xGridIntrv, float yGridIntrv)

Corrects for a distortion field and then applies a linear transformation, or applies a linear transformation then a warping field, using cubic or linear interpolation.

array   - The input image array
bray    - The output image array
nxa,nya - The dimensions of array
nxb,nyb - The dimensions of bray
amat    - A 2x2 matrix to specify rotation,scaling,skewing
xc,yc   - The coordinates of the center of ARRAY
xt,yt   - The translation to add in the linear transformation
scale   - A multiplicative scale factor for the intensities
dmean   - Mean intensity of image, or value to fill edges with
linear  - Set greater than zero to do linear interpolation, or less than zero for nearest neighbor interpolation
linFirst - Set non-zero to do linear transformation before warping
dxGrid, dyGrid - Grid of distortion displacements in X & Y; each value is the shift to get from a desired position in the undistorted or warped image to the corresponding position in the original image
ixgDim  - The first dimension of dxGrid and dyGrid
xGridStrt, yGridStrt - Coordinates at which grid starts in output image
xGridIntrv, yGridIntrv - Spacing between grid points in X & Y
nxGrid, nyGrid - Number of grid points in X & Y

The linear transformation is done as:
Xo = a11(Xi - Xc) + a12(Yi - Yc) + NXB/2. + XT
Yo = a21(Xi - Xc) + a22(Yi - Yc) + NYB/2. + YT
  where X coordinates run from 0 at the left edge of the first pixel to nxa at the right edge of the last pixel, etc.
When calling from C, indices in amat are transposed: a11 = amat[0][0], a12 = amat[1][0], a21 = amat[0][1], a22 = amat[1][1]
To call from Fortran, use arguments of the same type and in the same order. Indices in amat are in logical order: a11 = amat(1,1), a12 = amat(1,2), etc.
Both undistorting and warping are parallelized with OpenMP.

Functions for Magnification Gradients

void makeMagGradField(float idfDx, float idfDy, float gradDx, float gradDy, int lmGrid, int imageNx, int imageNy, int nxGrid, int nyGrid, float xGridStrt, float yGridStrt, float xGridIntrv, float yGridIntrv, float xcen, float ycen, float pixelSize, float axisRot, float tilt, float dmagPerUm, float rotPerUm)

Makes a distortion field array with the shifts based on a mag gradient.
gradDx, gradDy are the arrays returned with the X and Y shifts at each location
idfDx, idfDy are arrays used for temporary storage
All of these are dimensioned lmGrid x lmGrid
imageNx and imageNy are the image size that gradients are being applied to.
xGridStrt, yGridStrt are coordinates at which the grid starts
xGridIntrv, yGridIntrv are the spacing between grid points in X & Y
nxGrid, nyGrid are the number of grid points in X & Y
xcen, ycen is the center coordinate for the mag and rotation changes
pixelSize is the pixel size in Angstroms
axisRot is the rotation of the tilt axis from the vertical
tilt is the tilt angle
dmagPerUm is the percent change in magnification per micron of Z
rotPerUm is the rotation in degrees per micron of Z height

void magGradientShift(float xx, float yy, int imageNx, int imageNy, float xcen, float ycen, float pixelSize, float axisRot, float tilt, float dmagPerUm, float rotPerUm, float dx, float dy)

Computes the shifts from a mag gradient at one point.
xx, yy is the coordinate of the point
imageNx and imageNy are the image size that gradients are being applied to.
xcen, ycen is the center coordinate for the mag and rotation changes
pixelSize is the pixel size in Angstroms
axisRot is the rotation of the tilt axis from the vertical
tilt is the tilt angle
dmagPerUm is the percent change in magnification per micron of Z
rotPerUm is the rotation in degrees per micron of Z height
dx, dy are returned with the shifts