Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

BLENDMONT(1)							   BLENDMONT(1)

NAME
	blendmont - aligns and blends overlapping edges of montaged images

SYNOPSIS
	blendmont  [options]

DESCRIPTION

  BLENDMONT will take montaged images, blend their overlapping edges
  together, and output the blended images with essentially no overlap.
  Transformations can be applied to align serial sections, and
  densities can be floated over whole sections so that density
  occupies the maximum range for each section.  The program can also
  correct for minor or substantial displacements between pieces, using
  cross-correlation to find substantial shifts.  Multinegative montages
  can also be handled, with each negative transformed so as to produce
  the best fit between the negatives.

  The program performs these feats by examining each edge, or region
  of overlap, between adjacent pieces, and deriving a function that
  maps pixels in one piece to corresponding pixels in the adjacent
  piece.  These "edge functions" are stored in two separate files (for
  pieces that are adjacent in X or Y, respectively).  Thus, even if one
  needs to run the program more than once on the same input images,
  the edge functions need to be calculated only once, since they can
  be read from the files on later runs.  However, if the input image
  file is changed in any way, the edge functions must be recalculated.

  To blend images at an overlap zone, the program considers each pixel 
  in the output image in turn.  It finds the two corresponding 
  positions (in the two adjacent input pieces) whose weighted average 
  equals the position of the desired output pixel, where the weights
  are proportional to the distance across the overlap zone.  Near one
  edge of the overlap zone, the output pixel has very nearly the same
  position as the corresponding pixel in the nearby piece; in
  the middle of the overlap zone, the output pixel has a position
  midway between the positions of the corresponding pixels in the two
  pieces.

  If pieces are shifted by more than a few pixels from the positions
  specified by their piece coordinates, then the program will not be
  able to find the edge functions without doing an initial 
  cross-correlation between the regions that overlap in adjacent
  pieces.  Thus, if your montage is "sloppy" enough, you should select
  the option for initial cross-correlations.
  
  If the pieces are shifted at all from the positions specified by
  their piece coordinates, the program can correct for this.  It can
  take the information about the shift between each pair of overlapping
  pieces and use it to find the amounts to shift each piece so as to
  fit the pieces together best.  If the shifts are large, then an
  initial cross-correlation should be selected; otherwise this step is
  not needed.  There are three ways to implement this correction step.
  One is based solely on the information in the edge functions.
  Another is a hybrid method based  on both cross-correlation and edge
  functions; the program will solve for shifts twice, using the
  displacements implied by the edge  functions then those implied by
  correlations, and select the solution that gives the smallest mean
  error.  The third method is based on cross-correlations alone and is
  not as reliable as the hybrid method.  This method should be used
  with older data if it is important to have an image stack that
  exactly matches that produce by Blendmont prior to June 1, 2001,
  when the hybrid option was implemented. It might also be useful in
  cases where the edge functions are not reliable, such as when there
  are large blank areas in the edge regions. 

  In any case where cross-correlations are being computed, the program
  will write the displacements between pieces into a file with the
  extension ".ecd".  On another run of the program, you can choose to
  have these displacements read in from the file, just as edge
  functions can be read in instead of recomputed.  This allows you to
  edit bad displacements with Midas, then use Blendmont to get a
  stack with pieces properly shifted into register.

  If your montage frames have large displacements from their nominal
  positions, then a number of parameter changes can be needed to get
  reliable correlations.  Select the VerySloppyMontage option to get
  these parameter settings (see below for full listing).  If there are
  still numerous bad displacements in edges where there appears to be
  usable image information, then two of these parameters can be varied
  further.  Experiment with larger values of AspectRatio, the ratio of
  length to width of the overlap areas being correlated (up to 10), and
  with a larger value of ExtraXcorrWidth, which makes the areas being
  correlated wider than the nominal overlap zone (up to 0.5 has been
  tried with good results).

  If sections come from more than one negative, this may be specified
  in either of two ways.  If every section has the same division of
  pieces into negatives, then one can specify this universal division 
  into negatives as an interactive input to the program.
  Alternatively, one may add negative numbers after the z coordinates
  in the file of piece coordinates.  The only restriction on these
  numbers is that they should be non-zero, and every piece from the
  same negative should have the same number.  Thus, one could number
  negatives 1, 2, 3 ... in each section that has multiple negatives,
  or one could use the identifying number on each negative.

  When pieces of a section come from more than one negative, the
  program uses the edge functions between the negatives to determine
  how each negative should be rotated and translated to align it with
  adjacent negatives.  This collection of rotations and translations
  between adjacent negatives is then resolved into a single rotation
  and translation for each negative, so as to bring all of the
  negatives into best alignment.  Blending of edges is performed after
  such rotations and translations have been applied.

  When you specify the maximum frame size and minimum overlap of the
  output image, the program will pick the largest frame size less than
  that maximum, with the smallest overlap greater than that minimum,
  so that the resulting image will contain at least as many pixels as
  the original input image.  It picks a frame size that is a multiple
  of 2 and has no prime factor greater than 19 (so that fourier
  transforms can be run on the resulting pieces).

  Blendmont uses the PIP package for input (see the manual page for pip)
  and can still take sequential input interactively, to maintain compatibility
  with old command files.  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 blended.

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

 -imout OR -ImageOutputFile   File name
    Output file for blended images.

 -plout OR -PieceListOutput   File name
    File for list of coordinates of pieces in output image file.  This entry
    may be omitted if the output images are not being cut into pieces.

 -rootname OR -RootNameForEdges   Text string
    Root name for edge function and .ecd files.  Two files will be created or
    sought for, with the extensions .xef and .yef attached to this root name.

 -mode OR -ModeToOutput   Integer
    Mode for output file: 0 for bytes, 1 for integers, 2 for reals.  The
    default is the same mode as the input file.

 -float OR -FloatToRange
    Stretch intensities of each output section to fill range of data mode.

 -xform OR -TransformFile   File name
    File with g transformations to apply to align the images.

 -center OR -TransformCenterXandY   Two floats
    X and Y coordinates of center of transformations.  The default is the
    center of the input image.

 -order OR -InterpolationOrder   Integer
    Order of interpolation to use: 1 for linear, 2 for quadratic (the only one
    available before IMOD 3.6), 3 for cubic; the default is cubic when the
    program is run with PIP input and quadratic when run with sequential
    input.

 -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 to be applied for each section.  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.  The mag gradient
    correction is applied before a distortion field correction and is used
    when computing edge functions.

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

 -addgrad OR -AddToGradient   Two floats
    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, this option can be used to
    increment 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, and also -tiltfile if the data are at different
    tilt angles.

 -tiltfile OR -TiltFile   File name
    Name of file with tilt angles, one per line.  These angles will be used in
    computing mag gradients, 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.  Sometimes the gradient that gives the lowest error in registering
    the pieces will differ between the positive and negative side of the tilt
    series.  This entry can be used to give a better overall error reduction.

 -geometry OR -TiltGeometry   Three floats
    When magnification gradients are being corrected for, 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.

 -justUndistort OR -JustUndistort
    With this entry, the program can be used just to correct for magnification
    gradients and distortion fields, without computing edge functions or
    blending images.  The resulting images are the same as those used to
    compute edge functions, and will be suitable for fixing edge functions in
    Midas.  Either -distort or -gradient must be entered with this option. 
    The sections to do may be specified, but all entries with regard to frame
    and total sizes in X and Y and edge functions will be ignored.

 -test OR -TestMode
    This entry runs the program in a special mode in which it will compute
    edge functions and find the best shifts of the pieces for a given
    magnification gradient correction.  Output images will not be computed,
    although an empty output file will be produced.

 -sloppy OR -SloppyMontage
    Do initial cross-correlations for finding edge functions and shift pieces
    to minimize displacements in the overlap zones

 -very OR -VerySloppyMontage
    This option acts like SloppyMontage and also sets several parameters for
    dealing with very sloppy montages with displacements potentially bigger
    than half the width of the overlap zones.  The aspect ratio of the area
    used for correlating the overlap zones is increased from 2 to 5 and the
    filter parameter radius1 is set to -0.01 to eliminate more low frequencies
    from the correlation.  The fraction of the area over which images are
    tapered is increased from 0.1 to 0.2 to further reduce the frequencies of
    edge effects, and the area being correlated is made wider by setting the
    extra width fraction to 0.25.

 -shift OR -ShiftPieces
    Shift pieces to minimize displacements in the overlap zones.  The default
    is to use information from edge functions and from cross-correlations for
    each section and pick the one that gives lowest error.

 -edge OR -ShiftFromEdges
    Use only edge functions for shifting pieces.

 -xcorr OR -ShiftFromXcorrs
    Use only cross-correlations of overlap zones for shifting pieces (legacy
    behavior).

 -readxcorr OR -ReadInXcorrs
    Read displacements in the overlap zones from an existing .ecd file instead
    of computing correlations.

 -sections OR -SectionsToDo   List of integer ranges
    List of sections to blend into output file; comma-separated ranges are
    allowed.

 -xminmax OR -StartingAndEndingX   Two integers
    Minimum and maximum X index coordinates to output (numbered from 0).  The
    default is to output the entire image.

 -yminmax OR -StartingAndEndingY   Two integers
    Minimum and maximum Y index coordinates to output.

 -origin OR -AdjustOrigin
    Adjust the origin values in the image file header based on the starting X,
    Y, and Y that are output.  With this adjustment, a model built on the
    input stack should be correctly located when loaded onto the output stack
    in 3dmod.  Model points will be correctly located in Z provided that a
    contiguous set of sections is output.  This origin adjustment is
    inappropriate if an output piece list is used to read the data into 3dmod.

 -bin OR -BinByFactor   Integer
    Use binning to reduce images in size by the given factor.  Binning is
    applied to the data just before output, so the starting and ending X and Y
    coordinates to output should be specified in unbinned pixels.  With
    binning, the output must be a single piece.

 -maxsize OR -MaximumNewSizeXandY   Two integers
    Maximum size in X and Y of pieces in output file.  The default is to make
    output be a single piece, unless it exceeds the limits of the program.

 -minoverlap OR -MinimumOverlapXandY   Two integers
    Minimum overlap between pieces in X and Y in output file.  The default is
    an overlap of 2.

 -oldedge OR -OldEdgeFunctions
    Use existing edge functions, if they exist, rather than computing new
    ones.

 -perneg OR -FramesPerNegativeXandY   Two integers
    Number of frames in X and Y per negative for a multi-negative montage. 
    This option could be used instead of having negative numbers in the piece
    list file.

 -missing OR -MissingFromFirstNegativeXandY   Two integers
    Number of pieces missing from the first negative in X and Y.  For example,
    if there are 3 negatives across, with 2, 4, and 1 pieces in X from each,
    then the number missing is 2.

 -width OR -BlendingWidthXandY   Two integers
    Width in X and Y across which to blend overlaps.  The default is: 
      80% of the overlap zone width for overlap width less than 63, 
      50 pixels for overlap width between 63 and 100, or 
      50% of the overlap width for overlap width greater than 100.

 -boxsize OR -BoxSizeShortAndLong   Two integers
    Size of box for finding edge functions in short and long directions.  The
    short direction is across an overlap zone, the long direction is along it.
     The default size is 10 pixels in the short direction for frame sizes up
    to 1024 pixels, increasing proportional to the maximum dimension of the
    frame above 1024.  The default in the long direction is 1.5 times the size
    in the short direction.

 -grid OR -GridSpacingShortAndLong   Two integers
    Spacing of edge function grid in short and long directions.  The default
    is 10 pixels in each direction for frame sizes up to 1024 pixels,
    increasing proportional to the maximum dimension of the frame above 1024.

 -indents OR -IndentShortAndLong   Two integers
    Borders at the edge of the overlap zone in the short and long directions
    which will be excluded when finding edge functions.  The default size is 5
    pixels in each direction for frame sizes up to 1024 pixels, increasing
    proportional to the maximum dimension of the frame above 1024.

 -goodedge OR -GoodEdgeLowAndHighZ   Two integers
    Default lower and upper Z limits for where edge functions are good
    (numbered from 0).  Beyond these limits, the edge functions will be taken
    from the last good Z value.  If this option is entered, these limits will
    applied to all edges except ones specified with onegood.

 -onegood OR -OneGoodEdgeLimits   Multiple integers
    This options specifies lower and upper Z limits for a specific edge;
    beyond these limits the edge functions will be taken from the last good Z
    value.  Five values are expected: number of frame below the edge in X and
    Y (numbered from 1), 1 for an edge in X or 2 for an edge in Y, lower and
    upper Z limits (numbered from 0).
    (Successive entries accumulate)

 -exclude OR -ExcludeFillFromEdges
    With this option on, the program will detect image areas near an overlap
    zone that consist of uniform values and exclude these areas when computing
    the edge function.  In addition, in areas along an edge where one piece
    consists of uniform values and the other has actual image data, it will
    use the actual data across the whole edge instead of transitioning to the
    uniform data.

 -parallel OR -ParallelMode   Two integers
    Mode for setting up or running a parallel blend.  The possibilities for
    the first value are: 
       > 0: The program will check for the legality of blending in parallel
    and output subset section lists for running with the given number of
    target chunks.  The second value should be the maximum number of sections
    to put in each chunk.  
      -1: The program will create and write the header for a common output
    file to be written directly by multiple blends.  The second value is
    irrelevant.  
      -2: The program will write the given subset of sections directly to a
    common output file.  The second value is irrelevant.  
      -3: The program will take the SubsetToDo as the SectionsToDo and write
    these sections to a new file; multiple files will need to be stacked
    afterwards.  The second value is irrelevant.

 -subset OR -SubsetToDo   List of integer ranges
    List of subset of sections to blend when running multiple blends in
    parallel.  This option is ignored unless ParallelMode is -1 or -2.

