Last modified: August 2023

AHELP for CIAO 4.16


Context: Tools::Image


Create map from stack of input regions.


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


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.


Example 1

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

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,, 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


or use the "@stack_filename" syntax

% cat my_region.lis
% 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)"

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)]"

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 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.


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.


There are no known bugs for this tool.

See Also

dmfiltering, dmmasks, dmregions
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, pathfinder, vtbin
bkg_fixed_counts, convert_ds9_region_to_ciao_stack, dmcontour, dmellipse, dmgroupreg, dmimghull, dmimglasso, dmmakereg, psf_contour, rank_roi, regphystocel, roi, splitroi
mean_energy_map, pileup_map
dmstat, imgmoment, statmap