regArea

Context: region

Synopsis

*DEPRECATED* Calculate the area enclosed by a region.

Syntax

regArea(region)
regArea(region, xmin, ymin, xmax, ymax, pixsize)

The routine returns a scalar floating-point value.

Description

The regArea routine returns the area inside a region. The simple form simply takes a CIAO region variable and returns the total area inside the region; the last 5 parameters are omitted. However, if the region is complex and needs to be 'pixelated' to compute the area you may want to use the second version.

The region module is not available by default; see "ahelp region" for information on loading the module.

How are the areas calculated?

For "simple" regions the area is calculated analytically. For more-complicated regions - such as when shapes overlap - the area is calculated numerically by counting how many pixels fall within the region. The default values are to loop over the bounding box of the region and consider each pixel individually. Greater accuracy can be achieved by calling the routine with the pixsize argument set to a value less than 1, although the routine will then take longer to run.

The xmin, ymin, xmax, and ymax arguments define the region over which the numerical calculation is performed. When the one-argument form of regArea() is called these limits default to the bounding box of the regions, if one exists, otherwise the range -DBL_MAX to DBL_MAX. An example of a region with no bounding box is

sector(250, 400, 20, 45)

The regExtent() routine can be used to find the bounding-box of a region.

Examples

Example 1

>>> from region import *
>>> r1 = regParse("circle(10,10,4)")
>>> a1 = regArea(r1)
>>> print("The area of the region is {0}".format(a1))
The area of the region is 50.2654824574

Here we use the simple version of the regArea() call to calculate the area of the region

circle(10,10,4)

Example 2

>>> shape1 = "rotbox(4096.5,4196.5,100,150,45)"
>>> shape2 = "annulus(4096.5,4196.5,40,50)"
>>> r1 = regParse(shape1)
>>> r2 = regParse(shape2)
>>> r3 = regParse(shape1 + "-" + shape2)
>>> a1 = regArea(r1)
>>> a2 = regArea(r2)
>>> a3 = regArea(r3)
>>> print("Areas = {0:8.2f} {1:8.2f} {2:8.2f}".format(a1, a2, a3))
Areas = 15000.00 2827.43 12190.00

Here we create three shapes: a rotated rectangle, an annulus, and the rotated rectangle minus the annulus. The area of these three regions is then calculated using the simple (1 argument) version of regArea().

Example 3

>>> a1c = regArea(r1, 4000, 4100, 4200, 4300, 0.1)
>>> a2c = regArea(r2, 4000, 4100, 4200, 4300, 0.1)
>>> a3c = regArea(r3, 4000, 4100, 4200, 4300, 0.1)
>>> print("Areas = {0:8.2f} {1:8.2f} {2:8.2f}".format(a1c, a2c, a3c))
Areas = 15000.00 2827.43 12168.19

Here we use the extended version of the regArea() call to improve the accuracy of the calculation. It does not make a differrence for the first two regions, but the area of the third region has changed by

12190 - 12168.19 = 21.81

pixels, a 0.2% difference.

Note that the choice of bounding box is important for this calculation. The ranges for both axes was picked since the rotated box should fit within it. The regExtent() routine can be used to automatically calculate the bounding box of a region, as follows:

>>> (x0,y0,x1,y1) = regExtent(r3)
>>> fmt = "x= {0:.2f} - {1:.2f} y= {2:.2f} - {3:.2f}"
>>> print(fmt.format(x0,x1,y0,y1))
x= 4008.11 - 4184.89 y= 4108.11 - 4284.89

If we had used a smaller region - i.e. one smalller than the region of interest - then regArea() would have returned the area of the region intersected with this region. For instance:

>>> print(regArea(r1,4000,4100,4200,4300,0.1))
15000.0
>>> print(regArea(r1,4000,4000,4200,4200,0.1))
8003.2400000000016
>>> print(regArea(r1,4050,4150,4100,4250,0.1))
4765.25

Changes in CIAO 4.8

The region library (C version) was re-written in CIAO 4.8, so that some routines may give different answers, in particular when handling self-intersecting (non-simple) polygons.

Bugs

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

Refer to the CIAO bug pages for an up-to-date listing of known issues.