Synopsis
Performs various nonlinear image filtering techniques.
Syntax
dmimgfilt infile outfile function mask [numiter] [lookupTab] [randseed] [verbose] [clobber]
Description
`dmimgfilt' performs one of several different maskbased image filtering techniques on the input image. These different techniques all make use of an input mask and are helpful in reducing noise in the input image. They may also be used to estimate background, or to help define upper and lower limits on the data.
dmimgfilt respects the NULL or NaN values in the input image; the values are skipped and the mask is effectively reduced. Similarly, any image subspace (region filter) is respected. Edges are clipped so that the mask is again reduced in size.
Note: These filters are NOT energypreserving. Users should not expect to conserve flux when applying these filters to their data.
Examples
Example 1
% dmimgfilt in.img out.img mean mask="box(0,0,3,3)"
The pixels in the output image (out.img) are equal to the mean of the pixel values in a 3x3 box around the input pixels. (This is essentially convolving the input image with an unnormalized 3x3 box.)
Example 2
% dmimgfilt cas_a.fits diffuse.fits median mask="annulus(0,0,3,7)"
The pixels in the output image are equal to the median of the pixel values in a 4pixel annulus around the input pixels. The median (and in particular with an annular mask) is a good technique to estimate the local background.
Example 3
% dmimgfilt A,B,C,D,...Z mean.fits mean "point(0,0)"
Average a stack of 26 images. The output image at pixel(x,y) is equal to the mean values of the pixel(x,y) values from the stack of input images. For another method of averaging images, see "ahelp dmimgcalc".
Parameters
name  type  ftype  def  min  max  reqd  stacks 

infile  file  input  yes  yes  
outfile  file  output  yes  
function  string  median  yes  
mask  string  yes  
numiter  integer  1  1  no  
lookupTab  string  no  
randseed  integer  0  
verbose  integer  0  0  5  
clobber  boolean  no 
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input stacks=yes)
The input image.
The input 2D image. A stack of images can be input. The values that the nonlinear algorithm is applied to comes from the mask applied to all the images in the stack.
Parameter=outfile (file required filetype=output)
The output file name
The output filtered image.
Parameter=function (string required default=median)
The filter function to use.
The allowed filter fuctions are: min, max, mean, median, mode, sigma, extreme, locheq, kuwahara, unsharp, range, variance, nmode, q10, q25, q33, q67, q75, q90, mcv, sum, rclip, peak, ridge, valley, plain, count, olympic, pmean, mu3, mu4, jitter, rms, nslope, 3sigmean, and 3sigmedian.
Parameter=mask (string required)
The input mask where the filter function is applied.
The region specification of the mask to use when computing the filter function. CIAOstyle region syntax is support.
The mask parameter controls the aperture of values considered in the 'function' statistics. It takes the form of a region specification (see "ahelp dmregions"). There are several predefined masks included in the parameter file. The units of all regions should be in image pixels; thus "circle(0,0,3)" defines a circle w/ radius=3 pixels without any knowledge of the size (e.g. arcsec) of the pixels. The mask is assumed to be centered. Asymmetrical masks may lead to a shift in the output image with respect to the input image.
Parameter=numiter (integer not required default=1 min=1)
Number of iterations
The same filter can be applied to the data multiple times.
When there are more than one files input, the subsequent iterations are done only on the output data as opposed to adding the output data into the stack.
Parameter=lookupTab (string not required)
The header merging table
Rules to merge the headers when more than one file supplied.
Parameter=randseed (integer default=0)
Random seed when using function=jitter. Setting to 0 uses system clock time.
Parameter=verbose (integer default=0 min=0 max=5)
The tool chatter level
Verbose can be from 0 to 5, generating different amounts of debugging output.
Parameter=clobber (boolean default=no)
Remove output if it exists?
Used to specify whether or not to clobber existing file that has the same name as the specified output file
Filter functions
The following sections lists the available functions and provides a description of them. Note that these functions are NOT guaranteed to conserve signal, and all pixel values are converted to doubles (if they are an integer or singleprecision floating point value).
For those functions which need to chose a value from a list of values, a "round down" approach is used if the selected index is not an integer. This means that the median of six values is taken as the third value (from a sorted list) rather than averaging the third and fourth values.
min
The minimum value in the mask region.
max
The maximum value in the mask region.
mean
The average value in the mask region.
sum
The sum of the values in the mask region.
count
The number of valid pixels in the mask region. This can be lower at the edges of an image, near nonfinitevalued (e.g. NaN) pixels, and outside any spatial filter applied to the input data (as recorded in the data subspace of the input).
median
The median value in the mask region. This is a nonstandard median: if the number points is even, then the lower value is used rather than the mean of the two middle values.
mode
The mode of the values in the mask region. This is a calculated value, given by:
mode = 3 * median  2 * mean
This can be compared to the "mcv" method below.
nmode
The "normalized" mode of the values in the mask region. This is calculated by dviding the mode by the mean.
mcv
Use the Most Common Value of the pixels in the mask. A histogram of the values is computed and the bin with the largest value is used. This can be compared to the "mode" method above.
The scheme used for creating the histogram is very simple, and not guaranteed to be useful in all cases. The range is set by the range of pixel values, and the number of bins is set to the square root of the number of pixels in the mask.
sigma
The standard deviation of the values in the mask region. This is computed relative to the mean of the values.
variance
The variance of the values in the mask region. This is computed relative to the value of the center pixel.
rms
Use the rootmean square of the pixel values in the mask.
extreme
Pick the minimum or maximum of the values in the mask region, picking which ever is closer to the mean.
locheq
This represents local histogram equalization. The range of pixels in the mask region is stretched to the range of pixels in the whole image. It can be used to extract lowlevel structure in images.
kuwahara
This is an edgepreserving smoothing filter. The mask is split into quadrants (NE, NW, SE, SW) and the mean and sigma computed for each quadrant. The mean with the smallest sigma is chosen.
unsharp
An unsharp mask, where the output pixel value is equal to the input pixel minus the mean of the pixel values in the mask.
range
The output is the range of the pixel values in the mask. That is the maximum  minimum value.
mid
Use the midpoint between the minimum and maximum pixle values in the mask. That is (maximum + minimum) / 2.
q10
Use the 10% quantile value of the pixels in the mask.
q25
Use the 25% quantile value of the pixels in the mask.
q33
Use the 33% quantile value of the pixels in the mask.
q67
Use the 67% quantile value of the pixels in the mask.
q75
Use the 75% quantile value of the pixels in the mask.
q90
Use the 90% quantile value of the pixels in the mask.
rclip
If the value of the pixel is within the range of the pixels in the masked region (excluding the pixel itself) then the value is unchanged. If it is below the range minimum then the value is replaced with the range minimum value. If the pixel is above the range maximum, then the value is replaced with the range maximum value.
peak
If the pixel value is strictly greater than all the pixels in the mask region, use it, otherwise it is replaced with a NaN. See also 'ridge'.
ridge
If the pixel value is greater than or equal to all the pixels in the mask region, use it, otherwise it is replaced with a NaN. See also 'peak'.
valley
If the pixel value is strictly less than all the pixels in the mask region, use it, otherwise it is replaced with a NaN. See also 'plain'.
plain
If the pixel value is less than or equal to all the pixels in the mask region, use it, otherwise it is replaced with a NaN. See also 'valley'.
olympic
Use the average value of the mask pixels after excluding the minimum and maximum values. Note that only one occurrence at each limit is removed, so if the values were 1, 1, 2, 3, 4, 4, 4 then the average would be calculated from 1, 2, 3, 4, 4.
pmean
Use the Poisson mean of the pixel values in the mask. This is computed as the number of pixels with a value of 0 or 1 divided by the number of pixels with a value of 0, minus 1. If there are no pixels with a value of 0 then the median is returned. This was used in the first release of the Chandra Source Catalog, in the dmimgpm tool.
mu3
Use the third moment of the pixel values in the mask.
mu4
Use the fourth moment of the pixel values in the mask.
jitter
Randomly select one of the pixel values in the mask. The randseed paramter is used to set the random seed; randseed=0 uses the system clock time.
nslope
The minimum slope (difference) between the pixel values in the mask.
3sigmean
The mean value of the pixel values in the mask after five iterations of 3sigma clipping.
3sigmedian
The median value of the pixel values in the mask after five iterations of 3sigma clipping.
Changes in CIAO 4.15

Four new filters have been added:
 ridge : If the pixel value is greater than or equal to all the pixels in the mask region, use it, otherwise it is replaced with a NaN. See also 'peak'.
 plain : If the pixel value is less than or equal to all the pixels in the mask region, use it, otherwise it is replaced with a NaN. See also 'valley'.
 q10: Use the 10% quantile value of the pixels in the mask.
 q90: Use the 90% quantile value of the pixels in the mask.

A new randseed parameter has been added to control the filter=jitter random selection.

Updated the tool to recognize realvalued NULLs and to recognize valid data ranges.
Bugs
There are no known bugs for this tool.
See Also
 concept
 merging_rules, subspace
 dm
 dmfiltering, dmmasks, dmregions
 tools
 addresp, convert_ds9_region_to_ciao_stack, dither_region, dmappend, dmcontour, dmellipse, dmfilth, dmgroupreg, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimghull, dmimglasso, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmakereg, dmmaskbin, dmmaskfill, dmmerge, dmnautilus, dmregrid, dmregrid2, dmstat, evalpos, get_src_region, hrc_dtfstats, imgmoment, mean_energy_map, mkbgreg, mksubbgreg, pileup_map, reproject_image, reproject_image_grid, roi, splitroi, tg_create_mask