Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

SUMDENSITY(1)							 SUMDENSITY(1)

NAME
  sumdensity - adds densities above a threshold for pixels within contours

SYNOPSIS
  sumdensity [options] image_file model_file output_file

DESCRIPTION
  Sumdensity will sum the density within contours of selected IMOD model
  objects.  Pixels within a specified distance of the boundary contour can be
  excluded.  A threshold can be set so that only pixels above threshold are
  summed, and the threshold value is subtracted from the pixel values in the
  sum.  Data are reported by surface if there are surfaces defined in the model
  contours.

  The threshold density must be specified in one of three ways.  It can be
  entered as an absolute density value, such as one would view in the Pixel
  View window in 3dmod.  If you do not want to apply a threshold at all you
  could specify the minimum density in the file, or zero, whichever is less.
  The second way to enter the density is as a contrast setting.  Load the data
  into 3dmod without any intensity scaling (i.e., without using "-s").  Bring
  the black and white sliders together and adjust until structures of interest
  are selected by the threshold.  The slider value would be entered with the
  "-contrast" option.  Finally, one can draw contours around reference areas
  that contain the desired baseline density.  The mean of density within these
  contours will be taken as the threshold density.  All of these contours
  should be in a single object specified with "-reference".

  The output of the program consists of a summary table with the following
  columns: object number, surface number or ALL for the entire object, the
  number of pixels within the contour (after excluding the border region), the
  number of pixels above the threshold, the percent of pixels above threshold,
  and the sum and average of the densities above threshold.  If a pixel model
  is being produced then the number points selected for the model appears in a
  final column; this value can be less than the points above threshold if
  adjacent points are required.  These values are reported for each surface in
  an object, then for the sum of all surfaces.  With the "-verbose" option,
  values are reported for each contour.

  The program will detect contours that are nested inside other contours and
  exclude pixels that are inside or with a border distance of inner contours.
  There can be any number of levels of nested contours, and in the general
  case the program will exclude pixels that are inside an even-level contour
  but not inside an odd-level contour contained within it (where the outermost
  contour is considered level 1).

  Sumdensity 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 -):

 -image OR -ImageFile   File name
    Input image file with densities to be summed.  If this option is not
    entered, the first non-option argument will be used for this input file.

 -model OR -ModelFile   File name
    Input model file with contours delimiting areas to be summed.  If this
    option is not entered, the second non-option argument will be used for
    this input file.

 -output OR -OutputFile   File name
    Output file for results. If this option is not entered, the third
    non-option argument will be used for this output file.  If no output file
    is entered, results will be printed to standard output.

 -pixel OR -PixelModel   File name
    Output file for model with added scattered-point objects containing points
    on the pixels that were included in the sum.

 -adjacent OR -AdjacentRequired   Integer
    Number of adjacent points above threshold required to include a given
    point in the output model.  All points above threshold will be counted in
    the density sums, but only those that meet this requirement will be marked
    in the model.

 -diagonals OR -DiagonalsCount
    Count all 8 neighboring pixels,incuding ones on diagonals, when
    determining whether a point is adjacent to the required number above
    threshold.

 -objects OR -ObjectsToDo   List of integer ranges
    A list of objects containing boundary contours within which to compute
    sums.  The default is to do all closed contour objects.

 -border OR -BorderSize   Floating point
    Distance from contour within which to exclude pixels from consideration. 
    For example, if the contours are drawn on the centers of membranes, this
    entry can be used to exclude pixels in the membrane as well as within a
    certain distance of the membrane.  The default is to include all pixels
    within the contour.

 -inside OR -InsideBorder   Floating point
    Distance from interior contours within which to exclude pixels from
    consideration.  All pixels inside of interior contours will be excluded,
    so this entry governs the border outside those contours.  The default is
    to use the BorderSize value.

 -absolute OR -AbsoluteThreshold   Floating point
    Threshold value in absolute units of the image file density

 -contrast OR -ContrastThreshold   Integer
    Relative threshold in units of black/white contrast settings after loading
    the data into 3dmod with the default scaling.  This value should be in the
    range 0-255.

 -reference OR -ReferenceObject   Integer
    Object enclosing areas from which to measure threshold.  Multiple contours
    can be used to sample several areas for setting the threshold.

 -reverse OR -ReversePolarity
    Count and sum pixels lower than the threshold instead of higher.  The
    densities to be summed can have either positive or negative contrast; use
    this option in the latter case.

 -verbose OR -VerboseOutput
    Output counts and densities for every contour

 -param OR -ParameterFile   Parameter file
    Read parameter entries from file

 -help OR -usage
    Print help output

  -StandardInput
     Read parameter entries from standard input.