1reggeometry(n) SAORD Documentation reggeometry(n)
2
6 RegGeometry: Geometric Shapes in Spatial Region Filtering
7
9 This document describes the geometry of regions available for spatial
10 filtering in IRAF/PROS analysis.
11
13 Geometric shapes
14 Several geometric shapes are used to describe regions. The valid
16 shapes are:
17 shape: arguments:
19 ----- ----------------------------------------
20 ANNULUS xcenter ycenter inner_radius outer_radius
21 BOX xcenter ycenter xwidth yheight (angle)
22 CIRCLE xcenter ycenter radius
23 ELLIPSE xcenter ycenter xwidth yheight (angle)
24 FIELD none
25 LINE x1 y1 x2 y2
26 PIE xcenter ycenter angle1 angle2
27 POINT x1 y1
28 POLYGON x1 y1 x2 y2 ... xn yn
29 All arguments are real values; integer values are automatically con‐
31 verted to real where necessary. All angles are in degrees and specify
32 angles that run counter-clockwise from the positive y-axis.
33 Shapes can be specified using "command" syntax:
35 [shape] arg1 arg2 ...
37 or using "routine" syntax:
39 [shape](arg1, arg2, ...)
41 or by any combination of the these. (Of course, the parentheses must
43 balance and there cannot be more commas than necessary.) The shape key‐
44 words are case-insensitive. Furthermore, any shape can be specified by
45 a three-character unique abbreviation. For example, one can specify
46 three circular regions as:
47 "foo.fits[CIRCLE 512 512 50;CIR(128 128, 10);cir(650,650,20)]"
49 (Quotes generally are required to protect the region descriptor from
51 being processed by the Unix shell.)
52 The annulus shape specifies annuli, centered at xcenter, ycen‐
54 ter, with inner and outer radii (r1, r2). For example,
55 ANNULUS 25 25 5 10
57 specifies an annulus centered at 25.0 25.0 with an inner radius of 5.0
59 and an outer radius of 10. Assuming (as will be done for all examples
60 in this document, unless otherwise noted) this shape is used in a mask
61 of size 40x40, it will look like this:
62 1234567890123456789012345678901234567890
64 ----------------------------------------
65 40:........................................
66 39:........................................
67 38:........................................
68 37:........................................
69 36:........................................
70 35:........................................
71 34:....................111111111...........
72 33:...................11111111111..........
73 32:.................111111111111111........
74 31:.................111111111111111........
75 30:................11111111111111111.......
76 29:...............1111111.....1111111......
77 28:...............111111.......111111......
78 27:...............11111.........11111......
79 26:...............11111.........11111......
80 25:...............11111.........11111......
81 24:...............11111.........11111......
82 23:...............11111.........11111......
83 22:...............111111.......111111......
84 21:...............1111111.....1111111......
85 20:................11111111111111111.......
86 19:.................111111111111111........
87 18:.................111111111111111........
88 17:...................11111111111..........
89 16:....................111111111...........
90 15:........................................
91 14:........................................
92 13:........................................
93 12:........................................
94 11:........................................
95 10:........................................
96 9:........................................
97 8:........................................
98 7:........................................
99 6:........................................
100 5:........................................
101 4:........................................
102 3:........................................
103 2:........................................
104 1:........................................
105 The box shape specifies an orthogonally oriented box, centered at xcen‐
107 ter, ycenter, of size xwidth, yheight. It requires four arguments and
108 accepts an optional fifth argument to specify a rotation angle. When
109 the rotation angle is specified (in degrees), the box is rotated by an
110 angle that runs counter-clockwise from the positive y-axis.
111 The box shape specifies a rotated box, centered at xcenter, ycenter, of
113 size xwidth, yheight. The box is rotated by an angle specified in
114 degrees that runs counter-clockwise from the positive y-axis. If the
115 angle argument is omitted, it defaults to 0.
116 The circle shape specifies a circle, centered at xcenter, ycenter, of
118 radius r. It requires three arguments.
119 The ellipse shape specifies an ellipse, centered at xcenter, ycenter,
121 with y-axis width a and the y-axis length b defined such that:
122 x**2/a**2 + y**2/b**2 = 1
124 Note that a can be less than, equal to, or greater than b. The ellipse
126 is rotated the specified number of degrees. The rotation is done
127 according to astronomical convention, counter-clockwise from the posi‐
128 tive y-axis. An ellipse defined by:
129 ELLIPSE 20 20 5 10 45
131 will look like this:
133 1234567890123456789012345678901234567890
135 ----------------------------------------
136 40:........................................
137 39:........................................
138 38:........................................
139 37:........................................
140 36:........................................
141 35:........................................
142 34:........................................
143 33:........................................
144 32:........................................
145 31:........................................
146 30:........................................
147 29:........................................
148 28:........................................
149 27:............111111......................
150 26:............11111111....................
151 25:............111111111...................
152 24:............11111111111.................
153 23:............111111111111................
154 22:............111111111111................
155 21:.............111111111111...............
156 20:.............1111111111111..............
157 19:..............111111111111..............
158 18:...............111111111111.............
159 17:...............111111111111.............
160 16:................11111111111.............
161 15:..................111111111.............
162 14:...................11111111.............
163 13:.....................111111.............
164 12:........................................
165 11:........................................
166 10:........................................
167 9:........................................
168 8:........................................
169 7:........................................
170 6:........................................
171 5:........................................
172 4:........................................
173 3:........................................
174 2:........................................
175 1:........................................
176 The field shape specifies the entire field as a region. It is not usu‐
178 ally specified explicitly, but is used implicitly in the case where no
179 regions are specified, that is, in cases where either a null string or
180 some abbreviation of the string "none" is input. Field takes no argu‐
181 ments.
182 The pie shape specifies an angular wedge of the entire field, centered
184 at xcenter, ycenter. The wedge runs between the two specified angles.
185 The angles are given in degrees, running counter-clockwise from the
186 positive x-axis. For example,
187 PIE 20 20 90 180
189 defines a region from 90 degrees to 180 degrees, i.e., quadrant 2 of
191 the Cartesian plane. The display of such a region looks like this:
192 1234567890123456789012345678901234567890
194 ----------------------------------------
195 40:11111111111111111111....................
196 39:11111111111111111111....................
197 38:11111111111111111111....................
198 37:11111111111111111111....................
199 36:11111111111111111111....................
200 35:11111111111111111111....................
201 34:11111111111111111111....................
202 33:11111111111111111111....................
203 32:11111111111111111111....................
204 31:11111111111111111111....................
205 30:11111111111111111111....................
206 29:11111111111111111111....................
207 28:11111111111111111111....................
208 27:11111111111111111111....................
209 26:11111111111111111111....................
210 25:11111111111111111111....................
211 24:11111111111111111111....................
212 23:11111111111111111111....................
213 22:11111111111111111111....................
214 21:11111111111111111111....................
215 20:........................................
216 19:........................................
217 18:........................................
218 17:........................................
219 16:........................................
220 15:........................................
221 14:........................................
222 13:........................................
223 12:........................................
224 11:........................................
225 10:........................................
226 9:........................................
227 8:........................................
228 7:........................................
229 6:........................................
230 5:........................................
231 4:........................................
232 3:........................................
233 2:........................................
234 1:........................................
235 The pie slice specified is always a counter-clockwise sweep between the
237 angles, starting at the first angle and ending at the second. Thus:
238 PIE 10 15 30 60
240 describes a 30 degree sweep from 2 o'clock to 1 o'clock, while:
242 PIE 10 15 60 30
244 describes a 330 degree counter-clockwise sweep from 1 o'clock to 2
246 o'clock passing through 12 o'clock (0 degrees). Note in both of these
247 examples that the center of the slice can be anywhere on the plane.
248 The second mask looks like this:
249 1234567890123456789012345678901234567890
251 ----------------------------------------
252 40:111111111111111111111111................
253 39:11111111111111111111111.................
254 38:11111111111111111111111.................
255 37:1111111111111111111111..................
256 36:1111111111111111111111..................
257 35:111111111111111111111...................
258 34:11111111111111111111....................
259 33:11111111111111111111....................
260 32:1111111111111111111....................1
261 31:1111111111111111111..................111
262 30:111111111111111111.................11111
263 29:111111111111111111................111111
264 28:11111111111111111...............11111111
265 27:1111111111111111..............1111111111
266 26:1111111111111111.............11111111111
267 25:111111111111111............1111111111111
268 24:111111111111111..........111111111111111
269 23:11111111111111.........11111111111111111
270 22:11111111111111........111111111111111111
271 21:1111111111111.......11111111111111111111
272 20:111111111111......1111111111111111111111
273 19:111111111111....111111111111111111111111
274 18:11111111111....1111111111111111111111111
275 17:11111111111..111111111111111111111111111
276 16:1111111111.11111111111111111111111111111
277 15:1111111111111111111111111111111111111111
278 14:1111111111111111111111111111111111111111
279 13:1111111111111111111111111111111111111111
280 12:1111111111111111111111111111111111111111
281 11:1111111111111111111111111111111111111111
282 10:1111111111111111111111111111111111111111
283 9:1111111111111111111111111111111111111111
284 8:1111111111111111111111111111111111111111
285 7:1111111111111111111111111111111111111111
286 6:1111111111111111111111111111111111111111
287 5:1111111111111111111111111111111111111111
288 4:1111111111111111111111111111111111111111
289 3:1111111111111111111111111111111111111111
290 2:1111111111111111111111111111111111111111
291 1:1111111111111111111111111111111111111111
292 The pie slice goes to the edge of the field. To limit its scope, pie
294 usually is is combined with other shapes, such as circles and annuli,
295 using boolean operations. (See below and in "help regalgebra").
296 Pie Performance Notes:
298 Pie region processing time is proportional to the size of the image,
300 and not the size of the region. This is because the pie shape is the
301 only infinite length shape, and we essentially must check all y rows
302 for inclusion (unlike other regions, where the y limits can be calcu‐
303 lated beforehand). Thus, pie can run very slowly on large images. In
304 particular, it will run MUCH more slowly than the panda shape in image-
305 based region operations (such as funcnts). We recommend use of panda
306 over pie where ever possible.
307 If you must use pie, always try to put it last in a boolean && expres‐
309 sion. The reason for this is that the filter code is optimized to exit
310 as soon as the result is know. Since pie is the slowest region, it is
311 better to avoid executing it if another region can decide the result.
312 Consider, for example, the difference in time required to process a
313 Chandra ACIS file when a pie and circle are combined in two different
314 orders:
315 time ./funcnts nacis.fits "circle 4096 4096 100 && pie 4096 4096 10 78"
317 2.87u 0.38s 0:35.08 9.2%
318 time ./funcnts nacis.fits "pie 4096 4096 10 78 && circle 4096 4096 100 "
320 89.73u 0.36s 1:03.50 141.8%
321 Black-magic performance note:
323 Panda region processing uses a quick test pie region instead of the
325 normal pie region when combining its annulus and pie shapes. This qtpie
326 shape differs from the normal pie in that it utilizes the y limits from
327 the previous region with which it is combined. In a panda shape, which
328 is a series of annuli combined with pies, the processing time is thus
329 reduced to that of the annuli.
330 You can use the qtpie shape instead of pie in cases where you are com‐
332 bining pie with another shape using the && operator. This will cause
333 the pie limits to be set using limits from the other shape, and will
334 speed up the processing considerably. For example, the above execution
335 of funcnts can be improved considerably using this technique:
336 time ./funcnts nacis.fits "circle 4096 4096 100 && qtpie 4096 4096 10 78"
338 4.66u 0.33s 0:05.87 85.0%
339 We emphasize that this is a quasi-documented feature and might change
341 in the future. The qtpie shape is not recognized by ds9 or other pro‐
342 grams.
343 The line shape allows single pixels in a line between (x1,y1) and
345 (x2,y2) to be included or excluded. For example:
346 LINE (5,6, 24,25)
348 displays as:
350 1234567890123456789012345678901234567890
352 ----------------------------------------
353 40:........................................
354 39:........................................
355 38:........................................
356 37:........................................
357 36:........................................
358 35:........................................
359 34:........................................
360 33:........................................
361 32:........................................
362 31:........................................
363 30:........................................
364 29:........................................
365 28:........................................
366 27:........................................
367 26:........................................
368 25:.......................1................
369 24:......................1.................
370 23:.....................1..................
371 22:....................1...................
372 21:...................1....................
373 20:..................1.....................
374 19:.................1......................
375 18:................1.......................
376 17:...............1........................
377 16:..............1.........................
378 15:.............1..........................
379 14:............1...........................
380 13:...........1............................
381 12:..........1.............................
382 11:.........1..............................
383 10:........1...............................
384 9:.......1................................
385 8:......1.................................
386 7:.....1..................................
387 6:....1...................................
388 5:........................................
389 4:........................................
390 3:........................................
391 2:........................................
392 1:........................................
393 The point shape allows single pixels to be included or excluded.
395 Although the (x,y) values are real numbers, they are truncated to inte‐
396 ger and the corresponding pixel is included or excluded, as specified.
397 Several points can be put in one region declaration; unlike the origi‐
399 nal IRAF implementation, each now is given a different region mask
400 value. This makes it easier, for example, for funcnts to determine the
401 number of photons in the individual pixels. For example,
402 POINT (5,6, 10,11, 20,20, 35,30)
404 will give the different region mask values to all four points, as shown
406 below:
407 1234567890123456789012345678901234567890
409 ----------------------------------------
410 40:........................................
411 39:........................................
412 38:........................................
413 37:........................................
414 36:........................................
415 35:........................................
416 34:........................................
417 33:........................................
418 32:........................................
419 31:........................................
420 30:..................................4.....
421 29:........................................
422 28:........................................
423 27:........................................
424 26:........................................
425 25:........................................
426 24:........................................
427 23:........................................
428 22:........................................
429 21:........................................
430 20:...................3....................
431 19:........................................
432 18:........................................
433 17:........................................
434 16:........................................
435 15:........................................
436 14:........................................
437 13:........................................
438 12:........................................
439 11:.........2..............................
440 10:........................................
441 9:........................................
442 8:........................................
443 7:........................................
444 6:....1...................................
445 5:........................................
446 4:........................................
447 3:........................................
448 2:........................................
449 1:........................................
450 The polygon shape specifies a polygon with vertices (x1, y1) ... (xn,
452 yn). The polygon is closed automatically: one should not specify the
453 last vertex to be the same as the first. Any number of vertices are
454 allowed. For example, the following polygon defines a right triangle
455 as shown below:
456 POLYGON (10,10, 10,30, 30,30)
458 looks like this:
460 1234567890123456789012345678901234567890
462 ----------------------------------------
463 40:........................................
464 39:........................................
465 38:........................................
466 37:........................................
467 36:........................................
468 35:........................................
469 34:........................................
470 33:........................................
471 32:........................................
472 31:........................................
473 30:..........11111111111111111111..........
474 29:..........1111111111111111111...........
475 28:..........111111111111111111............
476 27:..........11111111111111111.............
477 26:..........1111111111111111..............
478 25:..........111111111111111...............
479 24:..........11111111111111................
480 23:..........1111111111111.................
481 22:..........111111111111..................
482 21:..........11111111111...................
483 20:..........1111111111....................
484 19:..........111111111.....................
485 18:..........11111111......................
486 17:..........1111111.......................
487 16:..........111111........................
488 15:..........11111.........................
489 14:..........1111..........................
490 13:..........111...........................
491 12:..........11............................
492 11:..........1.............................
493 10:........................................
494 9:........................................
495 8:........................................
496 7:........................................
497 6:........................................
498 5:........................................
499 4:........................................
500 3:........................................
501 2:........................................
502 1:........................................
503 Note that polygons can get twisted upon themselves if edge lines cross.
505 Thus:
506 POL (10,10, 20,20, 20,10, 10,20)
508 will produce an area which is two triangles, like butterfly wings, as
510 shown below:
511 1234567890123456789012345678901234567890
513 ----------------------------------------
514 40:........................................
515 39:........................................
516 38:........................................
517 37:........................................
518 36:........................................
519 35:........................................
520 34:........................................
521 33:........................................
522 32:........................................
523 31:........................................
524 30:........................................
525 29:........................................
526 28:........................................
527 27:........................................
528 26:........................................
529 25:........................................
530 24:........................................
531 23:........................................
532 22:........................................
533 21:........................................
534 20:........................................
535 19:..........1........1....................
536 18:..........11......11....................
537 17:..........111....111....................
538 16:..........1111..1111....................
539 15:..........1111111111....................
540 14:..........1111..1111....................
541 13:..........111....111....................
542 12:..........11......11....................
543 11:..........1........1....................
544 10:........................................
545 9:........................................
546 8:........................................
547 7:........................................
548 6:........................................
549 5:........................................
550 4:........................................
551 3:........................................
552 2:........................................
553 1:........................................
554 The following are combinations of pie with different shapes (called
556 "panda" for "Pie AND Annulus") allow for easy specification of radial
557 sections:
558 shape: arguments:
560 ----- ---------
561 PANDA xcen ycen ang1 ang2 nang irad orad nrad # circular
562 CPANDA xcen ycen ang1 ang2 nang irad orad nrad # circular
563 BPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # box
564 EPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # ellipse
565 The panda (Pies AND Annuli) shape can be used to create combinations of
567 pie and annuli markers. It is analogous to a Cartesian product on those
568 shapes, i.e., the result is several shapes generated by performing a
569 boolean AND between pies and annuli. Thus, the panda and cpanda specify
570 combinations of annulus and circle with pie, respectively and give
571 identical results. The bpanda combines box and pie, while epanda com‐
572 bines ellipse and pie.
573 Consider the example shown below:
575 PANDA(20,20, 0,360,3, 0,15,4)
577 Here, 3 pie slices centered at 20, 20 are combined with 4 annuli, also
579 centered at 20, 20. The result is a mask with 12 regions (displayed in
580 base 16 to save characters):
581 1234567890123456789012345678901234567890
583 ----------------------------------------
584 40:........................................
585 39:........................................
586 38:........................................
587 37:........................................
588 36:........................................
589 35:........................................
590 34:..............44444444444...............
591 33:............444444444444444.............
592 32:...........88444444444444444............
593 31:.........888844443333344444444..........
594 30:........88888833333333333444444.........
595 29:........88888733333333333344444.........
596 28:.......8888877733333333333344444........
597 27:......888887777332222233333344444.......
598 26:......888877777622222222333334444.......
599 25:.....88887777766622222222333334444......
600 24:.....88887777666622222222233334444......
601 23:.....88887777666651111222233334444......
602 22:.....88877776666551111122223333444......
603 21:.....88877776666555111122223333444......
604 20:.....888777766665559999aaaabbbbccc......
605 19:.....888777766665559999aaaabbbbccc......
606 18:.....888777766665599999aaaabbbbccc......
607 17:.....88887777666659999aaaabbbbcccc......
608 16:.....888877776666aaaaaaaaabbbbcccc......
609 15:.....888877777666aaaaaaaabbbbbcccc......
610 14:......8888777776aaaaaaaabbbbbcccc.......
611 13:......888887777bbaaaaabbbbbbccccc.......
612 12:.......88888777bbbbbbbbbbbbccccc........
613 11:........888887bbbbbbbbbbbbccccc.........
614 10:........888888bbbbbbbbbbbcccccc.........
615 9:.........8888ccccbbbbbcccccccc..........
616 8:...........88ccccccccccccccc............
617 7:............ccccccccccccccc.............
618 6:..............ccccccccccc...............
619 5:........................................
620 4:........................................
621 3:........................................
622 2:........................................
623 1:........................................
624 Several regions with different mask values can be combined in the same
626 mask. This supports comparing data from the different regions. (For
627 information on how to combine different shapes into a single region,
628 see "help regalgebra".) For example, consider the following set of
629 regions:
630 ANNULUS 25 25 5 10
632 ELLIPSE 20 20 5 10 315
633 BOX 15 15 5 10
634 The resulting mask will look as follows:
636 1234567890123456789012345678901234567890
638 ----------------------------------------
639 40:........................................
640 39:........................................
641 38:........................................
642 37:........................................
643 36:........................................
644 35:........................................
645 34:....................111111111...........
646 33:...................11111111111..........
647 32:.................111111111111111........
648 31:.................111111111111111........
649 30:................11111111111111111.......
650 29:...............1111111.....1111111......
651 28:...............111111.......111111......
652 27:...............11111.222222..11111......
653 26:...............111112222222..11111......
654 25:...............111112222222..11111......
655 24:...............111112222222..11111......
656 23:...............111112222222..11111......
657 22:...............111111222222.111111......
658 21:..............211111112222.1111111......
659 20:............322211111111111111111.......
660 19:............32222111111111111111........
661 18:............22222111111111111111........
662 17:............222222211111111111..........
663 16:............22222222111111111...........
664 15:............222222222...................
665 14:............22222222....................
666 13:............222222......................
667 12:............33333.......................
668 11:............33333.......................
669 10:........................................
670 9:........................................
671 8:........................................
672 7:........................................
673 6:........................................
674 5:........................................
675 4:........................................
676 3:........................................
677 2:........................................
678 1:........................................
679 Note that when a pixel is in 2 or more regions, it is arbitrarily
681 assigned to a one of the regions in question (often based on how a give
682 C compiler optimizes boolean expressions).
683 Region accelerators
685 Two types of \fBaccelerators, to simplify region specification, are
687 provided as natural extensions to the ways shapes are described. These
688 are: extended lists of parameters, specifying multiple regions, valid
689 for annulus, box, circle, ellipse, pie, and points; and n=, valid for
690 annulus, box, circle, ellipse, and pie (not point). In both cases, one
691 specification is used to define several different regions, that is, to
692 define shapes with different mask values in the region mask.
693 The following regions accept accelerator syntax:
695 shape arguments
697 ----- ------------------------------------------
698 ANNULUS xcenter ycenter radius1 radius2 ... radiusn
699 ANNULUS xcenter ycenter inner_radius outer_radius n=[number]
700 BOX xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle)
701 BOX xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle)
702 CIRCLE xcenter ycenter r1 r2 ... rn # same as annulus
703 CIRCLE xcenter ycenter rinner router n=[number] # same as annulus
704 ELLIPSE xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle)
705 ELLIPSE xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle)
706 PIE xcenter ycenter angle1 angle2 (angle3) (angle4) (angle5) ...
707 PIE xcenter ycenter angle1 angle2 (n=[number])
708 POINT x1 y1 x2 y2 ... xn yn
709 Note that the circle accelerators are simply aliases for the annulus
711 accelerators.
712 For example, several annuli at the same center can be specified in one
714 region expression by specifying more than two radii. If N radii are
715 specified, then N-1 annuli result, with the outer radius of each pre‐
716 ceding annulus being the inner radius of the succeeding annulus. Each
717 annulus is considered a separate region, and is given a separate mask
718 value. For example,
719 ANNULUS 20 20 0 2 5 10 15 20
721 specifies five different annuli centered at 20 20, and is equivalent
723 to:
724 ANNULUS 20.0 20.0 0 2
726 ANNULUS 20.0 20.0 2 5
727 ANNULUS 20.0 20.0 5 10
728 ANNULUS 20.0 20.0 10 15
729 ANNULUS 20.0 20.0 15 20
730 The mask is shown below:
732 1234567890123456789012345678901234567890
734 ----------------------------------------
735 40:........................................
736 39:.............5555555555555..............
737 38:...........55555555555555555............
738 37:.........555555555555555555555..........
739 36:........55555555555555555555555.........
740 35:......555555555555555555555555555.......
741 34:.....55555555544444444444555555555......
742 33:....5555555544444444444444455555555.....
743 32:....5555555444444444444444445555555.....
744 31:...555555444444444444444444444555555....
745 30:..55555544444444444444444444444555555...
746 29:..55555544444443333333334444444555555...
747 28:.5555554444444333333333334444444555555..
748 27:.5555544444433333333333333344444455555..
749 26:555555444444333333333333333444444555555.
750 25:555554444443333333333333333344444455555.
751 24:555554444433333332222233333334444455555.
752 23:555554444433333322222223333334444455555.
753 22:555554444433333222222222333334444455555.
754 21:555554444433333222111222333334444455555.
755 20:555554444433333222111222333334444455555.
756 19:555554444433333222111222333334444455555.
757 18:555554444433333222222222333334444455555.
758 17:555554444433333322222223333334444455555.
759 16:555554444433333332222233333334444455555.
760 15:555554444443333333333333333344444455555.
761 14:555555444444333333333333333444444555555.
762 13:.5555544444433333333333333344444455555..
763 12:.5555554444444333333333334444444555555..
764 11:..55555544444443333333334444444555555...
765 10:..55555544444444444444444444444555555...
766 9:...555555444444444444444444444555555....
767 8:....5555555444444444444444445555555.....
768 7:....5555555544444444444444455555555.....
769 6:.....55555555544444444444555555555......
770 5:......555555555555555555555555555.......
771 4:........55555555555555555555555.........
772 3:.........555555555555555555555..........
773 2:...........55555555555555555............
774 1:.............5555555555555..............
775 For boxes and ellipses, if an odd number of arguments is specified,
777 then the last argument is assumed to be an angle. Otherwise, the angle
778 is assumed to be zero. For example:
779 ellipse 20 20 3 5 6 10 9 15 12 20 45
781 specifies an 3 ellipses at a 45 degree angle:
783 1234567890123456789012345678901234567890
785 ----------------------------------------
786 40:........................................
787 39:........................................
788 38:........................................
789 37:........................................
790 36:........33333333........................
791 35:......333333333333......................
792 34:.....3333333333333333...................
793 33:....333333333333333333..................
794 32:....33333332222233333333................
795 31:...3333332222222222333333...............
796 30:...33333222222222222233333..............
797 29:...333332222222222222223333.............
798 28:...3333222222211112222223333............
799 27:...33332222211111111222223333...........
800 26:...333322222111111111122223333..........
801 25:...3333222211111111111122223333.........
802 24:....3332222111111..1111122223333........
803 23:....333322211111.....11112222333........
804 22:....33332222111.......11112223333.......
805 21:.....33322221111.......11122223333......
806 20:.....33332221111.......11112223333......
807 19:.....33332222111.......11112222333......
808 18:......33332221111.......11122223333.....
809 17:.......33322221111.....111112223333.....
810 16:.......3333222211111..1111112222333.....
811 15:........3333222211111111111122223333....
812 14:.........333322221111111111222223333....
813 13:..........33332222211111111222223333....
814 12:...........3333222222111122222223333....
815 11:............333322222222222222233333....
816 10:.............33333222222222222233333....
817 9:..............3333332222222222333333....
818 8:...............33333333222223333333.....
819 7:.................333333333333333333.....
820 6:..................3333333333333333......
821 5:.....................333333333333.......
822 4:.......................33333333.........
823 3:........................................
824 2:........................................
825 1:........................................
826 Note in the above example that the lower limit is not part of the
828 region for boxes, circles, and ellipses. This makes circles and annuli
829 equivalent, i.e.:
830 circle 20 20 5 10 15 20
832 annulus 20 20 5 10 15 20
833 both give the following region mask:
835 1234567890123456789012345678901234567890
837 ----------------------------------------
838 40:........................................
839 39:.............3333333333333..............
840 38:...........33333333333333333............
841 37:.........333333333333333333333..........
842 36:........33333333333333333333333.........
843 35:......333333333333333333333333333.......
844 34:.....33333333322222222222333333333......
845 33:....3333333322222222222222233333333.....
846 32:....3333333222222222222222223333333.....
847 31:...333333222222222222222222222333333....
848 30:..33333322222222222222222222222333333...
849 29:..33333322222221111111112222222333333...
850 28:.3333332222222111111111112222222333333..
851 27:.3333322222211111111111111122222233333..
852 26:333333222222111111111111111222222333333.
853 25:333332222221111111111111111122222233333.
854 24:33333222221111111.....11111112222233333.
855 23:3333322222111111.......1111112222233333.
856 22:333332222211111.........111112222233333.
857 21:333332222211111.........111112222233333.
858 20:333332222211111.........111112222233333.
859 19:333332222211111.........111112222233333.
860 18:333332222211111.........111112222233333.
861 17:3333322222111111.......1111112222233333.
862 16:33333222221111111.....11111112222233333.
863 15:333332222221111111111111111122222233333.
864 14:333333222222111111111111111222222333333.
865 13:.3333322222211111111111111122222233333..
866 12:.3333332222222111111111112222222333333..
867 11:..33333322222221111111112222222333333...
868 10:..33333322222222222222222222222333333...
869 9:...333333222222222222222222222333333....
870 8:....3333333222222222222222223333333.....
871 7:....3333333322222222222222233333333.....
872 6:.....33333333322222222222333333333......
873 5:......333333333333333333333333333.......
874 4:........33333333333333333333333.........
875 3:.........333333333333333333333..........
876 2:...........33333333333333333............
877 1:.............3333333333333..............
878 As a final example, specifying several angles in one pie slice expres‐
880 sion is equivalent to specifying several separate slices with the same
881 center. As with the annulus, if N angles are specified, then N-1
882 slices result, with the ending angle of each preceding slice being the
883 starting angle of the succeeding slice. Each slice is considered a
884 separate region, and is given a separate mask value. For example,
885 PIE 12 12 315 45 115 270
887 specifies three regions as shown below:
889 1234567890123456789012345678901234567890
891 ----------------------------------------
892 40:2222222222222222222222222222222222222222
893 39:2222222222222222222222222222222222222221
894 38:2222222222222222222222222222222222222211
895 37:2222222222222222222222222222222222222111
896 36:2222222222222222222222222222222222221111
897 35:3222222222222222222222222222222222211111
898 34:3222222222222222222222222222222222111111
899 33:3322222222222222222222222222222221111111
900 32:3322222222222222222222222222222211111111
901 31:3332222222222222222222222222222111111111
902 30:3332222222222222222222222222221111111111
903 29:3333222222222222222222222222211111111111
904 28:3333222222222222222222222222111111111111
905 27:3333322222222222222222222221111111111111
906 26:3333322222222222222222222211111111111111
907 25:3333322222222222222222222111111111111111
908 24:3333332222222222222222221111111111111111
909 23:3333332222222222222222211111111111111111
910 22:3333333222222222222222111111111111111111
911 21:3333333222222222222221111111111111111111
912 20:3333333322222222222211111111111111111111
913 19:3333333322222222222111111111111111111111
914 18:3333333332222222221111111111111111111111
915 17:3333333332222222211111111111111111111111
916 16:3333333333222222111111111111111111111111
917 15:3333333333222221111111111111111111111111
918 14:3333333333322211111111111111111111111111
919 13:3333333333322111111111111111111111111111
920 12:33333333333.1111111111111111111111111111
921 11:3333333333331111111111111111111111111111
922 10:333333333333.111111111111111111111111111
923 9:333333333333..11111111111111111111111111
924 8:333333333333...1111111111111111111111111
925 7:333333333333....111111111111111111111111
926 6:333333333333.....11111111111111111111111
927 5:333333333333......1111111111111111111111
928 4:333333333333.......111111111111111111111
929 3:333333333333........11111111111111111111
930 2:333333333333.........1111111111111111111
931 1:333333333333..........111111111111111111
932 The annulus, box, circle, ellipse, and pie shapes also accept an
934 n=[int] syntax for specifying multiple regions. The n=[int]syntax
935 interprets the previous (shape-dependent) arguments as lower and upper
936 limits for the region and creates n shapes with evenly spaced bound‐
937 aries. For example, if n=[int] is specified in an annulus, the two
938 immediately preceding radii (rn and rm) are divided into int annuli,
939 such that the inner radius of the first is rn and the outer radius of
940 the last is rm. For example,
941 ANNULUS 20 20 5 20 n=3
943 is equivalent to:
945 ANNULUS 20 20 5 10 15 20
947 If this syntax is used with an ellipse or box, then the two preceding
949 pairs of values are taken to be lower and upper limits for a set of
950 ellipses or boxes. A circle uses the two preceding arguments for upper
951 and lower radii. For pie, the two preceding angles are divided into n
952 wedges such that the starting angle of the first is the lower bound and
953 the ending angle of the last is the upper bound. In all cases, the
954 n=[int] syntax allows any single alphabetic character before the "=",
955 i.e, i=3, z=3, etc. are all equivalent.
956 Also note that for boxes and ellipses, the optional angle argument is
958 always specified after the n=[int] syntax. For example:
959 ellipse 20 20 4 6 16 24 n=3 45
961 specifies 3 elliptical regions at an angle of 45 degrees:
963 1234567890123456789012345678901234567890
965 ----------------------------------------
966 40:........33333333........................
967 39:.....33333333333333.....................
968 38:....33333333333333333...................
969 37:...33333333333333333333.................
970 36:..33333333333333333333333...............
971 35:.3333333333222223333333333..............
972 34:3333333322222222222233333333............
973 33:33333332222222222222223333333...........
974 32:333333222222222222222222333333..........
975 31:3333322222222222222222222333333.........
976 30:33333222222222111122222222333333........
977 29:333332222222111111112222222333333.......
978 28:3333222222211111111111222222333333......
979 27:3333222222111111111111112222233333......
980 26:33332222221111111111111112222233333.....
981 25:33332222211111111.111111112222233333....
982 24:333322222111111......111111222223333....
983 23:333322222111111.......111112222233333...
984 22:33333222221111.........11111222223333...
985 21:333332222211111.........11112222233333..
986 20:.33332222211111.........11111222223333..
987 19:.33333222221111.........111112222233333.
988 18:..33332222211111.........11112222233333.
989 17:..333332222211111.......111111222233333.
990 16:...333322222111111......111111222223333.
991 15:...333332222211111111.111111112222233333
992 14:....333332222211111111111111122222233333
993 13:.....33333222221111111111111122222233333
994 12:.....33333322222211111111111222222233333
995 11:......3333332222222111111112222222333333
996 10:.......333333222222221111222222222333333
997 9:........33333322222222222222222222333333
998 8:.........333333222222222222222222333333.
999 7:..........33333332222222222222223333333.
1000 6:...........3333333322222222222233333333.
1001 5:.............3333333333222223333333333..
1002 4:..............33333333333333333333333...
1003 3:................33333333333333333333....
1004 2:..................33333333333333333.....
1005 1:....................33333333333333......
1006 Both the variable argument syntax and the n=[int] syntax must occur
1008 alone in a region descriptor (aside from the optional angle for boxes
1009 and ellipses). They cannot be combined. Thus, it is not valid to pre‐
1010 cede or follow an n=[int] accelerator with more angles or radii, as in
1011 this example:
1012 # INVALID -- one too many angles before a=5 ...
1014 # and no angles are allowed after a=5
1015 PIE 12 12 10 25 50 a=5 85 135
1016 Instead, use three separate specifications, such as:
1018 PIE 12 12 10 25
1020 PIE 12 12 25 50 a=5
1021 PIE 12 12 85 135
1022 The original (IRAF) implementation of region filtering permitted this
1024 looser syntax, but we found it caused more confusion than it was worth
1025 and therefore removed it.
1026 NB: Accelerators may be combined with other shapes in a boolean expres‐
1028 sion in any order. (This is a change starting with funtools v1.1.1.
1029 Prior to this release, the accelerator shape had to be specified last).
1030 The actual region mask id values returned depend on the order in which
1031 the shapes are specified, although the total number of pixels or rows
1032 that pass the filter will be consistent. For this reason, use of accel‐
1033 erators in boolean expressions is discouraged in programs such as func‐
1034 nts, where region mask id values are used to count events or image pix‐
1035 els.
1036 [All region masks displayed in this document were generated using the
1038 fundisp routine and the undocumented "mask=all" argument (with spaced
1039 removed using sed ):
1040 fundisp "funtools/funtest/test40.fits[ANNULUS 25 25 5 10]" mask=all ⎪\
1042 sed 's/ //g'
1043 Note that you must supply an image of the appropriate size -- in this
1045 case, a FITS image of dimension 40x40 is used.]
1046
1048 See funtools(n) for a list of Funtools help pages
1049version 1.4.0 August 15, 2007 reggeometry(n)