Last modified: August 2023

AHELP for CIAO 4.16


Context: Tools::Image


Create adaptive bin image using Voronoi Tessellation


vtbin  infile outfile [binimg] [shape] [radius] [sitefile] [verbose]


vtbin starts by identifying the local maxima in the input image. Each local max is assigned a unique identification number. It then computes the Voronoi Tessellation around the location of the local maxima (sites) and assigns all pixels within the Voronoi cells to the group.

Users can override the initial site location by supplying their own sitefile. If not, then the input image should be smoothed on a scale larger than the local-max search size as specified by the shape and radius parameters. (default is a 5x5 box)

See also: centroid_map

Users may also want to consider the centroid_map tool. It runs vtbin repeatedly adjusting the input sites to be the centroid of each cell.


Example 1

% vtbin sm_img.fits

Here a smoothed image is input. With the default parameters, the tool will then identify all the local maxima in a 5x5 square neighborhood in the image. The Voronoi tessellation of the location of those maxima will then computed and the map created.

Example 2

% dmimgfilt sm_img.fits points.img "max" "box(0,0,3,1)+box(0,0,1,3)" %
dmimgblob points.img srconly=yes thresh=0.5 % vtbin

In this example we show how a user might create an input sitefile. We use the dmimgfilt too to identify local maxima in a plus (+) shape region (instead of the box or circle available in this tool). We then label each local maxima using the dmimgblob tool. With the sitefile specified, the script will use the locations in that file for the tessellation.

Example 3

% vtbin sm_img.fits shape=circle radius=4 binimg=vt.img

In this example the local maximum search is changed to use a circular region with a radius of 4 logical pixels. In addition we choose to output the binned image by specifying the binimg parameter.


name type ftype def min max reqd
infile file input       yes
outfile file output       yes
binimg file output        
shape string   box      
radius real   2.5      
sitefile file input        
verbose integer   1 0 5  
clobber boolean   no      

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input image.

The image to be grouped. Generally this algorithm works better if it is slightly smoothed.

Null and NaN pixels, as well as those pixels outside the image subspace will not be grouped.

Parameter=outfile (file required filetype=output)

Output map file

The outfile is a map file containing integer pixel values. The pixel values indicate which pixels are grouped together by the algorithm. A pixel value of 0 are pixels which are ungrouped.

Parameter=binimg (file filetype=output)

Optional, output binned image

If the binimg file is specified, the script will use the input image and the output map file to create a binned version of the input image.

Parameter=shape (string default=box)

Shape of local max search region.

The shape and radius parameters specify the region to use when searching for "local" maxima. The radius is expressed in logical (image) pixels.

Parameter=radius (real default=2.5)

Shape of local max search region.

The shape and radius parameters specify the region to use when searching for "local" maxima. The radius is expressed in logical (image) pixels.

Parameter=sitefile (file filetype=input)

Input site map file

If the sitefile is specified, then the local max search specified by the shape and radius parameters is not performed. The sitefile must have the same shape/size as the input image. The pixel values should be integers; values not equal to zero are used for the tessellation and the values must be unique. Typically there should be a few hundred to maybe a few thousand sites (based on the image sizes).

Parameter=verbose (integer default=1 min=0 max=5)

Amount of chatter from the tool.

Parameter=clobber (boolean default=no)

Delete outfile if it already exists?

Relation to weighted Voronoi Tesselation binning

Users of this tool should also be familiar with Diehl & Statler's the weighted Voronoi tessellation binning tool, wvt_bin .

About Contributed Software

This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.


There are no known bugs for this tool.

See Also

centroid_map, dmfilth, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmnautilus, dmradar, dmregrid, dmregrid2, energy_hue_map, evalpos, hexgrid, map2reg, merge_too_small, mkregmap, pathfinder
dmcontour, dmellipse, dmimghull, dmimglasso
mean_energy_map, pileup_map
dmstat, imgmoment, statmap