shape: arguments: ANNULUS xcenter ycenter inner_radius outer_radius ANNULUS xcenter ycenter inner_radius outer_radius (n=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.) BOX xcenter ycenter xwidth yheight (optional angle) CIRCLE xcenter ycenter radius ELLIPSE xcenter ycenter xwidth yheight angle FIELD LINE x1 y1 x2 y2 PANDA xcenter ycenter angle1 angle2 nangle iradius oradius nradius PIE xcenter ycenter angle1 angle2 PIE xcenter ycenter angle1 angle2 (n= ) POINT x1 y1 POINT x1 y1 x2 y2 ... xn yn POLYGON x1 y1 x2 y2 ... xn yn
Shapes can be specified using "command" syntax:
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:arg1 arg2 ... or using "routine" syntax: (arg1, arg2, ...)
"foo.fits[CIRCLE 512 512 50;CIR(128 128, 10);cir(650,650,20)]"(Quotes generally are required to protect the region descriptor from being processed by the Unix shell.)
The annulus shape specifies annuli, centered at xcenter, ycenter, with inner and outer radii (r1, r2). For example,
ANNULUS 25 25 5 10specifies an annulus centered at 25.0 25.0 with an inner radius of 5.0 and an outer radius of 10. Assuming (as will be done for all examples in this document, unless otherwise noted) this shape is used in a mask of size 40x40, it will look like this:
1234567890123456789012345678901234567890
----------------------------------------
40:........................................
39:........................................
38:........................................
37:........................................
36:........................................
35:........................................
34:....................111111111...........
33:...................11111111111..........
32:.................111111111111111........
31:.................111111111111111........
30:................11111111111111111.......
29:...............1111111.....1111111......
28:...............111111.......111111......
27:...............11111.........11111......
26:...............11111.........11111......
25:...............11111.........11111......
24:...............11111.........11111......
23:...............11111.........11111......
22:...............111111.......111111......
21:...............1111111.....1111111......
20:................11111111111111111.......
19:.................111111111111111........
18:.................111111111111111........
17:...................11111111111..........
16:....................111111111...........
15:........................................
14:........................................
13:........................................
12:........................................
11:........................................
10:........................................
9:........................................
8:........................................
7:........................................
6:........................................
5:........................................
4:........................................
3:........................................
2:........................................
1:........................................
The box shape specifies an orthogonally oriented box, centered at xcenter, ycenter, of size xwidth, yheight. It requires four arguments and accepts an optional fifth argument to specify a rotation angle. When the rotation angle is specified (in degrees), the box is rotated by an angle that runs counter-clockwise from the positive y-axis.
The box shape specifies a rotated box, centered at xcenter, ycenter, of size xwidth, yheight. The box is rotated by an angle specified in degrees that runs counter-clockwise from the positive y-axis. If the angle argument is omitted, it defaults to 0.
The circle shape specifies a circle, centered at xcenter, ycenter, of radius r. It requires three arguments.
The ellipse shape specifies an ellipse, centered at xcenter, ycenter, with y-axis width a and the y-axis length b defined such that:
x**2/a**2 + y**2/b**2 = 1Note that a can be less than, equal to, or greater than b. The ellipse is rotated the specified number of degrees. The rotation is done according to astronomical convention, counter-clockwise from the positive y-axis. An ellipse defined by:
ELLIPSE 20 20 5 10 45will look like this:
1234567890123456789012345678901234567890
----------------------------------------
40:........................................
39:........................................
38:........................................
37:........................................
36:........................................
35:........................................
34:........................................
33:........................................
32:........................................
31:........................................
30:........................................
29:........................................
28:........................................
27:............111111......................
26:............11111111....................
25:............111111111...................
24:............11111111111.................
23:............111111111111................
22:............111111111111................
21:.............111111111111...............
20:.............1111111111111..............
19:..............111111111111..............
18:...............111111111111.............
17:...............111111111111.............
16:................11111111111.............
15:..................111111111.............
14:...................11111111.............
13:.....................111111.............
12:........................................
11:........................................
10:........................................
9:........................................
8:........................................
7:........................................
6:........................................
5:........................................
4:........................................
3:........................................
2:........................................
1:........................................
The field shape specifies the entire field as a region. It is not usually specified explicitly, but is used implicitly in the case where no regions are specified, that is, in cases where either a null string or some abbreviation of the string "none" is input. Field takes no arguments.
The pie shape specifies an angular wedge of the entire field, centered at xcenter, ycenter. The wedge runs between the two specified angles. The angles are given in degrees, running counter-clockwise from the positive y-axis. For example,
PIE 20 20 90 180defines a region from 90 degrees to 180 degrees, i.e., quadrant 3 of the Cartesian plane. The display of such a region looks like this:
1234567890123456789012345678901234567890
----------------------------------------
40:........................................
39:........................................
38:........................................
37:........................................
36:........................................
35:........................................
34:........................................
33:........................................
32:........................................
31:........................................
30:........................................
29:........................................
28:........................................
27:........................................
26:........................................
25:........................................
24:........................................
23:........................................
22:........................................
21:........................................
20:11111111111111111111....................
19:11111111111111111111....................
18:11111111111111111111....................
17:11111111111111111111....................
16:11111111111111111111....................
15:11111111111111111111....................
14:11111111111111111111....................
13:11111111111111111111....................
12:11111111111111111111....................
11:11111111111111111111....................
10:11111111111111111111....................
9:11111111111111111111....................
8:11111111111111111111....................
7:11111111111111111111....................
6:11111111111111111111....................
5:11111111111111111111....................
4:11111111111111111111....................
3:11111111111111111111....................
2:11111111111111111111....................
1:11111111111111111111....................
The pie slice specified is always a counter-clockwise sweep between
the angles, starting at the first angle and ending at the second. Thus:
PIE 10 15 30 60describes a 30 degree sweep from 11 o'clock to 10 o'clock, while:
PIE 10 15 60 30describes a 330 degree counter-clockwise sweep from 10 o'clock to 11 o'clock passing through 12 o'clock (0 degrees). Note in both of these examples that the center of the slice can be anywhere on the plane. The second mask looks like this:
1234567890123456789012345678901234567890
----------------------------------------
40:1111111111111111111111111111111111111111
39:1111111111111111111111111111111111111111
38:1111111111111111111111111111111111111111
37:1111111111111111111111111111111111111111
36:1111111111111111111111111111111111111111
35:1111111111111111111111111111111111111111
34:1111111111111111111111111111111111111111
33:1111111111111111111111111111111111111111
32:1111111111111111111111111111111111111111
31:1111111111111111111111111111111111111111
30:.111111111111111111111111111111111111111
29:.111111111111111111111111111111111111111
28:..11111111111111111111111111111111111111
27:...1111111111111111111111111111111111111
26:...1111111111111111111111111111111111111
25:....111111111111111111111111111111111111
24:....111111111111111111111111111111111111
23:.....11111111111111111111111111111111111
22:.....11111111111111111111111111111111111
21:......1111111111111111111111111111111111
20:1......111111111111111111111111111111111
19:111....111111111111111111111111111111111
18:1111....11111111111111111111111111111111
17:111111..11111111111111111111111111111111
16:11111111.1111111111111111111111111111111
15:1111111111111111111111111111111111111111
14:1111111111111111111111111111111111111111
13:1111111111111111111111111111111111111111
12:1111111111111111111111111111111111111111
11:1111111111111111111111111111111111111111
10:1111111111111111111111111111111111111111
9:1111111111111111111111111111111111111111
8:1111111111111111111111111111111111111111
7:1111111111111111111111111111111111111111
6:1111111111111111111111111111111111111111
5:1111111111111111111111111111111111111111
4:1111111111111111111111111111111111111111
3:1111111111111111111111111111111111111111
2:1111111111111111111111111111111111111111
1:1111111111111111111111111111111111111111
The pie slice is usually combined with other shapes, such as circles
and annuli, using boolean operations (see below and in "help regalgebra").
Performance Note:
Pie region processing time is proportional to the size of the image, and not the size of the region. This is because the pie shape is the only infinite length shape, and we essentially must check all y rows for inclusion (unlike other regions, where the y limits can be calculated beforehand). Thus, pie can run very slowly on large images. In particular, it will run MUCH more slowly than the panda shape in image-based region operations (such as funcnts). We recommend use of panda over pie where ever possible.
If you must use pie, always try to put it last in a boolean && expression. The reason for this is that the filter code is optimized to exit as soon as the result is know. Since pie is the slowest region, it is better to avoid executing it if another region can decide the result. Consider, for example, the difference in time required to process a Chandra ACIS file when a pie and circle are combined in two different orders:
time ./funcnts nacis.fits "circle 4096 4096 100 && pie 4096 4096 10 78" 2.87u 0.38s 0:35.08 9.2% time ./funcnts nacis.fits "pie 4096 4096 10 78 && circle 4096 4096 100 " 89.73u 0.36s 1:03.50 141.8%
Black-magic performance note:
Panda region processing uses a quick test pie region instead of the normal pie region when combining its annulus and pie shapes. This qtpie shape differs from the normal pie in that it utilizes the y limits from the previous region with which it is combined. In a panda shape, which is a series of annuli combined with pies, the processing time is thus reduced to that of the annuli.
You can use the qtpie shape instead of pie in cases where you are combining pie with another shape using the && operator. This will cause the pie limits to be set using limits from the other shape, and will speed up the processing considerably. For example, the above execution of funcnts can be improved considerably using this technique:
time ./funcnts nacis.fits "circle 4096 4096 100 && qtpie 4096 4096 10 78" 4.66u 0.33s 0:05.87 85.0%
We emphasize that this is a quasi-documented feature and might change in the future. The qtpie shape is not recognized by ds9 or other programs.
The line shape allows single pixels in a line between (x1,y1) and (x2,y2) to be included or excluded. For example: LINE (5,6, 24,25)
1234567890123456789012345678901234567890
----------------------------------------
40:........................................
39:........................................
38:........................................
37:........................................
36:........................................
35:........................................
34:........................................
33:........................................
32:........................................
31:........................................
30:........................................
29:........................................
28:........................................
27:........................................
26:........................................
25:.......................1................
24:......................1.................
23:.....................1..................
22:....................1...................
21:...................1....................
20:..................1.....................
19:.................1......................
18:................1.......................
17:...............1........................
16:..............1.........................
15:.............1..........................
14:............1...........................
13:...........1............................
12:..........1.............................
11:.........1..............................
10:........1...............................
9:.......1................................
8:......1.................................
7:.....1..................................
6:....1...................................
5:........................................
4:........................................
3:........................................
2:........................................
1:........................................
The point shape allows single pixels to be included or excluded. Although the (x,y) values are real numbers, they are truncated to integer and the corresponding pixel is included or excluded, as specified.
Several points can be put in one region declaration; unlike the original IRAF implementation, each now is given a different region mask value. This makes it easier, for example, for funcnts to determine the number of photons in the individual pixels. For example,
POINT (5,6, 10,11, 20,20, 35,30)will give the different region mask values to all four points, as shown below:
1234567890123456789012345678901234567890
----------------------------------------
40:........................................
39:........................................
38:........................................
37:........................................
36:........................................
35:........................................
34:........................................
33:........................................
32:........................................
31:........................................
30:..................................4.....
29:........................................
28:........................................
27:........................................
26:........................................
25:........................................
24:........................................
23:........................................
22:........................................
21:........................................
20:...................3....................
19:........................................
18:........................................
17:........................................
16:........................................
15:........................................
14:........................................
13:........................................
12:........................................
11:.........2..............................
10:........................................
9:........................................
8:........................................
7:........................................
6:....1...................................
5:........................................
4:........................................
3:........................................
2:........................................
1:........................................
The polygon shape specifies a polygon with vertices (x1, y1) ... (xn, yn). The polygon is closed automatically: one should not specify the last vertex to be the same as the first. Any number of vertices are allowed. For example, the following polygon defines a right triangle as shown below:
POLYGON (10,10, 10,30, 30,30)looks like this:
1234567890123456789012345678901234567890
----------------------------------------
40:........................................
39:........................................
38:........................................
37:........................................
36:........................................
35:........................................
34:........................................
33:........................................
32:........................................
31:........................................
30:..........11111111111111111111..........
29:..........1111111111111111111...........
28:..........111111111111111111............
27:..........11111111111111111.............
26:..........1111111111111111..............
25:..........111111111111111...............
24:..........11111111111111................
23:..........1111111111111.................
22:..........111111111111..................
21:..........11111111111...................
20:..........1111111111....................
19:..........111111111.....................
18:..........11111111......................
17:..........1111111.......................
16:..........111111........................
15:..........11111.........................
14:..........1111..........................
13:..........111...........................
12:..........11............................
11:..........1.............................
10:........................................
9:........................................
8:........................................
7:........................................
6:........................................
5:........................................
4:........................................
3:........................................
2:........................................
1:........................................
Note that polygons can get twisted upon themselves if edge lines
cross. Thus:
POL (10,10, 20,20, 20,10, 10,20)will produce an area which is two triangles, like butterfly wings, as shown below:
1234567890123456789012345678901234567890
----------------------------------------
40:........................................
39:........................................
38:........................................
37:........................................
36:........................................
35:........................................
34:........................................
33:........................................
32:........................................
31:........................................
30:........................................
29:........................................
28:........................................
27:........................................
26:........................................
25:........................................
24:........................................
23:........................................
22:........................................
21:........................................
20:........................................
19:..........1........1....................
18:..........11......11....................
17:..........111....111....................
16:..........1111..1111....................
15:..........1111111111....................
14:..........1111..1111....................
13:..........111....111....................
12:..........11......11....................
11:..........1........1....................
10:........................................
9:........................................
8:........................................
7:........................................
6:........................................
5:........................................
4:........................................
3:........................................
2:........................................
1:........................................
PANDA(20,20, 0,360,3, 0,15,4)Here, 3 pie slices centered at 20, 20 are combined with 4 annuli, also centered at 20, 20. The result is a mask with 12 regions (displayed in base 16 to save characters):
1234567890123456789012345678901234567890
----------------------------------------
40:........................................
39:........................................
38:........................................
37:........................................
36:........................................
35:........................................
34:..............444444ccccc...............
33:............44444444ccccccc.............
32:...........444444444cccccccc............
31:.........44444444333bbcccccccc..........
30:........444444333333bbbbbcccccc.........
29:........444443333333bbbbbbccccc.........
28:.......4444433333333bbbbbbbccccc........
27:......44444333333222aabbbbbbccccc.......
26:......44443333322222aaaabbbbbcccc.......
25:.....444433333222222aaaaabbbbbcccc......
24:.....444433332222222aaaaaabbbbcccc......
23:.....44443333222211199aaaabbbbcccc......
22:.....444333322221111999aaaabbbbccc......
21:.....444333322221111999aaaabbbbccc......
20:.....444333322221111999aaaabbbbccc......
19:.....444333322221155599aaaabbbbccc......
18:.....444333322225555555aaaabbbbccc......
17:.....44443333266655555666abbbbcccc......
16:.....444433336666666666666bbbbcccc......
15:.....44443377766666666666777bbcccc......
14:......444877777666666666777778ccc.......
13:......48888777777666667777778888c.......
12:.......8888877777777777777788888........
11:........88888777777777777788888.........
10:........88888877777777777888888.........
9:.........888888887777788888888..........
8:...........88888888888888888............
7:............888888888888888.............
6:..............88888888888...............
5:........................................
4:........................................
3:........................................
2:........................................
1:........................................
Several regions with different mask values can be combined in the same mask. This supports comparing data from the different regions. (For information on how to combine different shapes into a single region, see "help regalgebra".) For example, consider the following set of regions:
ANNULUS 25 25 5 10 ELLIPSE 20 20 5 10 315 BOX 15 15 5 10The resulting mask will look as follows:
1234567890123456789012345678901234567890
----------------------------------------
40:........................................
39:........................................
38:........................................
37:........................................
36:........................................
35:........................................
34:....................111111111...........
33:...................11111111111..........
32:.................111111111111111........
31:.................111111111111111........
30:................11111111111111111.......
29:...............1111111.....1111111......
28:...............111111.......111111......
27:...............11111.222222..11111......
26:...............111112222222..11111......
25:...............111112222222..11111......
24:...............111112222222..11111......
23:...............111112222222..11111......
22:...............111111222222.111111......
21:..............211111112222.1111111......
20:............322211111111111111111.......
19:............32222111111111111111........
18:............22222111111111111111........
17:............222222211111111111..........
16:............22222222111111111...........
15:............222222222...................
14:............22222222....................
13:............222222......................
12:............33333.......................
11:............33333.......................
10:........................................
9:........................................
8:........................................
7:........................................
6:........................................
5:........................................
4:........................................
3:........................................
2:........................................
1:........................................
Note that when a pixel is in 2 or more regions, it is arbitrarily
assigned to a one of the regions in question (often based on how a
give C compiler optimizes boolean expressions).
Two types of \fBaccelerators, to simplify region specification, are
provided as natural extensions to the ways shapes are described.
These are: extended lists of parameters, specifying multiple regions,
valid for annulus and pie; and a form n=
Several annuli at the same center can be specified in one region expression by specifying more than two radii. If N radii are specified, then N-1 annuli result, with the outer radius of each preceding annulus being the inner radius of the succeeding annulus. Each annulus is considered a separate region, and is given a separate mask value. For example,
ANNULUS 20 20 0 2 5 10 15 20specifies five different annuli centered at 20 20, and is equivalent to:
ANNULUS 20.0 20.0 0 2 ANNULUS 20.0 20.0 2 5 ANNULUS 20.0 20.0 5 10 ANNULUS 20.0 20.0 10 15 ANNULUS 20.0 20.0 15 20The mask is shown below:
1234567890123456789012345678901234567890
----------------------------------------
40:........................................
39:.............5555555555555..............
38:...........55555555555555555............
37:.........555555555555555555555..........
36:........55555555555555555555555.........
35:......555555555555555555555555555.......
34:.....55555555544444444444555555555......
33:....5555555544444444444444455555555.....
32:....5555555444444444444444445555555.....
31:...555555444444444444444444444555555....
30:..55555544444444444444444444444555555...
29:..55555544444443333333334444444555555...
28:.5555554444444333333333334444444555555..
27:.5555544444433333333333333344444455555..
26:555555444444333333333333333444444555555.
25:555554444443333333333333333344444455555.
24:555554444433333332222233333334444455555.
23:555554444433333322222223333334444455555.
22:555554444433333222222222333334444455555.
21:555554444433333222111222333334444455555.
20:555554444433333222111222333334444455555.
19:555554444433333222111222333334444455555.
18:555554444433333222222222333334444455555.
17:555554444433333322222223333334444455555.
16:555554444433333332222233333334444455555.
15:555554444443333333333333333344444455555.
14:555555444444333333333333333444444555555.
13:.5555544444433333333333333344444455555..
12:.5555554444444333333333334444444555555..
11:..55555544444443333333334444444555555...
10:..55555544444444444444444444444555555...
9:...555555444444444444444444444555555....
8:....5555555444444444444444445555555.....
7:....5555555544444444444444455555555.....
6:.....55555555544444444444555555555......
5:......555555555555555555555555555.......
4:........55555555555555555555555.........
3:.........555555555555555555555..........
2:...........55555555555555555............
1:.............5555555555555..............
The annulus type also accepts an n=ANNULUS 20 20 0 2 5 20 n=3is equivalent to the last two examples given above. Note that the n=
Specifying several angles in one pie slice expression is equivalent to specifying several separate slices with the same center. As with the annulus, if N angles are specified, then N-1 slices result, with the ending angle of each preceding slice being the starting angle of the succeeding slice. Each slice is considered a separate region, and is given a separate mask value. For example,
PIE 12 12 315 45 115 270specifies three regions as shown below:
1234567890123456789012345678901234567890
----------------------------------------
40:1111111111111111111111111111111111111111
39:111111111111111111111111111111111111111.
38:11111111111111111111111111111111111111..
37:1111111111111111111111111111111111111...
36:111111111111111111111111111111111111....
35:11111111111111111111111111111111111.....
34:1111111111111111111111111111111111......
33:111111111111111111111111111111111.......
32:11111111111111111111111111111111........
31:1111111111111111111111111111111.........
30:111111111111111111111111111111..........
29:11111111111111111111111111111...........
28:1111111111111111111111111111............
27:111111111111111111111111111.............
26:11111111111111111111111111..............
25:1111111111111111111111111...............
24:111111111111111111111111................
23:21111111111111111111111.................
22:2211111111111111111111..................
21:222111111111111111111...................
20:22221111111111111111....................
19:2222211111111111111.....................
18:222222111111111111......................
17:22222221111111111.......................
16:2222222211111111........................
15:222222222111111.........................
14:22222222221111..........................
13:2222222222211...........................
12:2222222222223333333333333333333333333333
11:2222222223333333333333333333333333333333
10:2222222333333333333333333333333333333333
9:2222233333333333333333333333333333333333
8:2223333333333333333333333333333333333333
7:2333333333333333333333333333333333333333
6:3333333333333333333333333333333333333333
5:3333333333333333333333333333333333333333
4:3333333333333333333333333333333333333333
3:3333333333333333333333333333333333333333
2:3333333333333333333333333333333333333333
1:3333333333333333333333333333333333333333
The pie type also accepts the n=# INVALID -- nothing after a=5! PIE 12 12 275 310 50 a=5 85 135Instead, use two separate specifications, such as:
PIE 12 12 275 310 50 a=5 PIE 12 12 50 85 135The original (IRAF) implementation of region filtering permitted this syntax, but we found it caused more confusion than it was worth and therefore removed it. Also note that an extended list of pixels in a point specification is not an accelerator. An accelerator is a way to define multiple regions with a single specification, whereas the points are all given the same mask value.
NB: When a PANDA, an ANNULUS accelerator, or a PIE accelerator is combined with other shapes or filters in a boolean expression, please ensure that the PANDA or accelerator shape is specified last in the expression. Thus:
box(0,0,4,3,60) && (dx,dy)=panda(0,0,0,180,2,0,6,3)is legal syntax, but:
annulus(0,0,0,100,n=3) && box(0,0,4,3,60)is illegal and will generate an error message. [All region masks displayed in this document were generated using the fundisp routine and the undocumented "mask=all" argument:
fundisp "funtools-1.0/funtest/test40.fits[ANNULUS 25 25 5 10]" mask=allNote that you must supply an image of the appropriate size -- in this case, a FITS image of dimension 40x40 is used.]