Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

TOMOPIECES(1)							  TOMOPIECES(1)

NAME
	tomopieces - compute pieces for combining tomograms

SYNOPSIS
	tomopieces [options] filename

DESCRIPTION
  Tomopieces figures out how to chop up a tomogram into pieces so that the
  Fourier transforms or other operations on each piece can be done in
  memory.  It makes its decisions based on the maximum number of voxels
  that should be included in each piece.  For typical processing, such as
  for taking an FFT, the memory consumed will be about four times the
  number of voxels, since data are typically stored in memory as real
  numbers.  The program chooses a division of the volume that minimizes
  the total surface area of the extracted pieces, subject to specified
  constraints on the number of pieces in each dimension.
  
  Its one required input is the name of the tomogram file.  Optional
  inputs specify the maximum number of voxels, the maximum number of
  pieces to extract in each dimension, the border sizes for padding
  (and tapering) the extracted pieces, and the amount of overlap to
  generate between the extracted pieces. 

  It outputs the number of pieces in X and Z, the index coordinates in
  X, Y, and Z required for extracting each piece with Taperoutvol,
  and the index coordinates required for putting the pieces back
  together with Assemblevol (first the X coordinates for each position
  in X, then the Y coordinates for each position in Y, then the Z
  coordinates for each position in Z).
  
  Tomopieces uses the PIP package for input (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 -):

 -tomogram OR -TomogramOrSizeXYZ   File name
    Input file to be cut up, or the dimensions in X, Y and Z

 -megavox OR -MegaVoxels   Floating point
    Maximum number of megavoxels to allow in each piece (default 20)

 -xpad OR -XPadding   Integer
    Number of pixels to pad on each side in X (default 8)

 -ypad OR -YPadding   Integer
    Number of pixels to pad on each side in Y (default 4)

 -zpad OR -ZPadding   Integer
    Number of pixels to pad on each side in Z (default 8)

 -xmaxpiece OR -XMaximumPieces   Integer
    Maximum number of pieces in X.  Enter -1 for essentially no constraints (a
    maximum of X image size divided by 2).  The default is 0 for X and Y,
    which will make the total number of pieces in X and Y be no more than 19. 
    If the maximum for Y is set to 1, a value of 0 for X will make the number
    of pieces in X be no more than 19.  These constraints will allow
    Assemblevol to keep all files in one layer in Z open at once.

 -ymaxpiece OR -YMaximumPieces   Integer
    Maximum number of pieces in Y.  Enter -1 for essentially no constraints (a
    maximum of Y image size divided by 2).  The default is 0; see entry for
    XMaximumPieces.  If the maximum for X is set to 1, a value of 0 for Y will
    make the number of pieces in Y be no more than 19.

 -zmaxpiece OR -ZMaximumPieces   Integer
    Maximum number of pieces in Z.  The default is -1 for essentially no
    constraints (a maximum of Z image size divided by 2).

 -minoverlap OR -MinimumOverlap   Integer
    Minimum number of pixels to overlap between pieces (default 4)

 -nofft OR -NoFFTSizes
    Do not adjust the padding to give sizes suitable for an FFT.  If this
    option is entered, be sure that it is also sent to Taperoutvol.

 -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; revised for pieces in X 3/1/01
          Converted to PIP input and generalized to 3 dimensions, 6/14/04