Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

SORTBEADSURFS(1)				               SORTBEADSURFS(1)

NAME
  sortbeadsurfs - preprocess 3D model of gold bead positions for flattenwarp

SYNOPSIS
  sortbeadsurfs [options] input_model output_model

DESCRIPTION

  Sortbeadsurfs can be used to process two different kinds of models of the 3D
  positions of gold beads to make them suitable to use in Flattenwarp for
  describing a surface to be flattened.  One kind of model would be of gold
  positions measured directly in the tomogram, such as by Findbeads3d.
  Here it is essential that if the beads are on two surfaces, each surface be
  represented by a separate object.  Sortbeadsurfs uses the same routine that
  Tiltalign does to sort the beads into two objects.  The second kind of
  model is the one produced by Tiltalign of the fiducial positions in 3D.
  Here it is essential that the model be tilted around the X axis by the X
  axis tilt used to generate the tomogram, that its X and Y coordinates be
  shifted and/or scaled as appropriate to match the final tomogram, and that
  the points are in only one object for each surface.

  If you have a model from Findbead3d(1), you should first edit it to remove
  points that are obviously not on the surfaces.  (Flattenwarp has an option
  for removing more subtle outlying points, but it is best to get rid of the
  obvious points beforehand.)  Then run this program on the model.  Examine
  the output model to make sure points have been sorted correctly between the
  two surfaces.  If not, and if the failure is because the surface is too
  warped to analyze all at once, then try the -subarea option to analyze the
  beads in subareas.  If subareas are not suitable, you may have to edit the
  model to fix errors.  Each point in the output model is a separate contour,
  so it is possible to click on points with the third mouse button in the
  model view window to select them, and use the Edit_contour-Move dialog to
  move the points to the right object.

  If you have a model from Tiltalign, you should run this program on it to
  apply the X axis tilt that was used when generating the tomogram.  The
  program will attempt to sort the points into two surfaces, but if this
  creates a problem, use the -already option to skip the sorting if they are
  already sorted into two surfaces.  If fiducials were tracked with multiple
  objects, the program automatically combines them into two objects based on
  the colors of the objects.  If the beads are on one surface, use the -one
  option to skip the sorting and combine multiple objects, if any, into one
  object.  The program has a host of options for adjusting for: a full aligned
  stack bigger or smaller than the original stack; binning of the prealigned
  stack or of the final aligned stack or tomogram; trimming of the tomogram in
  X or Y (or alternatively, generation of a tomogram that is a subarea in X
  and Y); or flipping by Y and Z rather than rotation around X in the trimming
  step.

  You should be able to load the resulting model on the tomogram to verify
  that it has the right coordinates.  To do so, be sure to use the -rescale
  option to account for any change in binning and to start 3dmod with the
  -m option so that it ignores previous scale information in the model.  The
  points will not be on the right Z planes, so you will have to use the
  Edit-Model-Offsets dialog to shift the model in Z until it fits.

  Sortbeadsurfs 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 with scattered points for 3D gold bead positions.  If
    this option is not entered, the first non-option argument will be used for
    this file.

 -output OR -OutputFile   File name
    Output file for processed model.  If this option is not entered, the
    second non-option argument will be used for this file.

 -flipyz OR -FlipYandZ   Integer
    This option allows control over whether the Y and Z coordinates of the
    model are flipped.  By default, flipping will be done if the Z dimension
    (nz) of the modeled volume is greater than the Y dimension (ny).  Enter 1
    to force flipping even if this is not the case, or 0 to prevent it if this
    is the case.

 -subarea OR -SubareaSize   Integer
    Size of subareas over which to analyze for two surfaces.  This option is
    needed only if the area coated with beads is large enough and warped
    enough that the analysis fails to separate the two surfaces.  The area
    occupied by beads will be divided into non-overlapping subregions of
    approximately the given size in each dimension.  Each will be analyzed
    separately to sort all of the beads between the two surfaces.  Make this
    value as large as possible, since the analysis can easily fail if there
    are only ~10 beads in any of the subareas.

 -majority OR -MajorityObjectOnly
    Output a model with only one object containing the points on the surface
    that has the most beads.  Use this option if there are too few fiducials
    on one surface to fit a smooth surface to in Flattenwarp.

 -xaxis OR -XAxisTilt   Floating point
    The value of X axis tilt used when the tomogram was generated.  This value
    is needed for a 3D fiducial model output by Tiltalign (and only for
    such a model).

 -invert OR -InvertZAxis
    Invert the Z coordinates of the points so that they will match a
    reconstruction that was Y-Z flipped rather than rotated around the X axis.
     This option is needed only for a 3D fiducial model output by
    Tiltalign.

 -already OR -AlreadySorted
    Use this option to skip the analysis that sorts beads between two
    surfaces, and combine multiple objects by color if there are any.  You
    would use this for a 3D fiducial model from Tiltalign if the beads are
    already correctly sorted into two surfaces, or if they are on only one
    surface and in only one object.

 -one OR -OneSurface
    Use this option to skip the analysis that sorts beads between two
    surfaces, and to combine all points into one object.  You would use this
    for a 3D fiducial model from Tiltalign if the beads are all on one
    surface but in different objects.

 -aligned OR -AlignedSizeXandY   Two integers
    Unbinned X and Y size of the aligned stack used to make the
    reconstruction.  Use this option if the reconstruction is based on a final
    aligned stack whose unbinned size is smaller or larger than that of the
    raw stack, and if you are processing a 3D fiducial model from
    Tiltalign.  If the prealigned stack was binned, you must also enter the
    -prebin option.

 -xtrim OR -XTrimStartAndEnd   Two integers
    Starting and ending X coordinates of the aligned stack that appear in the
    final trimmed reconstruction, numbered from 1.  See next option.

 -ytrim OR -YTrimStartAndEnd   Two integers
    Starting and ending Y coordinates of the aligned stack that appear in the
    final trimmed reconstruction, numbered from 1.  These two options are
    needed only for a 3D fiducial model from Tiltalign.  If you built the
    full reconstruction (no SLICE or WIDTH and OFFSET entries to Tilt),
    then the coordinates for these two options are just the ones used to trim
    the volume with Trimvol.  If you built a subset of the reconstruction,
    the WIDTH and OFFSET entries can be used to derive the X coordinates, and
    the SLICE entries provide the Y coordinates.  If you then trimmed the
    volume, you need to combine the trimming coordinates with the one used to
    build the reconstruction.  If you enter these coordinates, you must enter
    the prealigned and the aligned stack binning if either is different from
    one.

 -prebin OR -PrealignedBinning   Integer
    Binning of prealigned stack used to build a 3D fiducial model.  This
    option is needed for a binning other than 1 if you enter the aligned stack
    size or trimming coordinates, or if you want to rescale to the coordinates
    of the reconstruction.

 -recbin OR -ReconstructionBinning   Integer
    Binning of aligned stack used to build the reconstruction.  This option is
    needed for a 3D fiducial model if you are entering trimming coordinates or
    if you want to rescale coordinates to match the reconstruction.

 -rescale OR -RescaleByBinnings
    Rescale the model coordinates to account for binning of the prealigned or
    final aligned stack.  By default output coordinates will still have the
    scaling of the prealigned stack; use this option to rescale them so that
    they match the scaling of the reconstruction.

 -check OR -CheckExistingGroups
    Check that the sorting is the same as in the input model, which must
    already have points divided into two groups.  All other output is
    suppressed, and if the sorting matches the program just exits with 0
    status; if there is a mismatch it prints the number of incorrect points
    and exits with an error status.

 -set OR -SetSurfaceSortParam   Two floats
    Set one parameter specified by the first number to the value specified by
    the second number in the surfaceSort routine.  See the library
    documentation of surfaceSort (or the code) for a list of the parameters. 
    To set the verbose level, use "-set 13,1" or "-set 13,2".
    (Successive entries accumulate)

 -help OR -usage
    Print help output.

  -StandardInput
     Read parameter entries from standard input.


HISTORY
  Added to IMOD, 12/6/09