xftoxg(1) General Commands Manual xftoxg(1)NAMExftoxg - Converts transforms between sections into alignment transformsSYNOPSISxftoxg [options] input_file [output_file]DESCRIPTIONXftoxg 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.OPTIONSXftoxg 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-InputFileFilenameInput file with f transforms-goutput(-g)OR-GOutputFileFilenameOutput 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-NumberToFitIntegerNumber of adjacent sections to fit, 0 for global alignment, or 1 for fit to all sections-ref(-re)OR-ReferenceSectionIntegerDo 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-OrderOfPolynomialFitIntegerOrder of the polynomial fit to the data. The default is 1 (lin- ear fit).-mixed(-mi)OR-HybridFitsIntegerNumber 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-RangeOfAnglesInAverageFloatingpointCompute 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-RobustFitUse 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-KFactorScalingIntegerAmount 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-MaximumIterationsIntegerThe 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-IterationParamsThreefloatsThis 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-usagePrint help output-StandardInputRead parameter entries from standard input.INTERACTIVEINPUTIf 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 transformsHISTORYWritten by David Mastronarde, 1988 Added hybrid method, 7/26/01 Converted to PIP input, 1/25/04 Added support for warping transforms, June 2011BUGSEmail bug reports to mast at colorado dot edu. IMOD 4.10.22 xftoxg(1)