map2reg

Context: Tools::Image

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.