Skip to the navigation links
Last modified: December 2009

URL: http://cxc-newtest.cfa.harvard.edu/ciao4.2/dmimgfilt.html
AHELP for CIAO 4.2

dmimgfilt

Context: tools

Synopsis

Performs various non-linear image filtering techniques.

Syntax

dmimgfilt infile outfile function mask [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 can be used to estimate background and to help to define upper or lower limits on the data.

Filter functions

  • 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 num of the values in the mask region
  • count - the num of pixels in the mask region (lower at edges and near NULL/NaN pixels)
  • median - the median value in the mask region. The median is the middle value from the array of pixel values. This is a slightly non-standard median: if number points is even then the lower value is used rather than the mean of the two middle values
  • mode - the mode is defines as the 3 * median - 2 * mean.
  • nmode - the mode is defines as the 3 * median - 2 * mean. nmode is the mode divided-by mean to get a normalized value.
  • sigma - the output image is the standard deviation of the pixels in the mask
  • extreme - if the mean is closer to the min then the min is used, else the max is used.
  • locheq - local histogram equalization. The range of pixels in the mask region is streched to the range of pixels in the whole image. Useful to extract low level structure in images.
  • kuwahara - the mask is split into quadrants (NE, NW, SE, SW). The mean and sigma is computed for each quadrant. The mean with the smallest sigma is used. This is an edge preserving smoothing filter.
  • unsharp - the output pixel value is equal to the input pixel minus the mean of the pixel values in the mask.
  • range - the output pixel is equal to the range (MAX - MIN) of the pixel values in the mask
  • mid - the middle value between the min and max == (MAX + MIN)/2.0
  • variance - the output pixel is equal to the sqrt of the sum of the squares of the center-pixel - the pixels in the mask.
  • q25 - the 25% quantile value of the pixels in the mask
  • q33 - the 33% quantile value of the pixels in the mask
  • q67 - the 67% quantile value of the pixels in the mask
  • q75 - the 75% quantile value of the pixels in the mask
  • mcv - the Most Common Value. A histogram of the values inside the mask is computed and the histogram bin w/ the largest value is used
  • rclip - If the center pixel value is less than the min pixel in the mask, replace with the min value. If greather than the max, replace with the max. Otherwise use original value.
  • peak - if center pixel is greater than all the pixels in the mask, then keep center value; else output NaN.
  • valley - if center pixel is less than all the pixels in the mask, then keep center value; else output NaN.
  • olympic - the min and max values are excluded and the average of of the remaining pixels is used.
  • pmean - Poisson mean computed as (#Pixels with value = 0 or 1 divided by #Pixels with value = 0 ) minus 1. If #pixels_0 is 0 then use median.

The mask parameter controls the apperature of values considered in the 'function' statistics. It takes the form of a region specification (see "ahelp dmregions"). There are several pre-defined maskes available at the end of the parameter file. The units of all regions should be in image-pixels; thus "circle(0,0,3)" defines a cirlce w/ radius=3 pixels without any knowledge of the size (eg arcsec) of the pixels. The mask is assumed to be centered -- asymetrical masks may lead to a shift in the output image with-respect-to the input image.

dmimgfilt will respect the NULL or NaN values in the input image (the values are skipped an 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.

Example 1

dmimgfilt infile=some_image.fits outfile=filtered.fits func=mean
mask="box(0,0,3,3)"

The pixels in the output image 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 infile=cas_a.fits outfile=diffuse.fits func=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 infile=@img.lis outfile=median.fits func=median
mask="point(0,0)"

The output image at pixel(x,y) is equal to the median values of the pixel(x,y) values from the stack of input images.

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  
clobber boolean   no        
verbose integer   0 0 5    

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, and unsharp.

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.

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

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.

Bugs

See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

See Also

concept
subspace
dm
dmfiltering, dmregions
tools
dither_region, dmappend, dmcontour, dmellipse, dmfilth, dmgroupreg, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimghist, dmimglasso, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmakereg, dmmaskbin, dmmaskfill, dmnautilus, dmregrid, dmregrid2, dmstat, evalpos, get_sky_limits, get_src_region, mkbgreg, mksubbgreg, pileup_map, tg_create_mask

Last modified: December 2009