Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

FINDGRADIENT(1)						       FINDGRADIENT(1)

NAME
  findgradient - Finds mag gradient that minimize montage blending error

SYNOPSIS
  findgradient [options]

DESCRIPTION
  Findgradient finds parameters related to magnification gradients that
  minimize the displacement errors when Blendmont shifts pieces into
  registration.  When the illumination in the microscope produces a
  significant gradient in magnification with changing Z height, montages taken
  at high tilt do not fit together well.  The error in the overlap zones,
  after shifting pieces into registration, can be several pixels.  Correcting
  for the gradient can reduce the error to a fraction of a pixel.  Thus, the
  parameters of the gradient can be found by adjusting them to give minimum
  error.  The two gradient parameters are the percent change in magnification
  and the degrees of rotation per micron of Z height change.  The other
  parameter that affects the Blendmont error is the effective tilt angle for
  the corrections, which can differ from the nominal tilt angle by several
  degrees.

  Findgradient can be run in three different modes, corresponding to the
  number entered with the SearchType option.  Two of these modes would be used
  when measuring mag gradients from a set of calibration montages, and the
  third would be used to adjust the tilt angles for an individual tilt series
  to give optimum correction.  

  For calibrating gradients, it is recommended that montages be taken at a
  single intensity at extreme positive and negative tilt angles (e.g., -60,
  -50, 50, and 60 degrees).  Then montages would be taken at one extreme angle
  and a series of intensities.  The first step in the analysis would be to run
  Findgradient on the sections taken at the same intensity and over a range of
  angles, computing the error from all of those sections together and
  searching for both the magnification gradient and the best offset to the
  tilt angle (SearchType 3, RunSeparately 0).  Then take the tilt offset from
  the search and specify it in the OffsetTilts entry, and search for the
  magnification gradient separately for all of the sections at the extreme
  angle (SearchType -2, RunSeparately 1).

  To find the best tilt offset for an individual tilt series once the mag
  gradients have been calibrated, select two or three views from each end of
  the tilt series.  Select views where Blendmont does not have any difficulty
  finding the displacements in the overlap zones, which may not be the case at
  the very highest tilt.  Run Findgradient to analyze all of these sections
  together and search for the tilt offset only (SearchType -1 or 1,
  RunSeparately 0).  The mag gradient file must also be specified with
  GradientFile.

  At the end of the search for each section or group of sections, the program
  prints a summary of the number of iterations in the search, the final error,
  and the gradient values.  The latter values are in addition to any initial
  gradient specified by a gradient file, so they would be entered into
  Blendmont with the AddToGradient option.

  Some of the options to Findgradient are passed directly to Blendmont.  If
  there are additional options that need to be used when running Blendmont,
  they can be specified with BlendOption entries.

  Findgradient 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 -):

 -imin OR -ImageInputFile   File name
    Montaged image input file to be analyzed

 -plin OR -PieceListInput   File name
    File with list of piece coordinates for image input file.

 -rootname OR -RootNameForFiles   Text string
    Root name for temporary files.  The program will append -fg and the
    starting and ending section numbers to create the full root name.  This
    name is used for the input parameter file (.param), files for image output
    and text output from Blendmont (.imtmp and .out), and the files created by
    Blendmont for edge functions (.xef, .yef) and edge correlations (.ecd).

 -distort OR -DistortionField   File name
    Image distortion field file to use for undistorting images.  The
    undistortion is applied when computing edge functions.

 -imagebinned OR -ImagesAreBinned   Integer
    The current binning of the images, so that the image distortion field can
    be applied correctly.  This entry is required when doing image distortion
    corrections unless the program can determine the binning unambiguously
    from the image size.

 -gradient OR -GradientFile   File name
    File with magnification gradients for each section; the minimization will
    determine the amounts to be added to these gradients.  This should be a
    file listing the tilt angle, the percent magnification change per micron
    of Z height, and the degrees of rotation per micron of Z height for each
    section, such as is produced by Extractmaggrad.

 -adjusted OR -AdjustedFocus
    Focus was adjusted for changing Z height when montage was acquired

 -addgrad OR -AddToGradient   Two floats
    This option provides starting values for the minimization.  The reported
    gradient is not incremental to these values, unlike when a gradient file
    is entered.  The magnification gradient correction is specified by two
    parameters: % of mag change per micron of Z height, and degrees of
    rotation per micron of Z height.  If -gradient has been entered, the
    values entered here will be treated as incremental to the values in the
    gradient file for each section.  If -gradient has not been entered, the
    values entered here will be used for all sections; but in this case the
    -geometry option must be entered to provide additional information.

 -geometry OR -TiltGeometry   Three floats
    This entry can be used in place of a gradient file to specify the pixel
    size in nanometers, tilt axis rotation angle, and tilt angle to be used
    for the gradient computation.  The entry has no effect if a gradient file
    is provided.

 -tiltfile OR -TiltFile   File name
    Name of file with tilt angles, one per line.  These angles will be used
    only if there is no mag gradient file to supply the tilt angles.

 -offset OR -OffsetTilts   Floating point
    Add the given value to the tilt angles from the gradient file or the tilt
    file.  For a search of 1 or 3 parameters, this value will be used as the
    starting value for finding the best offset.

 -sections OR -SectionsToDo   List of integer ranges
    List of sections on which to minimize overlap errors; comma-separated
    ranges are allowed.  The mean error over all of these sections will be
    minimized unless the -separate option is included, in which case the
    procedure is run separately on each section.

 -separate OR -RunSeparately
    Run minimization separately on each section, instead of combining the
    errors from all sections.  With this option, the list of sections must be
    specified with -sections.

 -search OR -SearchType   Integer
    Enter 1 or -1 to find just the tilt offset with a fixed mag gradient, 2 or
    -2 to find the mag gradient with a fixed tilt offset, and 3 to find both
    the mag gradient and the best tilt offset.  The latter should be used only
    when multiple sections with a big difference in their tilt angles are
    searched together (not separately).  The positive values do a search with
    a simplex algorithm.  Use -2 to find gradients with a routine that uses an
    estimated gradient from Blendmont to modify the gradient until it
    converges.  This method is faster and seems to be slightly more reliable. 
    Use -1 to search for the tilt offset with a simple routine that is faster
    and probably as reliable as the simplex routine.

 -trace OR -TraceOutput   Integer
    Output values during minimization: 1 for minima, 2 for all values

 -blend OR -BlendOption   Text string
    Option and value to pass to Blendmont.  This option will be added the end
    of the .param file.  There is no check for whether options entered this
    way conflict with the options placed into the .param file by findgradient.
    (Successive entries accumulate)

 -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.