diff options
Diffstat (limited to 'funtools/doc/regcoords.html')
| -rw-r--r-- | funtools/doc/regcoords.html | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/funtools/doc/regcoords.html b/funtools/doc/regcoords.html new file mode 100644 index 0000000..ff656c2 --- /dev/null +++ b/funtools/doc/regcoords.html @@ -0,0 +1,239 @@ +<!-- =defdoc regcoords regcoords n --> +<HTML> +<HEAD> +<TITLE>Spatial Region Coordinates</TITLE> +</HEAD> +<BODY> + +<!-- =section regcoords NAME --> +<H2><A NAME="regcoords">RegCoords: Spatial Region Coordinates</A></H2> + +<!-- =section regcoords SYNOPSIS --> +<H2>Summary</H2> +<P> +This document describes the specification of coordinate systems, and the +interpretation of coordinate values, for spatial region filtering. + +<!-- =section regcoords DESCRIPTION --> +<H2>Pixel coordinate systems</H2> +<P> +The default coordinate system for regions is PHYSICAL, which means +that region position and size values are taken from the original +data. (Note that this is a change from the original IRAF/PROS +implementation, in which the IMAGE coordinate system was the default.) +PHYSICAL coordinates always refer to pixel positions on the original +image (using IRAF LTM and LTV keywords). With PHYSICAL coordinates, +if a set of coordinates specifies the position of an object in an +original FITS file, the same coordinates will specify the same object +in any FITS derived from the original. Physical coordinates are +invariant with blocking of FITS files or taking sections of images, +even when a blocked section is written to a new file. + +<P> +Thus, although a value in pixels refers, by default, to the PHYSICAL +coordinate system, you may specify that position values refer to the +image coordinate system using the <B>global</B> or <B>local</B> +properties commands: + +<PRE> + global coordsys image + circle 512 512 100 +</PRE> + +The <B>global</B> command changes the coordinate system for all +regions that follow, while the <B>local</B> command changes the +coordinate system only for the region immediately following: +<PRE> + local coordsys image + circle 512 512 100 + circle 1024 1024 200 +</PRE> +This changes the coordinate system only for the region that follows. +In the above example, the second region uses the global coordinate +system (PHYSICAL by default). + +<P> +<H2>World Coordinate Systems</H2> + +If World Coordinate System information is contained in the data file +being filtered, it also is possible to define regions using a sky +coordinate system. Supported systems include: + +<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 +</PRE> + +In addition, two mosaic coordinate systems have been defined that +utilize the (evolving) IRAF mosaic keywords: + +<PRE> + name description + ---- ----------- + AMPLIFIER mosaic coords of original file using ATM/ATV + DETECTOR mosaic coords of original file using DTM/DTV +</PRE> +Again, to use one of these coordinate systems, the <B>global</B> or +<B>local</B> properties commands are used: + +<PRE> + global coordsys galactic +</PRE> + +<H2>WCS Positions and Sizes</H2> + +In addition to pixels, positional values in a WCS-enabled region can +be specified using sexagesimal or degrees format: + +<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 +</PRE> + +If ':' is used as sexagesimal separator, the value is considered to be +specifying hours/minutes/seconds if it is the first argument of a +positional pair, and degrees/minutes/seconds for the second argument +of a pair (except for galactic coordinates, which always use degrees): + +<PRE> + argument description + ----------- ----------- + 10:20:30.0 10 hours, 20 minutes, 30 seconds for 1st positional argument + 10 degrees, 20 minutes, 30 seconds for 2nd positional argument + 10h20m30.0 10 hours, 20 minutes, 30 seconds + 10d20m30.0 10 degrees, 20 minutes, 30 seconds + 10.20d 10.2 degrees +</PRE> + +Similarly, the units of size values are defined by the formating +character(s) attached to a number: + +<PRE> + 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> + +For example: +<PRE> + argument description + ----------- ----------- + 10 ten pixels + 10' ten minutes of arc + 10" ten seconds of arc + 10d ten degrees + 10p ten pixels + 0.5r half of a radian +</PRE> + +<P> +An example of using sky coordinate systems follows: + +<PRE> + global coordsys B1950 + -box 175.54d 20.01156d 10' 10' + local coordsys J2000 + pie 179.57d 22.4d 0 360 n=4 && annulus 179.57d 22.4d 3' 24' n=5 +</PRE> + +At the FK4 1950 coordinates 175.54d RA, 20.01156d DEC exclude a 10 +minute by 10 minute box. Then at the FK5 2000 coordinates 179.57d RA +22.4d DEC draw a radial profile regions pattern with 4 quadrants and 5 +annuli ranging from 3 minutes to 24 minutes in diameter. In this +example, the default coordinate system is overridden by the commands +in the regions spec. + +<H2>NB: The Meaning of Pure Numbers Are Context Sensitive</H2> + +<P> +When a "pure number" (i.e. one without a format directive such as 'd' +for 'degrees') is specified as a position or size, 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 coordinate 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. + +<P> +As a corollary, when a sky-formatted number is used with the IMAGE +or PHYSICAL coordinate system (which includes the default case of no +coordsys being specified), the formatted number is assumed to be in +the units of the WCS contained in the current file. If no sky WCS is +specified, an error results. + +<P> +Examples: + +<PRE> + circle(512,512,10) + ellipse 202.44382d 47.181656d 0.01d 0.02d +</PRE> + +<P> +In the absence of a specified coordinate system, the circle uses the +default PHYSICAL units of pixels, while the ellipse explicitly uses degrees, +presumably to go with the WCS in the current file. + +<PRE> + global coordsys=fk5 + global color=green font="system 10 normal" + circle 202.44382 47.181656 0.01 + circle 202.44382 47.181656 10p + ellipse(512p,512p,10p,15p,20) +</PRE> + + +<P> +Here, the circles use the FK5 units of degrees (except for the +explicit use of pixels in the second radius), while the ellipse +explicitly specifies pixels. The ellipse angle is in degrees. + +<P> +Note that Chandra data format appears to use "coordsys=physical" +implicitly. Therefore, for most Chandra applications, valid regions +can be generated safely by asking ds9 to save/display regions in +pixels using the PHYSICAL coordsys. + +<!-- =section regcoords 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> |