sumdensity(1)                                                    sumdensity(1)



NAME
       sumdensity - adds densities above a threshold for pixels within con-
       tours

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 con-
       trast 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 follow-
       ing 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, average, and standard deviation
       of the densities above threshold.  If a pixel model is being produced
       then the number of points selected for the model appears in a final
       column; this value can be less than the points above threshold if adja-
       cent 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).

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


       -image (-im) 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 (-m) 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 (-ou) 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 (-pi) OR -PixelModel    File name
              Output file for model with added scattered-point objects con-
              taining points on the pixels that were included in the sum.

       -adjacent (-ad) 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 (-d) 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 (-ob) 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 (-b) OR -BorderSize    Floating point
              Distance from contour within which to exclude pixels from con-
              sideration.  For example, if the contours are drawn on the cen-
              ters of membranes, this entry can be used to exclude pixels in
              the membrane as well as within a certain distance of the mem-
              brane.  The default is to include all pixels within the contour.

       -inside (-in) 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 con-
              tours.  The default is to use the BorderSize value.

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

       -contrast (-c) 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 (-ref) OR -ReferenceObject    Integer
              Object enclosing areas from which to measure threshold.  Multi-
              ple contours can be used to sample several areas for setting the
              threshold.

       -reverse (-rev) 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 (-v) OR -VerboseOutput
              Output counts and densities for every contour

       -param (-pa) OR -ParameterFile      Parameter file
              Read parameter entries from file

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

       -StandardInput
              Read parameter entries from standard input.

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                       sumdensity(1)