Skip to the navigation links
Last modified: December 2009

AHELP for CIAO 4.2


Context: region


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


Region_Type regParse( String_Type RegionString )

Error Return Value: NULL


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:


Format of RegionString

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




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 );
slsh> print( circle_var );
slsh> regPrintRegion( circle_var );
1 Circle(10.000000, 10.000000, 4.000000) (Pos: pixel, Size: pixel)
slsh> regRegionString( circle_var );

In this example we have just parsed the region string


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


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 contains

  % load in the region library

  % 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
  The area of the region = 6361.73 pixels


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

See Also

regarea, regextent, reginsideregion, regparse, regprintregion, regregionstring

Last modified: December 2009