1funregions(n) SAORD Documentation funregions(n)
2
6 Regions: Spatial Region Filtering
7
9 This document contains a summary of the user interface for spatial
10 region filtering images and tables.
11
13 Spatial region filtering allows a program to select regions of an image
14 or rows of a table (e.g., X-ray events) to process using simple geomet‐
15 ric shapes and boolean combinations of shapes. When an image is fil‐
16 tered, only pixels found within these shapes are processed. When a ta‐
17 ble is filtered, only rows found within these shapes are processed.
18 Spatial region filtering for images and tables is accomplished by means
20 of region specifications. A region specification consists of one or
21 more region expressions, which are geometric shapes,combined according
22 to the rules of boolean algebra. Region specifications also can con‐
23 tain comments and local/global processing directives.
24 Typically, region specifications are specified using bracket notation
26 appended to the filename of the data being processed:
27 foo.fits[circle(512,512,100)]
29 It is also possible to put region specification inside a file and then
31 pass the filename in bracket notation:
32 foo.fits[@my.reg]
34 When region filters are passed in bracket notation in this manner, the
36 filtering is set up automatically when the file is opened and all pro‐
37 cessing occurs through the filter. Programs also can use the filter
38 library API to open filters explicitly.
39 Region Expressions
41 More specifically, region specifications consist of one or more lines
43 containing:
44 # comment until end of line
46 global keyword=value keyword=value ... # set global value(s)
47 # include the following file in the region descriptor
48 @file
49 # use the FITS image as a mask (cannot be used with other regions)
50 @fitsimage
51 # each region expression contains shapes separated by operators
52 [region_expression1], [region_expression2], ...
53 [region_expression], [region_expression], ...
54 A single region expression consists of:
56 # parens and commas are optional, as is the + sign
58 [+-]shape(num , num , ...) OP1 shape num num num OP2 shape ...
59 e.g.:
61 ([+-]shape(num , num , ...) && shape num num ⎪⎪ shape(num, num)
63 # a comment can come after a region -- reserved for local properties
64 [+-]shape(num , num , ...) # local properties go here, e.g. color=red
65 Thus, a region descriptor consists of one or more region expressions or
67 regions, separated by comas, new-lines, or semi-colons. Each region
68 consists of one or more geometric shapes combined using standard bool‐
69 ean operation. Several types of shapes are supported, including:
70 shape: arguments:
72 ----- ----------------------------------------
73 ANNULUS xcenter ycenter inner_radius outer_radius
74 BOX xcenter ycenter xwidth yheight (angle)
75 CIRCLE xcenter ycenter radius
76 ELLIPSE xcenter ycenter xwidth yheight (angle)
77 FIELD none
78 LINE x1 y1 x2 y2
79 PIE xcenter ycenter angle1 angle2
80 POINT x1 y1
81 POLYGON x1 y1 x2 y2 ... xn yn
82 In addition, the following regions accept accelerator syntax:
84 shape arguments
86 ----- ------------------------------------------
87 ANNULUS xcenter ycenter radius1 radius2 ... radiusn
88 ANNULUS xcenter ycenter inner_radius outer_radius n=[number]
89 BOX xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle)
90 BOX xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle)
91 CIRCLE xcenter ycenter r1 r2 ... rn # same as annulus
92 CIRCLE xcenter ycenter rinner router n=[number] # same as annulus
93 ELLIPSE xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle)
94 ELLIPSE xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle)
95 PIE xcenter ycenter angle1 angle2 (angle3) (angle4) (angle5) ...
96 PIE xcenter ycenter angle1 angle2 (n=[number])
97 POINT x1 y1 x2 y2 ... xn yn
98 Note that the circle accelerators are simply aliases for the annulus
100 accelerators. See region geometry for more information about accelera‐
101 tors.
102 Finally, the following are combinations of pie with different shapes
104 (called "panda" for "Pie AND Annulus") allow for easy specification of
105 radial sections:
106 shape: arguments:
108 ----- ---------
109 PANDA xcen ycen ang1 ang2 nang irad orad nrad # circular
110 CPANDA xcen ycen ang1 ang2 nang irad orad nrad # circular
111 BPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # box
112 EPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # ellipse
113 The panda and cpanda specify combinations of annulus and circle with
115 pie, respectively and give identical results. The bpanda combines box
116 and pie, while epanda combines ellipse and pie. See region geometry
117 for more information about pandas.
118 The following "shapes" are ignored by funtools (generated by ds9):
120 shape: arguments:
122 ----- ---------
123 PROJECTION x1 y1 x2 y2 width # NB: ignored by funtools
124 RULER x1 y1 x2 y2 # NB: ignored by funtools
125 TEXT x y # NB: ignored by funtools
126 GRID # NB: ignored by funtools
127 TILE # NB: ignored by funtools
128 COMPASS # NB: ignored by funtools
129 All arguments to regions are real values; integer values are automati‐
131 cally converted to real where necessary. All angles are in degrees and
132 run from the positive image x-axis to the positive image y-axis. If a
133 rotation angle is part of the associated WCS header, that angle is
134 added implicitly as well.
135 Note that 3-letter abbreviations are supported for all shapes, so that
137 you can specify "circle" or "cir".
138 Columns Used in Region Filtering
140 By default, the x,y values in a region expression refer to the two
142 "image binning" columns, i.e. the columns that would be used to bin the
143 data into an image. For images, these are just the 2 dimensions of the
144 image. For tables, these usually default to x and y but can be changed
145 as required. For example, in Funtools, new binning columns are speci‐
146 fied using a bincols=(col1,col2) statement within the bracket string on
147 the command line.
148 Alternate columns for region filtering can be specified by the syntax:
150 (col1,col2)=region(...)
152 e.g.:
154 (X,Y)=annulus(x,y,ri,ro)
156 (PHA,PI)=circle(x,y,r)
157 (DX,DY)=ellipse(x,y,a,b[,angle])
158 Region Algebra
160 (See also Region Algebra for more complete information.)
162 Region shapes can be combined together using Boolean operators:
164 Symbol Operation Use
166 -------- --------- -----------------------------------
167 ! not Exclude this shape from this region
168 & or && and Include only the overlap of these shapes
169 ⎪ or ⎪⎪ inclusive or Include all of both shapes
170 ^ exclusive or Include both shapes except their overlap
171 Note that the !region syntax must be combined with another region in
173 order that we be able to assign a region id properly. That is,
174 !circle(512,512,10)
176 is not a legal region because there is no valid region id to work with.
178 To get the full field without a circle, combine the above with field(),
179 as in:
180 field() && !circle(512,512,10)
182 Region Separators Also Are Operators
184 As mentioned previously, multiple region expressions can be specified
186 in a region descriptor, separated by commas, new-lines, or semi-colons.
187 When such a separator is used, the boolean OR operator is automatically
188 generated in its place but, unlike explicit use of the OR operator, the
189 region ID is incremented (starting from 1).
190 For example, the two shapes specified in this example are given the
192 same region value:
193 foo.fits[circle(512,512,10)⎪⎪circle(400,400,20)]
195 On the other hand, the two shapes defined in the following example are
197 given different region values:
198 foo.fits[circle(512,512,10),circle(400,400,20)]
200 Of course these two examples will both mask the same table rows or pix‐
202 els. However, in programs that distinguish region id's (such as funcnts
203 ), they will act differently. The explicit OR operator will result in
204 one region expression consisting of two shapes having the same region
205 id and funcnts will report a single region. The comma operator will
206 cause funcnts to report two region expressions, each with one shape, in
207 its output.
208 In general, commas are used to separate region expressions entered in
210 bracket notation on the command line:
211 # regions are added to the filename in bracket notation
213 foo.fits[circle(512,512,100),circle(400,400,20)]
214 New-lines are used to separate region expressions in a file:
216 # regions usually are separated by new-lines in a file
218 # use @filename to include this file on the command line
219 circle(512,512,100)
220 circle(400,400,20)
221 Semi-colons are provided for backward compatibility with the original
223 IRAF/PROS implementation and can be used in either case.
224 If a pixel is covered by two different regions expressions, it is given
226 the mask value of the first region that contains that pixel. That is,
227 successive regions do not overwrite previous regions in the mask, as
228 was the case with the original PROS regions. In this way, an individ‐
229 ual pixel is covered by one and only one region. This means that one
230 must sometimes be careful about the order in which regions are defined.
231 If region N is fully contained within region M, then N should be
232 defined before M, or else it will be "covered up" by the latter.
233 Region Exclusion
235 Shapes also can be globally excluded from all the region specifiers in
237 a region descriptor by using a minus sign before a region:
238 operator arguments:
240 -------- -----------
241 - Globally exclude the region expression following '-' sign
242 from ALL regions specified in this file
243 The global exclude region can be used by itself; in such a case,
245 field() is implied.
246 A global exclude differs from the local exclude (i.e. a shape prefixed
248 by the logical not "!" symbol) in that global excludes are logically
249 performed last, so that no region will contain pixels from a globally
250 excluded shape. A local exclude is used in a boolean expression with an
251 include shape, and only excludes pixels from that include shape.
252 Global excludes cannot be used in boolean expressions.
253 Include Files
255 The @filename directive specifies an include file containing region
257 expressions. This file is processed as part of the overall region
258 descriptor:
259 foo.fits[circle(512,512,10),@foo]
261 A filter include file simply includes text without changing the state
263 of the filter. It therefore can be used in expression. That is, if the
264 file foo1 contains "pi==1" and foo2 contains "pha==2" then the follow‐
265 ing expressions are equivalent:
266 "[@foo1&&@foo2]" is equivalent to "[pi==1&&pha==2]"
268 "[pha==1⎪⎪@foo2]" is equivalent to "[pi==1⎪⎪pha==2]"
269 "[@foo1,@foo2]" is equivalent to "[pi==1,pha==2]"
270 Be careful that you specify evaluation order properly using parenthe‐
272 sis, especially if the include file contains multiple filter state‐
273 ments. For example, consider a file containing two regions such as:
274 circle 512 512 10
276 circle 520 520 10
277 If you want to include only events (or pixels) that are in these
279 regions and have a pi value of 4, then the correct syntax is:
280 pi==4&&(@foo)
282 since this is equivalent to:
284 pi==4 && (circle 512 512 10 ⎪⎪ circle 520 520 10)
286 If you leave out the parenthesis, you are filtering this statement:
288 pi==4 && circle 512 512 10 ⎪⎪ circle 520 520 10)
290 which is equivalent to:
292 (pi==4 && circle 512 512 10) ⎪⎪ circle 520 520 10)
294 The latter syntax only applies the pi test to the first region.
296 For image-style filtering, the @filename can specify an 8-bit or 16-bit
298 FITS image. In this case, the pixel values in the mask image are used
299 as the region mask. The valid pixels in the mask must have positive
300 values. Zero values are excluded from the mask and negative values are
301 not allowed. Moreover, the region id value is taken as the image pixel
302 value and the total number of regions is taken to be the highest pixel
303 value. The dimensions of the image mask must be less than or equal to
304 the image dimensions of the data. The mask will be replicated as needed
305 to match the size of the image. (Thus, best results are obtained when
306 the data dimensions are an even multiple of the mask dimensions.)
307 An image mask can be used in any image filtering operation, regardless
309 of whether the data is of type image or table. For example, the funcnts
310 ) program performs image filtering on images or tables, and so FITS
311 image masks are valid input for either type of data in this program..
312 An image mask cannot be used in a program such as fundisp ) when the
313 input data is a table, because fundisp displays rows of a table and
314 processes these rows using event-style filtering.
315 Global and Local Properties of Regions
317 The ds9 image display program describes a host of properties such as
319 color, font, fix/free state, etc. Such properties can be specified
320 globally (for all regions) or locally (for an individual region). The
321 global keyword specifies properties and qualifiers for all regions,
322 while local properties are specified in comments on the same line as
323 the region:
324 global color=red
326 circle(10,10,2)
327 circle(20,20,3) # color=blue
328 circle(30,30,4)
329 The first and third circles will be red, which the second circle will
331 be blue. Note that funtools currently ignores region properties, as
332 they are used in display only.
333 Coordinate Systems
335 For each region, it is important to specify the coordinate system used
337 to interpret the region, i.e., to set the context in which position and
338 size values are interpreted. For this purpose, the following keywords
339 are recognized:
340 name description
342 ---- ------------------------------------------
343 PHYSICAL pixel coords of original file using LTM/LTV
344 IMAGE pixel coords of current file
345 FK4, B1950 sky coordinate systems
346 FK5, J2000 sky coordinate systems
347 GALACTIC sky coordinate systems
348 ECLIPTIC sky coordinate systems
349 ICRS currently same as J2000
350 LINEAR linear wcs as defined in file
351 AMPLIFIER mosaic coords of original file using ATM/ATV
352 DETECTOR mosaic coords of original file using DTM/DTV
353 Specifying Positions, Sizes, and Angles
355 The arguments to region shapes can be floats or integers describing
357 positions and sizes. They can be specified as pure numbers or using
358 explicit formatting directives:
359 position arguments description
361 ------------------ ------------------------------
362 [num] context-dependent (see below)
363 [num]d degrees
364 [num]r radians
365 [num]p physical pixels
366 [num]i image pixels
367 [num]:[num]:[num] hms for 'odd' position arguments
368 [num]:[num]:[num] dms for 'even' position arguments
369 [num]h[num]m[num]s explicit hms
370 [num]d[num]m[num]s explicit dms
371 size arguments description
373 -------------- -----------
374 [num] context-dependent (see below)
375 [num]" arc seconds
376 [num]' arc minutes
377 [num]d degrees
378 [num]r radians
379 [num]p physical pixels
380 [num]i image pixels
381 When a "pure number" (i.e. one without a format directive such as 'd'
383 for 'degrees') is specified, its interpretation depends on the context
384 defined by the 'coordsys' keyword. In general, the rule is:
385 All pure numbers have implied units corresponding to the current coor‐
387 dinate system.
388 If no such system is explicitly specified, the default system is
390 implicitly assumed to be PHYSICAL.
391 In practice this means that for IMAGE and PHYSICAL systems, pure num‐
393 bers are pixels. Otherwise, for all systems other than linear, pure
394 numbers are degrees. For LINEAR systems, pure numbers are in the units
395 of the linear system. This rule covers both positions and sizes.
396 The input values to each shape can be specified in several coordinate
398 systems including:
399 name description
401 ---- ----------------------------
402 IMAGE pixel coords of current file
403 LINEAR linear wcs as defined in file
404 FK4, B1950 various sky coordinate systems
405 FK5, J2000
406 GALACTIC
407 ECLIPTIC
408 ICRS
409 PHYSICAL pixel coords of original file using LTM/LTV
410 AMPLIFIER mosaic coords of original file using ATM/ATV
411 DETECTOR mosaic coords of original file using DTM/DTV
412 If no coordinate system is specified, PHYSICAL is assumed. PHYSICAL or
414 a World Coordinate System such as J2000 is preferred and most general.
415 The coordinate system specifier should appear at the beginning of the
416 region description, on a separate line (in a file), or followed by a
417 new-line or semicolon; e.g.,
418 global coordsys physical
420 circle 6500 9320 200
421 The use of celestial input units automatically implies WORLD coordi‐
423 nates of the reference image. Thus, if the world coordinate system of
424 the reference image is J2000, then
425 circle 10:10:0 20:22:0 3'
427 is equivalent to:
429 circle 10:10:0 20:22:0 3' # j2000
431 Note that by using units as described above, you may mix coordinate
433 systems within a region specifier; e.g.,
434 circle 6500 9320 3' # physical
436 Note that, for regions which accept a rotation angle:
438 ellipse (x, y, r1, r2, angle) box(x, y, w, h, angle)
440 the angle is relative to the specified coordinate system. In particu‐
442 lar, if the region is specified in WCS coordinates, the angle is
443 related to the WCS system, not x/y image coordinate axis. For WCS sys‐
444 tems with no rotation, this obviously is not an issue. However, some
445 images do define an implicit rotation (e.g., by using a non-zero CROTA
446 value in the WCS parameters) and for these images, the angle will be
447 relative to the WCS axes. In such case, a region specification such as:
448 fk4;ellipse(22:59:43.985, +58:45:26.92,320", 160", 30)
450 will not, in general, be the same region specified as:
452 physical;ellipse(465, 578, 40, 20, 30)
454 even when positions and sizes match. The angle is relative to WCS axes
456 in the first case, and relative to physical x,y axes in the second.
457 More detailed descriptions are available for: Region Geometry, Region
459 Algebra, Region Coordinates, and Region Boundaries.
460
462 See funtools(n) for a list of Funtools help pages
463version 1.4.0 August 15, 2007 funregions(n)