diff options
Diffstat (limited to 'funtools/doc/pod/regalgebra.pod')
| -rw-r--r-- | funtools/doc/pod/regalgebra.pod | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/funtools/doc/pod/regalgebra.pod b/funtools/doc/pod/regalgebra.pod new file mode 100644 index 0000000..4c6da88 --- /dev/null +++ b/funtools/doc/pod/regalgebra.pod @@ -0,0 +1,286 @@ +=pod + +=head1 NAME + + + +B<RegAlgebra: Boolean Algebra on Spatial Regions> + + + +=head1 SYNOPSIS + + + + + +This document describes the boolean arithmetic defined for +region expressions. + + + +=head1 DESCRIPTION + + + + + +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 B<and> and B<not> +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: 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. + + +As described in "help regreometry", the B<PIE> slice goes to the +edge of the field. To limit its scope, B<PIE> usually is is +combined with other shapes, such as circles and annuli, using boolean +operations. In this context, it is worth noting that that there is a +difference between B<-PIE> and B<&!PIE>. The former is a +global exclude of all pixels in the B<PIE> slice, while the latter +is a local excludes of pixels affecting only the region(s) with which +the B<PIE> is combined. For example, the following region uses +B<&!PIE> as a local exclude of a single circle. Two other circles +are also defined and are unaffected by the local exclude: + + + CIRCLE(1,8,1) + CIRCLE(8,8,7)&!PIE(8,8,60,120)&!PIE(8,8,240,300) + CIRCLE(15,8,2) + + 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 + - - - - - - - - - - - - - - - + 15: . . . . . . . . . . . . . . . + 14: . . . . 2 2 2 2 2 2 2 . . . . + 13: . . . 2 2 2 2 2 2 2 2 2 . . . + 12: . . 2 2 2 2 2 2 2 2 2 2 2 . . + 11: . . 2 2 2 2 2 2 2 2 2 2 2 . . + 10: . . . . 2 2 2 2 2 2 2 . . . . + 9: . . . . . . 2 2 2 . . . . 3 3 + 8: 1 . . . . . . . . . . . . 3 3 + 7: . . . . . . 2 2 2 . . . . 3 3 + 6: . . . . 2 2 2 2 2 2 2 . . . . + 5: . . 2 2 2 2 2 2 2 2 2 2 2 . . + 4: . . 2 2 2 2 2 2 2 2 2 2 2 . . + 3: . . . 2 2 2 2 2 2 2 2 2 . . . + 2: . . . . 2 2 2 2 2 2 2 . . . . + 1: . . . . . . . . . . . . . . . + + +Note that the two other regions are not affected by the B<&!PIE>, +which only affects the circle with which it is combined. + + +On the other hand, a B<-PIE> is an global exclude that does +affect other regions with which it overlaps: + + + CIRCLE(1,8,1) + CIRCLE(8,8,7) + -PIE(8,8,60,120) + -PIE(8,8,240,300) + CIRCLE(15,8,2) + + 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 + - - - - - - - - - - - - - - - + 15: . . . . . . . . . . . . . . . + 14: . . . . 2 2 2 2 2 2 2 . . . . + 13: . . . 2 2 2 2 2 2 2 2 2 . . . + 12: . . 2 2 2 2 2 2 2 2 2 2 2 . . + 11: . . 2 2 2 2 2 2 2 2 2 2 2 . . + 10: . . . . 2 2 2 2 2 2 2 . . . . + 9: . . . . . . 2 2 2 . . . . . . + 8: . . . . . . . . . . . . . . . + 7: . . . . . . 2 2 2 . . . . . . + 6: . . . . 2 2 2 2 2 2 2 . . . . + 5: . . 2 2 2 2 2 2 2 2 2 2 2 . . + 4: . . 2 2 2 2 2 2 2 2 2 2 2 . . + 3: . . . 2 2 2 2 2 2 2 2 2 . . . + 2: . . . . 2 2 2 2 2 2 2 . . . . + 1: . . . . . . . . . . . . . . . + + +The two smaller circles are entirely contained within the two exclude +B<PIE> slices and therefore are excluded from the region. + + + +=head1 SEE ALSO + + + +See funtools(n) for a list of Funtools help pages + + + +=cut |