/ ciao4.17 / ahelp / vtbin.html

Jump to: Description · Examples · Parameters · Relation to weighted Voronoi Tesselation binning · About Contributed Software · Bugs · See Also

AHELP for CIAO 4.17

vtbin

Context: Tools::Image

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)

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.