## Usage

This document describes the boolean arithmetic defined for region expressions.

## Boolean operations

When defining a region, several shapes can be combined using boolean operations. The boolean operators are (in order of precedence):

```  Symbol	Operator		Associativity
------	--------		-------------
!		not			right to left
&		and			left to right
^  		exclusive or		left to right
|  		inclusive or		left to right

```
For example, to create a mask consisting of a large circle with a smaller box removed, one can use the \fIand\fR and \fInot\fR operators:
```  CIRCLE(11,11,15) & !BOX(11,11,3,6)
```
and the resulting mask is:
```         1234567890123456789012345678901234567890
----------------------------------------
1:1111111111111111111111..................
2:1111111111111111111111..................
3:11111111111111111111111.................
4:111111111111111111111111................
5:111111111111111111111111................
6:1111111111111111111111111...............
7:1111111111111111111111111...............
8:1111111111111111111111111...............
9:111111111...1111111111111...............
10:111111111...1111111111111...............
11:111111111...1111111111111...............
12:111111111...1111111111111...............
13:111111111...1111111111111...............
14:111111111...1111111111111...............
15:1111111111111111111111111...............
16:1111111111111111111111111...............
17:111111111111111111111111................
18:111111111111111111111111................
19:11111111111111111111111.................
20:1111111111111111111111..................
21:1111111111111111111111..................
22:111111111111111111111...................
23:..11111111111111111.....................
24:...111111111111111......................
25:.....11111111111........................
26:........................................
27:........................................
28:........................................
29:........................................
30:........................................
31:........................................
32:........................................
33:........................................
34:........................................
35:........................................
36:........................................
37:........................................
38:........................................
39:........................................
40:........................................
```
A three-quarter circle can be defined as:
```  CIRCLE(20,20,10) & !PIE(20,20,270,360)
```
and looks as follows:
```
1234567890123456789012345678901234567890
----------------------------------------
1:........................................
2:........................................
3:........................................
4:........................................
5:........................................
6:........................................
7:........................................
8:........................................
9:........................................
10:........................................
11:...............111111111................
12:..............11111111111...............
13:............111111111111111.............
14:............111111111111111.............
15:...........11111111111111111............
16:..........1111111111111111111...........
17:..........1111111111111111111...........
18:..........1111111111111111111...........
19:..........1111111111111111111...........
20:..........1111111111111111111...........
21:..........1111111111....................
22:..........1111111111....................
23:..........1111111111....................
24:..........1111111111....................
25:...........111111111....................
26:............11111111....................
27:............11111111....................
28:..............111111....................
29:...............11111....................
30:........................................
31:........................................
32:........................................
33:........................................
34:........................................
35:........................................
36:........................................
37:........................................
38:........................................
39:........................................
40:........................................
```
Two non-intersecting ellipses can be made into the same region:
```  ELL(20,20,10,20,90) | ELL(1,1,20,10,0)
```
and looks as follows:
```         1234567890123456789012345678901234567890
----------------------------------------
1:11111111111111111111....................
2:11111111111111111111....................
3:11111111111111111111....................
4:11111111111111111111....................
5:1111111111111111111.....................
6:111111111111111111......................
7:1111111111111111........................
8:111111111111111.........................
9:111111111111............................
10:111111111...............................
11:...........11111111111111111............
12:........111111111111111111111111........
13:.....11111111111111111111111111111......
14:....11111111111111111111111111111111....
15:..11111111111111111111111111111111111...
16:.1111111111111111111111111111111111111..
17:111111111111111111111111111111111111111.
18:111111111111111111111111111111111111111.
19:111111111111111111111111111111111111111.
20:111111111111111111111111111111111111111.
21:111111111111111111111111111111111111111.
22:111111111111111111111111111111111111111.
23:111111111111111111111111111111111111111.
24:.1111111111111111111111111111111111111..
25:..11111111111111111111111111111111111...
26:...11111111111111111111111111111111.....
27:.....11111111111111111111111111111......
28:.......111111111111111111111111.........
29:...........11111111111111111............
30:........................................
31:........................................
32:........................................
33:........................................
34:........................................
35:........................................
36:........................................
37:........................................
38:........................................
39:........................................
40:........................................
```
You can use several boolean operations in a single region expression, to create arbitrarily complex regions. With the important exception below, you can apply the operators in any order, using parentheses if necessary to override the natural precedences of the operators.

NB: When a PANDA, an ANNULUS accelerator, or a PIE accelerator is combined with other shapes or filters in a boolean expression, please ensure that the PANDA or accelerator shape is specified last in the expression. Thus:

```  box(0,0,4,3,60) && panda(0,0,0,180,2,0,6,3)
box(0,0,4,3,60) && annulus(0,0,10,30,n=2)
box(0,0,4,3,60) && pie(0,0,10,20,30)
```
are all legal syntax, but:
```  panda(0,0,0,180,2,0,6,3) && box(0,0,4,3,60)
annulus(0,0,0,100,n=3) && box(0,0,4,3,60)
pie(0,0,10,20,30) && box(0,0,4,3,60)
```
are all illegal and will generate an error message.

NB: Using a panda shape is always much more efficient than explicitly specifying "pie & annulus", due to the ability of panda to place a limit on the number of pixels checked in the pie shape. If you are going to specify the intersection of pie and annulus, use panda instead.

Index to the Funtools Help Pages