region-old

Context: region

Synopsis

*DEPRECATED* Provides the Python interface to the CXC region library

Description

The interfaces described in this help file have been deprecated. CIAO 4.10 includes a new object based interface which should be used instead of these routines. This document is provided for legacy support.

The region module is the interface between the Python interpreter and the CXC region library. For more information on specific region shapes see "ahelp dmregions".

The region module is not available by default; to use it in a Python program, it must be loaded using the Python import function by saying one of:

from region import *
import region

Functions provided by the module

The following functions are provided by the module; use "ahelp <function>" to get a detailed description of a function:

Function	Description
regParse	Convert a string containing a region into a region value.
regInsideRegion	Is a point - or set of points - inside a region?
regArea	Calculate the area of a region.
regExtent	Returns the coordinates of the bounding box that encloses a region.
regRegionString	Returns a string representation of a region.
regPrintRegion	Displays the contents of a region.

Using the Region object

The region module defines a Region object which is created by the regParse() routine. The regRegionString() routine can be used to get a string representation of the region and the regPrintRegion() routine prints diagnostic information on its contents to the stdout channel.

Coordinate systems

Note that the region module does not have any intrinsic knowledge of WCS coordinates, so cannot be directly used to match pointed Chandra observations to specific regions. The dmcoords tool can be useful when converting between different Chandra coordinate systems.

Example

>>> from region import *
>>> circle = regParse("circle(10,10,4)")
>>> in_circle = regInsideRegion(circle, 10, 10)
>>> print(in_circle)
1
>>> print(regInsideRegion(circle, 5, 5))
0
>>> area = regArea(circle)
>>> print(area)
50.2654824574
>>> print(np.pi * 4 * 4 / area)
1.0
>>> print(regRegionString(circle))
Circle(10,10,4)
>>> regPrintRegion(circle)
1 Circle(10,10,4) (Flag_Coord: Unknown) (Flag_Radius: Unknown)

Changes in CIAO 4.8

The region library (C version) was re-written in CIAO 4.8, so that some routines may give different answers, in particular when handling self-intersecting (non-simple) polygons. As part of this work, the screen output of the regPrintRegion command has changed.

Bugs

See the bugs page for the region library on the CIAO website for an up-to-date listing of known bugs.

Refer to the CIAO bug pages for an up-to-date listing of known issues.