ccderaser

ccderaser(1) General Commands Manual 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 sur-
 rounding pixels. It is designed to correct defects in electron micro-
 scope images from CCD cameras. It can use two algorithms to automati-
 cally 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 val-
 ues, or all of the pixels along a line. It can do this on only a spe-
 cific 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 inter-
 polating from the polynomial. If the peak does not deviate suffi-
 ciently from this local mean, but is stronger than the mean of the scan
 area by the scan criterion plus 1, then the mean and SD is again com-
 puted in a larger annulus. If the peak deviates from this mean by a
 number of SDs bigger than another criterion for extra-large peaks, a
 patch of pixels is found, but it is replaced only if enough pixels dif-
 fer from adjacent ones by large enough amounts (see the -big option
 below). The reason for these two stages is that the inner radius for
 the first stage must be set safely smaller than the radius of gold
 beads to avoid erasing part of the beads, whereas the second stage can
 work with larger areas because it has more stringent criteria that
 reject gold beads.
 After the peaks are found in a scanning 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 dif-
 ference 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.
 After all the patches have been scanned for a section, the program then
 searches for single pixels with large interpixel differences at the
 edges of the image, over the width set by the -border option. A dif-
 ference between a pixel and the mean of whatever adjacent pixels exist
 is computed and its deviation from the overall mean interpixel differ-
 ence is divided by the maximum SD of interpixel differences over all of
 the scans. When this value exceeds the difference criterion and the
 interpixel difference is greater than that of its neighbors, the pixel
 is replaced with the mean. This procedure is iterated up to 4 times to
 catch adjacent extreme pixels.
 Tuning the removal of X-rays would primarily involve adjusting two 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 could also be adjusted down or up depending
 on whether too few or too many pixels are included in a patch that is
 replaced, but this step is not usually done in practice. If there are
 strong, large artifacts that are not being removed, the big difference
 criterion for extra-large peaks should be lowered first, then if neces-
 sary, the maximum radius and criterion strength for extra-large peaks
 can be adjusted.
 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 sepa-
 rate contour. If the correction is to be made on only a single sec-
 tion, 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 prob-
 lem; 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.
OPTIONS
 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 com-
 mand files. The following options can be specified either as command
 line arguments (with the -) or one per line in a command file or param-
 eter file (without the -). Options can be abbreviated to unique let-
 ters; the currently valid abbreviations for short names are shown in
 parentheses.
 -input (-in) OR -InputFile File name
 Input image file. This may also be entered after all arguments
 on the command line.
 -output (-outp) 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.
 -halffloat (-ha) OR -HalfFloatModeOutput Integer
 Enter 2 to set the mode for output files to half-floats (16-bit
 floats) unconditionally, or 1 to do so only when the input file
 is floating point.
 -piece (-pi) 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 (-ov) 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 (-f) OR -FindPeaks
 Find and erase peaks a criterion # of SDs above or below back-
 ground. This option must be included for automatic removal of
 X-rays.
 -peak (-pe) OR -PeakCriterion Floating point
 Criterion # of SDs above local mean for erasing peak based on
 intensity (the default is 10 SDs).
 -diff (-d) 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 (-gr) OR -GrowCriterion Floating point
 Criterion # of SDs above mean for adding points to peak (the
 default is 4 SDs).
 -scan (-sc) OR -ScanCriterion Floating point
 Criterion # of SDs of mean of scan area for picking peaks in
 initial scan (the default is 3 SDs).
 -radius (-r) OR -MaximumRadius Floating point
 Maximum radius of peak area to erase (the default is 2.1 pix-
 els).
 -giant (-gi) OR -GiantCriterion Floating point
 Criterion # of SDs above local mean for erasing extra-large peak
 based on intensity (the default is 12 SDs). Enter 0 to disable
 this second stage of peak removal.
 -large (-la) OR -ExtraLargeRadius Floating point
 Maximum radius of extra-large peak area to erase (the default is
 8 pixels).
 -big (-bi) OR -BigDiffCriterion Floating point
 An extra-large peak will be erased only if the value for the
 maximum difference between adjacent pixels, averaged over the
 most extreme one-fourth of the pixels in the patch, exceeds this
 criterion, evaluated as the number of SDs above the mean abso-
 lute difference between adjacent pixels in the scan area. The
 default is 19. This high a value is needed to prevent gold era-
 sure on low-noise data sets with small gold particles, and a
 lower value may be needed to make extra-large peak removal use-
 ful.
 -maxdiff (-ma) 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 (-oute) 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 (-w) 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 (-x) OR -XYScanSize Integer
 Size of regions to compute mean and SD in for initial scans (the
 default is 100 pixels).
 -edge (-ed) OR -EdgeExclusionWidth Integer
 Width of area to exclude on all edges of image in pixels
 (default 0).
 -iterations (-it) OR -SearchIterations Integer
 Number of times to iterate search for peaks. For a given sec-
 tion, the iterations will be terminated after an iteration with
 no changes. Moreover, the program will keep track of which scan
 regions have changes on each iteration and stop redoing regions
 that have had no changes. The default is 3.
 -points (-po) 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 (-mo) OR -ModelFile File name
 Input model file specifying points or lines to be erased.
 -lines (-li) 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 (-bou) 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 pix-
 els.
 -allsec (-a) 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 (-c) OR -CircleObjects List of integer ranges
 List of objects that contain scattered points for replacing pix-
 els 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 (-be) 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 (-exp) 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 distribu-
 tion 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 (-me) 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.
 -skip (-sk) OR -SkipTurnedOffPoints
 Skip points in the model with contour values below threshold if
 they are not visible in 3dmod, namely if "Turn off below thresh-
 old" is set in the Bead Fixer, or "Turn off Low" is set in the
 Values panel of the Model View Object Edit dialog.
 -border (-bor) 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) 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 -1 and 3, where 0 will simply replace the pixels with
 the mean of the border points instead of fitting to them, and -1
 will fill the area with noise matching the standard deviation in
 surrounding pixels.
 -exclude (-exc) 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 (-t) OR -TrialMode
 Analyze for replacement points without writing output image
 file.
 -verbose (-v) OR -Verbose
 Print details on patches being replaced
 -PID (-PI) OR -ProcessID
 Output process ID
 -param (-pa) OR -ParameterFile Parameter file
 Read parameter entries as keyword-value pairs from a parameter
 file.
 -help (-he) OR -usage
 Print help output
 -StandardInput
 Read parameter entries from standard input.
INTERACTIVE 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
BUGS
 Email bug reports to mast at colorado dot edu.
IMOD 5.2.0 ccderaser(1)