edgepatches(1) edgepatches(1) NAME edgepatches - Initial steps in stitching montage of overlapping tomo- grams SYNOPSIS edgepatches options supermontage_info_file DESCRIPTION Edgepatches is a Python program that performs the first steps in stitching together tomograms that overlap laterally, which are referred to as a supermontage. Stitching is done by running four different pro- grams in sequence: Edgepatches, Fitpatches, Stitchalign, and Tomostitch. Edgepatches allows you to set up a master file with information about the tomograms and their overlap regions, referred to as a supermontage info file. It performs 2D and 3D cross-correlations to determine the shifts between the volumes, then correlates local patches between overlapping volumes to obtain a set of local displace- ments in the overlap zones. Next, you run Fitpatches to assess the quality of the patch displacements by seeing how well local transforma- tions fit to them. Fitpatches also generates patch vector models that you can edit to improve these fits and to prevent aberrant vectors from subsequently giving bad warping transformations. The next step is to run Stitchalign to take this information and determine how the volumes can be transformed into alignment. That program first derives an overall linear transformation (including shifts, rotations, size changes, and stretches as appropriate) to apply to each volume, and it also produces a set of vectors for each volume indicating how that vol- ume needs to be warped to match up with adjacent ones where they over- lap. Finally, you run Tomostitch to perform a series of tasks for building the stitched volume: 1) Deriving warping transformations from the warping vector fields; 2) Applying these warping transformations to each volume; 3) Adjusting densities of the volumes so that they match where they overlap; 4) Stacking the volumes so that they represent a montage readable by Blendmont; 5) Running Blendmont to blend the 2D montaged images into one. Edgepatches can set up the info file when given the right information. For complex situations, you will probably want to name your volumes following one of the conventions supported by this program and let the program do this initial setup. For simple situations, you have the option of starting the info file yourself with a text editor. In any case, there are some situations that require manually inserting infor- mation about individual volumes into the info file. The info file is in the BL3DEMC autodoc format, which consists of sec- tions of defined types, each containing information as key-value pairs. In the abstract, this looks like: [section_type = name] key1 = value1 key2 = value2 The defined kinds of sections (not to be confused with the physical slices that were reconstructed) are: Section Information about a slice as a whole; the name value is the name of the physical slice; the default is "rootname_Zvalue" if the slices have a defined Z value, or just "rootname" if not. Piece Information about a volume; the name value is the name of the reconstruction file. Edge Information about an overlap zone between two volumes. The name value is a standard name based on the rootname and the options that have been entered, such as set1_x1-2y1 for an edge between piece 1,1 and piece 2,1 The standard names for pieces and edges are determined from the root- name and the entries for three options: -ext, -underscore and -noz. The -ext option simply specifies an extension for the tomograms; the default is ".rec". With the default extension, the names are: Options Piece name Edge name rootname_x1y1z1.rec rootname_x1-2y1z1 -noz rootname_x1y1.rec rootname_x1-2y1 -underscore rootname_x1_y1_z1.rec rootname_x1-2_y1_z1 -noz -underscore rootname_x1_y1.rec rootname_x1-2_y1 where in each case the piece names are for piece 1,1 and the edge names are for the edge between piece 1,1 and piece 2,1. The expected names for specific patch region models would be the piece name with "_region.mod" instead of ".rec". To have the program set up the info file, decide on one of these naming conventions and have the volumes named appropriately. Your choice will depend on whether you have multiple sections, and whether you want the section number to be represented by a Z at the end or as part of the rootname. Then run Edgepatches with entries for -root, -xyadd (the number of frames in X and Y), -overlap (the expected overlap between frames in X and Y), and either -zadd (if you are doing multiple sec- tions with the above naming convention) or -noz (to indicate there are no Z values in the names). The other option to specify at this time is -model (a default patch region model that is used if no specific model is found for a piece.) When you run the program will all of these options, it will search for the piece volumes as well as patch region models under the names implied by your options. Thus, if individual volumes need region models to constrain the area used for patch corre- lations, you should make them before running the program. To set up an info file yourself, you need to make a section for each piece with one or two entries: [Piece = left.rec] Frame = 1 1 0 Model = left_region.mod Here the frame entry specifies the frame number in X, Y, and Z; you can leave out the Z value if you want. If you need to use a region model, specify it as shown. With a section already in place for each piece, you can then run the program with -root, -overlap, your choice of -noz and -underscore to govern the naming of edge-related files, and a -model entry for a default region model. Regardless of whether you add the supermontage using the program or specify pieces by hand, the first run of the program will add sections for all the edges and other data to the info file. You can do the full analysis on this first run, or you can defer the analysis if you need to adjust entries in the info file. There are two items that you may need to edit in by hand after creating an info file. One would be a region model, specified in the section for a piece with Model = piecename_region.mod where the name can be whatever you want if you are inserting this your- self. The second item would be lower and upper limits for the Z range from which patches can be taken for correlation. These limits can be entered in the section for a piece, in which case they will be used when that piece is the lower one in a pair, or in the section for an edge, in which case the limits will apply only for that overlap zone. The entry is Zlimits = zlo zhi where zlo and zhi are the limits, numbered from 1. For a particular edge, the Z limits are taken first from an entry for that edge if that exists; then from an entry for the lower piece if that exists; then from the Z border entered with the -borders option if neither exists. To analyze overlap zones, enter either the -all option to analyze all edges, or one or more of the options for specifying a range of X, Y, or Z to analyze. By default, the program will not redo the global cross- correlations to find the shifts between pieces, but will redo the local patch correlations. Use the -redo option to force it to redo the global correlations, or the -skip option to make it skip any patch cor- relations that were already done. The patch correlations are run similarly to when aligning dual-axis tomograms. However, the default parameters are based on binned data (~2 nm pixel) and should not be relied on in general; patch sizes may need to be increased substantially for unbinned data. Another differ- ence is that region models for both the upper and the lower piece are applied to determine the limits for patches in an overlap zone. Another important difference is in the consequences of having bad vec- tors. With dual-axis tomograms, the vectors are fed directly into Findwarp, which has outlier elimination that usually eliminates the most aberrant vectors. The vectors produced here are going to be pro- cessed by Stitchalign, which does not do its own outlier elimina- tion, so bad displacements will be carried through into the final warped volumes. It is thus crucial to run Fitpatches after running this program, and after editing any patches. Fitpatches will show you the results of finding local transformations in Findwarp and will store information on residuals and on which vectors are outliers into a new patch file. This information will be used by Stitchalign to eliminate some bad vectors. In general, you should use the informa- tion from Fitpatches in order to adjust the parameters used in Edgepatches to produce the best vectors possible, and then edit out bad vectors manually if necessary. Options Edgepatches uses the PIP package for input (see the manual page for pip). Options can be specified either as command line arguments (with the -) or one per line in a command file (without the -): -info OR -InfoFile File name Name of a supermontage info file in which all data about the files will be stored. If the file exists, it will be read in when the program starts, and renamed to filename~ before writing a new version when the program exits. If this option is not entered, the first non-option argument will be taken as the name of the info file. -noz OR -NoZValues Search for and create names without Z values and assume the Z value is zero. This option cannot be used when adding a super- montage to an existing one, or when specifying a z range with -zadd. -root OR -RootName Text string Rootname for existing files and ones to be created. Existing files need not be named according to the conventions if they are already listed in the info file. -overlap OR -OverlapInXandY Two integers Nominal overlap between adjacent volumes in X and Y. This only needs to be a rough approximation. This entry is required when adding a supermontage or the first time a manually prepared info file is read. -underscore OR -UnderscoreXYZ Use underscores between x, y, and z in composing names for files being searched for and created. -ext OR -ExtensionOnVolumes Text string Extension on filenames when searching for volumes, including the period. There may be characters before the true extension, such as if all files are named "binned.rec". The default is .rec. -xyadd OR -AddMontageXandY Two integers Add a supermontage with the given number of frames in X and Y. The program will search for pieces by rootname and frame number in X and Y, with numbers starting from 1. -xadd OR -AddMontageXRange Two integers Starting and ending X values to search for when adding a super- montage. Use this option and -yadd if the starting frame number is not 1 in X or in Y. If one of the two options -xadd and -yadd is entered, then the other must be entered as well, and -xyadd must not be entered. -yadd OR -AddMontageYRange Two integers Starting and ending Y values to search for when adding a super- montage. -zadd OR -AddMontageZRange Two integers Starting and ending Z values to search for when adding a super- montage. If this option is entered, then either -xyadd, or -xadd and -yadd, must be entered. -model OR -DefaultRegionModel File name Patch region model to use for an overlap zone if one is not found when initially setting up the Edge entries in the info file. This option will have an effect only when adding a super- montage or processing a manually prepared info file for the first time. -all OR -RunAll Analyze overlap zones for all frames. No analysis will be done unless this option or one or more of -xrun, -yrun, or -zrun are entered. -xrun OR -XRunStartEnd Two integers Starting and ending frame number in X for overlap zones to ana- lyze -yrun OR -YRunStartEnd Two integers Starting and ending frame number in Y for overlap zones to ana- lyze -zrun OR -ZRunStartEnd Two integers Starting and ending Z value for overlap zones to analyze -skip OR -SkipDone Skip any overlap zones that were already analyzed. The default is to use any shifts that were found previously but to rerun patch correlations. -redo OR -RedoShifts Recompute the shifts between frames for any that were already done. -long OR -LongFraction Floating point Fraction of long dimension of the overlap zone to use for find- ing the X/Y shift between the projections of the two pieces. The default is 0.5. When pieces are significantly skewed from each other, rather than arranged nearly horizontally or verti- cally, this fraction should be made higher, such as 1.0. -size OR -PatchSizeXYZ Three integers Size in X, Y, and Z of patches to correlate. The default is 100 x 100 x 50. -intervals OR -IntervalsShortLongZ Three integers Interval between patches in the short, long, and Z dimensions of overlap zones. The program will use these intervals to deter- mine how many patches to specify when running Corrsearch3d. The defaults are 80,120,50. -force OR -ForceNumberInZ Integer Set the number of patches in Z to the given value, regardless of the interval between them. -borders OR -BordersInXYandZ Two integers Borders in X/Y and in Z for region in which to do patch correla- tions. These borders are distances from the edge of each image file, and thus define borders in the overlap zone. The border is X and Y is redundant to limiting the region with a patch region model. The border in Z is a default value that will be overriden by a Zlimits entry for an individual piece. The default is 50,10. -kernel OR -KernelSigma Floating point Sigma for real-space smoothing with 3D Gaussian kernel (in pix- els). Patches will be smoothed before correlating with 3x3x3 kernel (for sigma < 1.5) or a 5x5x5 kernel (sigma not < 1.5) whose coefficients are proportional to a Gaussian with the given sigma centered on the central pixel. -test OR -TestMode Integer Sum of 1 for verbose output and 2 to leave temporary files -StandardInput Read parameter entries from standard input FILES When the info file is modified, the existing copy is renamed to a backup with the ~ extension. This is done only once per run of the program, although the program will save the info file after each over- lap zone is processed. AUTHOR David Mastronarde SEE ALSO corrsearch3d, xyzproj, tiltxcorr, fitpatches, stitchalign, tomostitch BUGS Comments in the info file will not be preserved. Email bug reports to mast at colorado dot edu. BL3DEMC 4.3.7 edgepatches(1)