diff options
| author | William Joye <wjoye@cfa.harvard.edu> | 2016-10-26 21:13:00 (GMT) |
|---|---|---|
| committer | William Joye <wjoye@cfa.harvard.edu> | 2016-10-26 21:13:00 (GMT) |
| commit | da2e3d212171bbe64c1af39114fd067308656990 (patch) | |
| tree | 9601f7ed15fa1394762124630c12a792bc073ec2 /funtools/doc/reggeometry.html | |
| parent | 76b109ad6d97d19ab835596dc70149ef379f3733 (diff) | |
| download | blt-da2e3d212171bbe64c1af39114fd067308656990.zip blt-da2e3d212171bbe64c1af39114fd067308656990.tar.gz blt-da2e3d212171bbe64c1af39114fd067308656990.tar.bz2 | |
rm funtools for update
Diffstat (limited to 'funtools/doc/reggeometry.html')
| -rw-r--r-- | funtools/doc/reggeometry.html | 1148 |
1 files changed, 0 insertions, 1148 deletions
diff --git a/funtools/doc/reggeometry.html b/funtools/doc/reggeometry.html deleted file mode 100644 index faca53f..0000000 --- a/funtools/doc/reggeometry.html +++ /dev/null @@ -1,1148 +0,0 @@ -<!-- =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> |