Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

XFJOINTOMO(1)					                  XFJOINTOMO(1)

NAME
  xfjointomo - use model features to refine serial tomogram alignment

SYNOPSIS
  xfjointomo [options] input_file output_file(s)

DESCRIPTION
  
  Xfjointomo computes transforms for aligning tomograms of serial sections
  from features modeled on an initial joined tomogram.  This fiducial model
  can have two kinds of features: contours following trajectories on either
  side of a boundary, and contours with one point on either side of a
  boundary.  Thus, features such as oblique microtubules can be used for
  alignment and, if trajectories at different angles are available, the
  optimal spacing between the tomograms can be determined.

  The inputs to and outputs from the program depend on how one plans to
  generate an aligned joined tomogram.  If this refinement step is done right
  after making a joined tomogram, then the results should be used to rerun
  Finishjoin, since this avoids interpolating the data twice.  In this
  case, the program needs to be informed about the offsets and binning, if
  any, used to compute the joined file that was modeled.  It will output
  two transform files: one with the transforms that align each tomogram to
  the previous one (referred to as f transforms); and one with global
  transforms (g transforms) to be passed to Finishjoin.  Note that the
  latter are not necessarily suitable for transforming the fiducial model
  into the new alignment; rather, transforms for this purpose should be 
  obtained by running "xftoxg -n 0" on the output file of f transforms.
  The resulting g transforms can be used with Xfmodel provided that the
  sizes of the sections are given to Xfmodel with the -chunk option.  When
  used in this mode, the program can run repeatedly to "edit" a file of f 
  transforms.  For example, you can run it with one set of parameters and get
  solutions for a subset of the boundaries, then run it again with other
  parameters for a different subset of boundaries.

  The second way of using the program is with the intention of using
  Newstack to transform the existing joined volume, or Xfmodel to
  transform a model on that volume.  Transforming the joined volume will
  degrade the image data slightly but might be the most convenient option in
  some cases.  To use this method, use the -slice option to get one transform
  per slice in the image file.  These are f transforms relating each slice to
  the previous, and need to be converted to g transforms with "xftoxg -n 0".
  Note that the resulting transformation will be slightly different from that
  produced by running Xfjointomo without the -slice option, so you need to
  avoid mixing the modes of operation of this program.

  Data from trajectories such as microtubules are used to determine a pair of
  positions at a boundary between two sections, each position determined by
  extrapolating the trajectory on each side of the boundary.  When you model
  trajectories such as microtubules, use enough points on each side of a
  boundary so that a line fit will give a reasonable extrapolation of the
  trajectory.  The number of points used for the line fit is controlled by the
  -points entry; by default, fits will be done to 5 points if they are
  available, and to a minimum of 2 points.  Thus, if a microtubule is curved
  at some distance from a boundary, you should add points densely enough so
  that the points being fit will be in a straight segment near the
  boundary. Avoid using the "Fill in Z" option, because that will create
  redundant data between actual points within a section, and incorrect data in
  a line segment across the boundary.

  In addition to trajectories, you can use contours with two points in them to
  specify the centers of features that should align across a boundary.  You
  may find that setting a symbol size or spherical point size for each point
  allows you to judge the centering of the point in a feature such as a
  vesicle.  These pairs of points are included together with the pairs of
  positions extrapolated from trajectories in a single least-squares fit to
  find the transformation at a boundary.  You can select the kind of
  transformation to solve for: translation only, rotation as well,
  magnification as well, or a full linear transformation including stretch.
  The linear transformation requires the most data, and requires data spread
  out over the area that you want to align well.

  With data from trajectories, the program can fit the data with different
  assumed spacings between the sections (gap sizes) and find the adjustment to
  the spacing that minimizes the error.  It will print out the error and other
  information for each gap size, and save the transform that occurs at the gap
  size wit the minimum error.  If you find that the minimum error occurs at a
  gap other than zero, you can change the number of sections in the final
  join, adding sections for a positive gap size and taking some away for a
  negative gap size.  If you do not want to adjust the section spacing, leave
  out the -gap option to get the best fitting solution for the current spacing
  between sections.  Note that if you are transforming a model and need to
  adjust section spacings, you can use Remapmodel after transforming.

  Xfjointomo uses the PIP package for input exclusively (see the manual page
  for pip).  The following options can be specified either as command line
  arguments (with the -) or one per line in a command file or parameter file
  (without the -):

 -input OR -InputFile   File name
    Input model file from which transforms will be found.  If this option is
    not entered, the first non-option argument will be used.

 -foutput OR -FOutputFile   File name
    Output file for list of f transforms, which align each section to the
    previous one.  If this option is not entered, the second non-option
    argument will be used.

 -goutput OR -GOutputFile   File name
    Output file for list of global transforms that can be supplied to
    Finishjoin, adjusted for any offsets used when making the join file
    that was modeled.  This entry is required unless not outputting transforms
    for every slice, in which case it must be omitted.  If this option is not
    entered, the third non-option argument will be used.

 -edit OR -EditExistingFile
    If the specified output file for f transforms exists, read transforms from
    it and use them for any boundaries not being aligned.  This option allows
    the program to be run repeatedly, computing transforms for a subset of
    boundaries each time.

 -slice OR -SliceTransforms
    Output transforms for every slice of joined tomogram that was modeled. 
    Use this option if you plan to transform the joined file instead of
    rerunning Finishjoin.

 -join OR -JoinFileOrSizeXYZ   File name
    Joined tomogram that model was built on, or its size in X, Y, and Z.  If
    this option is not entered, the image X and Y size will be used from the
    model header.

 -sizes OR -SizesOfSections   Multiple integers
    Number of slices in each section of joined file

 -zvalues OR -ZValuesOfBoundaries   Multiple integers
    Z value of last slice before each boundary (numbered from 1).  Either this
    entry or the sizes of the sections must be entered.  If this option and
    the -slice option are used, then a -join entry is also needed to inform
    the program of the full Z size of the file.

 -offset OR -OffsetOfJoin   Two integers
    Offset applied in making the join file that was modeled.  This is the same
    as the offset entry to Finishjoin, and the negative of the shift values
    that appear in eTomo.

 -binning OR -BinningOfJoin   Integer
    Binning used to make the join file that was modeled

 -refsec OR -ReferenceSection   Integer
    Reference section that was not transformed in the join, numbered from 1

 -transonly OR -TranslationOnly
    Solve for transformations that include only translations in X and Y.

 -rottrans OR -RotationTranslation
    Solve for transformations that include rotations and translations, which
    requires at least 2 points at each boundary.

 -magrot OR -MagRotTrans
    Solve for transformations that include magnifications, rotations and
    translations, i.e. no stretch.  These solutions require at least 3 points
    at each boundary.  If none of of these three options is given, the default
    is to solve for a full linear transformation, which requires at least 4
    points.

 -boundaries OR -BoundariesToAnalyze   List of integer ranges
    List of boundaries to find transformations across, numbered from 1.  The
    default is to do all boundaries.

 -points OR -PointsToFit   Two integers
    Maximum and minimum number of points to fit on each side of boundary.  If
    a contour contains the minimum number of points in each of the sections
    forming a boundary, then lines will be fit separately to the points on
    each side.  The number of points in each fit is limited by the given
    maximum value.  A contour is ignored at a particular boundary if it has
    fewer than the minimum number of points in the section on either side,
    unless it has just one point on each side.  The defaults are 5 and 2.

 -gap OR -GapStartEndInc   Three floats
    Starting and ending gap size to try between sections, and increment
    between gap sizes.  The gap sizes can be negative or positive.  Only one
    gap size will be used if the ending value equals the starting value or the
    increment is 0.  The default is 0,0,0.

 -objects OR -ObjectsToInclude   List of integer ranges
    Objects to include in the fits

 -param OR -ParameterFile   Parameter file
    Read parameter entries as keyword-value pairs from a parameter file.

 -help OR -usage
    Print help output

  -StandardInput
     Read parameter entries from standard input.

HISTORY
  Written by David Mastronarde, 10/26/06