Performs various non-linear image filtering techniques.
dmimgfilt infile outfile function mask [numiter] [lookupTab] [randseed] [verbose] [clobber]
`dmimgfilt' performs one of several different mask-based 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 energy-preserving. Users should not expect to conserve flux when applying these filters to their data.
% 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 un-normalized 3x3 box.)
% 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 4-pixel annulus around the input pixels. The median (and in particular with an annular mask) is a good technique to estimate the local background.
% 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".
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 non-linear 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. CIAO-style 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 pre-defined 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
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 single-precision 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.
The minimum value in the mask region.
The maximum value in the mask region.
The average value in the mask region.
The sum of the values in the mask region.
The number of valid pixels in the mask region. This can be lower at the edges of an image, near non-finite-valued (e.g. NaN) pixels, and outside any spatial filter applied to the input data (as recorded in the data subspace of the input).
The median value in the mask region. This is a non-standard median: if the number points is even, then the lower value is used rather than the mean of the two middle values.
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.
The "normalized" mode of the values in the mask region. This is calculated by dviding the mode by the mean.
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.
The standard deviation of the values in the mask region. This is computed relative to the mean of the values.
The variance of the values in the mask region. This is computed relative to the value of the center pixel.
Use the root-mean square of the pixel values in the mask.
Pick the minimum or maximum of the values in the mask region, picking which ever is closer to the mean.
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 low-level structure in images.
This is an edge-preserving 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.
An unsharp mask, where the output pixel value is equal to the input pixel minus the mean of the pixel values in the mask.
The output is the range of the pixel values in the mask. That is the maximum - minimum value.
Use the mid-point between the minimum and maximum pixle values in the mask. That is (maximum + minimum) / 2.
Use the 10% quantile value of the pixels in the mask.
Use the 25% quantile value of the pixels in the mask.
Use the 33% quantile value of the pixels in the mask.
Use the 67% quantile value of the pixels in the mask.
Use the 75% quantile value of the pixels in the mask.
Use the 90% quantile value of the pixels in the mask.
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.
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'.
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'.
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'.
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'.
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.
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.
Use the third moment of the pixel values in the mask.
Use the fourth moment of the pixel values in the mask.
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.
The minimum slope (difference) between the pixel values in the mask.
The mean value of the pixel values in the mask after five iterations of 3-sigma clipping.
The median value of the pixel values in the mask after five iterations of 3-sigma 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 real-valued NULLs and to recognize valid data ranges.
There are no known bugs for this tool.
- merging_rules, subspace
- dmfiltering, dmmasks, dmregions
- 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