Provided by: libfuntools-dev_1.4.8-1.1build2_amd64 bug

NAME

       RegGeometry - Geometric Shapes in Spatial Region Filtering

SYNOPSIS

       This document describes the geometry of regions available for spatial filtering in
       IRAF/PROS analysis.

DESCRIPTION

       Geometric shapes

       Several   geometric shapes are  used to   describe  regions. The valid shapes are:

         shape:        arguments:
         -----         ----------------------------------------
         ANNULUS       xcenter ycenter inner_radius outer_radius
         BOX           xcenter ycenter xwidth yheight (angle)
         CIRCLE        xcenter ycenter radius
         ELLIPSE       xcenter ycenter xwidth yheight (angle)
         FIELD         none
         LINE          x1 y1 x2 y2
         PIE           xcenter ycenter angle1 angle2
         POINT         x1 y1
         POLYGON       x1 y1 x2 y2 ... xn yn

       All arguments are real values; integer values are automatically converted to real where
       necessary.  All angles are in degrees and specify angles that run counter-clockwise from
       the positive y-axis.

       Shapes can be specified using "command" syntax:

         [shape] arg1 arg2 ...

       or using "routine" syntax:

         [shape](arg1, arg2, ...)

       or by any combination of the these. (Of course, the parentheses must balance and there
       cannot be more commas than necessary.) The shape keywords are case-insensitive.
       Furthermore, any shape can be specified by a three-character unique abbreviation.  For
       example, one can specify three circular regions as:

         "foo.fits[CIRCLE 512 512 50;CIR(128 128, 10);cir(650,650,20)]"

       (Quotes generally are required to protect the region descriptor from being processed by
       the Unix shell.)

       The  annulus    shape  specifies  annuli, centered  at  xcenter, ycenter, with inner and
       outer radii (r1, r2). For example,

         ANNULUS 25 25 5 10

       specifies an annulus centered at 25.0 25.0 with an inner radius of 5.0 and an outer radius
       of 10. Assuming (as will be done for all examples in this document, unless otherwise
       noted) this shape is used in a mask of size 40x40, it will look like this:

               1234567890123456789012345678901234567890
               ----------------------------------------
               40:........................................
               39:........................................
               38:........................................
               37:........................................
               36:........................................
               35:........................................
               34:....................111111111...........
               33:...................11111111111..........
               32:.................111111111111111........
               31:.................111111111111111........
               30:................11111111111111111.......
               29:...............1111111.....1111111......
               28:...............111111.......111111......
               27:...............11111.........11111......
               26:...............11111.........11111......
               25:...............11111.........11111......
               24:...............11111.........11111......
               23:...............11111.........11111......
               22:...............111111.......111111......
               21:...............1111111.....1111111......
               20:................11111111111111111.......
               19:.................111111111111111........
               18:.................111111111111111........
               17:...................11111111111..........
               16:....................111111111...........
               15:........................................
               14:........................................
               13:........................................
               12:........................................
               11:........................................
               10:........................................
               9:........................................
               8:........................................
               7:........................................
               6:........................................
               5:........................................
               4:........................................
               3:........................................
               2:........................................
               1:........................................

       The box shape specifies an orthogonally oriented box, centered at xcenter, ycenter, of
       size xwidth, yheight. It requires four arguments and accepts an optional fifth argument to
       specify a rotation angle.  When the rotation angle is specified (in degrees), the box is
       rotated by an angle that runs counter-clockwise from the positive y-axis.

       The box shape specifies a rotated box, centered at xcenter, ycenter, of size xwidth,
       yheight. The box is rotated by an angle specified in degrees that runs counter-clockwise
       from the positive y-axis.  If the angle argument is omitted, it defaults to 0.

       The circle shape specifies a circle, centered at xcenter, ycenter, of radius r.  It
       requires three arguments.

       The ellipse shape specifies an ellipse, centered at xcenter, ycenter, with y-axis width a
       and the y-axis length b defined such that:

         x**2/a**2 + y**2/b**2 = 1

       Note that a can be less than, equal to, or greater than b. The ellipse is rotated the
       specified number of degrees.  The rotation is done according to astronomical convention,
       counter-clockwise from the positive y-axis.  An ellipse defined by:

         ELLIPSE 20 20 5 10 45

       will look like this:

                1234567890123456789012345678901234567890
                ----------------------------------------
             40:........................................
             39:........................................
             38:........................................
             37:........................................
             36:........................................
             35:........................................
             34:........................................
             33:........................................
             32:........................................
             31:........................................
             30:........................................
             29:........................................
             28:........................................
             27:............111111......................
             26:............11111111....................
             25:............111111111...................
             24:............11111111111.................
             23:............111111111111................
             22:............111111111111................
             21:.............111111111111...............
             20:.............1111111111111..............
             19:..............111111111111..............
             18:...............111111111111.............
             17:...............111111111111.............
             16:................11111111111.............
             15:..................111111111.............
             14:...................11111111.............
             13:.....................111111.............
             12:........................................
             11:........................................
             10:........................................
              9:........................................
              8:........................................
              7:........................................
              6:........................................
              5:........................................
              4:........................................
              3:........................................
              2:........................................
              1:........................................

       The field shape specifies the entire field as a region.  It is not usually specified
       explicitly, but is used implicitly in the case where no regions are specified, that is, in
       cases where either a null string or some abbreviation of the string "none" is input.
       Field takes no arguments.

       The pie shape specifies an angular wedge of the entire field, centered at xcenter,
       ycenter.  The wedge runs between the two specified angles.  The angles are given in
       degrees, running counter-clockwise from the positive x-axis. For example,

         PIE 20 20 90 180

       defines a region from 90 degrees to 180 degrees, i.e., quadrant 2 of the Cartesian plane.
       The display of such a region looks like this:

               1234567890123456789012345678901234567890
               ----------------------------------------
               40:11111111111111111111....................
               39:11111111111111111111....................
               38:11111111111111111111....................
               37:11111111111111111111....................
               36:11111111111111111111....................
               35:11111111111111111111....................
               34:11111111111111111111....................
               33:11111111111111111111....................
               32:11111111111111111111....................
               31:11111111111111111111....................
               30:11111111111111111111....................
               29:11111111111111111111....................
               28:11111111111111111111....................
               27:11111111111111111111....................
               26:11111111111111111111....................
               25:11111111111111111111....................
               24:11111111111111111111....................
               23:11111111111111111111....................
               22:11111111111111111111....................
               21:11111111111111111111....................
               20:........................................
               19:........................................
               18:........................................
               17:........................................
               16:........................................
               15:........................................
               14:........................................
               13:........................................
               12:........................................
               11:........................................
               10:........................................
               9:........................................
               8:........................................
               7:........................................
               6:........................................
               5:........................................
               4:........................................
               3:........................................
               2:........................................
               1:........................................

       The pie slice specified is always a counter-clockwise sweep between the angles, starting
       at the first angle and ending at the second.  Thus:

         PIE 10 15 30 60

       describes a 30 degree sweep from 2 o'clock to 1 o'clock, while:

         PIE 10 15 60 30

       describes a 330 degree counter-clockwise sweep from 1 o'clock to 2 o'clock passing through
       12 o'clock (0 degrees). Note in both of these examples that the center of the slice can be
       anywhere on the plane.  The second mask looks like this:

               1234567890123456789012345678901234567890
               ----------------------------------------
               40:111111111111111111111111................
               39:11111111111111111111111.................
               38:11111111111111111111111.................
               37:1111111111111111111111..................
               36:1111111111111111111111..................
               35:111111111111111111111...................
               34:11111111111111111111....................
               33:11111111111111111111....................
               32:1111111111111111111....................1
               31:1111111111111111111..................111
               30:111111111111111111.................11111
               29:111111111111111111................111111
               28:11111111111111111...............11111111
               27:1111111111111111..............1111111111
               26:1111111111111111.............11111111111
               25:111111111111111............1111111111111
               24:111111111111111..........111111111111111
               23:11111111111111.........11111111111111111
               22:11111111111111........111111111111111111
               21:1111111111111.......11111111111111111111
               20:111111111111......1111111111111111111111
               19:111111111111....111111111111111111111111
               18:11111111111....1111111111111111111111111
               17:11111111111..111111111111111111111111111
               16:1111111111.11111111111111111111111111111
               15:1111111111111111111111111111111111111111
               14:1111111111111111111111111111111111111111
               13:1111111111111111111111111111111111111111
               12:1111111111111111111111111111111111111111
               11:1111111111111111111111111111111111111111
               10:1111111111111111111111111111111111111111
               9:1111111111111111111111111111111111111111
               8:1111111111111111111111111111111111111111
               7:1111111111111111111111111111111111111111
               6:1111111111111111111111111111111111111111
               5:1111111111111111111111111111111111111111
               4:1111111111111111111111111111111111111111
               3:1111111111111111111111111111111111111111
               2:1111111111111111111111111111111111111111
               1:1111111111111111111111111111111111111111

       The pie slice goes to the edge of the field. To limit its scope, pie usually is is
       combined with other shapes, such as circles and annuli, using boolean operations. (See
       below and in "help regalgebra").

       Pie Performance Notes:

       Pie region processing time is proportional to the size of the image, and not the size of
       the region. This is because the pie shape is the only infinite length shape, and we
       essentially must check all y rows for inclusion (unlike other regions, where the y limits
       can be calculated beforehand). Thus, pie can run very slowly on large images.  In
       particular, it will run MUCH more slowly than the panda shape in image-based region
       operations (such as funcnts). We recommend use of panda over pie where ever possible.

       If you must use pie, always try to put it last in a boolean && expression.  The reason for
       this is that the filter code is optimized to exit as soon as the result is know. Since pie
       is the slowest region, it is better to avoid executing it if another region can decide the
       result. Consider, for example, the difference in time required to process a Chandra ACIS
       file when a pie and circle are combined in two different orders:

         time ./funcnts nacis.fits "circle 4096 4096 100 && pie 4096 4096 10 78"
       2.87u 0.38s 0:35.08 9.2%

         time ./funcnts nacis.fits "pie 4096 4096 10 78 && circle 4096 4096 100 "
       89.73u 0.36s 1:03.50 141.8%

       Black-magic performance note:

       Panda region processing uses a quick test pie region instead of the normal pie region when
       combining its annulus and pie shapes. This qtpie shape differs from the normal pie in that
       it utilizes the y limits from the previous region with which it is combined. In a panda
       shape, which is a series of annuli combined with pies, the processing time is thus reduced
       to that of the annuli.

       You can use the qtpie shape instead of pie in cases where you are combining pie with
       another shape using the && operator. This will cause the pie limits to be set using limits
       from the other shape, and will speed up the processing considerably.  For example, the
       above execution of funcnts can be improved considerably using this technique:

         time ./funcnts nacis.fits "circle 4096 4096 100 && qtpie 4096 4096 10 78"
       4.66u 0.33s 0:05.87 85.0%

       We emphasize that this is a quasi-documented feature and might change in the future. The
       qtpie shape is not recognized by ds9 or other programs.

       The line shape allows single pixels in a line between (x1,y1) and (x2,y2) to be included
       or excluded. For example:

         LINE (5,6, 24,25)

       displays as:

                1234567890123456789012345678901234567890
                ----------------------------------------
             40:........................................
             39:........................................
             38:........................................
             37:........................................
             36:........................................
             35:........................................
             34:........................................
             33:........................................
             32:........................................
             31:........................................
             30:........................................
             29:........................................
             28:........................................
             27:........................................
             26:........................................
             25:.......................1................
             24:......................1.................
             23:.....................1..................
             22:....................1...................
             21:...................1....................
             20:..................1.....................
             19:.................1......................
             18:................1.......................
             17:...............1........................
             16:..............1.........................
             15:.............1..........................
             14:............1...........................
             13:...........1............................
             12:..........1.............................
             11:.........1..............................
             10:........1...............................
              9:.......1................................
              8:......1.................................
              7:.....1..................................
              6:....1...................................
              5:........................................
              4:........................................
              3:........................................
              2:........................................
              1:........................................

       The point shape allows single pixels to be included or excluded.  Although the (x,y)
       values are real numbers, they are truncated to integer and the corresponding pixel is
       included or excluded, as specified.

       Several points can be put in one region declaration; unlike the original IRAF
       implementation, each now is given a different region mask value.  This makes it easier,
       for example, for funcnts to determine the number of photons in the individual pixels. For
       example,

         POINT (5,6,  10,11,  20,20,  35,30)

       will give the different region mask values to all four points, as shown below:

                1234567890123456789012345678901234567890
                ----------------------------------------
             40:........................................
             39:........................................
             38:........................................
             37:........................................
             36:........................................
             35:........................................
             34:........................................
             33:........................................
             32:........................................
             31:........................................
             30:..................................4.....
             29:........................................
             28:........................................
             27:........................................
             26:........................................
             25:........................................
             24:........................................
             23:........................................
             22:........................................
             21:........................................
             20:...................3....................
             19:........................................
             18:........................................
             17:........................................
             16:........................................
             15:........................................
             14:........................................
             13:........................................
             12:........................................
             11:.........2..............................
             10:........................................
              9:........................................
              8:........................................
              7:........................................
              6:....1...................................
              5:........................................
              4:........................................
              3:........................................
              2:........................................
              1:........................................

       The polygon shape specifies a polygon with vertices (x1, y1) ... (xn, yn). The polygon is
       closed automatically: one should not specify the last vertex to be the same as the first.
       Any number of vertices are allowed.  For example, the following polygon defines a right
       triangle as shown below:

         POLYGON (10,10,  10,30,  30,30)

       looks like this:

                1234567890123456789012345678901234567890
                ----------------------------------------
             40:........................................
             39:........................................
             38:........................................
             37:........................................
             36:........................................
             35:........................................
             34:........................................
             33:........................................
             32:........................................
             31:........................................
             30:..........11111111111111111111..........
             29:..........1111111111111111111...........
             28:..........111111111111111111............
             27:..........11111111111111111.............
             26:..........1111111111111111..............
             25:..........111111111111111...............
             24:..........11111111111111................
             23:..........1111111111111.................
             22:..........111111111111..................
             21:..........11111111111...................
             20:..........1111111111....................
             19:..........111111111.....................
             18:..........11111111......................
             17:..........1111111.......................
             16:..........111111........................
             15:..........11111.........................
             14:..........1111..........................
             13:..........111...........................
             12:..........11............................
             11:..........1.............................
             10:........................................
              9:........................................
              8:........................................
              7:........................................
              6:........................................
              5:........................................
              4:........................................
              3:........................................
              2:........................................
              1:........................................

       Note that polygons can get twisted upon themselves if edge lines cross.  Thus:

         POL (10,10,  20,20,  20,10,  10,20)

       will produce an area which is two triangles, like butterfly wings, as shown below:

                1234567890123456789012345678901234567890
                ----------------------------------------
             40:........................................
             39:........................................
             38:........................................
             37:........................................
             36:........................................
             35:........................................
             34:........................................
             33:........................................
             32:........................................
             31:........................................
             30:........................................
             29:........................................
             28:........................................
             27:........................................
             26:........................................
             25:........................................
             24:........................................
             23:........................................
             22:........................................
             21:........................................
             20:........................................
             19:..........1........1....................
             18:..........11......11....................
             17:..........111....111....................
             16:..........1111..1111....................
             15:..........1111111111....................
             14:..........1111..1111....................
             13:..........111....111....................
             12:..........11......11....................
             11:..........1........1....................
             10:........................................
              9:........................................
              8:........................................
              7:........................................
              6:........................................
              5:........................................
              4:........................................
              3:........................................
              2:........................................
              1:........................................

       The following are combinations of pie with different shapes (called "panda" for "Pie AND
       Annulus") allow for easy specification of radial sections:

         shape:   arguments:
         -----    ---------
         PANDA    xcen ycen ang1 ang2 nang irad orad nrad   # circular
         CPANDA   xcen ycen ang1 ang2 nang irad orad nrad   # circular
         BPANDA   xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # box
         EPANDA   xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # ellipse

       The panda (Pies AND Annuli) shape can be used to create combinations of pie and annuli
       markers. It is analogous to a Cartesian product on those shapes, i.e., the result is
       several shapes generated by performing a boolean AND between pies and annuli. Thus, the
       panda and cpanda specify combinations of annulus and circle with pie, respectively and
       give identical results. The bpanda combines box and pie, while epanda combines ellipse and
       pie.

       Consider the example shown below:

         PANDA(20,20, 0,360,3, 0,15,4)

       Here, 3 pie slices centered at 20, 20 are combined with 4 annuli, also centered at 20, 20.
       The result is a mask with 12 regions (displayed in base 16 to save characters):

               1234567890123456789012345678901234567890
               ----------------------------------------
               40:........................................
               39:........................................
               38:........................................
               37:........................................
               36:........................................
               35:........................................
               34:..............44444444444...............
               33:............444444444444444.............
               32:...........88444444444444444............
               31:.........888844443333344444444..........
               30:........88888833333333333444444.........
               29:........88888733333333333344444.........
               28:.......8888877733333333333344444........
               27:......888887777332222233333344444.......
               26:......888877777622222222333334444.......
               25:.....88887777766622222222333334444......
               24:.....88887777666622222222233334444......
               23:.....88887777666651111222233334444......
               22:.....88877776666551111122223333444......
               21:.....88877776666555111122223333444......
               20:.....888777766665559999aaaabbbbccc......
               19:.....888777766665559999aaaabbbbccc......
               18:.....888777766665599999aaaabbbbccc......
               17:.....88887777666659999aaaabbbbcccc......
               16:.....888877776666aaaaaaaaabbbbcccc......
               15:.....888877777666aaaaaaaabbbbbcccc......
               14:......8888777776aaaaaaaabbbbbcccc.......
               13:......888887777bbaaaaabbbbbbccccc.......
               12:.......88888777bbbbbbbbbbbbccccc........
               11:........888887bbbbbbbbbbbbccccc.........
               10:........888888bbbbbbbbbbbcccccc.........
               9:.........8888ccccbbbbbcccccccc..........
               8:...........88ccccccccccccccc............
               7:............ccccccccccccccc.............
               6:..............ccccccccccc...............
               5:........................................
               4:........................................
               3:........................................
               2:........................................
               1:........................................

       Several regions with different mask values can be combined in the same mask.  This
       supports comparing data from the different regions.  (For information on how to combine
       different shapes into a single region, see "help regalgebra".)  For example, consider the
       following set of regions:

         ANNULUS 25 25 5 10
         ELLIPSE 20 20 5 10 315
         BOX 15 15 5 10

       The resulting mask will look as follows:

                1234567890123456789012345678901234567890
                ----------------------------------------
             40:........................................
             39:........................................
             38:........................................
             37:........................................
             36:........................................
             35:........................................
             34:....................111111111...........
             33:...................11111111111..........
             32:.................111111111111111........
             31:.................111111111111111........
             30:................11111111111111111.......
             29:...............1111111.....1111111......
             28:...............111111.......111111......
             27:...............11111.222222..11111......
             26:...............111112222222..11111......
             25:...............111112222222..11111......
             24:...............111112222222..11111......
             23:...............111112222222..11111......
             22:...............111111222222.111111......
             21:..............211111112222.1111111......
             20:............322211111111111111111.......
             19:............32222111111111111111........
             18:............22222111111111111111........
             17:............222222211111111111..........
             16:............22222222111111111...........
             15:............222222222...................
             14:............22222222....................
             13:............222222......................
             12:............33333.......................
             11:............33333.......................
             10:........................................
              9:........................................
              8:........................................
              7:........................................
              6:........................................
              5:........................................
              4:........................................
              3:........................................
              2:........................................
              1:........................................

       Note that when a pixel is in 2 or more regions, it is arbitrarily assigned to a one of the
       regions in question (often based on how a give C compiler optimizes boolean expressions).

       Region accelerators

       Two types of \fBaccelerators, to simplify region specification, are provided as natural
       extensions to the ways shapes are described.  These are: extended lists of parameters,
       specifying multiple regions, valid for annulus, box, circle, ellipse, pie, and points; and
       n=, valid for annulus, box, circle, ellipse, and pie (not point).  In both cases, one
       specification is used to define several different regions, that is, to define shapes with
       different mask values in the region mask.

       The following regions accept accelerator syntax:

         shape      arguments
         -----      ------------------------------------------
         ANNULUS    xcenter ycenter radius1 radius2 ... radiusn
         ANNULUS    xcenter ycenter inner_radius outer_radius n=[number]
         BOX        xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle)
         BOX        xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle)
         CIRCLE     xcenter ycenter r1 r2 ... rn              # same as annulus
         CIRCLE     xcenter ycenter rinner router n=[number]  # same as annulus
         ELLIPSE    xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle)
         ELLIPSE    xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle)
         PIE        xcenter ycenter angle1 angle2 (angle3) (angle4) (angle5) ...
         PIE        xcenter ycenter angle1 angle2 (n=[number])
         POINT      x1 y1 x2 y2 ... xn yn

       Note that the circle accelerators are simply aliases for the annulus accelerators.

       For example, several annuli at the same center can be specified in one region expression
       by specifying more than two radii.  If N radii are specified, then N-1 annuli result, with
       the outer radius of each preceding annulus being the inner radius of the succeeding
       annulus.  Each annulus is considered a separate region, and is given a separate mask
       value. For example,

         ANNULUS 20 20 0 2 5 10 15 20

       specifies five different annuli centered at 20 20, and is equivalent to:

         ANNULUS 20.0 20.0  0  2
         ANNULUS 20.0 20.0  2  5
         ANNULUS 20.0 20.0  5 10
         ANNULUS 20.0 20.0 10 15
         ANNULUS 20.0 20.0 15 20

       The mask is shown below:

                1234567890123456789012345678901234567890
                ----------------------------------------
             40:........................................
             39:.............5555555555555..............
             38:...........55555555555555555............
             37:.........555555555555555555555..........
             36:........55555555555555555555555.........
             35:......555555555555555555555555555.......
             34:.....55555555544444444444555555555......
             33:....5555555544444444444444455555555.....
             32:....5555555444444444444444445555555.....
             31:...555555444444444444444444444555555....
             30:..55555544444444444444444444444555555...
             29:..55555544444443333333334444444555555...
             28:.5555554444444333333333334444444555555..
             27:.5555544444433333333333333344444455555..
             26:555555444444333333333333333444444555555.
             25:555554444443333333333333333344444455555.
             24:555554444433333332222233333334444455555.
             23:555554444433333322222223333334444455555.
             22:555554444433333222222222333334444455555.
             21:555554444433333222111222333334444455555.
             20:555554444433333222111222333334444455555.
             19:555554444433333222111222333334444455555.
             18:555554444433333222222222333334444455555.
             17:555554444433333322222223333334444455555.
             16:555554444433333332222233333334444455555.
             15:555554444443333333333333333344444455555.
             14:555555444444333333333333333444444555555.
             13:.5555544444433333333333333344444455555..
             12:.5555554444444333333333334444444555555..
             11:..55555544444443333333334444444555555...
             10:..55555544444444444444444444444555555...
              9:...555555444444444444444444444555555....
              8:....5555555444444444444444445555555.....
              7:....5555555544444444444444455555555.....
              6:.....55555555544444444444555555555......
              5:......555555555555555555555555555.......
              4:........55555555555555555555555.........
              3:.........555555555555555555555..........
              2:...........55555555555555555............
              1:.............5555555555555..............

       For boxes and ellipses, if an odd number of arguments is specified, then the last argument
       is assumed to be an angle. Otherwise, the angle is assumed to be zero. For example:

         ellipse 20 20 3 5 6 10 9 15 12 20 45

       specifies an 3 ellipses at a 45 degree angle:

               1234567890123456789012345678901234567890
               ----------------------------------------
               40:........................................
               39:........................................
               38:........................................
               37:........................................
               36:........33333333........................
               35:......333333333333......................
               34:.....3333333333333333...................
               33:....333333333333333333..................
               32:....33333332222233333333................
               31:...3333332222222222333333...............
               30:...33333222222222222233333..............
               29:...333332222222222222223333.............
               28:...3333222222211112222223333............
               27:...33332222211111111222223333...........
               26:...333322222111111111122223333..........
               25:...3333222211111111111122223333.........
               24:....3332222111111..1111122223333........
               23:....333322211111.....11112222333........
               22:....33332222111.......11112223333.......
               21:.....33322221111.......11122223333......
               20:.....33332221111.......11112223333......
               19:.....33332222111.......11112222333......
               18:......33332221111.......11122223333.....
               17:.......33322221111.....111112223333.....
               16:.......3333222211111..1111112222333.....
               15:........3333222211111111111122223333....
               14:.........333322221111111111222223333....
               13:..........33332222211111111222223333....
               12:...........3333222222111122222223333....
               11:............333322222222222222233333....
               10:.............33333222222222222233333....
               9:..............3333332222222222333333....
               8:...............33333333222223333333.....
               7:.................333333333333333333.....
               6:..................3333333333333333......
               5:.....................333333333333.......
               4:.......................33333333.........
               3:........................................
               2:........................................
               1:........................................

       Note in the above example that the lower limit is not part of the region for boxes,
       circles, and ellipses. This makes circles and annuli equivalent, i.e.:

         circle  20 20 5 10 15 20
         annulus 20 20 5 10 15 20

       both give the following region mask:

               1234567890123456789012345678901234567890
               ----------------------------------------
               40:........................................
               39:.............3333333333333..............
               38:...........33333333333333333............
               37:.........333333333333333333333..........
               36:........33333333333333333333333.........
               35:......333333333333333333333333333.......
               34:.....33333333322222222222333333333......
               33:....3333333322222222222222233333333.....
               32:....3333333222222222222222223333333.....
               31:...333333222222222222222222222333333....
               30:..33333322222222222222222222222333333...
               29:..33333322222221111111112222222333333...
               28:.3333332222222111111111112222222333333..
               27:.3333322222211111111111111122222233333..
               26:333333222222111111111111111222222333333.
               25:333332222221111111111111111122222233333.
               24:33333222221111111.....11111112222233333.
               23:3333322222111111.......1111112222233333.
               22:333332222211111.........111112222233333.
               21:333332222211111.........111112222233333.
               20:333332222211111.........111112222233333.
               19:333332222211111.........111112222233333.
               18:333332222211111.........111112222233333.
               17:3333322222111111.......1111112222233333.
               16:33333222221111111.....11111112222233333.
               15:333332222221111111111111111122222233333.
               14:333333222222111111111111111222222333333.
               13:.3333322222211111111111111122222233333..
               12:.3333332222222111111111112222222333333..
               11:..33333322222221111111112222222333333...
               10:..33333322222222222222222222222333333...
               9:...333333222222222222222222222333333....
               8:....3333333222222222222222223333333.....
               7:....3333333322222222222222233333333.....
               6:.....33333333322222222222333333333......
               5:......333333333333333333333333333.......
               4:........33333333333333333333333.........
               3:.........333333333333333333333..........
               2:...........33333333333333333............
               1:.............3333333333333..............

       As a final example, specifying several angles in one pie slice expression is equivalent to
       specifying several separate slices with the same center.  As with the annulus, if N angles
       are specified, then N-1 slices result, with the ending angle of each preceding slice being
       the starting angle of the succeeding slice.  Each slice is considered a separate region,
       and is given a separate mask value. For example,

         PIE 12 12 315 45 115 270

       specifies three regions as shown below:

               1234567890123456789012345678901234567890
               ----------------------------------------
               40:2222222222222222222222222222222222222222
               39:2222222222222222222222222222222222222221
               38:2222222222222222222222222222222222222211
               37:2222222222222222222222222222222222222111
               36:2222222222222222222222222222222222221111
               35:3222222222222222222222222222222222211111
               34:3222222222222222222222222222222222111111
               33:3322222222222222222222222222222221111111
               32:3322222222222222222222222222222211111111
               31:3332222222222222222222222222222111111111
               30:3332222222222222222222222222221111111111
               29:3333222222222222222222222222211111111111
               28:3333222222222222222222222222111111111111
               27:3333322222222222222222222221111111111111
               26:3333322222222222222222222211111111111111
               25:3333322222222222222222222111111111111111
               24:3333332222222222222222221111111111111111
               23:3333332222222222222222211111111111111111
               22:3333333222222222222222111111111111111111
               21:3333333222222222222221111111111111111111
               20:3333333322222222222211111111111111111111
               19:3333333322222222222111111111111111111111
               18:3333333332222222221111111111111111111111
               17:3333333332222222211111111111111111111111
               16:3333333333222222111111111111111111111111
               15:3333333333222221111111111111111111111111
               14:3333333333322211111111111111111111111111
               13:3333333333322111111111111111111111111111
               12:33333333333.1111111111111111111111111111
               11:3333333333331111111111111111111111111111
               10:333333333333.111111111111111111111111111
               9:333333333333..11111111111111111111111111
               8:333333333333...1111111111111111111111111
               7:333333333333....111111111111111111111111
               6:333333333333.....11111111111111111111111
               5:333333333333......1111111111111111111111
               4:333333333333.......111111111111111111111
               3:333333333333........11111111111111111111
               2:333333333333.........1111111111111111111
               1:333333333333..........111111111111111111

       The annulus, box, circle, ellipse, and pie shapes also accept an n=[int] syntax for
       specifying multiple regions. The n=[int]syntax interprets the previous (shape-dependent)
       arguments as lower and upper limits for the region and creates n shapes with evenly spaced
       boundaries.  For example, if n=[int] is specified in an annulus, the two immediately
       preceding radii (rn and rm) are divided into int annuli, such that the inner radius of the
       first is rn and the outer radius of the last is rm. For example,

         ANNULUS 20 20 5 20 n=3

       is equivalent to:

         ANNULUS 20 20 5 10 15 20

       If this syntax is used with an ellipse or box, then the two preceding pairs of values are
       taken to be lower and upper limits for a set of ellipses or boxes. A circle uses the two
       preceding arguments for upper and lower radii.  For pie, the two preceding angles are
       divided into n wedges such that the starting angle of the first is the lower bound and the
       ending angle of the last is the upper bound.  In all cases, the n=[int] syntax allows any
       single alphabetic character before the "=", i.e, i=3, z=3, etc. are all equivalent.

       Also note that for boxes and ellipses, the optional angle argument is always specified
       after the n=[int] syntax. For example:

         ellipse 20 20 4 6 16 24 n=3 45

       specifies 3 elliptical regions at an angle of 45 degrees:

         1234567890123456789012345678901234567890
         ----------------------------------------
         40:........33333333........................
         39:.....33333333333333.....................
         38:....33333333333333333...................
         37:...33333333333333333333.................
         36:..33333333333333333333333...............
         35:.3333333333222223333333333..............
         34:3333333322222222222233333333............
         33:33333332222222222222223333333...........
         32:333333222222222222222222333333..........
         31:3333322222222222222222222333333.........
         30:33333222222222111122222222333333........
         29:333332222222111111112222222333333.......
         28:3333222222211111111111222222333333......
         27:3333222222111111111111112222233333......
         26:33332222221111111111111112222233333.....
         25:33332222211111111.111111112222233333....
         24:333322222111111......111111222223333....
         23:333322222111111.......111112222233333...
         22:33333222221111.........11111222223333...
         21:333332222211111.........11112222233333..
         20:.33332222211111.........11111222223333..
         19:.33333222221111.........111112222233333.
         18:..33332222211111.........11112222233333.
         17:..333332222211111.......111111222233333.
         16:...333322222111111......111111222223333.
         15:...333332222211111111.111111112222233333
         14:....333332222211111111111111122222233333
         13:.....33333222221111111111111122222233333
         12:.....33333322222211111111111222222233333
         11:......3333332222222111111112222222333333
         10:.......333333222222221111222222222333333
         9:........33333322222222222222222222333333
         8:.........333333222222222222222222333333.
         7:..........33333332222222222222223333333.
         6:...........3333333322222222222233333333.
         5:.............3333333333222223333333333..
         4:..............33333333333333333333333...
         3:................33333333333333333333....
         2:..................33333333333333333.....
         1:....................33333333333333......

       Both the variable argument syntax and the n=[int] syntax must occur alone in a region
       descriptor (aside from the optional angle for boxes and ellipses).  They cannot be
       combined. Thus, it is not valid to precede or follow an n=[int] accelerator with more
       angles or radii, as in this example:

         # INVALID -- one too many angles before a=5 ...
         # and no angles are allowed after a=5
         PIE 12 12 10 25 50 a=5 85 135

       Instead, use three separate specifications, such as:

         PIE 12 12 10 25
         PIE 12 12 25 50 a=5
         PIE 12 12 85 135

       The original (IRAF) implementation of region filtering permitted this looser syntax, but
       we found it caused more confusion than it was worth and therefore removed it.

       NB: Accelerators may be combined with other shapes in a boolean expression in any order.
       (This is a change starting with funtools v1.1.1. Prior to this release, the accelerator
       shape had to be specified last).  The actual region mask id values returned depend on the
       order in which the shapes are specified, although the total number of pixels or rows that
       pass the filter will be consistent. For this reason, use of accelerators in boolean
       expressions is discouraged in programs such as funcnts, where region mask id values are
       used to count events or image pixels.

       [All region masks displayed in this document were generated using the fundisp routine and
       the undocumented "mask=all" argument (with spaced removed using sed ):

         fundisp "funtools/funtest/test40.fits[ANNULUS 25 25 5 10]" mask=all ⎪\
         sed 's/ //g'

       Note that you must supply an image of the appropriate size -- in this case, a FITS image
       of dimension 40x40 is used.]

SEE ALSO

       See funtools(7) for a list of Funtools help pages