dmcontour

Context: tools

Syntax

dmcontour infile levels outfile [verbose] [clobber] [mode]

`dmcontour' allows the user to generate a region file from a 2-dimensional image that can be used to subsequently filter their data from contour levels in an input image. A virtual image file created from a table file with dm syntax can be used.

The region filters are created such that they include the contour level and everything above it -- including possibly other contour levels. Only closed contours will generate regions.

For best results users should smooth their image prior to running dmcontour. The actual region will be a polygon approximation to the contour.

If the input image has a physical coordinate system (e.g. a binned Chandra event file), the output is in the physical coordinates of the image. This makes using the file as a filter for event lists/tables, as well as images which have physical coordinates preserved, easy. If an image that doesn't have physical coordinates (e.g. an optical image) is used to define the contour levels, the output is in logical coordinates. It will be difficult to display these contours on anything other than another image which is congruent to the input image.

NB: The FITS region file produced by dmcontour can be loaded into ds9 directly. However, if you find a display full of excluded regions, you may wish to make a simpler regions version by choosing only one level, e.g. "dmcopy regions.fits[contour_level=10] region10.fits".

Example

dmcontour in_image.fits "1,5,10,20" out_region.fits

Will read in the image, "in_image.fits" and create an output region file that has contour intervals for each of the specified levels.

The output region file will have region filters that will inlcude everything > 1, everything > 5, everything > 10, and everything > 20.

The syntax to use this with another tool (for example to extract a histogram/spectrum) would be:

infile="my_file[sky=region(out_region.fits[contour_level=1])]"

This will filter the "sky" vector column in "my_file" with the contour level = 1 region in the file "out_region.fits"

Parameters

name	type	ftype	def	min	max	units	reqd
infile	file	input					yes
levels	string					image	yes
outfile	file	output					yes
verbose	integer		0	0	5		no
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile `(file required filetype=input)`

Input file name.

The name of the input file. It can be a table with a DM virtual file specficiation that makes it into an image, eg "[bin ...]"

Parameter=levels `(string required units=image)`

The contour levels to define regions. Only closed contours will generate regions.

This parameter can either be a comma separated list of values or it can be a range of values. Do not include any spaces.

value1,value2,...,valueN	comma separated list of contour levels
value1:value2:value3	Generate intervals from value1 to value2 in steps of value3
:value2:value3	Generate intervals from min(data) to value2 in steps of value3
value1::value3	Generate intervals from value1 to max(data) in steps of value3.
::value3	Intervals from min(data) to max(data) in steps of value3

Parameter=outfile `(file required filetype=output)`

Output file name

The name of the output FITS region file.

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

Controls amount of information to print (0-5).

Parameter=clobber `(boolean default=no)`

Clobber output if it exists? [y/n]

Bugs

Problems at the edge of images (01 Dec 2006)

When a contour intersects the edge of an image, dmcontour draws a frame around the image and creates contours that are marked as "exclude" regions (i.e. have a red line through them when displayed in ds9).

Workaround:

If you are running into this problem, you have to make sure that your contours don't have a value that occurs at the edge of the image. The safest way to do this is to check the max value for the bounding rows/edges and then choose your contour level to be greater than that. It looks tedious, but you could script this if you are doing it often:

unix% dmlist image.fits blocks
 
--------------------------------------------------------------------
Dataset: image.fits
--------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------
Block    1: CONVOLVE                       Image      Real4(263x218)


unix% dmstat image.fits"[#2=1]" median=yes centroid=no |grep max
    max:        2.8171137093e-18              @:        ( 3856.13 4208.04 )

unix% dmstat image.fits"[#1=1]" median=yes centroid=no |grep max
    max:        3.6766300528e-18              @:        ( 3840.33 4214.44 )

unix% dmstat image.fits"[#1=263]" median=yes centroid=no |grep max
    max:        5.2055576098e-18              @:        ( 3866.53 4229.24 )

unix% dmstat image.fits"[#2=218]" median=yes centroid=no |grep max
    max:        7.753583262e-18               @:        ( 3863.73 4229.64 )

So as long as the contour level is > 7.75e-18, you won't get the frame/exclude behavior.

This doesn't mean that you can't choose contours lower than the max value. It just means that by setting your bar above the highest, you know that you will not run into this bug.

dmcontour

Parameter=infile (file required filetype=input)

Parameter=levels (string required units=image)

Parameter=outfile (file required filetype=output)