/ ciao4.15 / ahelp / dmimgfilt.html

Jump to: Description · Examples · Parameters · Filter functions · Changes in CIAO 4.15 · Bugs · See Also

AHELP for CIAO 4.15

dmimgfilt

Synopsis

Performs various non-linear image filtering techniques.

Syntax

dmimgfilt  infile outfile function mask [numiter] [lookupTab]
[randseed] [verbose] [clobber]

Description

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

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

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

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

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

median

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.

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 root-mean 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 low-level structure in images.

kuwahara

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.

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 mid-point 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 3-sigma clipping.

3sigmedian

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.

Bugs

There are no known bugs for this tool.