setupstitch(1)                                                  setupstitch(1)



NAME
       setupstitch - Initial set up for stitching montage of overlapping tomo-
       grams

SYNOPSIS
       setupstitch  options  supermontage_info_file

DESCRIPTION
       Setupstitch is a Python program that performs the first step in stitch-
       ing together tomograms that overlap laterally, which are referred to as
       a supermontage.  Stitching is done by running five different programs
       in sequence: Setupstitch, Edgepatches, Fitpatches,
       Stitchalign, and Tomostitch.  Setupstitch allows you to set up a
       master file with information about the tomograms and their overlap
       regions, referred to as a supermontage info file.  Edgepatches per-
       forms 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 displacements in the overlap zones.  Next, you
       run Fitpatches to assess the quality of the patch displacements by
       seeing how well local transformations 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 appropri-
       ate) to apply to each volume, and it also produces a set of vectors for
       each volume indicating how that volume needs to be warped to match up
       with adjacent ones where they overlap.  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.

       Setupstitch 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 IMOD autodoc format, which consists of sections
       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 autodoc 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 Setupstitch 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 with 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, this program will add sections for all the
       edges and other data to 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.


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

       -info (-i) 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 (-n) 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 (-r) 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 (-o) 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.  To measure overlap, for example in X, click on a
              corresponding point in two adjacent volumes.  The overlap in X
              is XR + NXL - XL where
                 XR = X position in volume on the right
                 NXL = Size in X of volume on the left
                 XL = X position in volume on the left

       -underscore (-un) OR -UnderscoreXYZ
              Use underscores between x, y, and z in composing names for files
              being searched for and created.

       -ext (-e) 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 (-xy) 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 (-xa) 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 (-y) OR -AddMontageYRange     Two integers
              Starting and ending Y values to search for when adding a super-
              montage.

       -zadd (-z) 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 (-m) 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.

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

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

AUTHOR
       David Mastronarde

SEE ALSO
       corrsearch3d, xyzproj, tiltxcorr, edgepatches, fit-
       patches(1), stitchalign, tomostitch

BUGS
       Comments in the info file will not be preserved.

       Email bug reports to mast at colorado dot edu.



IMOD                                 4.9.5                      setupstitch(1)