blendmont(1) General Commands Manual 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.
Shifting Pieces into Alignment
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.
Very Sloppy Montages
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).
Excluding Edges
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.
The program can automatically detect some bad overlaps and mark them to
be skipped. It analyzes the local standard deviation within the images
being correlated for the initial shifts, and computes the 95th per-
centile value of the local SD. Once all edges on a section are ana-
lyzed, it computes the median of this value and the median deviation
from the median. Edges whose deviation from the median value suffi-
ciently exceed the median deviation are set to be excluded. This
method should work well for overlap areas that are black (i.e, over
grid bars), and may also work for areas over featureless resin if they
sufficiently few and if the distribution of SD values in the remaining
edges is distinct enough from that of the blank areas.
To make a model instead of Midas, run 3dmod on the unblended mon-
tage, and edit the object type to make the type be scattered points
with symbols displayed 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 actually 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 bin-
ning 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
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 =".
Correcting Intensity Differences and Gradients
Two kinds of intensity problems can be corrected: variations in illumi-
nation or camera response between pieces, and consistent gradients in
illumination or response within each piece. The program can actually
apply corrections in three different ways:
1) From measurements of intensity differences between adjacent pieces
where they overlap, it can solve for the scaling to apply to each piece
that will minimize those intensity differences. This involves solving
the same kind of linear equations that are used to determine the shift
of each piece from the shifts in their overlap zones.
2) The same intensity differences can be averaged over the full
extent in X and Y (as long as there are at least two pieces in each
direction) to give an average planar gradient in intensity. When a
gradient is being determined this way, it is used to adjust the inten-
sity differences that are used to solve for individual piece scalings
in (1). However, if the illumination changes progressively during a
large montage, the effect on these intensity differences is indistin-
guishable from the effect of a gradient within each piece. Thus, try-
ing to correct for gradients this way can result in a gradient being
imposed within each piece instead, or an existing gradient being incom-
pletely removed. Also, the solution will fail to remove the progres-
sive change because it gets incorporated into the gradient. This prob-
lem will not occur with montages small enough for the illumination to
be essentially the same for each piece.
3) The problem just described with large montages can be solved with
an independent method of estimating the gradient: summing all of the
montage pieces and fitting a plane or a higher order polynomial to
them. The Clip program provides two operations for this fitting:
"planefit", which fits a plane and outputs the slopes of the plane for
use in Blendmont; and "flatfield", which fits a polynomial with an
order up to 4 and produces an image from the polynomial that will cor-
rect the gradient by multiplication. In both cases, the fit can be
based on a subset of images, or on multiple image files. This method
will work best if nearly all pieces being summed are uniformly filled
with material, or if so many pieces are summed that it overcomes non-
uniformities. For example, the sum will have an inappropriate gradient
if cellular material fills the lower right of a montage but the left
and upper sides have pieces dominated by resin outside of a cell. The
simplest way to invoke this correction is with the -sum option to
Blendmont, which runs "clip planefit" on the entire image stack and
uses the result. The slopes are placed in a file with the root name of
the input file plus "_grad.txt".
The gradient correction based on image sums, (3), is applied to all
images when they are read in, with the same correction is applied to
all sections. Edge functions and intensity differences are computed
from these corrected images. The corrections based on intensity dif-
ferences, (1) and (2), are computed separately for each section and are
applied only when composing the output image. It should always be use-
ful to solve for piece scalings after an initial sum-based gradient
correction; it may also be useful to do a second-order correction for
gradients based on intensity differences, but only if there are not
progressive changes across the montage that could masquerade as gradi-
ents.
Output Frame Size
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.
Obsolete/Untested Handling of Multiple Negatives
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.
-aligned (-al) OR -AlignedPieceCoordFile File name
Full file name or extension for an output file of aligned coor-
dinates of input pieces, namely the original coordinates plus
the alignment shift for each piece, rounded to the nearest inte-
ger. If an extension is entered, .i.e. a string starting with
".", the file will be named with the root name for edge func-
tions plus this extension. Each line will have aligned coordi-
nates (X, Y, Z) comparable to ones in the input piece list, the
piece number in X and Y, numbered from one, and the aligned
coordinates in X and Y starting from 0. The first line will
also have the piece size in X and Y.
-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.
INTENSITY CORRECTION OPTIONS
These options control correction of intensity differences and gradi-
ents
-intensity (-int) OR -FixIntensityFromEdges Integer
Analyze intensity differences between each pair of pieces in
their overlap zone and solve for the scaling factors to apply
that will minimize these differences. With an entry of 2, the
program will first average the intensity differences over the
whole range in X and in Y to determine the two slopes of a pla-
nar intensity gradient. The intensity differences will be
adjusted for this gradient before solving for the scaling fac-
tors.
-base (-ba) OR -BaseIntensityForScaling Floating point
A base value for the intensity scaling, the value that would be
obtained with no illumination or no signal obtained from the
sample. This value is subtracted before scaling, then added
back on. Usually, with transmission EM, the base value is zero;
however, if unsigned values are stored as signed integers by
subtracting 32768, the base would be -32768.
-sum OR -SumPiecesForGradient
Add together all the pieces in the image file and fit a plane to
the sum to estimate a planar intensity gradient. With this
option, the program first runs "clip planefit" on the input file
and reads in the gradient slopes that it produces (see Clip).
All pieces are adjusted for this gradient when read in, and edge
functions are thus based on such adjusted data. If the gradient
values change, i.e., if this option is added or dropped out, the
edge functions need to be recomputed.
-other (-ot) OR -OtherSumGradientFile File name
File with planar intensity gradient estimated separately, such
as by running "clip planefit" on a collection of image files in
addition to the input file. This option cannot be used with
-sum.
-flatfield (-fla) OR -FlatfieldFile File name
File with image to scale by for correcting intensity gradients.
Such a file can be produced by summing one or several image
files, including the input file here, with "clip flatfield".
Generally, one would use the -n option to Clip(3) to specify the
order (2 to 4) of a polynomial to fit to the summed image, in
which case the flatfield image will be the inverse of that poly-
nomial.
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 signed 16-bit integers,
2 for 32-bit floats, 6 for unsigned integers, 12 for 16-bit
floats. The default is the same mode as the input file,
although the default mode of floating point output for MRC files
is governed by the value of environment variable
IMOD_WRITE_FLOATS_16BIT. Mode 12 is allowed only if the output
format is MRC.
-float (-flo) 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 scaling 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 qua-
dratic 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 Floating point
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.
-emgrid (-em) OR -EMGridMapFilter Floating point
Set up filters and other parameters for finding piece shifts in
a grid map where there may be strong signals from regularly
spaced holes within grid squares. The entry specifies the high
frequency cutoff frequency in reciprocal microns, which will be
converted to a value of radius2 in reciprocal pixels of images
that are cross-correlated to find initial shifts. The falloff
(sigma2) will be set to 1/8 of the cutoff. For the low fre-
quency filter, sigma1 is set to a default of 0.01 and radius1 is
set to 0 even if -very was entered. These values can be over-
ridden with -sigma1 and -radius1 entries, but neither -radius2
nor -sigma2 can be entered. In addition, the default number of
cross-correlation peaks analyzed is set to 50, or 100 if -very
is entered; this can be overridden with the -numpeaks option.
Weighting by deviation from the expected shifts is also acti-
vated with the default half-fall distance, which can be modified
with the -weight option, or effectively disabled with a very
large entry to the option.
-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.
-weight (-we) OR -WeightForExpectedShifts Floating point
Analyze multiple cross-correlation peaks when finding the ini-
tial shift between a pair of pieces and weight their cross-cor-
relation coefficients by their distances from the expected peak
position. This option can be helpful when there are periodic
structures that produce many cross-correlation peaks, but only
if the montage pieces were acquired in reasonably good align-
ment, so that the correct match between these periodic struc-
tures has the lowest shift. The weighting is with a Gaussian
function that falls to half at a default distance equal to the
width of the region correlated (i.e., the overlap width plus the
extra width if any). Enter 1 to use the default, or a specific
distance in unbinned pixels. By default, 16 cross-correlation
peaks are analyzed.
-expected (-exp) OR -ExpectedShiftsFromEcd File name
Use displacements from the given input .ecd file as expected
shifts for correlations. With expected shifts, the program will
be able to correlate overlap regions that match instead of being
offset from each other, which can give more reliable correla-
tions. If an expected shift is known, it is preferable to use
it than to provide large amounts of extra width in the regions
correlated. This option and the next one are mutually exclu-
sive, but will be ignored if -readxcorr is entered.
-mdoc (-md) OR -MdocForExpectedShifts
Get expected shifts for the correlations from an .mdoc file,
.idoc file, or the autodoc stored in an HDF file. See the
-expected option for the implications of using expected shifts.
The MontSection for each montage will be used, and each overlap
region on a section will be given the same expected shift, so
this option is currently suitable only when taking montages with
the Multiple Records routine in SerialEM. The shifts will be
sought first in XEdgeExpectedShifts and YEdgeExpectedShifts
entries (added to SerialEM 4.1, 6/7/22). If those are not
found, the program will compute the shifts from the tilt angle
and tilt axis rotation angle.
-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 val-
ues, 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 (-wi) 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 (-ind) 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 (-sub) 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 a set of overlapping subareas throughout as much
of the extracted image areas as possible for a given shift.
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 displacement between the areas. The
true peak will generally give a stronger correlation coefficient
in such a case, when measured in comparable-sized subareas. The
subareas alleviate the problems of correlating larger areas when
there is substantial distortion between the two images. A local
search for the peak is done within each subarea. This value is
set to 1 by default unless VerySloppyMontage or an option that
activates weighting for expected shifts is entered, in which
case the default is 16, or EMGridMapFilter is entered, in which
case the default is 50, or 100 with VerySloppyMontage.
-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
-print (-pr) OR -PrintXYSizeAndExit
Determine output file size in X and Y, print it, and exit
-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.
IMOD 5.2.0 blendmont(1)