Chandra X-Ray Observatory
Skip to the navigation links
Last modified: December 2013

AHELP for CIAO 4.10


Context: tools


Performs various non-linear image filtering techniques.


dmimgfilt  infile outfile function mask [numiter] [lookupTab] [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.

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 sum of the values in the mask region
  • count - the sum 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 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 is defined as the 3 * median - 2 * mean.
  • nmode - the mode is defined 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; otherwise, the max is used.
  • locheq - local histogram equalization. The range of pixels in the mask region is stretched to the range of pixels in the whole image. Useful to extract low-level structure in images.
  • kuwahara - an edge-preserving smoothing filter. 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.
  • 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 with 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 it is greater 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; otherwise, output NaN.
  • valley - if center pixel is less than all the pixels in the mask, then keep center value; otherwise, 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.
  • mu3 - third moment
  • mu4 - fourth moment
  • jitter - randomly select one of the values in the mask
  • rmf - root mean square
  • nslope - minimum slope (difference) between values in mask
  • 3sigmean - mean value after doing 5 iterations of 3-sigma clipping
  • 3sigmedian - median value after doing 5 iterations of 3-sigma clipping

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.


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


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, unsharp, range, variance, nmode, q25, q33, q67, q75, mcv, sum, rclip, peak, valley, 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=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.

Changes in CIAO 4.10

  • Updated to check for mask() syntax and error out if found.


There are no known bugs for this tool.

See Also

merging_rules, subspace
dmfiltering, dmmasks, dmregions
addresp, dither_region, dmappend, dmcontour, dmellipse, dmfilth, dmgroupreg, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, 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

Last modified: December 2013
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email: Smithsonian Institution, Copyright © 1998-2017. All rights reserved.