Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: December 2013

URL: http://cxc.harvard.edu/chips/ahelp/add_region.html
AHELP for CIAO 4.6 ChIPS v1

add_region

Context: regions

Synopsis

Creates a region.

Syntax

add_region([id,] xvals, yvals, [,attributes])
add_region([id,] sides, xx, yy, radius [,attributes])

Polygons, ellipses, and boxes (rectangles) can also be created directly
from the GUI using the "Annotate" menu item.

Description

The function arguments.

Argument Description
id A ChipsId structure identifying the item.
xvals, yvals Arrays of x and y coordinates to create a region from (xvals[0],yvals[0]) to (xpos[n], yvals[n]); the current coordinate system is used if the "coordsys" attribute is not set. Regions are always closed, so the last point need not be the same as the first. Degenerate (self-intersecting) polygons are not supported.
sides The number of sides of the regular polygon.
xx, yy The location of the center of the regular polygon; the current coordinate system is used if the "coordsys" attribute is not set.
radius The distance from the center (xx,yy) of the regular polygon to the edge, using the same coordinate system as xx, yy.
attributes Configure object properties by giving an attribute string (a space-separated list of key=value pairs), list, dictionary, or a ChIPS object.

The add_region command creates a region whose attributes are specified by user preferences or in an attribute list. The new region becomes current by default; providing a ChipsId overrides the currency state.

Regions versus Lines

Regions are always closed, even if the last coordinate does not match the first one in the xvals,yvals arrays, can not be degenerate, and can be filled. To create an open set of lines, or one where the segments cross, use the add_line command.

Clipping

Regions displayed in data coordinates are clipped at the plot boundaries.

Customizing the Region

There are several attributes that control the region characteristics. The attributes can be set to the ChIPS defaults, values provided in the add_region command, or values from the user's preference file.

The attributes may also be modified with the set_region command at any time; see "ahelp set_region" and "ahelp setget" for more information.

Please see the section "Region Preferences and Attributes" below the examples for a list of the region preferences.

Example 1

chips> add_region(6,.5,.5,.4)

Add a hexagon region in the current coordinate system.

Example 2

chips> add_curve(x, y, dy)
chips> yl = y - dy
chips> yh = y + dy
chips> xr = np.append(x, x[::-1])
chips> yr = np.append(yl, yh[::-1])
chips> add_region(xr, yr, ['depth', 80])

In this example a region is created that encompases the error bounds of the data, which is first plotted as a curve. The yl and yh arrays contain the Y coordinates of the edge of the error region; we append the reversed yh range - the "[::-1]" NumPy slice - to yl to get the Y coordinates of the region. The X coordinates are appended together (reversing the second set) to create xr.

Example 3

chips> xc = [0.05, 0.95, 0.95, 0.05]
chips> yc = [0.95, 0.95, 0.9, 0.9]
chips> attrs = { 'coordsys': PLOT_NORM }
chips> attrs['fill.color'] = 'orange'
chips> attrs['edge.color'] = 'red'
chips> add_region(xc, yc, attrs)

An orange rectangle, with red edges, is drawn at the top of the plot.

Example 4

chips> add_region([.1,.5,.9], [.9,.2,.7], ["edge.color", "red",
"edge.style", "shortdash"])

Create region with a red, dashed edge, specifying the attribute values in a list.

Example 5

chips> reg = ChipsRegion()
chips> reg.fill.color = "cyan"
chips> reg.fill.style = chips_solid
chips> reg.opacity = 0.5
chips> reg.edge.color = "beige"
chips> add_region([40,70,70], [10,70,10], reg)

Populate the "reg" structure with the attribute values, then add a triangle with vertices at (40,10), (70,70), and (70,10)

Region Preferences and Attributes

The attributes associated with regions are given in the following table, where the "Set?" column refers to whether the attribute can be changed using the set_region() command. To change the region preference settings prepend "region." to the attribute name.

Attribute Description Options Default Set?
angle Angle, in degrees, at which the region is drawn -360.0 to 360.0 0.0 Yes
coordsys coordinate system for the region PIXEL, WINDOW_NORM, FRAME_NORM, PLOT_NORM, DATA see "ahelp coordsys" No
depth Integer value indicating region depth see the Depth section of "ahelp chipsopt" default Yes
edge.color region edge color name or hex; see the Color section of "ahelp chipsopt" green Yes
edge.style stipple pattern used to draw the region edges see the Line Style section of "ahelp chipsopt" chips_solid Yes
edge.thickness Thickness of the region edge 0.5 to 10.0; see the Thickness section of "ahelp chipsopt" 1 Yes
fill.color region fill color name or hex; see the Color section of "ahelp chipsopt" green Yes
fill.style Fill style for the region see the Fill Pattern section of "ahelp chipsopt" 0 (no fill) Yes
opacity Opacity of the region fill 0.0 to 1.0, inclusive, where 0 is fully transparent and 1 is fully opaque 0.5 Yes
stem stem used for region id An alpha-numeric character sequence that does not contain a space reg No

Using closed regions

When regions are given as a list of coordinates, the last point need not be the same as the first point. Since regions are always closed there is no difference in regions defined either way; that is

chips> add_region([0.1, 0.9, 0.9], [0.1, 0.1, 0.9])

and

chips> add_region([0.1, 0.9, 0.9, 0.1], [0.1, 0.1, 0.9, 0.1])

create the same region.

Changes in CIAO 4.6

The error message created when add_region is given a degenerate polygon has been improved.

Bugs

Transparency support and PostScript formats

The Postscript (PS and EPS) output formats do not support the alpha settings of images or the opacity settings of region or histograms. The attribute values are treated as 1 when the object are displayed in these formats.

See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.

See Also

chips
chips, chipsgui, chipsrc, show_gui
concepts
aspectratio, attributes, chipsid, chipsopt, colors, coordsys, currency, depthcontrol, entitycreation, preferences, setget
contrib
chips_regions
regions
current_region, delete_region, display_region, get_region, hide_region, move_region, set_region, shuffle_region
utilities
load_fill

Last modified: December 2013
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxcweb@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2014. All rights reserved.