add_region

Context: regions

Syntax

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

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

Description

ChipsId - an optional ChipsId structure containing values to modify the currency state for the command.
xvals, yvals - arrays of x and y coordinates to create a non-convex region from (xvals[0],yvals[0]) to (xpos[n], yvals[n]). 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 on a regular polygon (i.e. 3=triangle, 4=square, 5=pentagon, etc.)
xx,yy - the location of the center of the regular polygon; the current coordinate system is used if one is not specified.
radius - the distance from the center (xx,yy) of the regular polygon to the edge; the current coordinate system is used if one is not specified.
attributes - optional parameters which allow the user to configure properties though a structure, list, dictionary or attribute string.

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.

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_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 3

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

Changes in CIAO 4.5

Using closed regions

When regions are given as a list of coordinates, the last point can now be the same as the first point (in CIAO 4.4 this would cause the ChIPS server to crash). 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.

Creating polygons, ellipses, and boxes from the GUI

Polygons, ellipses, and boxes (rectangles) can now be added directly from the GUI, using either the "Annotate" menu item or the "Annotate" option brought up by using the Right-Mouse Button in the ChIPS window.

Coordinate system support

It is now possible to set the coordsys attribute of annotation objects - i.e. those created by ChipsLabel(), ChipsLine(), ChipsPoint(), ChipsRegion(), and ChipsColorBar() - to define the coordinate system used to create the object. So the following will add a label - of the current time - to the bottom-right corner of the frame.

chips> l = ChipsLabel()
chips> l.coordsys = FRAME_NORM
chips> l.halign = 1
chips> import time
chips> add_label(0.95, 0.05, time.asctime(), l)

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.