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.  Linear or warping transforma-
       tions 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 substan-
       tial displacements between pieces, using cross-correlation to find sub-
       stantial shifts.

       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 func-
       tions 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 posi-
       tion 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 corre-
       sponding 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 more than a few pixels, then an ini-
       tial 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 the -xcorr option) 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 func-
       tions are not reliable, such as when there are large blank areas in the
       edge regions.  It is also used by default (as of IMOD 4.2.3) when there
       is only one piece in one of the two directions, because in this case
       the mean error is zero regardless of whether correlations or edge func-
       tions are used.  In such cases, you would have to use the -edge option
       to have it use the displacements from edge functions instead.

       In any case where cross-correlations are being computed, the program
       will write the displacements between pieces into a file with the exten-
       sion ".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 dis-
       placements 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).

       Sometimes there is simply not enough information in an overlap zone to
       allow the displacement between pieces to be determined.  You can
       exclude such overlap zones from being considered in two different ways:
       1) by marking edges to exclude in Midas; 2) by making a model mark-
       ing each edge to be excluded.  The simplest way to handle bad edges is
       just with Midas and not with a model file.  Do an initial run of
       Blendmont then run Midas with the .ecd file.  Find each bad edge and
       select the checkbox to exclude it.  Save the .ecd file and rerun Blend-
       mont with that .ecd file read in.

       To make a model instead, run 3dmod on the unblended montage, and edit
       the object type to make the type be scattered points with symbols dis-
       played at each point, but with no sphere radius.  Mark an edge to be
       excluded by placing a point near the middle of the line (discontinuity)
       that appears between the two adjacent pieces.  This position is actu-
       ally on one side of the overlap zone between the pieces, but Blendmont
       will be able to assign your points to edges based upon where it thinks
       each such line appears in 3dmod.  Blendmont will correctly scale a
       model that was built on a montage at a different binning than the one
       being blended.

       Information about excluded edges is maintained in the edge displacement
       (.ecd) file written and read by both Blendmont and Midas.  When
       Blendmont writes the file, it will mark all edges excluded by a model
       file.  These edges will then show up as excluded when the .ecd file is
       read into Midas.  You can fix a displacement and include an edge
       that was previously excluded, but if you do that, you should either
       remove the model file from the options to Blendmont or set the -nonzero
       option to 1 or 2, depending on whether you want to have an edge func-
       tion computed for such edges.  Otherwise, edges will be excluded if
       they either marked as excluded in the .ecd file or marked in the model
       file.

       Warping transformations can consist of either displacements at a set of
       control points, as output directly by Midas, or displacements on a
       regular grid, as produced by Xftoxg.  Such warping files contain
       information about the size of the images that were aligned and their
       pixel size.  The transforms will be adjusted for a difference between
       that pixel size and the pixel size of the image file being transformed.
       They will also be extrapolated as necessary to cover an image area
       larger than that specified in the warping file.  If there is a size
       mismatch, the program assumes that the input images are centered on the
       images with which the warping file was prepared, unless the starting
       coordinates of the file that was used for alignment are entered with
       -unaligned option.  Suitable values for this option were output when
       Blendmont was run to create the unaligned file with a line "Starting
       coordinates of output in X and Y =".

       By default, the program puts the output into a single frame.  However,
       when you specify the maximum frame size and minimum overlap of the out-
       put 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 origi-
       nal input image.  The program 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).  This behavior is silly for very
       large images and can be overridden with the -nofft option.

       The program was originally written to handle montages digitized from
       multiple film negatives, with each negative transformed so as to pro-
       duce the best fit between the negatives.  This is unlikely to work, but
       here is the documentation for it. If sections come from more than one
       negative, this may be specified in either of two ways.  If every sec-
       tion has the same division of pieces into negatives, then one can spec-
       ify 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 neg-
       atives 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 adja-
       cent negatives is then resolved into a single rotation and translation
       for each negative, so as to bring all of the negatives into best align-
       ment.  Blending of edges is performed after such rotations and transla-
       tions have been applied.

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


   INPUT AND OUTPUT FILE OPTIONS
         These options give information about input and output files.

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

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

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

       -plout (-plo) 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 (-roo) 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.

       -oldedge (-ol) OR -OldEdgeFunctions
              Use existing edge functions, if they exist, rather than comput-
              ing new ones.

       -perneg (-pe) 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 (-mis) 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.

   OUTPUT CONTROL OPTIONS
         These options control various aspects of the output.

       -mode (-mo) 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 (-fl) OR -FloatToRange
              Stretch intensities of each output section to fill range of data
              mode.

       -fill (-fi) OR -FillValue      Floating point
              Value to fill areas of the output image that have no image data.
              The value is used before any scling by the -float option, so it
              will not work as intended with -float.

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

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

       -unaligned (-una) OR -UnalignedStartingXandY       Two integers
              Starting X and Y coordinates of file used to align images with
              warping.  If warping transforms are being applied and the image
              region being output does not match the region used to align the
              images, these coordinates should be entered.  If they are not
              entered, the program will assume that the unaligned file was
              centered on the input montage.

       -order (-ord) 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.

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

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

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

       -nofft (-nof) OR -NoResizeForFFT
              Do not increase the size of the output to be suitable for taking
              an FFT.  By default, output sizes are increased to have no
              higher prime factor than 19.  This option suppresses that
              increase.  When output is to a single frame, the exact size
              requested will be output.  Otherwise, frame sizes will be made
              even.

       -origin (-ori) 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 sec-
              tions is output.  This origin adjustment is inappropriate if an
              output piece list is used to read the data into 3dmod.

       -bin (-bi) OR -BinByFactor     Integer
              Use binning to reduce images in size by the given factor.  Bin-
              ning 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 (-ma) 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 lim-
              its of the program.

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

   DISTORTION CORRECTION OPTIONS
         These options are related to corrections for an image distortion
       field and for distortion due to magnification gradients in tilted
       images.

       -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 (-gra) OR -GradientFile   File name
              File with magnification gradients to be applied for each sec-
              tion.  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 (-adj) OR -AdjustedFocus
              Focus was adjusted for changing Z height when montage was
              acquired

       -addgrad (-add) OR -AddToGradient   Two floats
              The magnification gradient correction is specified by two param-
              eters: % 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 (-ti) 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 gra-
              dient file to supply the tilt angles.

       -offset (-of) 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 (-ge) 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 (-j) 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 suit-
              able 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 (-te) 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 pro-
              duced.

   PIECE SHIFT OPTIONS
       These options are related to the determination of displacements between
       pieces in overlap zones and the shifting of pieces into best alignment.

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

       -very (-v) OR -VerySloppyMontage
              This option acts like SloppyMontage and also sets several param-
              eters 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 cor-
              relation.  The area being correlated is made wider by setting
              the extra width fraction to 0.25.  Up to 16 peaks in the corre-
              lation are evaluated by cross-correlation coefficient.  If dis-
              tortion corrections are being done, the default is changed to
              taper instead of trimming out fill areas for correlation.

       -shift (-sh) 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 (-ed) OR -ShiftFromEdges
              Use only edge functions for shifting pieces.

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

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

       -ecdbin (-ec) OR -BinningForEdgeShifts   Floating point
              The binning of the images used to determine the edge displace-
              ments being read in, relative to the current binning of the
              images, if any.  You can used binned images to determine edge
              displacements and fix them in Midas, then use those displace-
              ments directly with unbinned images by specifying the original
              binning with this option.

       -overlap (-ov) OR -OverlapForEdgeShifts       Two integers
              This option allows you to change the overlap between pieces and
              use edge displacements determined with the original overlaps.
              Bad artifacts can occur when the difference between the actual
              average overlap between pieces and the overlap in the piece list
              is big enough to change the actual coordinates of pieces by more
              than twice the piece size.  The program will detect this situa-
              tion and issue a warning advising that you change the overlap.
              You can use Edpiecepoint to get a new piece list with a dif-
              ferent overlap in one or both dimensions.  Set the new overlap
              to the old overlap minus the average edge displacement reported
              in the warning.  If you want to use existing edge displacements
              rather than starting from scratch, use this option to specify
              the overlaps in the run originally used to compute edge dis-
              placements.  If that run was done with binned images, enter the
              binned overlap value.

       -skip (-sk) OR -SkipEdgeModelFile   File name
              Model file with points near edges to exclude when computing edge
              functions and displacements.  You can exclude edges where the
              overlap cannot be determined correctly in order to prevent bad
              displacements from affecting the placement of surrounding
              pieces.  On an initial run of Blendmont, marked edges will be
              given zero correlation displacements and zero edge functions.
              On subsequent runs, the treatment of such edges may be affected
              by the -nonzero option described next.  If an edge is marked in
              a model file, it will be excluded even if it is not marked as
              excluded in the edge displacement file that was read in.

       -nonzero (-non) OR -NonzeroSkippedEdgeUse     Integer
              An indicator of how to treat excluded edges that have non-zero
              shifts read in from the edge displacement file.  Possible values
              are: 0, to exclude the edge from computation of piece shifts and
              to give it a zero edge function; 1, to include the displacement
              in the computation of piece shifts but still give the edge a
              zero edge function; 2, to include the displacement in the compu-
              tation of piece shifts and compute an edge function for it.  The
              default is 0.

       -robust (-rob) OR -RobustFitCriterion    Floating point
              When solving for the piece shifts from the displacements between
              pieces, the program can give less weight to, or completely
              ignore, displacements that appear to be outliers.  This option
              activates this robust fitting and specifies the criterion for
              determining an outlier.  A value of 1 will generally find nearly
              all outliers but may downweight some edge displacements inappro-
              priately and give a poor blend across those edges.  Higher
              values, up to about 1.5, will avoid the latter problem but will
              tend not to catch actual outliers.  This option is ideal for
              getting a higher quality blend quickly for a low-magnification
              map where grid bars ruin some of the displacements.  For data to
              be analyzed, it is preferable to fix the bad displacements or
              mark edges to be excluded in Midas.  Robust fitting is avail-
              able only with more than 10 pieces.

   EDGE FUNCTION OPTIONS
       These options control the computation and use of the edge functions.

       -width (-w) 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 (-box) OR -BoxSizeShortAndLong       Two integers
              Size of box for finding edge functions in short and long direc-
              tions.  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 512 pixels, increasing
              proportional to the maximum dimension of the frame above 512 and
              up to a value of 80.  (For this and the next two options, there
              is no increase in the default above a frame size of 4096.)  The
              default in the long direction is 1.5 times the size in the short
              direction.

       -grid (-gri) OR -GridSpacingShortAndLong      Two integers
              Spacing of edge function grid in short and long directions.  The
              default is 6 pixels in each direction for frame sizes up to 512
              pixels, increasing proportional to the maximum dimension of the
              frame above 512, up to a value of 48.

       -indents (-in) 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 3 pixels in each direction for frame sizes
              up to 512 pixels, increasing proportional to the maximum dimen-
              sion of the frame above 512 up to a value of 24 pixels.

       -goodedge (-go) 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 (-on) 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)

       -same (-sa) OR -SameEdgeShifts
              Edge shifts are the same on all sections, so that it is possible
              to use the -goodedge and -onegood options even though pieces are
              being shifted.  If pieces are being shifted, the program will
              not accept the good edge limit options unless this option is
              given.

       -exclude (-exc) 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.

       -unsmooth (-uns) OR -UnsmoothedPatchFile      File name
              Text file for edge functions before smoothing to be output as
              displacement vectors.  This file can be converted to an IMOD
              model with "patch2imod -l -f"; use the -s option to control how
              much the vector lengths are scaled.  Each edge is output at a
              different Z value, so the model can be viewed in the Zap window.
              You can use this model to assess whether the box size is large
              enough to give accurate edge functions.

       -smooth (-sm) OR -SmoothedPatchFile      File name
              Text file for edge functions after smoothing to be output as
              displacement vectors.  This file can be converted to an IMOD
              model with "patch2imod -l -f".  This model shows the functions
              actually applied when blending the overlap zones.

   PARALLEL BLENDING OPTIONS
       These options allow for running a blending operation in parallel using
       Splitblend.

       -parallel (-paral) OR -ParallelMode      Two integers
              Mode for setting up or running a parallel blend.  The second
              value should be 0 for chunks in Z, or 1 for chunks in Y.  The
              possibilities for the first value are:
                 > 0: The program will check for the legality of blending in
              parallel and output subset section or line lists for running
              with the given number of target chunks.
                -1: The program will create and write the header for a common
              output file to be written directly by multiple blends.
                -2: The program will write the given subset of sections
              directly to a common output file.
                -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.  It should not be necessary to write
              multiple files; increase the boundary pixels if artifacts occur
              when writing to a single file.

       -subset (-su) 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 neg-
              ative.

       -lines (-l) OR -LineSubsetToDo      Two integers
              Starting and ending Y values of lines to blend when running mul-
              tiple blends in parallel.  This option is ignored unless Paral-
              lelMode is negative.

       -boundary (-bou) OR -BoundaryInfoFile    File name
              File with information about boundary locations and files when
              directly writing in parallel to a single output file.

       -functions (-fu) OR -EdgeFunctionsOnly   Integer
              Compute edge functions (and correlations, if appropriate) then
              exit.  Enter 1 or 2 for X or Y edges alone, or 3 to compute
              both.  If 1 or 2 is entered and edge correlation displacements
              are being written to a file, then the first or second half of
              the file is produced in a file with extension ".xecd" or
              ".yecd", and the two halves may simply be concatenated to obtain
              the full file.  Blendmont will produce a concatenated file when
              it is told to read in the edge displacements and it finds only
              these two partial files.

   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 (-as) 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 qual-
              ity if there is substantial distortion between the two images in
              an overlap zone.  The value determines the length of the area
              relative to the width of the overlap zone, before any expansion
              of the correlated width with the -extra option.

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

       -extra (-ext) 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.

       -numpeaks (-nu) OR -NumberOfXcorrPeaks   Integer
              If this entry is greater than one, the program will keep track
              of this number of the strongest peaks in the cross-correlation,
              and for each peak, it will compute a correlation coefficient in
              real space from the pixels that overlap in the areas extracted
              from the overlap zone.  The areas will each be filtered with the
              same filter applied in the cross-correlation.  This option is
              appropriate if montages are very sloppy, because the raw peak
              strength of a correlation is less the lower the overlap between
              the areas correlated, and it is easy for a spurious peak to
              become stronger than the true peak when there is much displace-
              ment between the areas.  The true peak will generally still give
              a stronger correlation coefficient in such a case.  This value
              is set to 1 by default unless VerySloppyMontage is entered, in
              which case the default is 16.

       -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 atten-
              uated by a Gaussian curve that is 1 at this cutoff radius and
              falls off above this radius with a standard deviation specified
              by FilterSigma2.  The default is 0.35.

       -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 fre-
              quency 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.  The
              default is 0.05.

       -treat (-tr) OR -TreatFillForXcorr       Integer
              Sets the treatment of fill areas created by distortion correc-
              tions for the cross-correlations.  Enter 0 to do nothing, 1 to
              trim the correlation width to exclude possible fill areas, or 2
              to taper image into fill areas.  The default is 1, appropriate
              for image-shift based montages with reliable overlap widths.  If
              trimming overlap areas produces too little overlap, the trimming
              can be avoided either with entry 0 or 2: 0 will leave edges that
              may produce spurious correlation, while 2 will taper the image
              down at the edges.  When VerySloppyMontage is used, there are
              distortion corrections, and this option is not entered, the
              value is set to 2.

       -xcdbg (-xcd) 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.

       -taper (-ta) OR -TaperFraction      Floating point
              Discontinued option

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


INTERACTIVE 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 nega-
       tives, 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 speci-
       fying 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 direc-
       tions.


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.

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                        blendmont(1)