Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

EDMONT(1)							   EDMONT(1)

NAME
  edmont - to edit, combine, split apart, bin, and restack montages

SYNOPSIS
  edmont [options] input_file(s) output_file

DESCRIPTION
  Edmont is a general montage editor than can be used to extract a subset of
  a montage, combine multiple montaged files or split a montage into multiple
  files, rescale images to a common range or mean of density, and  bin the
  montage pieces.  
         
  If there are piece coordinates in the extended header of the image file,
  the program will transfer those coordinates to the output file.  These
  coordinates can be used instead of ones from a piece list file.  If one
  wishes to have sections numbered sequentially from zero, or the X and Y
  coordinates of an extracted subset of pieces shifted to start at zero, the
  coordinates in the header of the output file will be modified
  appropriately.

  The general requirement when combining multiple montages is that they all
  have the same image size and overlap between adjacent pieces, and that
  they all fit on the same regular grid of positions.  They may have
  different numbers of pieces in each direction, and pieces at different
  locations; indeed, it is possible to assemble a montage from different files
  containing laterally adjacent pieces.
  
  If floating is not selected, data are rescaled uniformly, if necessary, to
  fit a new output data mode.  Specifically, data will be rescaled when going
  between byte and signed or unsigned integer modes, but only by the
  difference in data range between input and output modes.  Use the -1
  floating option to have the data scaled to fill the data range instead.  If
  the input file has real data (mode 2) that is not confined to the range of
  the output mode, then you must specify one of the three kinds of floating
  to avoid truncating the data.

  Edmont uses the PIP package for input exclusively (see the manual page
  for pip).  The following options can be specified either as command line
  arguments (with the -) or one per line in a command file or parameter file
  (without the -):

 -imin OR -ImageInputFile   File name
    Montaged image input file.  If there is more than one non-option argument,
    all except the last one are also taken as image input files, following any
    files entered with this option.
    (Successive entries accumulate)

 -plin OR -PieceListInput   File name
    File with list of piece coordinates for image input file.  This file may
    be omitted if the image file has piece coordinates in its header, but if
    this entry is made for any image file, there must be an entry for each
    image file.  However, a filename of "none" can be entered if some image
    files have coordinates in the header and some do not.
    (Successive entries accumulate)

 -imout OR -ImageOutputFile   File name
    Output file for montaged images.  If there are any non-option arguments,
    the last one is also taken as an output image file, following any
    filenames entered with this option.
    (Successive entries accumulate)

 -plout OR -PieceListOutput   File name
    File for list of coordinates of pieces in output image file.  This entry
    may be omitted if the coordinates are being placed in the image header,
    but is required if there are input piece list files.
    (Successive entries accumulate)

 -secs OR -SectionsToRead   List of integer ranges
    List of sections to read from an input file, numbered from 0.  Ranges may
    be entered (e.g., 1-3,5,8), and / may be used to specify all sections in
    the file.  If multiple lists are entered, each one will be applied to the
    respective input file.  If no list is entered for a file, all sections
    will be read.  Note that montages can have missing sections, and a list
    that includes such missing sections will generate an error.
    (Successive entries accumulate)

 -numout OR -NumberToOutput   Multiple integers
    Number of sections to write to each output file, when there are multiple
    output files.  These numbers may be listed in sequence in one entry, or in
    several entries.  If there is one output file per section being written,
    then one section will be written to each file and this entry is not
    needed.
    (Successive entries accumulate)

 -mode OR -ModeToOutput   Integer
    The storage mode of the output file; 0 for byte, 1 for 16-bit signed
    integer, 6 for 16-bit unsigned integer, or 2 for 32-bit floating point. 
    The default is the mode of the first input file.

 -xminmax OR -XMinAndMax   Two integers
    Minimum and maximum X coordinates to include in output.  Any piece
    containing pixels within this range will be included in the output.  Thus,
    you need to pick coordinates that are far enough away from the edges of a
    piece to exclude overlapping pieces that you do not want.

 -Yminmax OR -YMinAndMax   Two integers
    Minimum and maximum Y coordinates to include in output.  Any piece
    containing pixels within this range will be included in the output.

 -xframes OR -XFrameMinAndMax   Two integers
    Starting and ending frames in X to include in the output.  Frames are
    numbered from one for the leftmost frame in any of the input files, up to
    the rightmost frame in any of the input files.

 -yframes OR -YFrameMinAndMax   Two integers
    Starting and ending frames in Y to include in the output.  Frames are
    numbered from 1 for the bottommost frame of any input file, up to the
    topmost frame in any input file.

 -float OR -FloatDensities   Integer
    Adjust densities of sections individually or together.  Enter 1 for each
    section to fill the data range, 2 to scale sections to common mean and
    standard deviation, or -1 to scale all sections by the same factors to
    fill the data range.  The latter scaling occurs only when changing from
    one fixed point mode (0, 1, or 6) to another.  It is most useful when
    converting from an integer to a byte mode, because otherwise the data will
    fill only the fraction of the byte range that they occupy in the integer
    range.

 -bin OR -BinByFactor   Integer
    Use binning to reduce images in size by the given factor.  Because
    coordinates are kept as integers, binning may not produce exactly the same
    spacing between pieces as in the original data.  This is not a problem if
    the data are still to be blended, since Blendmont can adjust for any
    shifts induced by the binning.  However, if data are already blended, the
    pieces will not be precisely aligned unless both the original image size
    and overlap are evenly divisible by the the binning.  Use Reducemont
    for binning if this is not the case.

 -exclude OR -ExclusionModel   File name
    Model file with points on pieces to exclude from output.  This option
    allows you to remove bad pieces from a montage.  To make a model, set the
    object type to scattered points and turn on a symbol display so that you
    can see the points.  Place points near the middle of the unwanted pieces. 
    A point must be in the region outside the overlap zones, if overlap is
    less that one quarter of the piece size, or within the central half of the
    piece if overlap is higher than that.  If overlap is high, you will have
    to anticipate where the entire piece is located in the 3dmod display,
    since pieces are generally overlaid on two sides by overlapping pieces
    that occur later in the image file.  All points in the model will be used
    as exclusion points.

 -renumber OR -RenumberZFromZero
    Renumber Z values to be sequential and start at zero.  This option can be
    used to close up gaps from missing sections or to shift the Z values of a
    subset stack down to start at zero.  It is required if you are combining
    two montages that have pieces at the same coordinates.

 -shift OR -ShiftXYToZero
    Adjust X and Y piece coordinates to start at zero.  If the data are going
    into multiple output files, the coordinates of the entire collection of
    output sections will start at zero, but the coordinates in any one file
    may not start at zero.  To achieve other shifts of piece coordinates, use
    Edpiecepoint.

 -param OR -ParameterFile   Parameter file
    Read parameter entries as keyword-value pairs from a parameter file.

 -help OR -usage
    Print help output

  -StandardInput
     Read parameter entries from standard input.

HISTORY
  Written by David Mastronarde, 5/9/89
  1999: added ability to knock out pieces.
  1/3/00: made it handle extra header data, made scaling logic more
  like NEWSTACK and made sure it could handle negative integers. 
  10/24/00: made it actually use coordinates in header and renumber
  sections sequentially.
  7/2/10: Converted to PIP, used memory allocation, added many error checks,

  default section lists, binning, shifting, subsetting by frame number, and
  more flexibility in assembling montages.

SEE ALSO
  blendmont, newstack, reducemont