Synopsis
Create adaptive bin image using Voronoi Tessellation
Syntax
vtbin infile outfile [binimg] [shape] [radius] [sitefile] [verbose] [clobber]
Description
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.
Examples
Example 1
% vtbin sm_img.fits vt.map
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 point.map srconly=yes thresh=0.5 % vtbin sm_img.fits vt.map sitefile=points.map
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 vt.map 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.
Parameters
| 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.
Bugs
There are no known bugs for this tool.
See Also
- dm
- dmfiltering
- tools::core
- dmappend
- tools::image
- 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
- tools::region
- dmcontour, dmellipse, dmimghull, dmimglasso
- tools::response
- mean_energy_map, pileup_map
- tools::statistics
- dmstat, imgmoment, statmap