xfmodel
xfmodel(1) General Commands Manual xfmodel(1)
NAME
xfmodel - solves for transformations and applies them to models
SYNOPSIS
xfmodel [options] input_model output_file
DESCRIPTION
Xfmodel will take an IMOD model, and either a) use corresponding points
in two sections to obtain a transformation
between the sections, or b) transform the points in the model to
match a new alignment of images
To solve for transforms, the model objects should consist of corre-
sponding points in two or more successive sections. The program con-
siders each pair of successive sections independently. If an object
contains two points in the same section, the program will take the
point whose Z value is closer to that of the other section in the pair.
The program can "edit" an existing list of f transforms (transforms
that relate each section to the previous one). That is, the model may
have points from only a few sections, or one may specify which sections
to find transforms for, and the program will output a list containing
new transforms for those sections and transforms from the existing list
for the rest.
In solving for transforms, the model can be built on unaligned images
or on images that have been aligned with a previously existing set of
transforms. In the latter case, if you specify the file of g trans-
forms that were used to prealign the images, then the new transforms
will apply to the original images; otherwise, the new transforms are
incremental to the first alignment and would apply to the prealigned
images.
When the program solves for the transformation between a pair of sec-
tions, it applies the transformation to the points on the second sec-
tion of the pair, and computes the displacement, or deviation, between
each point and the corresponding point on the first section of the
pair. It then reports the mean deviation for all of the points, the
maximum deviation, and the object number of the point with maximum
deviation. In addition, you may elect to have a complete report of the
deviations of all points for particularly bad sections. If you choose
this option, you control which sections are reported by specifying cri-
terion values for the mean and maximum deviations; the full report will
be made for any sections with mean or maximum deviations greater than
the respective criteria.
If the images are montaged, this is specified by entering the the name
of the file of piece coordinates. The Z values in this list of pieces
are used to establish the correspondence between Z values in the model
and transform number in the list of transforms. If the image is miss-
ing some sections, you should specify whether the transform lists con-
tain a transform only for each existing section or a transform for each
section number, including the missing sections. The choice here will
be applied both to lists of existing transforms that are read in and to
the list that is computed by the program, if any. In either case, if
there are model objects that bridge a gap over missing sections, the
program can compute a transform between the sections on either side of
the gap.
Instead of solving for transforms between pairs of adjacent sections,
the typical mode of operation, the program can solve for transforms
between a single specified section and each other section.
It is possible to find the X/Y translation alone that best aligns the
set of points on a section to those on a previous section. The result-
ing transformations (which involve no rotations or size changes) can be
used in a second stage of model alignment to remove progressive shifts
in position while retaining trends in size and rotation. It is also
possible to find the translation and rotation alone that best aligns
two sections. The resulting transformations (which involve no size
changes) can be used in a second stage of model alignment to remove
progressive shifts in position and rotations while retaining trends in
size. Finally, you can also obtain transformations that include trans-
lation, rotation, and magnification change but no stretch.
Transforming Models
A model that was built on unaligned images can be transformed to match
with aligned images. A model built on aligned images can be back-
transformed to match the raw, unaligned images, or it can be trans-
formed to match a new alignment of the images. This behavior is con-
trolled by specifying the transforms used for prealignment. The possi-
bilities can be illustrated with operations on a fiducial model for
tilt series alignment, which was built on images prealigned with the
transforms in setname.prexg. Tiltalign produces transforms in set-
name.tltxf that could be used to bring the prealigned images into final
alignment. To transform the fiducial model to the final aligned stack,
use:
xfmodel -xf setname.tltxf setname.fid setname.fidali
Once setname.tltxf and setname.prexg are multiplied to obtain the full
alignment transforms setname.xf, the same result is achieved with:
xfmodel -xf setname.xf -pre setname.prexg setname.fid setname.fidali
To transform the model back to the raw stack, use:
xfmodel -back -pre setname.prexg setname.fid setname.fidunali
When a distortion field is specified, it is important to indicate the
prealignment transforms, if any, because the distortion field is accu-
rate only for the original images. The program can behave in 4 differ-
ent ways:
1) -distort only: the model is assumed to be built on unaligned
images and is simply undistorted (or redistorted, if -back in included)
2) -distort and -xform: the model is assumed to be built on unaligned
images and is undistorted then transformed by the given transforms.
3) -distort and -prealign: the model was built on prealigned images.
It is back-transformed, undistorted, then re-transformed into alignment
with undistorted prealigned images.
4) -distort, -prealign, -xform: the model was built on prealigned
images. The transforms specified by -xform must be ones that would
apply to original rather than prealigned images. The model is back-
transformed by the prealignment transforms, undistorted, then re-trans-
formed by the transforms specified by -xform.
Each linear transformation in a transform file is specified by a line
with six numbers:
A11 A12 A21 A22 DX DY where the coordinate (X, Y) is transformed to
(X', Y') by:
X' = A11 * X + A12 * Y + DX
Y' = A21 * X + A22 * Y + DY
OPTIONS
Xfmodel uses the PIP package for input (see the manual page for pip)
and can take input interactively only for options available when the
program was converted to PIP input, to maintain compatibility with old
command files. The following options can be specified either as com-
mand line arguments (with the -) or one per line in a command file or
parameter file (without the -). Options can be abbreviated to unique
letters; the currently valid abbreviations for short names are shown in
parentheses.
-input (-in) OR -InputFile File name
Input model file to be transformed, or from which transforma-
tions will be found.
-output (-o) OR -OutputFile File name
Output file, either transformed model or list of transforma-
tions.
-image (-im) OR -ImageFile File name
Image file that model was built on, used to determine center
coordinate for transformations. If neither this nor Center-
InXandY are entered, the image size will be used from the model
header.
-piece (-pi) OR -PieceListFile File name
Name of piece list file for a montaged image file
-allz (-al) OR -AllZhaveTransforms
When there is a list of piece coordinates that has gaps in the Z
values, use this entry to indicate that transform files have
transforms for all Z values; otherwise the files will be assumed
to have matching gaps in Z.
-center (-ce) OR -CenterInXandY Two floats
Center coordinates of image in X and Y. If neither this nor
ImageFile are entered, the image size will be used from the
model header.
-transonly (-t) OR -TranslationOnly
Solve for transformations that include only translations in X
and Y.
-rottrans (-r) OR -RotationTranslation
Solve for transformations that include rotations and transla-
tions.
-magrot (-m) OR -MagRotTrans
Solve for transformations that include magnifications, rotations
and translations, i.e. no stretch.
-sections (-se) OR -SectionsToAnalyze List of integer ranges
List of sections to find transformations for. identified by the
second one of each pair, numbered from 0. The default is all
sections.
-single (-si) OR -SingleSection Integer
Align all sections to a single reference section with the given
section number.
-full (-f) OR -FullReportMeanAndMax Two floats
A detailed report will be printed for any section that exceeds
either the given mean deviation or the given maximum deviation.
-prealign (-pr) OR -PrealignTransforms File name
File of g transforms that were used to prealign the images on
which the model was built
-edit (-e) OR -EditTransforms File name
Name of file with existing f transforms to be replaced by any
transforms that are solved for
-xforms (-x) OR -XformsToApply File name
File of g transforms to apply to transform the model
-useline (-use) OR -UseTransformLine Integer
Line number of single transform to apply to all points in model,
regardless of their Z values. Line numbers start at 0. This
option can be used only when forward or back-transforming the
model. This option will be invoked automatically if there is
only one transform in the file. If prealignment transforms are
specified when transforming or undistorting a model, they will
be applied as usual, with a separate transform used for each Z
value.
-chunks (-ch) OR -ChunkSizes List of integer ranges
If the model consists of a set of blocks in Z, such as a model
built on a set of serial tomograms, then this option can be used
to apply one transform per chunk of Z values. Enter a list giv-
ing the number of sections in each chunk. Z values beyond the
total of these chunk sizes will not be transformed. The same
chunk structure will be used when applying prealignment trans-
forms if -prealign is entered.
-back (-ba) OR -BackTransform
If no distortion field is involved, apply the inverse of the
transforms specified by -prealign or -xforms. Either of these
two options may be used to specify transforms, but not both. If
a distortion field or mag gradient is specified, this option can
be used to transform a model built on undistorted images to
match original images. In this case, prealignment transforms
will be treated differently depending on how they are specified:
with -xforms, the model will be back-transformed to match the
raw images; with -prealign, the model will be transformed to
match prealigned but distorted images.
-scale (-sc) OR -ScaleShifts Floating point
Factor by which to scale X/Y translations in the transforms
before applying them. Use this option if a set of transforms is
appropriate for images at one scale but the model was built on
images at another scale. For example, if images are scaled by
binning, the factor would be the binning of the images that the
transforms apply to, divided by the binning of the images on
which the model was built.
-adjust (-ad) OR -AdjustForRotationBy90 Integer
When transforming the model, adjust for a rotation near 90
degrees by shifting by the difference between center coordinates
in X and Y. This operation assumes that the model is going to
be used with an image file whose X and Y sizes are transposed
from the original image. Newstack automatically transposes
sizes when it detects that the transformations make this size
fit the transformed images better. However, this option should
not be used when the rotated image was made with the -adjust
option to Newstack, because origin values inserted by New-
stack(1) will already result in an appropriate shift in the
model in Xfmodel. Enter 1 to detect a 90-degree rotation and
adjust if it is detected, or 2 to apply the adjustment regard-
less, which would be useful if the detection fails because a
small fraction of images are not rotated enough.
-distort (-d) OR -DistortionField File name
File with image distortion field to be applied in transforming
model. If BackTransform is specified, the model will be redis-
torted, i.e. transformed to match original distorted images.
-binning (-bi) OR -BinningOfImages Floating point
The camera binning at which images were taken. This entry may
be required when undistorting if the program cannot deduce the
binning unambiguously.
-gradient (-g) OR -GradientFile File name
File with magnification gradients to be applied for each image.
This should be a file listing the tilt angle, the percent magni-
fication change per micron of Z height, and the degrees of rota-
tion per micron of Z height for each image, such as is produced
by Extractmaggrad. The mag gradient correction is applied
before a distortion field correction and before any transforma-
tions.
-param (-pa) OR -ParameterFile Parameter file
Read parameter entries as keyword-value pairs from a parameter
file.
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input.
INTERACTIVE INPUT
If the program is started with no command line arguments, it reverts to
interactive input with the following entries:
Name of image file that model was built on, or blank line to enter cen-
ter coordinates instead
IF you entered an image file name, next enter the name of a piece list
file if the image is a montage, otherwise enter a blank line
OR if you did not enter an image file, next enter the X and Y index
coordinates of the center of the image (NX/2, NY/2)
IF there are gaps in the Z values described by the piece list, next
enter 0 if transform files have transforms only for the Z values that
exist, or 1 if they have transforms for all Z values
Name of model file
Enter one of:
-1 to back-transform the model to fit a raw image stack
0 to find linear transformations
1 to transform the model with a set of transformations
2 to find X/Y translations only
3 to find translations and rotations
4 to find translation, ratation, and mag change
IF you entered any option other than -1 to back-transform, next enter 0
if the model was built on raw sections, or the sections that you want
to further transform; or 1 if the model was built on pre-aligned sec-
tions and you want to reference transforms to the raw sections
IF you are back-transforming OR if you entered 1 to the last query,
next enter the file name of the g transforms used to pre-align the sec-
tions
IF you are transforming or back-transforming the model, next enter the
name of the output model file. This is the final entry for option -1
IF you are transforming, enter the name of the file with transforms to
apply; this is the final entry for option 1
IF you finding transforms instead, continue with the following entries:
Name of file with existing f transforms to be replaced by any trans-
forms that are solved for
Name of output file for new f transforms
A list of section numbers to find transforms for (the second section of
each pair, sections numbered from zero), or / to find transforms for
all sections with data in the model, or -999 to find transforms of all
sections relative to a single section
IF you entered -999, next enter:
The number of the single section
The real list of transforms to find sections for, or / for all
1 for complete reports of the deviations for each point on sections
with bad fits, or 0 for no detailed reports
IF you entered 1, then enter a criterion for the mean deviation and a
criterion for the maximum deviation; a complete report will be given
for any section that exceeds either criterion.
HISTORY
Written by David Mastronarde, 1988
DNM 7/20/89 changes for new model format
DNM 1/10/90 have it transform only existing model points, not all
points in p_coord array, to avoid bad Z values
DNM 5/28/90 fix bug in rounding 0.5 values, implement ability to
transform relative to a single section.
DNM 3/31/92 Implement translation only finding
DNM 5/1/92 Implement translation and rotation only finding
DNM 4/24/95 changed model reading/writing to be portable
DNM 9/23/97 Add translation, rotation, and mag change finding
DNM 9/4/02 Change to take scaling from model and scale properly
DNM 12/27/03 Convert to PIP input, add distortion correction
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.2.0 xfmodel(1)