diff options
Diffstat (limited to 'funtools/doc/pod/reggeometry.pod')
| -rw-r--r-- | funtools/doc/pod/reggeometry.pod | 1156 |
1 files changed, 1156 insertions, 0 deletions
diff --git a/funtools/doc/pod/reggeometry.pod b/funtools/doc/pod/reggeometry.pod new file mode 100644 index 0000000..0d442d5 --- /dev/null +++ b/funtools/doc/pod/reggeometry.pod @@ -0,0 +1,1156 @@ +=pod + +=head1 NAME + + + +B<RegGeometry: Geometric Shapes in Spatial Region Filtering> + + + +=head1 SYNOPSIS + + + + + +This document describes the geometry of regions available for spatial +filtering in IRAF/PROS analysis. + + + +=head1 DESCRIPTION + + + +B<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 B<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 B<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 B<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 B<circle> shape specifies a circle, centered at xcenter, +ycenter, of radius r. It requires three arguments. + + + + +The B<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 B<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. +B<Field> takes no arguments. + + + + +The B<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 B<quick test> pie region instead of +the normal pie region when combining its annulus and pie shapes. This +B<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 B<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 B<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 B<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 B<panda> (B<P>ies B<AND> B<A>nnuli) 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). + + +B<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 +B<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 B<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 B<N> +radii are specified, then B<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 B<N> angles are +specified, then B<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 +B<n=[int]> syntax for specifying multiple regions. The +B<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 B<n=[int]> +is specified in an annulus, the two immediately preceding radii +(B<rn> and B<rm>) are divided into B<int> annuli, such +that the inner radius of the first is B<rn> and the outer radius +of the last is B<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 B<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 B<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 B<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 B<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 +B<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.] + + + +=head1 SEE ALSO + + + +See funtools(n) for a list of Funtools help pages + + + +=cut |