Last modified: February 2018

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/region_old.html
AHELP for CIAO 4.16

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.

See Also

region
regarea, regextent, reginsideregion, region, regparse, regprintregion, regregionstring