mkregmap

Synopsis

Create map from stack of input regions.

Syntax

mkregmap  infile regions outfile [binimg] [coord] [verbose] [clobber]

Description

The tool take an image and a stack of region descriptions. The regions can be multiple files, multiple rows in a single file, or a list individual shapes. The output image pixel values indicate which region each pixel is inside. If a pixel is inside more than one region, the last region number is used.

Examples

Example 1

% mkregmap img.fits "region1.fits,region2.fits,region3.fits" reg.map

Three region files are supplied as input using commas (",") to separate them. The output map file will contain values 1, 2, or 3 if the pixels in the input image, img.fits, are inside any of those regions. The outfile, reg.map, stores this information, and will have pixels equal to zero (0) if they are not included in any of the regions, or if the input pixels were NaN. We could also use the "region(filename)" syntax

"region(region1.fits),region(region2.fits),region(region3.fits)"

or use the "@stack_filename" syntax

% cat my_region.lis
region1.fits
region2.fits
region3.fits
circle(3288,6778,100)
% mkregmap region=@my_region.lis

Note: Users should be careful when using the "@" syntax with list files located in different directories. The "@-" syntax may be need to suppress appending the directory name to the stack elements.

Example 2

% mkregmap img.fits "pgrid(4096,4096,0:1000:100,0:360:360)" pgrid.map

Here we use the polar-grid, "pgrid", stack syntax to create a set of 10 annuli, all centered at (4096,4096), with radii that go from 0 to 1000 pixels in 100 pixel steps.

Example 3

% dmellipse img.fits out=ellipse.out fraction="lgrid(0.05:1.0:0.025)"
% dmsort ellipse.out ellipse_sort.fits key=-component
% mkregmap img.fits "ellipse_sort.fits[#row=igrid(1:100:1)]" ellipse.map

Here we start by using dmellipse to generate a set of ellipses which enclose from 5% to 100% of the flux in the input image. We then reverse sort these based on the COMPONENT column value (ie in descending order). These are then fed into mkregmap to create an elliptical-annulus map. We sorted the values since the inner most region (5%) is typically fully enclosed by the larger fractions and since mkregmap uses the last region when regions overlap, we need it to be at the end of the stack.

Example 4

% mkregmap xmm.fits @region.lis xmm.map coord="pos"

Not all images have a "sky" coordinate system that the scripts can understand. Some images likes those from XMM data products contain a "pos" coordinate system.

Users can use dmlist with the "cols" option to see the coordinate axis name needed to use the script.

Parameters

name	type	ftype	def	min	max	reqd	stacks
infile	file	input				yes
regions	string					yes	yes
outfile	file	output				yes
binimg	file	output
coord	string		sky
verbose	integer		1	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input image.

Null and NaN pixels, as well as those pixels outside the image subspace will not be grouped. Otherwise the pixel values are ignored, just the size and dimensions of the image are used.

Parameter=regions (string required stacks=yes)

Stack of regions

Each region in the stack is assigned an ID, from 1 to N. The output image is set to the region ID if the pixel is inside the region. If multiple regions overlap, the last region in the stack will be used to set the group ID (highest region ID).

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 (ie outside the image subspace).

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=coord (string default=sky)

Axis name to filter input image

Not all images have a "sky" coordinate system. For example XMM images typically have a "pos" coordinate system. Users can use the dmlist command with the "cols" option to determine the column name to filter on.

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?

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.