Last modified: December 2013

AHELP for CIAO 4.13


Context: tools


Perform a quad-tree adaptive binning on 2D images


dmnautilus infile outfile snr [inerrfile] [outmaskfile] [outsnrfile]
[outareafile] [verbose] [clobber]


`dmnautilus' does a form of adaptive binning of a 2D image known as a 'quad-tree' algorithm. A detailed description of the technique can be found in Samet, H. "The Quadtree and Related Hierarchical Data Structures", 1984, ACM Computing Surveys, 16, 187.

The tool looks at the entire image and computes the signal-to-noise ratio (SNR). If the SNR is greater than the input threshold, the image is divided in half in both the horizontal and vertical directions. For each sub-image, the process is repeated until the SNR drops below the user-supplied value or a single pixel remains above the SNR limit. The output pixels are then the sum of the pixels in the sub-image divided by the area of the sub-image. The tool can also optionally output the area, snr, and a mask/group number for each output pixel.

Pixels that fall outside of the data subspace, NaNs, and integer NULL value pixels are all ignored when computing the sum, area and SNR.

While square images will give the most natural-looking binning, rectangular images can be input and rectangular bins will be used.

If no error file is supplied (inerrfile parameter), then a Gaussian approximation "(sqrt(image value))" is used. If an error file is supplied, it must be the same size as the input image.

The output mask file can be used with dmmaskbin to group another image of the same dimensions using the same bin sizes. This is useful say to group the data based on broad-band energy filter and then group narrow band images using the same grouping scheme.


Example 1

dmnautilus inimg.fits outimg.fits 9

Adaptivly bins the image in inimg.fits to a SNR threshold of 9. Since no error image is supplied the SNR is computed as the sqrt(inimg.fits).

Example 2

dmnautilus inimg.fits outimg.fits 15 inerr=errs.fits

Bins the input image to a SNR threshold of 15. The error of each pixel is taken from the errs.fits file.

Example 3

dmnautilus inimg.fits outimg.fits 9 outmaskfile=mask.fits

Similar to Example 1 but outputs the mask information. Each pixel in the mask.fits file indicates which group the pixel was assigned to.

Example 4

dmnautilus inimg.fits . 9 outmask=. outsnr=. outarea=.

Similar to above but also outputs the output SNR threshold image and the area image. It uses autonaming to name the outfile, outmaskfile, outsnrfile, and outareafile files.


name type ftype def min max reqd autoname
infile file input       yes  
outfile file output       yes yes
snr real   0 0   yes  
inerrfile file input       no  
outmaskfile file output       no yes
outsnrfile file output       no yes
outareafile file output       no yes
verbose integer   0 0 0 no  
clobber boolean   no     no  

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input 2D image

Image to be adaptive binned.

Parameter=outfile (file required filetype=output autoname=yes)

Output adaptive binned image.

Output of the adaptive binning routine. Data will be stored as floating point values.

Parameter=snr (real required default=0 min=0)

Signal-To-Noise-Ratio threshold

The signal to noise ration to split the image into 4 sub-images. It may seem unnatural but this is an upper-limit on the SNR.

Parameter=inerrfile (file not required filetype=input)

Input error image

Image containing the error estimate for each pixel in infile. The square of the pixel values is used when computing the SNR. The error image must be the same dimensionality as infile (datatype is arbitrary).

Parameter=outmaskfile (file not required filetype=output autoname=yes)

Image with grouping information

Indicated which group number (arbitrary) the pixel belongs to. Can be used with dmmaskbin to bin another image of the same dimension using the same grouping scheme.

Parameter=outsnrfile (file not required filetype=output autoname=yes)

Image containg the SNR for each pixel/sub-image

The SNR value computed for each sub-image is stored in this file. Sharp edges in the SNR map can be used to detect extended emission.

Parameter=outareafile (file not required filetype=output autoname=yes)

The area (in number of pixels) of each sub-image.

The area of each sub-image is stored. This can be useful to exclude particularly large regions where statistics may dominate the analysis or to remove data from the edge of the image.

Parameter=verbose (integer not required default=0 min=0 max=0)

Tool chatter level

Currently disabled.

Parameter=clobber (boolean not required default=no)

Remove existing outputs?

Remove existing output files if they already exist?


There are no known bugs for this tool.

See Also

dmappend, dmcontour, dmellipse, dmfilth, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimghull, dmimglasso, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmregrid, dmregrid2, dmstat, evalpos, imgmoment, mean_energy_map, pileup_map