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

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

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.

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.

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.

&pr; from region import *
&pr; circle = regParse("circle(10,10,4)")
&pr; in_circle = regInsideRegion(circle, 10, 10)
&pr; print(in_circle)
1
&pr; print(regInsideRegion(circle, 5, 5))
0
&pr; area = regArea(circle)
&pr; print(area)
50.2654824574
&pr; print(np.pi * 4 * 4 / area)
1.0
&pr; print(regRegionString(circle))
Circle(10,10,4)
&pr; 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.

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

February 2018