reg2master

reg2master - Convert DS9 Region File to Master Table

Space Telescope Science Institute

Synopsis

Convert a DS9 region file into a master table file with standardized columns for source positions and region geometry.

Command Line Usage

reg2master.py [-h] regionfile [masterfile]

Required Arguments:

regionfile

Input DS9 region file containing source region definitions.

Optional Arguments:

masterfile

Output master table filename. If not specified, defaults to <regionfile>.txt.

-h

Display this help message and exit.

Description

This program parses a DS9 region file and extracts source positions and region geometry into a standardized master table format. The output can be used as input for photometry routines or converted back to region files using master2reg.py.

Supported region types:

  • circle - Circular apertures

  • ellipse - Elliptical apertures

  • box - Rectangular regions

  • annulus - Circular annuli

Output

An ASCII table in fixed_width_two_line format with columns:

  • Source_name : str - Source identifier (from region label or auto-generated)

  • RA : float - Right Ascension in degrees

  • Dec : float - Declination in degrees

  • RegType : str - Region type

  • Major : float - Major axis/radius in arcseconds

  • Minor : float - Minor axis in arcseconds

  • Theta : float - Position angle in degrees

  • Color : str - Region color from DS9 file

Notes

  • Source names are extracted from the text={} field in region definitions

  • If no name is provided, names are auto-generated as ‘zzz001’, ‘zzz002’, etc.

  • Colors are preserved from the region file for downstream use

  • For boxes, Theta corresponds to the angle E of N for the Minor axis

  • The same convention applies to ellipses

History

090109 ksl

Initial coding

111111 ksl

Fixed for pydocs compatibility

190507 ksl

Added Color column extraction

241230 ksl

Added box region type support

Functions

doit(regionfile[, masterfile])

Create a master table from a region file.

radec2deg(ra, dec)

Convert RA/Dec strings to decimal degrees.

read_regions(filename)

Read and parse a DS9 region file.

size2arcsec(word)

Convert a size string to arcseconds.

steer(argv)

Parse command line arguments and execute conversion.

write_masterfile(masterfile, records[, source, type])

Write a master table file from parsed region records.

Module Contents

reg2master.doit(regionfile, masterfile='')

Create a master table from a region file.

Parameters

regionfilestr

Input DS9 region file.

masterfilestr, optional

Output master table filename. If empty, defaults to <regionfile>.txt.

Returns

None

Writes master table to disk.

reg2master.radec2deg(ra, dec)

Convert RA/Dec strings to decimal degrees.

Parameters

rastr

Right Ascension as ‘HH:MM:SS’ string or decimal degrees string.

decstr

Declination as ‘DD:MM:SS’ string or decimal degrees string.

Returns

tuple of (float, float)

RA and Dec in decimal degrees.

Notes

RA in sexagesimal format is assumed to be in hours and is converted to degrees (multiplied by 15).

reg2master.read_regions(filename)

Read and parse a DS9 region file.

Parameters

filenamestr

Path to the DS9 region file.

Returns

tuple of (str, list)

Coordinate type (‘fk5’, ‘image’, ‘physical’, or ‘unknown’) and list of region records. Each record is a list: [name, ra, dec, regtype, major, minor, theta, color].

Notes

Parses the following region types: circle, ellipse, box, annulus. Source names are extracted from text={} fields or auto-generated as ‘zzz001’, ‘zzz002’, etc. if not present.

reg2master.size2arcsec(word)

Convert a size string to arcseconds.

Parameters

wordstr

Size value with optional unit suffix (’’ for arcsec, ‘ for arcmin).

Returns

float

Size in arcseconds.

Notes

Recognizes:

  • " suffix - value is in arcseconds

  • ' suffix - value is in arcminutes (converted to arcsec)

  • No suffix - value is returned as-is (assumed arcseconds)

reg2master.steer(argv)

Parse command line arguments and execute conversion.

Parameters

argvlist of str

Command line arguments (typically sys.argv).

Returns

None

Calls doit() to perform the conversion.

reg2master.write_masterfile(masterfile, records, source='unknown', type='unknown')

Write a master table file from parsed region records.

Parameters

masterfilestr

Output filename for the master table.

recordslist

List of region records from read_regions().

sourcestr, optional

Source file identifier. Default is ‘unknown’.

typestr, optional

Coordinate type from region file. Default is ‘unknown’.

Returns

None

Writes table to disk in ascii.fixed_width_two_line format.

Notes

Output columns: Source_name, RA, Dec, RegType, Major, Minor, Theta, Color. Numeric columns are formatted with appropriate precision.