diff options
Diffstat (limited to 'funtools/doc/regions.html')
| -rw-r--r-- | funtools/doc/regions.html | 563 |
1 files changed, 563 insertions, 0 deletions
diff --git a/funtools/doc/regions.html b/funtools/doc/regions.html new file mode 100644 index 0000000..33a8cde --- /dev/null +++ b/funtools/doc/regions.html @@ -0,0 +1,563 @@ +<!-- =defdoc funregions funregions n --> +<HTML> +<HEAD> +<TITLE>Spatial Region Filtering</TITLE> +</HEAD> +<BODY> + +<!-- =section funregions NAME --> +<H2><A NAME="regions">Regions: Spatial Region Filtering</A></H2> + +<!-- =section funregions SYNOPSIS --> +<H2>Summary</H2> +<P> +This document contains a summary of the user interface for spatial +region filtering images and tables. + +<!-- =section funregions DESCRIPTION --> +<H2>Description</H2> +<P> +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. + +<P> +Spatial region filtering for images and tables is accomplished by +means of <B>region specifications</B>. A region specification +consists of one or more <B>region expressions</B>, which are geometric +shapes,combined according to the rules of boolean algebra. Region +specifications also can contain comments and local/global processing +directives. + +<P> +Typically, region specifications are specified using bracket notation +appended to the filename of the data being processed: +<PRE> + foo.fits[circle(512,512,100)] +</PRE> +It is also possible to put region specification inside a file and +then pass the filename in bracket notation: +<PRE> + foo.fits[@my.reg] +</PRE> + +<P> +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. + +<H2>Region Expressions</H2> + +More specifically, region specifications consist of one or more lines +containing: +<PRE> + # 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], ... +</PRE> + +<P> +A single region expression consists of: +<PRE> + # 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 +</PRE> + +<P> +Thus, a region descriptor consists of one or more <B>region +expressions</B> or <B>regions</B>, separated by comas, new-lines, or +semi-colons. Each <B>region</B> consists of one or more <B>geometric +shapes</B> combined using standard boolean operation. Several types +of shapes are supported, including: + +<PRE> + shape: arguments: + ----- ---------------------------------------- + ANNULUS xcenter ycenter inner_radius outer_radius + BOX xcenter ycenter xwidth yheight (angle) + CIRCLE xcenter ycenter radius + ELLIPSE xcenter ycenter xwidth yheight (angle) + FIELD none + LINE x1 y1 x2 y2 + PIE xcenter ycenter angle1 angle2 + POINT x1 y1 + POLYGON x1 y1 x2 y2 ... xn yn +</PRE> + +<P> +In addition, the following regions accept <B>accelerator</B> syntax: + +<PRE> + shape arguments + ----- ------------------------------------------ + ANNULUS xcenter ycenter radius1 radius2 ... radiusn + ANNULUS xcenter ycenter inner_radius outer_radius n=[number] + BOX xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle) + BOX xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle) + CIRCLE xcenter ycenter r1 r2 ... rn # same as annulus + CIRCLE xcenter ycenter rinner router n=[number] # same as annulus + ELLIPSE xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle) + ELLIPSE xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle) + PIE xcenter ycenter angle1 angle2 (angle3) (angle4) (angle5) ... + PIE xcenter ycenter angle1 angle2 (n=[number]) + POINT x1 y1 x2 y2 ... xn yn +</PRE> +Note that the circle accelerators are simply aliases for the annulus +accelerators. See <A HREF="./reggeometry.html">region geometry</A> +for more information about accelerators. + +<P> +Finally, the following are combinations of pie with different shapes +(called "panda" for "Pie AND Annulus") allow for easy specification of +radial sections: + +<PRE> + shape: arguments: + ----- --------- + PANDA xcen ycen ang1 ang2 nang irad orad nrad # circular + CPANDA xcen ycen ang1 ang2 nang irad orad nrad # circular + BPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # box + EPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # ellipse +</PRE> + +The 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 <A HREF="./reggeometry.html">region geometry</A> +for more information about pandas. + +<P> +The following "shapes" are ignored by funtools (generated by ds9): +<PRE> + 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 +</PRE> + +<P> +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. + +<P> +Note that 3-letter abbreviations are supported for all shapes, so that +you can specify "circle" or "cir". + +<P> +<H2>Columns Used in Region Filtering</H2> +<P> +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. +<P> +Alternate columns for region filtering can be specified by the syntax: +<PRE> + (col1,col2)=region(...) +</PRE> +e.g.: +<PRE> + (X,Y)=annulus(x,y,ri,ro) + (PHA,PI)=circle(x,y,r) + (DX,DY)=ellipse(x,y,a,b[,angle]) +</PRE> + +<P> +<H2>Region Algebra</H2> + +(See also <A HREF="./regalgebra.html">Region Algebra</A> for more complete +information.) + +<P> +Region shapes can be combined together using Boolean operators: +<PRE> + 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 +</PRE> +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, +<PRE> + !circle(512,512,10) +</PRE> +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: +<PRE> + field() && !circle(512,512,10) +</PRE> + +<H2> Region Separators Also Are Operators</H2> + +<P> +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). + +<P> +For example, the two shapes specified in this example are given the +same region value: +<PRE> + foo.fits[circle(512,512,10)||circle(400,400,20)] +</PRE> +On the other hand, the two shapes defined in the following example are +given different region values: +<PRE> + foo.fits[circle(512,512,10),circle(400,400,20)] +</PRE> + +<P> +Of course these two examples will both mask the same table rows or +pixels. However, in programs that distinguish region id's (such as +<A HREF="programs.html#funcnts">funcnts</A> ), 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. + +<P> +In general, commas are used to separate region expressions entered +in bracket notation on the command line: +<PRE> + # regions are added to the filename in bracket notation + foo.fits[circle(512,512,100),circle(400,400,20)] +</PRE> +New-lines are used to separate region +expressions in a file: +<PRE> + # 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) +</PRE> +Semi-colons are provided for backward compatibility with the original +IRAF/PROS implementation and can be used in either case. + +<P> +If a pixel is covered by two different regions expressions, it is +given the mask value of the <B>first</B> region that contains that +pixel. That is, successive regions <B>do not</b> 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</B> M, or else it will be +"covered up" by the latter. + +<H2>Region Exclusion</H2> +<P> +Shapes also can be globally excluded from all the region specifiers in +a region descriptor by using a minus sign before a region: + +<PRE> + operator arguments: + -------- ----------- + - Globally exclude the region expression following '-' sign + from ALL regions specified in this file +</PRE> +The global exclude region can be used by itself; in such a case, field() is +implied. + +<P> +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. + +<H2>Include Files</H2> + +<P> +The <B>@filename</B> directive specifies an include file +containing region expressions. This file is processed as part of +the overall region descriptor: +<PRE> + foo.fits[circle(512,512,10),@foo] +</PRE> +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: +<pre> + "[@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]" +</pre> +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: +<pre> + circle 512 512 10 + circle 520 520 10 +</pre> +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: +<pre> + pi==4&&(@foo) +</pre> +since this is equivalent to: +<pre> + pi==4 && (circle 512 512 10 || circle 520 520 10) +</pre> +If you leave out the parenthesis, you are filtering this statement: +<pre> + pi==4 && circle 512 512 10 || circle 520 520 10) +</pre> +which is equivalent to: +<pre> + (pi==4 && circle 512 512 10) || circle 520 520 10) +</pre> +The latter syntax only applies the pi test to the first region. + +<P> +For image-style filtering, the <B>@filename</B> 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.) + +<P> +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 +<A HREF="programs.html#funcnts">funcnts</A> ) +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 +<A HREF="programs.html#fundisp">fundisp</A> ) +when the input data is a table, because fundisp displays +rows of a table and processes these rows using event-style filtering. + +<H2>Global and Local Properties of Regions</H2> + +<P> +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</B> keyword specifies properties and qualifiers for all +regions, while local properties are specified in comments on the same +line as the region: +<PRE> + global color=red + circle(10,10,2) + circle(20,20,3) # color=blue + circle(30,30,4) +</PRE> +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. + +<H2> Coordinate Systems</H2> + +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: + +<PRE> + 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 +</PRE> + +<P> +<H2>Specifying Positions, Sizes, and Angles</H2> + +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: + +<PRE> + 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 +</PRE> + +<!- this helps emacs close the open quote " > +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: + +<P> +<B>All pure numbers have implied units corresponding to the current +coordinate system.</B> + +<P> +If no such system is explicitly specified, the default system is +implicitly assumed to be PHYSICAL. + +<P> +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. + +<P> +The input values to each shape can be specified in several coordinate +systems including: + +<PRE> + 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 +</PRE> + +<P> +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., + +<PRE> + global coordsys physical + circle 6500 9320 200 +</PRE> + +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 + +<PRE> + circle 10:10:0 20:22:0 3' +</PRE> + +is equivalent to: + +<PRE> + circle 10:10:0 20:22:0 3' # j2000 +</PRE> + +</PRE> +Note that by using units as described above, you may mix coordinate +systems within a region specifier; e.g., + +<PRE> + circle 6500 9320 3' # physical +</PRE> + +<P> +Note that, for regions which accept a rotation angle: + +<PRE> +ellipse (x, y, r1, r2, angle) +box(x, y, w, h, angle) +</PRE> + +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: + +<PRE> +fk4;ellipse(22:59:43.985, +58:45:26.92,320", 160", 30) +</PRE> + +will not, in general, be the same region specified as: + +<PRE> +physical;ellipse(465, 578, 40, 20, 30) +</PRE> + +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. + + +<P> +More detailed descriptions are available for: +<A HREF="./reggeometry.html">Region Geometry</A>, +<A HREF="./regalgebra.html">Region Algebra</A>, +<A HREF="./regcoords.html">Region Coordinates</A>, and +<A HREF="./regbounds.html">Region Boundaries</A>. + +<!-- =section funregions SEE ALSO --> +<!-- =text See funtools(n) for a list of Funtools help pages --> +<!-- =stop --> + +<P> +<A HREF="./help.html">Go to Funtools Help Index</A> + +<H5>Last updated: November 17, 2005</H5> + +</BODY> +</HTML> |