dmimghull

Synopsis

Create convex polygon around pixels in an image

Syntax

dmimghull  infile outfile [tolerance] [clobber] [verbose]

Description

`dmimghull' computes a polygon region that encloses the image pixels above the tolerance threshold. The output is convex polygon (all interior angles greater than or equal to 90 degrees). Such a polygon is often referred to as a convex "hull" giving rise to the tools name.

A convex polygon can be a very useful approximation for objects that are not quite elliptical or circular in nature but still have smoothly varying outline. For example if a source is at the edge of the field, a circle or ellipse region may extend beyond the edge of the detector yielding an incorrect area. Using a polygon will provide a region that follows data and would yield a better area calculation.

A convex hulls are also useful to establish search boundaries around a collection of points. For example when doing source matching one can construct the convex hull around the sources in an observation, then pre-filter the match list -- only those sources in the convex hull around the source list need to be checked for one-to-one matching.

Examples

Example 1

dmimghull img.fits hull.fits tol=0

Computes the convex hull around the pixels in the image whose values are greater than 0. The output is an ASC-FITS region file that can be used in ds9 or used as a CIAO filter.

Example 2

aconvolve img.fits sm_img.fits "lib:gaus(2,1,5,3,3)"
dmimghull sm_img.fits src.reg tol=0.1
dmextract "img.fits[sky=region(src.reg)]" imgstats.fits op=generic

Supposed that the background around a faint source was expected to be ~0.1 counts per pixel. A simple source detection tool can then be created by smoothing the image and then computing the convex polygon around the flux above 0.1 counts per pixel.

In the case of a faint source, a contour region may have many features along the outline due to the statistical noise. An elliptical region may fail for faint sources if the emission is not centrally peaked. In this case, a polygon outline around the edge of emission may be the best choice to describe the source morphology.

This only works in the case of a single source. If multiple sources are present then the input image would need to be filtered to enclose each separately.

Example 3

dmimghull "XMM_evt[ccdnr=1][bin x=::100,y=::100]" xmm_ccdnr1.fov

This example shows to use dmimghull to create a a convex hull around the data for one XMM CCD; effectively creating a Field Of View like file. This file can then be used with CIAO tasks when filtering to get the correct area calculations.

Parameters

name	type	ftype	def	min	max	reqd
infile	file	input				yes
outfile	file	output				yes
tolerance	real
clobber	boolean		no
verbose	integer		0	0	5

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input image

The input must be a 2D image. All calculations are done physical coordinates

Parameter=outfile (file required filetype=output)

Output region file

The output file is a FITS region file that include the polygon that encloses the input pixels strictly above the threshold value.

Parameter=tolerance (real)

Value below which to consider background

Parameter=clobber (boolean default=no)

Remove output if it exists?

If clobber=yes and a file exists that has the same name as the name of the output file, then the existing file is overwritten.

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

Tool verbosity level

Verbose can be from 0 to 5, which determines the amount of screen output that is generated.

Changes in CIAO 4.15

The output file will now contain any WCS transforms set on the input image.

The WCS on the input image is now copied to the X,Y columns in the output table.
Updated the tool to recognize real-valued NULLs and to recognize valid data ranges.

Bugs

There are no known bugs for this tool.