Last modified: January 2024

AHELP for CIAO 4.16


Context: Tools::Image


Convert a map file into a region file.


map2reg  infile outfile [parallel] [nproc] [verbose] [clobber]


This script creates a polygon region around each unique set of pixel values in the input map file. The `dmimglasso' tool is used to identify the polygons. The polgyons may contain multiple components if there is a hole in the interior (eg a separate group completely surrounded by another group).

This script assumes that all groups are contiguous. If a group is split into multiple disjoint sections then only 1 of those sub-groups will be processed.

Only pixel values greater than zero (>0) are considered. Pixel values equal to zero are considered as being ungrouped.

This script runs in parallel; though for a large number of unique map IDs it can still be slow.

The map values in the infile are not the same as the COMPONENT values in the output region file.


% map2reg hex.reg % ds9 -region hex.reg

Convert the map file,, into an ASC-FITS format region file, hex.reg. We then use ds9 to display the results.


name type ftype def min max reqd
infile file input       yes
outfile file output       yes
parallel boolean   yes     no
nproc integer   INDEF 1   no
verbose integer   1 0 5  
clobber boolean   no      

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input map file.

The map file should contain integer pixel values which represent which pixels are grouped together. Pixel values equal to 0 are ignored (treated as being ungrouped).

Parameter=outfile (file required filetype=output)

Output region file

The output is stored as an ASC-FITS format region file. Each map ID in the input image will be output as one or more polygons. The map ID is not stored (it is not guaranteed to be the COMPONENT value). Each component may have interior polygons excluded if they completely surround another group (or an ungrouped area).

Parameter=parallel (boolean not required default=yes)

Run code in parallel using multiple processors?

If multiple processors are available, then this parameter controls whether the tool should run various underlying tools in parallel.

Parameter=nproc (integer not required default=INDEF min=1)

Number of processors to use

If parallel=yes, then this controls the number of processes to run at once. The default, INDEF, will use all available processors. The value cannot be larger than the number of processors.

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?

Changes in scripts 4.16.1 (Q1 2024) release

Internal changes to fix possible crash when dealing with large regions, eg polygons with many sides. The tool may require more memory and run slower but should now be more robust.

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