Synopsis
Convert a map file into a region file.
Syntax
map2reg infile outfile [parallel] [nproc] [verbose] [clobber]
Description
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.
Example
% map2reg hex.map hex.reg % ds9 hex.map -region hex.reg
Convert the map file, hex.map, into an ASC-FITS format region file, hex.reg. We then use ds9 to display the results.
Parameters
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.2 (August 2024) release
Due to continued problems writing the output file for large number of regions, needed to re-write the code that creates the output file. Now runs much faster and uses much less memory.
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.
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, merge_too_small, mkregmap, pathfinder, vtbin
- tools::region
- bkg_fixed_counts, convert_ds9_region_to_ciao_stack, dmcontour, dmellipse, dmgroupreg, dmimghull, dmimglasso, dmmakereg, psf_contour, rank_roi, regphystocel, roi, splitroi
- tools::response
- mean_energy_map, pileup_map
- tools::statistics
- dmstat, imgmoment, statmap