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