diff options
Diffstat (limited to 'doc/pod/funregions.pod')
| -rw-r--r-- | doc/pod/funregions.pod | 571 |
1 files changed, 571 insertions, 0 deletions
diff --git a/doc/pod/funregions.pod b/doc/pod/funregions.pod new file mode 100644 index 0000000..7f975ad --- /dev/null +++ b/doc/pod/funregions.pod @@ -0,0 +1,571 @@ +=pod + +=head1 NAME + + + +B<Regions: Spatial Region Filtering> + + + +=head1 SYNOPSIS + + + + + +This document contains a summary of the user interface for spatial +region filtering images and tables. + + + +=head1 DESCRIPTION + + + + + +Spatial region filtering allows a program to select regions of an +image or rows of a table (e.g., X-ray events) to process using +simple geometric shapes and boolean combinations of shapes. When an +image is filtered, only pixels found within these shapes are +processed. When a table is filtered, only rows found within these +shapes are processed. + + +Spatial region filtering for images and tables is accomplished by +means of B<region specifications>. A region specification +consists of one or more B<region expressions>, which are geometric +shapes,combined according to the rules of boolean algebra. Region +specifications also can contain comments and local/global processing +directives. + + +Typically, region specifications are specified using bracket notation +appended to the filename of the data being processed: + + foo.fits[circle(512,512,100)] + +It is also possible to put region specification inside a file and +then pass the filename in bracket notation: + + foo.fits[@my.reg] + + + +When region filters are passed in bracket notation in this manner, the +filtering is set up automatically when the file is opened and all +processing occurs through the filter. Programs also can use the filter +library API to open filters explicitly. + +B<Region Expressions> + +More specifically, region specifications consist of one or more lines +containing: + + # comment until end of line + global keyword=value keyword=value ... # set global value(s) + # include the following file in the region descriptor + @file + # use the FITS image as a mask (cannot be used with other regions) + @fitsimage + # each region expression contains shapes separated by operators + [region_expression1], [region_expression2], ... + [region_expression], [region_expression], ... + + + +A single region expression consists of: + + # parens and commas are optional, as is the + sign + [+-]shape(num , num , ...) OP1 shape num num num OP2 shape ... + +e.g.: + + ([+-]shape(num , num , ...) && shape num num || shape(num, num) + # a comment can come after a region -- reserved for local properties + [+-]shape(num , num , ...) # local properties go here, e.g. color=red + + + +Thus, a region descriptor consists of one or more region +expressions or B<regions>, separated by comas, new-lines, or +semi-colons. Each B<region> consists of one or more geometric +shapes combined using standard boolean operation. Several types +of shapes are supported, including: + + + shape: arguments: + ----- ---------------------------------------- + ANNULUS xcenter ycenter inner_radius outer_radius + BOX xcenter ycenter xwidth yheight (angle) + CIRCLE xcenter ycenter radius + ELLIPSE xcenter ycenter xwidth yheight (angle) + FIELD none + LINE x1 y1 x2 y2 + PIE xcenter ycenter angle1 angle2 + POINT x1 y1 + POLYGON x1 y1 x2 y2 ... xn yn + + + +In addition, the following regions accept B<accelerator> syntax: + + + shape arguments + ----- ------------------------------------------ + ANNULUS xcenter ycenter radius1 radius2 ... radiusn + ANNULUS xcenter ycenter inner_radius outer_radius n=[number] + BOX xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle) + BOX xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle) + CIRCLE xcenter ycenter r1 r2 ... rn # same as annulus + CIRCLE xcenter ycenter rinner router n=[number] # same as annulus + ELLIPSE xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle) + ELLIPSE xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle) + PIE xcenter ycenter angle1 angle2 (angle3) (angle4) (angle5) ... + PIE xcenter ycenter angle1 angle2 (n=[number]) + POINT x1 y1 x2 y2 ... xn yn + +Note that the circle accelerators are simply aliases for the annulus +accelerators. See region geometry +for more information about accelerators. + + +Finally, the following are combinations of pie with different shapes +(called "panda" for "Pie AND Annulus") allow for easy specification of +radial sections: + + + shape: arguments: + ----- --------- + PANDA xcen ycen ang1 ang2 nang irad orad nrad # circular + CPANDA xcen ycen ang1 ang2 nang irad orad nrad # circular + BPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # box + EPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # ellipse + + +The panda and cpanda specify combinations of annulus and circle with pie, +respectively and give identical results. The bpanda combines box and pie, +while epanda combines ellipse and pie. +See region geometry +for more information about pandas. + + +The following "shapes" are ignored by funtools (generated by ds9): + + shape: arguments: + ----- --------- + PROJECTION x1 y1 x2 y2 width # NB: ignored by funtools + RULER x1 y1 x2 y2 # NB: ignored by funtools + TEXT x y # NB: ignored by funtools + GRID # NB: ignored by funtools + TILE # NB: ignored by funtools + COMPASS # NB: ignored by funtools + + + +All arguments to regions are real values; integer values are +automatically converted to real where necessary. All angles are in +degrees and run from the positive image x-axis to the positive image +y-axis. If a rotation angle is part of the associated WCS header, that +angle is added implicitly as well. + + +Note that 3-letter abbreviations are supported for all shapes, so that +you can specify "circle" or "cir". + + +B<Columns Used in Region Filtering> + +By default, the x,y values in a region expression refer to the two +"image binning" columns, i.e. the columns that would be used to +bin the data into an image. For images, these are just the 2 dimensions +of the image. For tables, these usually default to x and y but +can be changed as required. For example, in Funtools, new binning +columns are specified using a bincols=(col1,col2) statement within +the bracket string on the command line. + +Alternate columns for region filtering can be specified by the syntax: + + (col1,col2)=region(...) + +e.g.: + + (X,Y)=annulus(x,y,ri,ro) + (PHA,PI)=circle(x,y,r) + (DX,DY)=ellipse(x,y,a,b[,angle]) + + + +B<Region Algebra> + +(See also Region Algebra for more complete +information.) + + +Region shapes can be combined together using Boolean operators: + + Symbol Operation Use + -------- --------- ----------------------------------- + ! not Exclude this shape from this region + & or && and Include only the overlap of these shapes + | or || inclusive or Include all of both shapes + ^ exclusive or Include both shapes except their overlap + +Note that the !region syntax must be combined with another region in order +that we be able to assign a region id properly. That is, + + !circle(512,512,10) + +is not a legal region because there is no valid region id to work with. +To get the full field without a circle, combine the above with field(), +as in: + + field() && !circle(512,512,10) + + +B< Region Separators Also Are Operators> + + +As mentioned previously, multiple region expressions can be specified +in a region descriptor, separated by commas, new-lines, or +semi-colons. When such a separator is used, the boolean OR operator +is automatically generated in its place but, unlike explicit use of +the OR operator, the region ID is incremented (starting from 1). + + +For example, the two shapes specified in this example are given the +same region value: + + foo.fits[circle(512,512,10)||circle(400,400,20)] + +On the other hand, the two shapes defined in the following example are +given different region values: + + foo.fits[circle(512,512,10),circle(400,400,20)] + + + +Of course these two examples will both mask the same table rows or +pixels. However, in programs that distinguish region id's (such as +funcnts ), they will act +differently. The explicit OR operator will result in one region +expression consisting of two shapes having the same region id and +funcnts will report a single region. The comma operator will cause +funcnts to report two region expressions, each with one shape, in +its output. + + +In general, commas are used to separate region expressions entered +in bracket notation on the command line: + + # regions are added to the filename in bracket notation + foo.fits[circle(512,512,100),circle(400,400,20)] + +New-lines are used to separate region +expressions in a file: + + # regions usually are separated by new-lines in a file + # use @filename to include this file on the command line + circle(512,512,100) + circle(400,400,20) + +Semi-colons are provided for backward compatibility with the original +IRAF/PROS implementation and can be used in either case. + + +If a pixel is covered by two different regions expressions, it is +given the mask value of the B<first> region that contains that +pixel. That is, successive regions B<do not> overwrite previous +regions in the mask, as was the case with the original PROS regions. +In this way, an individual pixel is covered by one and only one +region. This means that one must sometimes be careful about the order +in which regions are defined. If region N is fully contained within +region M, then N should be defined B<before> M, or else it will be +"covered up" by the latter. + +B<Region Exclusion> + +Shapes also can be globally excluded from all the region specifiers in +a region descriptor by using a minus sign before a region: + + + operator arguments: + -------- ----------- + - Globally exclude the region expression following '-' sign + from ALL regions specified in this file + +The global exclude region can be used by itself; in such a case, field() is +implied. + + +A global exclude differs from the local exclude (i.e. a shape prefixed +by the logical not "!" symbol) in that global excludes are logically +performed last, so that no region will contain pixels from a globally +excluded shape. A local exclude is used in a boolean expression with +an include shape, and only excludes pixels from that include shape. +Global excludes cannot be used in boolean expressions. + +B<Include Files> + + +The B<@filename> directive specifies an include file +containing region expressions. This file is processed as part of +the overall region descriptor: + + foo.fits[circle(512,512,10),@foo] + +A filter include file simply includes text without changing the state +of the filter. It therefore can be used in expression. That is, if the +file foo1 contains "pi==1" and foo2 contains "pha==2" then +the following expressions are equivalent: + + "[@foo1&&@foo2]" is equivalent to "[pi==1&&pha==2]" + "[pha==1||@foo2]" is equivalent to "[pi==1||pha==2]" + "[@foo1,@foo2]" is equivalent to "[pi==1,pha==2]" + +Be careful that you specify evaluation order properly using +parenthesis, especially if the include file contains multiple +filter statements. For example, consider a file containing two +regions such as: + + circle 512 512 10 + circle 520 520 10 + +If you want to include only events (or pixels) that are in these regions +and have a pi value of 4, then the correct syntax is: + + pi==4&&(@foo) + +since this is equivalent to: + + pi==4 && (circle 512 512 10 || circle 520 520 10) + +If you leave out the parenthesis, you are filtering this statement: + + pi==4 && circle 512 512 10 || circle 520 520 10) + +which is equivalent to: + + (pi==4 && circle 512 512 10) || circle 520 520 10) + +The latter syntax only applies the pi test to the first region. + + +For image-style filtering, the B<@filename> can specify an 8-bit +or 16-bit FITS image. In this case, the pixel values in the mask image +are used as the region mask. The valid pixels in the mask must have +positive values. Zero values are excluded from the mask and negative +values are not allowed. Moreover, the region id value is taken as +the image pixel value and the total number of regions is taken to be +the highest pixel value. The dimensions of the image mask must be less +than or equal to the image dimensions of the data. The mask will be +replicated as needed to match the size of the image. (Thus, best +results are obtained when the data dimensions are an even multiple of +the mask dimensions.) + + +An image mask can be used in any image filtering operation, regardless +of whether the data is of type image or table. For example, the +funcnts ) +program performs image filtering on images or tables, and so +FITS image masks are valid input for either type of data in this +program.. An image mask cannot be used in a program such as +fundisp ) +when the input data is a table, because fundisp displays +rows of a table and processes these rows using event-style filtering. + +B<Global and Local Properties of Regions> + + +The ds9 image display program describes a host of properties such as +color, font, fix/free state, etc. Such properties can be specified +globally (for all regions) or locally (for an individual region). +The B<global> keyword specifies properties and qualifiers for all +regions, while local properties are specified in comments on the same +line as the region: + + global color=red + circle(10,10,2) + circle(20,20,3) # color=blue + circle(30,30,4) + +The first and third circles will be red, which the second circle will +be blue. Note that funtools currently ignores region properties, as +they are used in display only. + +B< Coordinate Systems> + +For each region, it is important to specify the coordinate system +used to interpret the region, i.e., to set the context in which position and +size values are interpreted. For this purpose, the following keywords +are recognized: + + + name description + ---- ------------------------------------------ + PHYSICAL pixel coords of original file using LTM/LTV + IMAGE pixel coords of current file + FK4, B1950 sky coordinate systems + FK5, J2000 sky coordinate systems + GALACTIC sky coordinate systems + ECLIPTIC sky coordinate systems + ICRS currently same as J2000 + LINEAR linear wcs as defined in file + AMPLIFIER mosaic coords of original file using ATM/ATV + DETECTOR mosaic coords of original file using DTM/DTV + + + +B<Specifying Positions, Sizes, and Angles> + +The arguments to region shapes can be floats or integers describing +positions and sizes. They can be specified as pure numbers or using +explicit formatting directives: + + + position arguments description + ------------------ ------------------------------ + [num] context-dependent (see below) + [num]d degrees + [num]r radians + [num]p physical pixels + [num]i image pixels + [num]:[num]:[num] hms for 'odd' position arguments + [num]:[num]:[num] dms for 'even' position arguments + [num]h[num]m[num]s explicit hms + [num]d[num]m[num]s explicit dms + + size arguments description + -------------- ----------- + [num] context-dependent (see below) + [num]" arc seconds + [num]' arc minutes + [num]d degrees + [num]r radians + [num]p physical pixels + [num]i image pixels + + + +When a "pure number" (i.e. one without a format directive such as 'd' +for 'degrees') is specified, its interpretation depends on the context +defined by the 'coordsys' keyword. In general, the rule is: + + +All pure numbers have implied units corresponding to the current +coordinate system. + + +If no such system is explicitly specified, the default system is +implicitly assumed to be PHYSICAL. + + +In practice this means that for IMAGE and PHYSICAL systems, pure +numbers are pixels. Otherwise, for all systems other than linear, +pure numbers are degrees. For LINEAR systems, pure numbers are in the +units of the linear system. This rule covers both positions and +sizes. + + +The input values to each shape can be specified in several coordinate +systems including: + + + name description + ---- ---------------------------- + IMAGE pixel coords of current file + LINEAR linear wcs as defined in file + FK4, B1950 various sky coordinate systems + FK5, J2000 + GALACTIC + ECLIPTIC + ICRS + PHYSICAL pixel coords of original file using LTM/LTV + AMPLIFIER mosaic coords of original file using ATM/ATV + DETECTOR mosaic coords of original file using DTM/DTV + + + +If no coordinate system is specified, PHYSICAL is assumed. PHYSICAL or +a World Coordinate System such as J2000 is preferred and most general. +The coordinate system specifier should appear at the beginning of the +region description, on a separate line (in a file), or followed by a +new-line or semicolon; e.g., + + + global coordsys physical + circle 6500 9320 200 + + +The use of celestial input units automatically implies WORLD +coordinates of the reference image. Thus, if the world coordinate +system of the reference image is J2000, then + + + circle 10:10:0 20:22:0 3' + + +is equivalent to: + + + circle 10:10:0 20:22:0 3' # j2000 + + + +Note that by using units as described above, you may mix coordinate +systems within a region specifier; e.g., + + + circle 6500 9320 3' # physical + + + +Note that, for regions which accept a rotation angle: + + +ellipse (x, y, r1, r2, angle) +box(x, y, w, h, angle) + + +the angle is relative to the specified coordinate system. In +particular, if the region is specified in WCS coordinates, the angle +is related to the WCS system, not x/y image coordinate axis. For WCS +systems with no rotation, this obviously is not an issue. However, +some images do define an implicit rotation (e.g., by using a non-zero +CROTA value in the WCS parameters) and for these images, the angle +will be relative to the WCS axes. In such case, a region specification +such as: + + +fk4;ellipse(22:59:43.985, +58:45:26.92,320", 160", 30) + + +will not, in general, be the same region specified as: + + +physical;ellipse(465, 578, 40, 20, 30) + + +even when positions and sizes match. The angle is relative to WCS axes +in the first case, and relative to physical x,y axes in the second. + + + +More detailed descriptions are available for: +Region Geometry, +Region Algebra, +Region Coordinates, and +Region Boundaries. + + + +=head1 SEE ALSO + + + +See funtools(n) for a list of Funtools help pages + + + +=cut |