Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/dmcontour.html
AHELP for CIAO 4.16

dmcontour

Context: Tools::Region

Synopsis

Make contour regions from a 2-D image

Syntax

dmcontour  infile levels outfile [verbose] [clobber]

Description

`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 stack of values or it can be a grid of values. Examples include

Examples of allowable levels values.
Example Explanation
value1,value2,...,valueN comma separated list of contour levels
value1 value2 ... valueN space separated list of contour levels
value1;value2;...;valueN semicolon separated list of contour levels
lgrid(value1:value2:value3) Use the stack "lgrid" to create a linear grid of values from value1 to value2 in steps of value3.
@levels.lis The list of values stored in an ASCII stack list file. If the file is in a different directory, then be sure to use "@-" to omit the directory.
value1:value2:value3 Generate intervals from value1 to value2 in steps of value3
value1:value2:#value3 Generate intervals from value1 to value2 in value3 number of equal steps
value1:value2:#value3l Generate intervals from value1 to value2 in value3 number of logarithmically spaced steps
value1:value2 Generate intervals from value1 to value2 in steps of 1.
: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
grid(filename[cols colA,colB]) Retrieve the levels from the input file using the lo/hi values from columns colA and colB.

When using a grid syntax, the upper range limit value is always used. For example 0:10:3 will generate levels: 0, 3, 6, 9, 10.

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]


Changes in CIAO 4.15

The parsing of the levels parameter has been updated to match other CIAO tools that handle binning and ranges. This means that the tool may behave differently for certain inputs.

Changes in CIAO 4.16


Bugs

There are no known bugs for this tool.

See Also

concept
subspace
dm
dmfiltering, dmmasks, dmregions
tools::aspect
dither_region
tools::core
dmappend
tools::detect
get_src_region
tools::gratings
tg_create_mask
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, vtbin
tools::region
bkg_fixed_counts, convert_ds9_region_to_ciao_stack, dmellipse, dmgroupreg, dmimghull, dmimglasso, dmmakereg, psf_contour, rank_roi, regphystocel, roi, splitroi
tools::response
mean_energy_map, pileup_map
tools::statistics
dmstat, imgmoment, statmap