Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

CCDERASER(1)							  CCDERASER(1)

NAME
  ccderaser - erase X-rays, defects and fiducial markers from images

SYNOPSIS
  ccderaser [options] [input_file] [output_file]

DESCRIPTION

  This program replaces deviant pixels with interpolated values from
  surrounding pixels.  It is designed to correct defects in electron
  microscope images from CCD cameras.  It can use two algorithms to
  automatically remove peaks in intensity caused by X-rays.  It can also
  take an IMOD model file with specifications of regions to be replaced; in
  this mode it can be used to erase gold fiducial markers.  With a model,
  the program can replace a group of adjacent pixels with interpolated
  values, or all of the pixels along a line.  It can do this on only a
  specific image, or on all of the sections in the file. The program can
  operate in trial mode, without making an output file, and it can output a
  model file with points at the pixels to be replaced.

  AUTOMATIC X-RAY REMOVAL: The automatic removal of X-rays works by dividing
  the area of each image into patches for scanning.  The mean and standard
  deviation (SD) of the pixels in a patch are computed.  The patch is then
  scanned for pixels that deviate from the mean by more than a criterion
  number of SDs (the scan criterion, a relatively low number to keep from
  missing peaks).  When such a pixel is found, the program searches
  neighboring pixels to find a peak in intensity.  It then computes the mean
  and SD of pixels in an annulus around the peak and makes sure that the
  peak deviates from this local mean by more than a criterion number of SDs
  (the peak criterion).  Neighboring pixels inside the inner radius of the
  annulus are added to the list of pixels to be replaced if they deviate by
  a lower criterion (the grow criterion).  The patch of pixels is then
  replaced by fitting a polynomial to adjacent pixels and interpolating from
  the polynomial.

  After the peaks are found in a patch, the program next finds the
  difference between each pixel and the mean of the eight adjacent pixels.
  The mean and SD of this difference is computed, then pixels are sought
  that deviate from the mean by yet another criterion, the difference
  criterion.  When such a pixel is found, neighboring pixels are examined
  and added to the patch of pixels to replace if their difference exceeds
  the grow criterion.  If the number of pixels in the patch does not exceed
  a specified maximum, replacement proceeds as above; otherwise the patch is
  ignored.

  Two methods are used because the first method is probably more reliable
  for dealing with strong peaks that extend over several pixels, while the
  second method is definitely better for finding small X-rays.

  Tuning the removal of X-rays would primarily involve adjusting three of
  the criteria.  The peak and difference criteria would be adjusted down or
  up to increase or decrease the number of deviant pixels that are found.
  The grow criterion would be adjusted down or up depending on whether too
  few or too many pixels are included in a patch that is replaced.

  MANUAL REMOVAL OF DEFECTS AND MARKERS: For manual removal of defects,
  prepare an IMOD model file to specify the points to be replaced.  There
  can be four kinds of objects:

  1)  Pixel objects, in which there is a point inside of every pixel to be
  replaced, and each contour corresponds to a separate patch of points.

  2) Boundary objects, in which each contour encloses a separate patch of
  pixels to be replaced.

  3) Line objects, in which each contour defines a horizontal or vertical
  line of points to be replaced.

  4) Circle objects, used to replace pixels in a circle around each point.

  Pixel, boundary, and line objects can be applied either on the section
  where they are drawn, or on all sections.  For example, one might have two
  different pixel objects, one for patches to be replaced on a single
  section and one for patches to be replaced on all sections.  Note that if
  you are working with a montage, "all sections" means "all pieces".  If you
  are modeling on images displayed as a montage with no overlap between the
  pieces, you only need to draw a patch on one of the pieces to have it erased
  on all the pieces at each view.

  TO set up a pixel object, make the object type be scattered points, and
  turn on drawing of circles, but leave the sphere radius at zero.  To
  specify a patch of points, start a new contour and place a point inside of
  EVERY pixel in the patch.  Each separate patch should be in a
  separate contour.  If the correction is to be made on only a single
  section, all of the points must lie on that section; but the points for a
  patch to be corrected on all sections can be on more than one section,
  because sometimes they are more discernable on particular sections.
  
  A boundary object should be the default, closed contour type.  Draw a
  contour around each patch of pixels to be erased.  A pixel will be
  included in the erasure if its center is inside or on the boundary line.
  Contours can be arbitrarily large, and there is tapering of intensities
  inside contours that are bigger than 1000 pixels.

  A line object should be closed or open contour type.  To specify a line of
  points, make a contour with two points, at the start and end of the line
  to be replaced.  Lines must be horizontal or vertical.  Each pixel will be
  replaced by the average of the two pixels on either side of the line.  Put
  each line in a different contour.  Ajdacent lines will be detected and
  erased together.

  To set up a circle object, make the object type be scattered points, set
  the sphere radius to an appropriate value, and check the option to display
  spheres only on their center section.  If necessary, you can give some of
  the points sizes that are different from the default by opening a dialog
  with Edit-Point-Size.  A pixel will be replaced if its center lies inside
  or on the circle.  For small radii, the fact that the default sphere
  radius is constrained to an integer may be a problem; if so, use the
  -better option to enter a floating point default radius for Ccderaser to
  use.  For using circle objects to remove gold markers, -merge should also
  be used so that adjacent markers are removed together, and -exclude will
  help keep dark pixels just outside the circle from making the filled in
  region too dark.

  Ccderaser uses the PIP package for input (see the manual page for pip)
  and can take input interactively only for specifying manual replacement
  with a model file, to maintain compatibility with old command files.  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 -):

 -input OR -InputFile   File name
    Input image file.  This may also be entered after all arguments on the
    command line.

 -output OR -OutputFile   File name
    Output image file.  This may also be entered after an input file name on
    the command line.  If no output file is specified and the program is not
    run in trial mode, pixels will be replaced in the input file.  USE
    REPLACEMENT OPTION WITH CAUTION.

 -piece OR -PieceListFile   File name
    File with piece coordinates for a montaged image file.  With this entry,
    the program will assume that an input model was drawn on a display of the
    montage with overlaps adjusted to be either 0,0 or the amount indicated by
    the -overlaps option.  The output model file with points found will also
    be formatted to fit on such a display.

 -overlaps OR -OverlapsForModel   Two integers
    Overlaps in X and Y at which a montaged image is being viewed both when
    producing an input model and viewing the output model of pixels being
    replaced.  The same values should be used as are provided to the -o option
    of 3dmod.  The default is 0,0, which represents no overlap between images.

 -find OR -FindPeaks
    Find and erase peaks a criterion # of SDs above or below background.  This
    option must be included for automatic removal of X-rays.

 -peak OR -PeakCriterion   Floating point
    Criterion # of SDs above local mean for erasing peak based on intensity
    (the default is 10 SDs).

 -diff OR -DiffCriterion   Floating point
    Criterion # of SDs above mean pixel-to-pixel difference for erasing a peak
    based on differences (the default is 10 SDs)

 -grow OR -GrowCriterion   Floating point
    Criterion # of SDs above mean for adding points to peak (the default is 4
    SDs).

 -scan OR -ScanCriterion   Floating point
    Criterion # of SDs of mean of scan area for picking peaks in initial scan
    (the default is 3 SDs).

 -radius OR -MaximumRadius   Floating point
    Maximum radius of peak area to erase (the default is 2.1 pixels).

 -maxdiff OR -MaxPixelsInDiffPatch   Integer
    Maximum number of pixels in a patch that exceeds the difference criterion.
     If the number of pixels that satisfy the criteria exceed this limit, none
    of the pixels in the patch will be replaced.  The default is 2.

 -outer OR -OuterRadius   Floating point
    Outer radius of annulus around a peak in which to calculate local mean and
    SD (the default is 4.1 pixels).  This option and -width are mutually
    exclusive.

 -width OR -AnnulusWidth   Floating point
    Difference between outer and inner radius of the annulus around a peak in
    which to calculate local mean and SD (the default is 2.0 pixels).  This
    option and -radius are mutually exclusive.

 -xyscan OR -XYScanSize   Integer
    Size of regions to compute mean and SD in for initial scans (the default
    is 100 pixels).

 -edge OR -EdgeExclusionWidth   Integer
    Width of area to exclude on all edges of image in pixels (default 0).

 -points OR -PointModel   File name
    Output model file with points replaced in peak search.  Each patch of
    points will be in a separate contour.  Patches are sorted into separate
    objects based on how much the peak exceeds a criterion.

 -model OR -ModelFile   File name
    Input model file specifying points or lines to be erased.

 -lines OR -LineObjects   List of integer ranges
    List of objects that define lines to be replaced.  Ranges can be entered,
    and / to specify all objects.

 -boundary OR -BoundaryObjects   List of integer ranges
    List of objects that contain boundary contours around pixels to be
    replaced.  Ranges can be entered, and / to specify all objects.  Boundary
    contours can be arbitrarily large.  When a contour encloses more than 1000
    pixels, a different procedure is use to erase the points, and intensities
    are tapered down over 8 pixels on the inside of the patch from the value
    of the nearest pixel just outside the patch to the mean of the surrounding
    pixels.

 -allsec OR -AllSectionObjects   List of integer ranges
    List of objects with points to be replaced on all sections.  Ranges can be
    entered, and / to specify all objects.

 -circle OR -CircleObjects   List of integer ranges
    List of objects that contain scattered points for replacing pixels within
    a circle around each point.  The sphere radius, which can be an individual
    value for each point, is used to indicate the size of circle to replace. 
    Ranges can be entered, and / to specify all objects.

 -better OR -BetterRadius   Multiple floats
    For circle objects, this entry specifies a radius to use for points
    without an individual point size instead of the object's default sphere
    radius.  This entry is floating point and can be used to overcome the
    limitations of having an integer default sphere radius.  If there are
    multiple circle objects, enter one value to apply to all objects or a
    value for each object.

 -expand OR -ExpandCircleIterations   Integer
    Number of iterations of a procedure that expands the area erased around
    the points of a circle object.  This procedure analyzes the intensity of
    pixels adjacent to the patch being erased and adds pixels in the
    appropriate tail of the intensity distribution to the patch.  Iterating
    simply repeats the procedure.  If edges of gold particles are left because
    points are not very well centered, try this option instead of just
    increasing the radius, as it will tend to erase just the remaining points
    on the edge instead of a whole ring of points.

 -merge OR -MergePatches
    Merge patches in the model if they touch each other, as long as the
    resulting patch is still within the maximum radius.  Patches from objects
    with points to be replaced on all sections are ignored.  This option
    should be used if an output model from automatic peak finding is modified
    and used as an input model.

 -border OR -BorderSize   Integer
    Size of border around points in patch, which contains the points which
    will be fit to (the default is 2 pixels)

 -order OR -PolynomialOrder   Integer
    Order of polynomial to fit to border points.  The default is 2, which
    includes terms in x, y, x**2, y**2 and x*y.  The order can be between 0
    and 3, where 0 will simply replace the pixels with the mean of the border
    points instead of fitting to them.

 -exclude OR -ExcludeAdjacent
    Exclude points adjacent to patch points from the fit; in other words,
    compute the polynomial fit to points that do not touch the ones being
    replaced.

 -trial OR -TrialMode
    Analyze for replacement points without writing output image file.

 -verbose OR -verbose
    Print details on patches being replaced

 -PID OR -ProcessID
    Output process ID

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


  If the program is started with no command line arguments, it reverts to
  interactive  input with the following entries:

  Input image file

  Output image file, or <Return> to place modified sections back into
  the input file.  USE REPLACEMENT OPTION WITH CAUTION

  Model file

  A list of objects which specify points or lines to be replaced on
  all sections, or / if all objects do so, or Return if none do.
  Ranges may be entered.

  A list of objects which specify lines to be replaced, or / if
  all objects do so, or Return if none do.  Ranges may be entered.

  Size of the border around the points in a patch, which contains the
  points which will be fit to (/ for default of 2 pixels)
  
  Order of polynomial (/ for default of 2, which includes terms in
  x, y, x**2, y**2 and x*y)

  0 to exclude or 1 to include points adjacent to the points being replaced
  in the polynomial fit (/ for default of 1)
  
HISTORY
  Written by David Mastronarde  11/10/98
  Automatic X-ray removal and pioneer use of PIP input, 6/9/03