CROSS-CORRELATION CONTROL OPTIONS 
  These options control the cross-correlations used to find the initial
alignment in the overlap zones when montages are sloppy.

 -aspect OR -AspectRatioForXcorr   Floating point
    Maximum aspect ratio of areas cross-correlated in overlap zones.  The
    default is 2, which is generally adequate.  Larger values are required if
    the displacements can be very large, but the value should not be made much
    larger than necessary because the correlations will take longer to compute
    and may be poorer quality if there is substantial distortion between the
    two images in an overlap zone.

 -pad OR -PadFraction   Floating point
    Areas from the overlap zones will be padded by this fraction on each side
    for correlation.  The default value is 0.45, which allows large shifts to
    be measured unambiguously.  Padding for the short dimension will be this
    fraction times the size in that dimension; padding in the long dimension
    will be either this fraction times the long dimension size, or 0.9 times
    the size in the short dimension, whichever is smaller.

 -taper OR -TaperFraction   Floating point
    Areas from the overlap zones will be tapered down to their mean
    intensities over a distance equal to this fraction times the size in the
    respective dimension.

 -extra OR -ExtraXcorrWidth   Floating point
    This entry will increase the width of the areas correlated in overlap
    zones by including image area in the interior of each frame, i.e., outside
    the overlap zone.  The width of the extra area is this fraction times the
    width of the area within the overlap zone.  This option is appropriate if
    montages are very sloppy, particularly if they tend to overlap by much
    more than the nominal amount.

 -radius1 OR -FilterRadius1   Floating point
    When this entry is positive, low spatial frequencies in the overlap zone
    cross-correlations will be attenuated by a Gaussian curve that is 1 at
    this cutoff radius and falls off below this radius with a standard
    deviation specified by FilterSigma2.  Spatial frequency units range from 0
    to 0.5.  A negative entry is used to set the starting point of the filter
    specified by FilterSigma1, which gives a more predictable attenuation of
    low frequencies.

 -radius2 OR -FilterRadius2   Floating point
    High spatial frequencies in the cross-correlation will be attenuated by a
    Gaussian curve that is 1 at this cutoff radius and falls off above this
    radius with a standard deviation specified by FilterSigma2.

 -sigma1 OR -FilterSigma1   Floating point
    Sigma value to filter low frequencies in the correlations with a curve
    that is an inverted Gaussian.  This filter is 0 at 0 frequency and decays
    up to 1 with the given sigma value.  However, if a negative value of
    radius1 is entered, this filter will be zero from 0 to |radius1| then
    decay up to 1.  The default is 0.05.

 -sigma2 OR -FilterSigma2   Floating point
    Sigma value for the Gaussian rolloff below and above the cutoff
    frequencies specified by FilterRadius1 and FilterRadius2

 -xcdbg OR -XcorrDebug
    Output image files with the padded images being correlated in the overlap
    zones and with the cross-correlations.  Separate files are generated for X
    and Y edges, with extensions .xdbg and .ydbg.

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


  If there are no command-line arguments, Blendmont takes sequential input
  the old way, with the following entries:

  Input image file

  Output image file

  Data mode for output file (the default is same as mode of input)

  1 to float each section to maximum range for the data mode, 0 not to

  Name of file of g transforms to apply to align the sections, or a
   	blank line for no transforms

  Name of input file with list of piece coordinates

  IF this file has entries specifying that pieces are on different
  negatives, enter 1 to do an initial cross-correlation in the overlap
  zones to find the average displacement between pieces

  IF this file does NOT have any entries specifying that pieces belong
  to different negatives, there are several possibilities for either
  specifying negatives or correcting for displacements between frames.
  Use the negative of an option to do initial cross-correlations to
  correct for sloppy montages:

   	Enter 1 or -1 to specify how the sections should be divided
           into negatives
        OR 2 or -2 to use edge functions to find a shift for each frame
           that aligns the frames as well as possible
        OR 3 or -3 to use cross-correlations exclusively, rather than
           edge functions to find the best shift for each frame
           (obsolete, use 5/-5 except to replicate old data)
        OR 4 or -4 to use only cross-correlations read from an edge
           correlation displacement file to find the best shifts
           (obsolete, use 6/-6 except to replicate old data)
        OR 5 or -5 to use both cross-correlations and edge functions
           (whichever is better) to find the best shifts
        OR 6 or -6 to use both cross-correlations read from a file and
           edge functions to find the best shifts
  	OR 0 for none of these options

     IF you enter 1 or 2 to specify division into negatives, enter 2 
           lines:

   	# of frames (pieces) per negative in the X direction, and the
   	    # of frames missing from the left-most negative.  E.g., if
   	    there are 2 frames from the left-most negative, 4 from the
   	    middle one, and 1 from the right-most one, there are 4
   	    frames per negative, with 2 missing from the left-most one

   	# of frames (pieces) per negative in the Y direction, and the
   	    # of frames missing from the bottom-most negative.

  Name of new file for list of coordinates of pieces in the output file, or
  Return to skip making this file, which is not needed when the output image
  is a single piece.

  IF you have g transforms, enter on the next line:
     X and Y center coordinates of the transforms, or / to accept the
     default, which is the center of the input image.

  List of sections to be included in output file, or / to include all
     sections from the input file in the output file.  Ranges may be
     entered (e.g. 0-5,8-14,17-23)

  Minimum and maximum X, and minimum and maximum Y coordinates that
   	should be included in the output image.  Enter "/" to obtain
   	the entire input image.

  Maximum limit on the X and Y frame size for output pieces, and
   	minimum limit on overlap between output pieces.  The program
   	will then choose new frame sizes and overlaps based on these
   	limits

  0 to accept the program's choices of frame size and overlap.  When
   	running interactively, entering 1 will allow you to loop back
   	and enter new minimum and maximum X and Y coordinates and a
   	new maximum frame and minimum overlap.  Note that on the first
        two entries, the program will enforce a minimum overlap of 2;
        if for some reason you want an overlap of 0, you need to loop
        back so that you enter the frame size and overlap 3 times.

  0 to build new files of edge functions, 1 to use old files that were
   	generated on a previous run of the program

  Root filename for edge function files. 

  Widths over which to blend positions at an edge, in the X and Y directions.


HISTORY
  Written by David Mastronarde, February 1989
  12/21/98: added ability to do initial cross-correlation and to find best
  shifts to correct for sloppy montages
  6/1/01: implemented ability to write and read in edge correlation
  displacements; added a search step to improve on cross-correlations  
  8/9/03: converted to PIP input.