Skip to the navigation links
Last modified: December 2009

URL: http://cxc-newtest.cfa.harvard.edu/ciao4.2/regparse.html
AHELP for CIAO 4.2

regParse

Context: region

Synopsis

Parse a region for use by the routines in the region library

Syntax

Region_Type regParse( String_Type RegionString )

Error Return Value: NULL

Description

Before a region can be used by the other routines in the region library - e.g. to calculate the area or to find out if a point lies inside or outside the region - it must be parsed. The regParse() routine does this parsing and returns a value, of type Region_Type, which represents this region and should be used when calling the other routines. A NULL value is returned if the region is not valid; for instance due to a syntax error or using a shape that is not understood by the CIAO region library.

The region module is not available by default; to use it in a S-Lang program, it must be loaded using the S-Lang require() function:

  require("region");

Format of RegionString

The input variable to regParse() should be a valid CIAO region string, such as

circle(100.23,50.54,23.421)

or

region(ds9.reg)

See "ahelp dmregions" for a description of the CIAO region syntax.

Example 1

slsh> require("region");
slsh> circle_var = regParse("circle(10,10,4)");
slsh> typeof( circle_var );
Region_Type
slsh> print( circle_var );
Region_Type
slsh> regPrintRegion( circle_var );
1 Circle(10.000000, 10.000000, 4.000000) (Pos: pixel, Size: pixel)
slsh> regRegionString( circle_var );
Circle(10,10,4)

In this example we have just parsed the region string

circle(10,10,4)

and stored the result in the S-Lang variable circle_var. This variable can then be used with other functions from the region library, as will be shown in the following examples.

Note that the region library must be made available before you can use the fucntions. This is achieved by the line

require("region")

which only needs to be called once per Slsh or Sherpa session, or slsh script.

The typeof() and print() calls show that the return value of the regParse() routine is a Region_Type variable. You can not do anything with this variable other than use it as an argument to other functions.

Example 2

slsh> r1 = regParse("circle(50,35,22)-rect(20,10,40,12");
slsh> r2 = regParse("region(src.reg)");

See "ahelp dmregions" for a description of the syntax of CIAO regions.

Example 3

slsh> reg = regParse("circle(10,10,4)");
slsh> area = regArea(reg);
slsh> vmessage( "The region area is %f", area );
The region area is 50.265482

In this example we used the regArea() call to calculate the area of the region. Please see the ahelp pages for the other functions in the regino library for further examples.

Example 4

If the file example.sl contains

  % load in the region library
  %
  require("region");

  % parse the region (checking for errors)
  %
  variable reg = regParse("circle(100,30,45)");
  if ( reg == NULL )
    error( "Unable to parse the region" );

  % what is the area of this region
  %
  vmessage( "The area of the region = %7.2f pixels", regArea(reg) );

then it can be run using slsh, which gives

  unix% slsh example.sl
  The area of the region = 6361.73 pixels

Bugs

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

See Also

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

Last modified: December 2009