xftoxg(1) General Commands Manual xftoxg(1)
NAME
xftoxg - Converts transforms between sections into alignment transforms
SYNOPSIS
xftoxg [options] input_file [output_file]
DESCRIPTION
Xftoxg takes a list of transformations (f) from each section to the
previous one, and computes a list of xforms (g) to apply to each sec-
tion to obtain a single consistent set of alignments. Transforms can
be simple 6-component linear transforms or warping transformations.
Three different modes of operation can be selected. In the first,
all sections will be transformed to a single position in the "center"
of the series. Here "position" refers to the entire set of parame-
ters describing the transformation, i.e. not just the x,y coordinates
but the rotation and stretch as well. This mode, sometimes referred as
giving a global alignment, can be invoked with the option "-n 0". This
mode will remove any consistent trends in the data stack, such as a
progressive rotation, compression or shift. Because of this effect,
this mode is often inappropriate for large sets of serial sections.
For example, if the alignment is dominated by a structure (such as a
cell boundary) that becomes actually smaller toward one end of the
series, the global alignment will erroneously expand sections at the
end of the series to keep the structure the same size.
In the second mode, the "center" position is allowed to change progres-
sively over the series. For each section, the program fits polynomials
to the transformation parameters over the selected distance (centered
on the given section, if possible), and uses these polynomial fits to
define the position to which that section should be transformed. This
mode will retain trends in the data stack that occur over the range of
the specified distance; for the example in the last paragraph, the
trend for the cell to get smaller would be retained and sections would
not be expanded inappropriately. This is the default mode of opera-
tion, with linear fits over 7 adjacent sections.
In the third mode, the "center" position is assumed to change progres-
sively over the whole series, based on a polynomial fit to the series,
and a transformation will be computed for each section that will align
it to a fitted shifting center position. If a polynomial order of 1 is
selected, the center position will shift linearly from one end to the
other of the data stack. This mode will retain trends in the data
stack to the extent that they can be fit by the order of polynomial
chosen. For example, if order 1 is chosen, the fit is a linear one,
and the resulting transforms will retain trends that occur at a con-
stant rate from one end to the other.
It is also possible to do a mixed or hybrid alignment in which trends
are retained for some parameters while they are eliminated for others.
Trends will be eliminated for X and Y translations, and can optionally
be eliminated for rotations and overall size changes. The most appro-
priate choice would be to eliminate trends for translations and rota-
tions, unless the rotation trends in the data are meaningful and should
be preserved. This hybrid method can be used with either local or
global polynomial fits (the second or third mode of operation).
Sometimes a small minority of sections are rotated at a large angle
from the rest. Including such sections in the computation of the "cen-
ter" position would skew the average rotation. In such cases, the
"-range" option can be used to exclude sections whose rotation angles
fall outside of the given range from the averaging and fitting proce-
dures. For example, if a range of 45 degrees is given, then the pro-
gram will find the largest group of sections whose angles span a range
of 45 degrees or less, and use only these sections to compute the
global average alignment.
The input file can contain warping transformations, which can be speci-
fied either as displacements at a set of control points, or as dis-
placements on a regular grid. In either case, the output will consist
of a regular grid of displacements, with the same grid locations for
every section. The program first analyzes each warping transform to
remove the linear component from it and combine that with the separate
linear transformation. The linear transforms are treated as usual,
according to the various options that are given, including the choice
for a hybrid alignment. The remaining warp transforms are analyzed
similarly to the linear transforms. When a global alignment is being
done, the program forms a cumulative warping transform by multiplying
successive transforms, determines the average cumulative transform and
multiplies each cumulative transform by this average. This method pro-
duces an acceptable result for a small number of sections. When local
or global polynominal fits are used for the linear transforms, a simi-
lar fitting method is applied at each position of the warping trans-
forms. This method keeps the converted warp vectors from building up
over large numbers of sections.
The program can also do robust fitting, in which it attempts to elimi-
nate or down-weight transformation components that appear to be out-
liers. This is an experimental feature intended to deal with situa-
tions where a few isolated images need a much bigger shift, rotation,
size change, or stretch than others to bring them into alignment. With
the default linear fitting to 7 sections, an aberrant image would be
brought 6/7 of the way into alignment with its neighbors, and the
neighbors would be pulled out of their proper alignment by the remain-
ing 1/7. In principle, with robust fitting, the aberrant image would
be eliminated from local fits, the neighbors' alignments would be
undisturbed, and the aberrant one would be brought to their alignment.
To do the averaging and fitting, the program converts the A matrix of
the g transforms to the "semi-natural" parameters: global rotation and
magnification, and differences between Y and X axis rotation and
stretch. This conversion allows the hybrid alignments to be done. It
also means that if input transformations involve only a restricted set
of these parameters (e.g., rotation only), this restriction will be
retained in the final g transforms.
The ability to use both the local fits and fits of order higher than 1
is somewhat redundant. If local fitting is used, start with order 1
and go to higher orders only if necessary.
OPTIONS
Xftoxg uses the PIP package for input (see the manual page for pip)
and can take also input interactively to maintain compatibility with
old command files. The following options can be specified either as
command line arguments (with the -) or one per line in a command 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 file with f transforms
-goutput (-g) OR -GOutputFile File name
Output file for g transforms. If an output filename is omitted
and the input filename ends in xf, the input filename will be
used as output with the last letter converted from f to g.
-nfit (-n) OR -NumberToFit Integer
Number of adjacent sections to fit, 0 for global alignment, or 1
for fit to all sections
-ref (-re) OR -ReferenceSection Integer
Do a global alignment to the given section; this will give the
reference section a unit transform and keep it from being trans-
formed. Sections are numbered from 1.
-order (-o) OR -OrderOfPolynomialFit Integer
Order of the polynomial fit to the data. The default is 1 (lin-
ear fit).
-mixed (-mi) OR -HybridFits Integer
Number of parameters to eliminate trends for with a hybrid
alignment: 2 for translations only, 3 for rotations also, 4 for
size changes also.
-range (-ra) OR -RangeOfAnglesInAverage Floating point
Compute the global average center position, and the center posi-
tion for local fits, using the largest group of sections whose
rotation angles fall within the given range.
-robust (-ro) OR -RobustFit
Use robust weighting when fitting to find the center position.
The fits will be done iteratively, with a weight assigned to
each point in the fit and the weight adjusted after each itera-
tion based on the fitting error of that point. Weights are
adjusted together in a fit to the four rotation/magnification
parameters, and independently adjusted in a separate fit to the
X and Y shift values.
-kfactor (-k) OR -KFactorScaling Integer
Amount to scale the K factor that controls how many points are
down-weighted in the robust fitting. The default scaling of 1
gives a K factor of 4.685, the factor commonly used for the
Tukey bisquare weighting. A smaller factor will down-weight and
eliminate more points.
-max (-ma) OR -MaximumIterations Integer
The maximum number of iterations in the robust fitting. The
default is 200. A negative number can be entered to obtain out-
put about the changes in weights after each iteration.
-iteration (-it) OR -IterationParams Three floats
This option sets three values that control the robust fitting:
(1) The maximum fraction of points that are allowed to have zero
weight. The actual limit for a particular fit is the nearest
integer of this value times the number of points being fit. The
default is 0.2. (2) The maximum change in weights allowed
before considering that a fit has converged, if the fit is not
oscillating between two states. The default is 0.02. (3) The
maximum change in weights allowed for terminating the fit if it
is oscillating between two states; the change in weights in one
state must also be less than the maximum described in (2). The
default is 0.04.
-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:
0 to align all sections to a single average central alignment, 1 to
align to an average alignment fit to a single polynomial, N > 1 to
align each section to an average alignment fit to the nearest N sec-
tions, or -1 or -N to do a hybrid of central and shifting alignments
with fits to a single polynomial or to locally fitted polynomials
IF you entered a negative number, next enter 2 for central alignment of
translations only, 3 for central alignment of translations and rota-
tions, or 4 for central alignment of translations, rotations and size
changes
IF you entered a nonzero number to the first query, next enter the
order of the polynomials to fit (1 for linear fits)
Name of input file of F transforms
Name of output file of G transforms
HISTORY
Written by David Mastronarde, 1988
Added hybrid method, 7/26/01
Converted to PIP input, 1/25/04
Added support for warping transforms, June 2011
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 4.11.0 xftoxg(1)