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 input variable to regParse() should be a valid
CIAO region string, such as
circle(100.23,50.54,23.421)
or
See 'ahelp dmregions' for a description of the CIAO
region syntax.
chips> require("region")
chips> circle_var = regParse("circle(10,10,4)")
chips> typeof( circle_var )
Region_Type
chips> print( circle_var )
Region_Type
chips> regPrintRegion( circle_var )
1 Circle(10.000000, 10.000000, 4.000000) (Pos: pixel, Size: pixel)
chips> regRegionSring( circle_var )
Circle(10,10,4)
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 ChIPS 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.
chips> r1 = regParse("circle(50,35,22)-rect(20,10,40,12")
chips> r2 = regParse("region(src.reg)")
See 'ahelp dmregions' for a description of the syntax
of CIAO regions.
chips> reg = regParse("circle(10,10,4)")
chips> area = regArea(reg)
chips> 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.
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
|
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}