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 reg-
       istration.  When the illumination in the microscope produces a signifi-
       cant 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.  Cor-
       recting 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 anal-
       ysis 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 gradi-
       ent 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, RunSepa-
       rately 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 addi-
       tion 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.

OPTIONS
       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 -).  Options can be abbreviated to
       unique letters; the currently valid abbreviations for short names are
       shown in parentheses.


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

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

       -rootname (-r) 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 (-d) OR -DistortionField   File name
              Image distortion field file to use for undistorting images.  The
              undistortion is applied when computing edge functions.

       -imagebinned (-ima) 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 deter-
              mine the binning unambiguously from the image size.

       -gradient (-gr) OR -GradientFile    File name
              File with magnification gradients for each section; the mini-
              mization will determine the amounts to be added to these gradi-
              ents.  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 (-adj) OR -AdjustedFocus
              Focus was adjusted for changing Z height when montage was
              acquired

       -addgrad (-add) 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 (-ge) 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 (-ti) 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 (-o) 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 (-sec) OR -SectionsToDo   List of integer ranges
              List of sections on which to minimize overlap errors; comma-sep-
              arated 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 (-sep) OR -RunSeparately
              Run minimization separately on each section, instead of combin-
              ing the errors from all sections.  With this option, the list of
              sections must be specified with -sections.

       -search (-sea) OR -SearchType       Integer
              Enter 1 or -1 to find just the tilt offset with a fixed mag gra-
              dient, 2 or -2 to find the mag gradient with a fixed tilt off-
              set, and 3 to find both the mag gradient and the best tilt off-
              set.  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 sim-
              ple routine that is faster and probably as reliable as the sim-
              plex routine.

       -trace (-tr) OR -TraceOutput   Integer
              Output values during minimization: 1 for minima, 2 for all val-
              ues

       -blend (-b) 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 accumu-
              late)

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

       -help (-h) OR -usage
              Print help output.

       -StandardInput
              Read parameter entries from standard input.

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                     findgradient(1)