diff options
Diffstat (limited to 'funtools/doc/pod/regcoords.pod')
-rw-r--r-- | funtools/doc/pod/regcoords.pod | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/funtools/doc/pod/regcoords.pod b/funtools/doc/pod/regcoords.pod new file mode 100644 index 0000000..a026a5c --- /dev/null +++ b/funtools/doc/pod/regcoords.pod @@ -0,0 +1,247 @@ +=pod + +=head1 NAME + + + +B<RegCoords: Spatial Region Coordinates> + + + +=head1 SYNOPSIS + + + + + +This document describes the specification of coordinate systems, and the +interpretation of coordinate values, for spatial region filtering. + + + +=head1 DESCRIPTION + + + +B<Pixel coordinate systems> + +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. + + +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> or B<local> +properties commands: + + + global coordsys image + circle 512 512 100 + + +The B<global> command changes the coordinate system for all +regions that follow, while the B<local> command changes the +coordinate system only for the region immediately following: + + local coordsys image + circle 512 512 100 + circle 1024 1024 200 + +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). + + +B<World Coordinate Systems> + +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: + + + 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 + + +In addition, two mosaic coordinate systems have been defined that +utilize the (evolving) IRAF mosaic keywords: + + + name description + ---- ----------- + AMPLIFIER mosaic coords of original file using ATM/ATV + DETECTOR mosaic coords of original file using DTM/DTV + +Again, to use one of these coordinate systems, the B<global> or +B<local> properties commands are used: + + + global coordsys galactic + + +B<WCS Positions and Sizes> + +In addition to pixels, positional values in a WCS-enabled region can +be specified using sexagesimal or degrees format: + + + 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 + + +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): + + + 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 + + +Similarly, the units of size values are defined by the formating +character(s) attached to a number: + + + 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 + + +For example: + + 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 + + + +An example of using sky coordinate systems follows: + + + 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 + + +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. + +B<NB: The Meaning of Pure Numbers Are Context Sensitive> + + +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: + + +All pure numbers have implied units corresponding to the current +coordinate system. + + +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. + + +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. + + +Examples: + + + circle(512,512,10) + ellipse 202.44382d 47.181656d 0.01d 0.02d + + + +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. + + + 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) + + + + +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. + + +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. + + + +=head1 SEE ALSO + + + +See funtools(n) for a list of Funtools help pages + + + +=cut |