*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
Functions provided by the module
The following functions are provided by the module; use "ahelp <function>" to get a detailed description of a function:
|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.
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.
>>> 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.
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.