diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2016-10-25 20:57:49 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2016-10-25 20:57:49 (GMT) |
commit | d1c4bf158203c4e8ec29fdeb83fd311e36320885 (patch) | |
tree | 15874534e282f67505ce4af5ba805a1ff70ec43e /funtools/doc/reggeometry.html | |
parent | e19a18e035dc4d0e8e215f9b452bb9ef6f58b9d7 (diff) | |
parent | 339420dd5dd874c41f6bab5808291fb4036dd022 (diff) | |
download | blt-d1c4bf158203c4e8ec29fdeb83fd311e36320885.zip blt-d1c4bf158203c4e8ec29fdeb83fd311e36320885.tar.gz blt-d1c4bf158203c4e8ec29fdeb83fd311e36320885.tar.bz2 |
Merge commit '339420dd5dd874c41f6bab5808291fb4036dd022' as 'funtools'
Diffstat (limited to 'funtools/doc/reggeometry.html')
-rw-r--r-- | funtools/doc/reggeometry.html | 1148 |
1 files changed, 1148 insertions, 0 deletions
diff --git a/funtools/doc/reggeometry.html b/funtools/doc/reggeometry.html new file mode 100644 index 0000000..faca53f --- /dev/null +++ b/funtools/doc/reggeometry.html @@ -0,0 +1,1148 @@ +<!-- =defdoc reggeometry reggeometry n --> +<HTML> +<HEAD> +<TITLE>Region Geometry</TITLE> +</HEAD> +<BODY> + +<!-- =section reggeometry NAME --> +<H2><A NAME="reggeometry">RegGeometry: Geometric Shapes in Spatial Region Filtering</A></H2> + +<!-- =section reggeometry SYNOPSIS --> +<H2>Summary</H2> +<P> +This document describes the geometry of regions available for spatial +filtering in IRAF/PROS analysis. + +<!-- =section reggeometry DESCRIPTION --> +<H2>Geometric shapes</H2> +<P> +Several geometric shapes are used to describe regions. The valid +shapes are: + +<PRE> + 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 +</PRE> + + +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. + +<P> +Shapes can be specified using "command" syntax: +<PRE> + [shape] arg1 arg2 ... +</PRE> +or using "routine" syntax: +<PRE> + [shape](arg1, arg2, ...) +</PRE> +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: + +<PRE> + "foo.fits[CIRCLE 512 512 50;CIR(128 128, 10);cir(650,650,20)]" +</PRE> + +(Quotes generally are required to protect the region descriptor +from being processed by the Unix shell.) + +<HR> + +<P> +The <B>annulus</B> shape specifies annuli, centered at xcenter, +ycenter, with inner and outer radii (r1, r2). For example, +<PRE> + ANNULUS 25 25 5 10 +</PRE> +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: +<PRE> + 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:........................................ +</PRE> + +<HR> + +<P> +The <B>box</B> 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. + +<P> +The <B>box</B> 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. + +<HR> + +<P> +The <B>circle</B> shape specifies a circle, centered at xcenter, +ycenter, of radius r. It requires three arguments. + +<HR> + +<P> +The <B>ellipse</B> shape specifies an ellipse, centered at +xcenter, ycenter, with y-axis width a and the y-axis length b defined such +that: +<PRE> + x**2/a**2 + y**2/b**2 = 1 +</PRE> +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: +<PRE> + ELLIPSE 20 20 5 10 45 +</PRE> +will look like this: +<PRE> + 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:........................................ +</PRE> + + +<HR> + +<P> +The <B>field</B> 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</B> takes no arguments. + +<HR> + +<P> +The <B>pie</B> 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, +<PRE> + PIE 20 20 90 180 +</PRE> +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: + +<PRE> + 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:........................................ +</PRE> +The pie slice specified is always a counter-clockwise sweep between +the angles, starting at the first angle and ending at the second. Thus: +<PRE> + PIE 10 15 30 60 +</PRE> +describes a 30 degree sweep from 2 o'clock to 1 o'clock, while: +<PRE> + PIE 10 15 60 30 +</PRE> +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: + +<PRE> + 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 +</PRE> +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"). + +<P> +Pie Performance Notes: +<P> +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. + +<P> +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: + +<PRE> + 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% +</PRE> + +<P> +Black-magic performance note: + +<P> +Panda region processing uses a <B>quick test</B> pie region instead of +the normal pie region when combining its annulus and pie shapes. This +<B>qtpie</B> 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. + +<P> +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: + +<PRE> + time ./funcnts nacis.fits "circle 4096 4096 100 && qtpie 4096 4096 10 78" +4.66u 0.33s 0:05.87 85.0% +</PRE> + +<P> +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. + +<HR> + +<P> +The <B>line</B> shape allows single pixels in a line between (x1,y1) and +(x2,y2) to be included or excluded. For example: +<PRE> + LINE (5,6, 24,25) +<PRE> +displays as: +<PRE> + 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:........................................ +</PRE> + +<HR> + +<P> +The <B>point</B> 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. + +<P> +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, +<PRE> + POINT (5,6, 10,11, 20,20, 35,30) +</PRE> +will give the different region mask values to all four points, as shown below: + +<PRE> + 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:........................................ +</PRE> + +<HR> + +<P> +The <B>polygon</B> 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: +<PRE> + POLYGON (10,10, 10,30, 30,30) +</PRE> + +looks like this: + +<PRE> + 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:........................................ +</PRE> +Note that polygons can get twisted upon themselves if edge lines +cross. Thus: +<PRE> + POL (10,10, 20,20, 20,10, 10,20) +</PRE> +will produce an area which is two triangles, like butterfly wings, as shown +below: + +<PRE> + 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:........................................ +</PRE> + +<HR> + +<P> +The following are combinations of pie with different shapes +(called "panda" for "Pie AND Annulus") allow for easy specification of +radial sections: +<PRE> + 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 +</PRE> + +The <B>panda</B> (<B>P</B>ies <B>AND</B> <B>A</B>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. + +<P> +Consider the example shown below: +<PRE> + PANDA(20,20, 0,360,3, 0,15,4) +</PRE> +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): +<PRE> + 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:........................................ +</PRE> + +<HR> + +<P> +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: +<PRE> + ANNULUS 25 25 5 10 + ELLIPSE 20 20 5 10 315 + BOX 15 15 5 10 +</PRE> +The resulting mask will look as follows: + +<PRE> + 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:........................................ +</PRE> +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). + +<P> +<H2>Region accelerators</H2> + +<P> +Two types of \fBaccelerators</B>, 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=<int></B>, 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. + +<P> +The following regions accept <B>accelerator</B> syntax: +<PRE> + 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 +</PRE> +Note that the circle accelerators are simply aliases for the annulus +accelerators. + +<P> +For example, several annuli at the same center can be specified in one +region expression by specifying more than two radii. If <B>N</B> +radii are specified, then <B>N</B>-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, +<PRE> + ANNULUS 20 20 0 2 5 10 15 20 +</PRE> +specifies five different annuli centered at 20 20, and is equivalent to: +<PRE> + 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 +</PRE> +The mask is shown below: + +<PRE> + 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.............. +</PRE> + +<P> +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: +<PRE> + ellipse 20 20 3 5 6 10 9 15 12 20 45 +</PRE> +specifies an 3 ellipses at a 45 degree angle: +<PRE> + 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:........................................ +</PRE> +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.: +<PRE> + circle 20 20 5 10 15 20 + annulus 20 20 5 10 15 20 +</PRE> +both give the following region mask: +<PRE> + 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.............. + +</PRE> + +<P> +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</B> angles are +specified, then <B>N</B>-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, +<PRE> + PIE 12 12 315 45 115 270 +</PRE> +specifies three regions as shown below: +<PRE> + 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 +</PRE> + +<P> +The annulus, box, circle, ellipse, and pie shapes also accept an +<B>n=[int]</B> syntax for specifying multiple regions. The +<B>n=[int]</b>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]</B> +is specified in an annulus, the two immediately preceding radii +(<B>rn</B> and <B>rm</B>) are divided into <B>int</B> annuli, such +that the inner radius of the first is <B>rn</B> and the outer radius +of the last is <B>rm</B>. For example, +<PRE> + ANNULUS 20 20 5 20 n=3 +</PRE> +is equivalent to: +<PRE> + ANNULUS 20 20 5 10 15 20 +</PRE> +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]</B> syntax allows any single alphabetic character +before the "=", i.e, i=3, z=3, etc. are all equivalent. + +<P> +Also note that for boxes and ellipses, the optional angle argument is +always specified after the <B>n=[int]</B> syntax. For example: +<PRE> + ellipse 20 20 4 6 16 24 n=3 45 +<PRE> +specifies 3 elliptical regions at an angle of 45 degrees: + +<PRE> + 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...... +</PRE> + +<P> +Both the variable argument syntax and the <B>n=[int]</B> 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]</B> accelerator with more angles or +radii, as in this example: +<PRE> + # 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 +</PRE> +Instead, use three separate specifications, such as: +<PRE> + PIE 12 12 10 25 + PIE 12 12 25 50 a=5 + PIE 12 12 85 135 +</PRE> +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. + +<P> +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. + +<P> +[All region masks displayed in this document were generated using the +<B>fundisp</B> routine and the undocumented "mask=all" argument (with +spaced removed using sed ): +<PRE> + fundisp "funtools/funtest/test40.fits[ANNULUS 25 25 5 10]" mask=all |\ + sed 's/ //g' +</PRE> +Note that you must supply an image of the appropriate size -- in this case, +a FITS image of dimension 40x40 is used.] + +<!-- =section reggeometry SEE ALSO --> +<!-- =text See funtools(n) for a list of Funtools help pages --> +<!-- =stop --> + +<P> +<A HREF="./help.html">Go to Funtools Help Index</A> + +<H5>Last updated: March 12, 2007</H5> + +</BODY> +</HTML> |