diff options
Diffstat (limited to 'funtools/man/man7')
| -rw-r--r-- | funtools/man/man7/funcombine.7 | 248 | ||||
| -rw-r--r-- | funtools/man/man7/funds9.7 | 216 | ||||
| -rw-r--r-- | funtools/man/man7/funenv.7 | 352 | ||||
| -rw-r--r-- | funtools/man/man7/funfiles.7 | 802 | ||||
| -rw-r--r-- | funtools/man/man7/funfilters.7 | 464 | ||||
| -rw-r--r-- | funtools/man/man7/funidx.7 | 327 | ||||
| -rw-r--r-- | funtools/man/man7/funregions.7 | 678 | ||||
| -rw-r--r-- | funtools/man/man7/funtext.7 | 713 | ||||
| -rw-r--r-- | funtools/man/man7/funtools.7 | 379 | ||||
| -rw-r--r-- | funtools/man/man7/funview.7 | 523 | ||||
| -rw-r--r-- | funtools/man/man7/regalgebra.7 | 400 | ||||
| -rw-r--r-- | funtools/man/man7/regbounds.7 | 305 | ||||
| -rw-r--r-- | funtools/man/man7/regcoords.7 | 345 | ||||
| -rw-r--r-- | funtools/man/man7/regdiff.7 | 181 | ||||
| -rw-r--r-- | funtools/man/man7/reggeometry.7 | 1271 |
15 files changed, 0 insertions, 7204 deletions
diff --git a/funtools/man/man7/funcombine.7 b/funtools/man/man7/funcombine.7 deleted file mode 100644 index b2e5dc4..0000000 --- a/funtools/man/man7/funcombine.7 +++ /dev/null @@ -1,248 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funcombine 7" -.TH funcombine 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunCombine \- Combining Region and Table Filters -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document discusses the conventions for combining region and table -filters, especially with regards to the comma operator. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBComma Conventions\fR -.PP -Filter specifications consist of a series of boolean expressions, -separated by commas. These expressions can be table filters, -spatial region filters, or combinations thereof. Unfortunately, -common usage requires that the comma operator must act differently -in different situations. Therefore, while its use is intuitive in -most cases, commas can be a source of confusion. -.PP -According to long-standing usage in \s-1IRAF\s0, when a comma separates two -table filters, it takes on the meaning of a boolean \fBand\fR. Thus: -.PP -.Vb 1 -\& foo.fits[pha==1,pi==2] -.Ve -.PP -is equivalent to: -.PP -.Vb 1 -\& foo.fits[pha==1 && pi==2] -.Ve -.PP -When a comma separates two spatial region filters, however, it has -traditionally taken on the meaning of a boolean \fBor\fR. Thus: -.PP -.Vb 1 -\& foo.fits[circle(10,10,3),ellipse(20,20,8,5)] -.Ve -.PP -is equivalent to: -.PP -.Vb 1 -\& foo.fits[circle(10,10,3) || ellipse(20,20,8,5)] -.Ve -.PP -(except that in the former case, each region is given a unique id -in programs such as funcnts). -.PP -Region and table filters can be combined: -.PP -.Vb 1 -\& foo.fits[circle(10,10,3),pi=1:5] -.Ve -.PP -or even: -.PP -.Vb 1 -\& foo.fits[pha==1&&circle(10,10,3),pi==2&&ellipse(20,20,8,5)] -.Ve -.PP -In these cases, it is not obvious whether the command should utilize an -\&\fBor\fR or \fBand\fR operator. We therefore arbitrarily chose to -implement the following rule: -.IP "\(bu" 4 -if both expressions contain a region, the operator used is \fBor\fR. -.IP "\(bu" 4 -if one (or both) expression(s) does not contain a region, the operator -used is \fBand\fR. -.PP -This rule handles the cases of pure regions and pure column filters properly. -It unambiguously assigns the boolean \fBand\fR to all mixed cases. Thus: -.PP -.Vb 1 -\& foo.fits[circle(10,10,3),pi=1:5] -.Ve -.PP -and -.PP -.Vb 1 -\& foo.fits[pi=1:5,circle(10,10,3)] -.Ve -.PP -both are equivalent to: -.PP -.Vb 1 -\& foo.fits[circle(10,10,3) && pi=1:5] -.Ve -.PP -[\s-1NB:\s0 This arbitrary rule \fBreplaces the previous arbitrary rule\fR -(pre\-funtools 1.2.3) which stated: -.IP "\(bu" 4 -if the 2nd expression contains a region, the operator used is \fBor\fR. -.IP "\(bu" 4 -if the 2nd expression does not contain a region, the operator -used is \fBand\fR. -.PP -In that scenario, the \fBor\fR operator was implied by: -.PP -.Vb 1 -\& pha==4,circle 5 5 1 -.Ve -.PP -while the \fBand\fR operator was implied by -.PP -.Vb 1 -\& circle 5 5 1,pha==4 -.Ve -.PP -Experience showed that this non-commutative treatment of the comma -operator was confusing and led to unexpected results.] -.PP -The comma rule must be considered provisional: comments and complaints -are welcome to help clarify the matter. Better still, we recommend -that the comma operator be avoided in such cases in favor of an -explicit boolean operator. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funds9.7 b/funtools/man/man7/funds9.7 deleted file mode 100644 index 963084a..0000000 --- a/funtools/man/man7/funds9.7 +++ /dev/null @@ -1,216 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funds9 7" -.TH funds9 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunDS9 \- Funtools and DS9 Image Display -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -Describes how funtools can be integrated into the ds9 Analysis menu. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -SAOImage/DS9 is an astronomical imaging and data visualization -application used by astronomers around the world. \s-1DS9\s0 can display -standard astronomical \s-1FITS\s0 images and binary tables, but also has -support for displaying raw array files, shared memory files, and data -files automatically retrieved via \s-1FTP\s0 and \s-1HTTP\s0. Standard functional -capabilities include multiple frame buffers, colormap and region -manipulation, and many data scaling algorithms. \s-1DS9\s0's advanced -features include TrueColor visuals, deep frame buffers, true -PostScript printing, and display of image mosaics. The program's -support of image tiling, \*(L"blinking\*(R", arbitrary zoom, rotation, and pan -is unparalleled in astronomy. It also has innovative support for -automatic retrieval and display of standard image data such as the -Digital Sky Survey (using servers at \s-1SAO\s0, StScI, or \s-1ESO\s0). -.PP -\&\s-1DS9\s0 can communicate with external programs such as Funtools using the -\&\s-1XPA\s0 -messaging system. In addition, programs can be integrated directly -into the \s-1DS9\s0 \s-1GUI\s0 by means of a configurable Analysis menu. By -default, the \s-1DS9\s0 Analysis menu contains algorithms deemed essential to -the core functions of \s-1DS9\s0, e.g., display cross-cuts of data, -iso-intensity contours, and \s-1WCS\s0 grids. However, new programs can be -added to \s-1DS9\s0 by creating a set-up file which can be loaded into \s-1DS9\s0 -to reconfigure the Analysis menu. -.PP -The basic format of the analysis set-up file is: -.PP -.Vb 6 -\& # -\& # Analysis command descriptions: -\& # menu label/description -\& # file templates for this command -\& # "menu" (add to menu) |"bind" (bind to key) -\& # analysis command line -.Ve -.PP -For example, the funcnts program can be specified in this way: -.PP -.Vb 4 -\& Funcnts (counts in source/bkgd regions; options: none) -\& * -\& menu -\& funcnts $filename $regions(source,,) $regions(background,,) | $text -.Ve -.PP -As shown above, \s-1DS9\s0 supports a macro facility to provide information -as well as task support to command lines. For example, the \f(CW$regions\fR -macro is expanded by \s-1DS9\s0 to provide the current source and/or -background region to the analysis command. The \f(CW$text\fR macro is expanded -to generate a text window display. It also is possible to query for -parameters using a \f(CW$param\fR macro, plot data using a \f(CW$plot\fR macro, -etc. See the \s-1DS9\s0 documentation for further details. -.PP -A set-up file called funtools.ds9 will -load some useful Funtools applications (counts in regions, radial -profile, X\-ray light curve and energy spectrum, 1D histogram) into the \s-1DS9\s0 -Analysis menu (version 2.1 and above). The file resides in the bin -directory where Funtools programs are installed. It can be manually -loaded into \s-1DS9\s0 from the \fBLoad Analysis Commands ...\fR option of -the \fBAnalysis\fR menu. Alternatively, you can tell \s-1DS9\s0 to load -this file automatically at start-up time by adding the pathname to the -\&\fBEdit\fR\->\fBPreferences\fR\->\fBAnalysis Menu\fR\->Analysis -File menu option. (\s-1NB:\s0 make sure you select -\&\fBEdit\fR\->\fBPreferences\fR\->\fBSave Preferences\fR after setting -the pathname.) -.PP -The tasks in this setup file generally process the original disk-based -\&\s-1FITS\s0 file. Funcnts-based results (radial profile, counts in regions) -are presented in \s-1WCS\s0 units, if present in the \s-1FITS\s0 header. For -situations where a disk file is not available (e.g., image data -generated and sent to \s-1DS9\s0's 'fits' \s-1XPA\s0 access point), versions of the -radial profile and counts in regions tasks also are also offered -utilizing \s-1DS9\s0's internal image data. Results are presented in pixels. -Aside from the units, the results should be identical to the file-based -results. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funenv.7 b/funtools/man/man7/funenv.7 deleted file mode 100644 index 4b29218..0000000 --- a/funtools/man/man7/funenv.7 +++ /dev/null @@ -1,352 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funenv 7" -.TH funenv 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunEnv \- Funtools Environment Variables -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -Describes the environment variables which can be used to tailor the overall -Funtools environment. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The following environment variables are supported by Funtools: -.IP "\(bu" 4 -\&\fB\s-1FITS_EXTNAME\s0\fR -.Sp -The \fB\s-1FITS_EXTNAME\s0\fR environment variable specifies the -default \s-1FITS\s0 extension name when \fIFunOpen()\fR is called on a file lacking -a primary image. Thus, -.Sp -.Vb 1 -\& setenv FITS_EXTNAME "NEWEV" -.Ve -.Sp -will allow you to call \fIFunOpen()\fR on files without specifying \s-1NEWEV\s0 in -the -Funtools bracket specification. -If no \s-1FITS_EXTNAME\s0 variable is defined and the extension name also is -not passed in the bracket specification, then the default will be to -look for standard X\-ray event table extension names \*(L"\s-1EVENTS\s0\*(R" or -\&\*(L"\s-1STDEVT\s0\*(R" (we are, after all, and X\-ray astronomy group at heart!). -.IP "\(bu" 4 -\&\fB\s-1FITS_EXTNUM\s0\fR -.Sp -The \fB\s-1FITS_EXTNUM\s0\fR environment variable specifies the -default \s-1FITS\s0 extension number when \fIFunOpen()\fR is called on a file lacking -a primary image. Thus, -.Sp -.Vb 1 -\& setenv FITS_EXTNUM 7 -.Ve -.Sp -will allow you to call \fIFunOpen()\fR on files to open the seventh -extension without specifying the number in the -Funtools bracket specification. -.IP "\(bu" 4 -\&\fB\s-1FITS_BINCOLS\s0\fR and \fB\s-1EVENTS_BINCOLS\s0\fR -.Sp -These environment variable specifies the default binning key for -\&\s-1FITS\s0 binary tables and raw event files, respectively. They can be -over-ridden using the \fBbincols=[naxis1,naxis2]\fR keyword in a -Funtools bracket specification. -The value of each environment variable -is a pair of comma-delimited columns, enclosed in parentheses, to use -for binning. For example, if you want to bin on detx and dety by -default, then use: -.Sp -.Vb 1 -\& setenv FITS_BINCOLS "(detx,dety)" -.Ve -.Sp -in preference to adding a bincols specification to each filename: -.Sp -.Vb 1 -\& foo.fits[bincols=(detx,dety)] -.Ve -.IP "\(bu" 4 -\&\fB\s-1FITS_BITPIX\s0\fR and \fB\s-1EVENTS_BITPIX\s0\fR -.Sp -These environment variable specifies the default bitpix value for -binning \s-1FITS\s0 binary tables and raw event files, respectively. They can -be over-ridden using the \fBbitpix=[value]\fR keyword in a -Funtools bracket specification. The value -of each environment variable is one of the standard \s-1FITS\s0 bitpix values -(8,16,32,\-32,\-64). For example, if you want binning routines to -create a floating array, then use: -.Sp -.Vb 1 -\& setenv FITS_BITPIX \-32 -.Ve -.Sp -in preference to adding a bitpix specification to each filename: -.Sp -.Vb 1 -\& foo.fits[bitpix=-32] -.Ve -.IP "\(bu" 4 -\&\fB\s-1ARRAY\s0\fR -.Sp -The \fB\s-1ARRAY\s0\fR environment variable specifies the default -definition of an array file for Funtools. -It is used if there is no array specification passed in the -\&\fB\s-1\f(BIARRAY\s0()\fB\fR directive in a -Non-FITS Array specification. -The value of the environment variable is a valid array specification such as: -.Sp -.Vb 2 -\& setenv ARRAY "s100.150" -\& foo.arr[ARRAY()] -.Ve -.Sp -This can be defined in preference to adding the specification to each filename: -.Sp -.Vb 1 -\& foo.arr[ARRAY(s100.150)] -.Ve -.IP "\(bu" 4 -\&\fB\s-1EVENTS\s0\fR -.Sp -The \fB\s-1EVENTS\s0\fR environment variable specifies the default -definition of an raw event file for Funtools. -It is used if there is no \s-1EVENTS\s0 specification passed in the -\&\fB\s-1\f(BIEVENTS\s0()\fB\fR directive in a -Non-FITS \s-1EVENTS\s0 specification. -The value of the environment variable is a valid \s-1EVENTS\s0 specification such as: -.Sp -.Vb 2 -\& setenv EVENTS "x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024" -\& foo.ev[EVENTS()] -.Ve -.Sp -This can be defined in preference to adding the specification to each filename: -.Sp -.Vb 1 -\& foo.ev[EVENTS(x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024)] -.Ve -.PP -The following filter-related environment variables are supported by Funtools: -.IP "\(bu" 4 -\&\fB\s-1FILTER_PTYPE\s0\fR -.Sp -The \fB\s-1FILTER_PTYPE\s0\fR environment variable specifies how to -build a filter. There are three possible methods: -.RS 4 -.IP "\(bu" 4 -process or p -.Sp -The filter is compiled and linked against the funtools library (which -must therefore be accessible in the original install directory) to produce -a slave program. This program is fed events or image data and returns -filter results. -.IP "\(bu" 4 -dynamic or d (gcc only) -.Sp -The filter is compiled and linked against the funtools library (which -must therefore be accessible in the original install directory) to produce -a dynamic shared object, which is loaded into the funtools program and -executed as a subroutine. (Extensive testing has shown that, contrary to -expectations, this method is no faster than using a slave process.) -.IP "\(bu" 4 -contained or c -.Sp -The filter and all supporting region code is compiled and linked -without reference to the funtools library to produce a slave program -(which is fed events or image data and returns filter results). This method -is slower than the other two, because of the time it takes to compile the -region filtering code. It is used by stand-alone programs such as ds9, -which do not have access to the funtools library. -.RE -.RS 4 -.Sp -By default, \fBdynamic\fR is generally used for gcc compilers and -\&\fBprocess\fR for other compilers. However the filter building algorithm -will check for required external files and will use \fBcontained\fR is -these are missing. -.RE -.IP "\(bu" 4 -\&\fB\s-1FUN_MAXROW\s0\fR -.Sp -The \fB\s-1FUN_MAXROW\s0\fR environment variable is used by core -row-processing Funtools programs (funtable, fundisp, funcnts, funhist, -funmerge, and funcalc) to set the maximum number of rows read at once -(i.e. it sets the third argument to the \fIFunTableRowGet()\fR call). The -default is 8192. Note that this variable is a convention only: it will -not be a part of a non-core Funtools program unless code is explicitly -added, since each call to \fIFunTableRowGet()\fR specifies its own maximum -number of rows to read. \s-1NB:\s0 if you make this value very large, you -probably will need to increase \fB\s-1FUN_MAXBUFSIZE\s0\fR (see below) as well. -.IP "\(bu" 4 -\&\fB\s-1FUN_MAXBUFSIZE\s0\fR -.Sp -The \fB\s-1FUN_MAXBUFSIZE\s0\fR environment variable is used to limit the -max buffer size that will be allocated to hold table row data. This -buffer size is calculated to be the row size of the table multiplied -by the maximum number of rows read at once (see above). Since the -row size is unlimited (and we have examples of it being larger than 5 -Mb), it is possible that the total buffer size will exceed the machine -capabilities. We therefore set a default value of 5Mb for the max buffer -size, and adjust maxrow so that the total size calculated is less than -this max buffer size. (If the row size is greater than this max buffer -size, then maxrow is set to 1.) This environment variable will change -the max buffer size allowed. -.IP "\(bu" 4 -\&\fB\s-1FILTER_CC\s0\fR -.Sp -The \fB\s-1FILTER_CC\s0\fR environment variable specifies the compiler to -use for compiling a filter specification. You also can use the \fB\s-1CC\s0\fR -environment variable. If neither has been set, then gcc will be used -if available. Otherwise cc is used if available. -.IP "\(bu" 4 -\&\fB\s-1FILTER_EXTRA\s0\fR -.Sp -The \fB\s-1FILTER_EXTRA\s0\fR environment variable specifies extra options -to add to a filter compile command line. In principle, you can add libraries, -include files, and compiler switches. This variable should be used with care. -.IP "\(bu" 4 -\&\fB\s-1FILTER_TMPDIR\s0\fR -.Sp -The \fB\s-1FILTER_TMPDIR\s0\fR environment variable specifies the temporary -directory for filter compilation intermediate files. You also can use -the \fB\s-1TMPDIR\s0\fR and \fB\s-1TMP\s0\fR variables. By default, /tmp is used -as the temporary directory. -.IP "\(bu" 4 -\&\fB\s-1FILTER_KEEP\s0\fR -.Sp -The \fB\s-1FILTER_KEEP\s0\fR environment variable specifies whether the -intermediate filter files (i.e. C source file and compile log file) -should be saved after a filter is built. The default is \*(L"false\*(R", so that -these intermediate files are deleted. This variable is useful for debugging, -but care should be taken to reset its value to false when debugging is -complete. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funfiles.7 b/funtools/man/man7/funfiles.7 deleted file mode 100644 index f401833..0000000 --- a/funtools/man/man7/funfiles.7 +++ /dev/null @@ -1,802 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funfiles 7" -.TH funfiles 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunFiles \- Funtools Data Files -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document describes the data file formats (\s-1FITS\s0, array, raw -events) as well as the file types (gzip, socket, etc.) supported -by Funtools. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Funtools supports \s-1FITS\s0 images and binary tables, and binary files -containing array (homogeneous) data or event (heterogeneous) data. -IRAF-style brackets are appended to the filename to specify various -kinds of information needed to characterize these data: -.PP -.Vb 3 -\& file[ext|ind|ARRAY()|EVENTS(),section][filters] -\& or -\& file[ext|ind|ARRAY()|EVENTS(),section,filters] -.Ve -.PP -where: -.IP "\(bu" 4 -\&\fBfile\fR is the Funtools file name -.IP "\(bu" 4 -\&\fBext\fR is the \s-1FITS\s0 extension name -.IP "\(bu" 4 -\&\fBind\fR is the \s-1FITS\s0 extension number -.IP "\(bu" 4 -\&\fB\s-1\f(BIARRAY\s0()\fB\fR is an array specification -.IP "\(bu" 4 -\&\fB\s-1\f(BIEVENTS\s0()\fB\fR is an event specification -.IP "\(bu" 4 -\&\fBsection\fR is the image section specification -.IP "\(bu" 4 -\&\fBfilters\fR are spatial region and table (row) filters -.PP -\&\fBSupported Data Formats\fR -.PP -Funtools programs (and the underlying libraries) support the -following data file formats: -.IP "\(bu" 4 -\&\s-1FITS\s0 images (and image extensions) -.IP "\(bu" 4 -\&\s-1FITS\s0 binary tables -.IP "\(bu" 4 -binary files containing an array of homogeneous data -.IP "\(bu" 4 -binary files containing events, i.e. records of heterogeneous data -.IP "\(bu" 4 -column-based text files, which are documented here -.IP "\(bu" 4 -non-disk files and lists of files -.PP -Information needed to identify and characterize -the event or image data can be specified on the command line -using IRAF-style bracket notation appended to the filename: -.PP -.Vb 5 -\& foo.fits # open FITS default extension -\& image.fits[3] # open FITS extension #3 -\& events.fits[EVENTS] # open EVENTS extension -\& array.file[ARRAY(s1024)] # open 1024x1024 short array -\& events.file[EVENTS(x:1024,y:1024...)] # open non-FITS event list -.Ve -.PP -Note that in many Unix shells (e.g., csh and tcsh), filenames must -be enclosed in quotes to protect the brackets from shell processing. -.PP -\&\fB\s-1FITS\s0 Images and Binary Tables\fR -.PP -When \fIFunOpen()\fR opens a \s-1FITS\s0 file -without a bracket specifier, the default behavior is to look for a -valid image in the primary \s-1HDU\s0. In the absence of a primary image, -Funtools will try to open an extension named either \fB\s-1EVENTS\s0\fR or -\&\fB\s-1STDEVT\s0\fR, if one of these exists. This default behavior supports -both \s-1FITS\s0 image processing and standard X\-ray event list processing -(which, after all, is what we at \s-1SAO/HEAD\s0 do). -.PP -In order to open a \s-1FITS\s0 binary table or image extension explicitly, it -is necessary to specify either the extension name or the extension -number in brackets: -.PP -.Vb 3 -\& foo.fits[1] # open extension #1: the primary HDU -\& foo.fits[3] # open extension #3 of a FITS file -\& foo.fits[GTI] # open GTI extension of a FITS file -.Ve -.PP -The ext argument specifies the name of the \s-1FITS\s0 extension (i.e. the -value of the \s-1EXTENSION\s0 header parameter in a \s-1FITS\s0 extension), while -the index specifies the value of the \s-1FITS\s0 \s-1EXTVER\s0 header parameter. -Following \s-1FITS\s0 conventions, extension numbers start at 1. -.PP -When a \s-1FITS\s0 data file is opened for reading using -\&\fIFunOpen()\fR, the specified extension -is automatically located and is used to initialize the Funtools internal -data structures. -.PP -\&\fBNon-FITS Raw Event Files\fR -.PP -In addition to \s-1FITS\s0 tables, Funtools programs and libraries can operate -on non-FITS files containing heterogeneous event records. To specify -such an event file, use: -.IP "\(bu" 4 -file[\s-1EVENTS\s0(event\-spec)] -.IP "\(bu" 4 -file[\s-1\fIEVENTS\s0()\fR] -.PP -where \fBevent-spec\fR is a string that specified the names, data -types, and optional image dimensions for each element of the event -record: -.IP "\(bu" 4 -[name]:[n][type]:[(lodim:)hidim] -.PP -Data types follow standard conventions for \s-1FITS\s0 binary tables, but include -two extra unsigned types ('U' and 'V'): -.IP "\(bu" 4 -\&\fBB\fR \*(-- unsigned 8-bit char -.IP "\(bu" 4 -\&\fBI\fR \*(-- signed 16-bit int -.IP "\(bu" 4 -\&\fBJ\fR \*(-- signed 32-bit int -.IP "\(bu" 4 -\&\fBK\fR \*(-- signed 64-bit int -.IP "\(bu" 4 -\&\fBE\fR \*(-- 32-bit float -.IP "\(bu" 4 -\&\fBD\fR \*(-- 64-bit float -.IP "\(bu" 4 -\&\fBU\fR \*(-- unsigned 16-bit int -.IP "\(bu" 4 -\&\fBV\fR \*(-- unsigned 32-bit int -.PP -An optional integer value \fBn\fR can be prefixed to the type to indicate -that the element is an array of n values. For example: -.PP -.Vb 1 -\& foo.fits[EVENTS(x:I,y:I,status:4J)] -.Ve -.PP -defines x and y as 16-bit ints and status as an array of 4 32-bit ints. -.PP -Furthermore, image dimensions can be attached to the event specification -in order to tell Funtools how to bin the events into an image. They -follow the conventions for the \s-1FITS\s0 \s-1TLMIN/TLMAX\s0 keywords. If the low -image dimension is not specified, it defaults to 1. Thus: -.IP "\(bu" 4 -\&\s-1RAWX:J:1:100\s0 -.IP "\(bu" 4 -\&\s-1RAWX:J:100\s0 -.PP -both specify that the dimension of this column runs from 1 to 100. -.PP -\&\s-1NB:\s0 it is required that all padding be specified in the record -definition. Thus, when writing out whole C structs instead of -individual record elements, great care must be taken to include -the compiler-added padding in the event definition. -.PP -For example, suppose a \s-1FITS\s0 binary table has the following set of column -definitions: -.PP -.Vb 22 -\& TTYPE1 = 'X ' / Label for field -\& TFORM1 = '1I ' / Data type for field -\& TLMIN1 = 1 / Min. axis value -\& TLMAX1 = 10 / Max. axis value -\& TTYPE2 = 'Y ' / Label for field -\& TFORM2 = '1I ' / Data type for field -\& TLMIN2 = 2 / Min. axis value -\& TLMAX2 = 11 / Max. axis value -\& TTYPE3 = 'PHA ' / Label for field -\& TFORM3 = '1I ' / Data type for field -\& TTYPE4 = 'PI ' / Label for field -\& TFORM4 = '1J ' / Data type for field -\& TTYPE5 = 'TIME ' / Label for field -\& TFORM5 = '1D ' / Data type for field -\& TTYPE6 = 'DX ' / Label for field -\& TFORM6 = '1E ' / Data type for field -\& TLMIN6 = 1 / Min. axis value -\& TLMAX6 = 10 / Max. axis value -\& TTYPE7 = 'DY ' / Label for field -\& TFORM7 = '1E ' / Data type for field -\& TLMIN7 = 3 / Min. axis value -\& TLMAX7 = 12 / Max. axis value -.Ve -.PP -An raw event file containing these same data would have the event -specification: -.PP -.Vb 1 -\& EVENTS(X:I:10,Y:I:2:11,PHA:I,PI:J,TIME:D,DX:E:10,DY:E:3:12) -.Ve -.PP -If no event specification string is included within the \s-1\fIEVENTS\s0()\fR operator, -then the event specification is taken from the \fB\s-1EVENTS\s0\fR environment -variable: -.PP -.Vb 1 -\& setenv EVENTS "X:I:10,Y:I:10,PHA:I,PI:J,TIME:D,DX:E:10,DY:E:10" -.Ve -.PP -In addition to knowing the data structure, it is necessary to know the -\&\fIendian\fR ordering of the data, i.e., whether or not the data is -in \fIbigendian\fR format, so that we can convert to the native -format for this platform. This issue does not arise for \s-1FITS\s0 Binary -Tables because all \s-1FITS\s0 files use big-endian ordering, regardless of -platform. But for non-FITS data, big-endian data produced on a Sun -workstation but read on a Linux \s-1PC\s0 needs to be byte\-swapped, since PCs -use little-endian ordering. To specify an ordering, use the -\&\fIbigendian=\fR or \fIendian=\fR keywords on the command-line -or the \s-1EVENTS_BIGENDIAN\s0 or \s-1EVENTS_ENDIAN\s0 environment variables. The -value of the \fIbigendian\fR variables should be \*(L"true\*(R" or \*(L"false\*(R", -while the value of the \fIendian\fR variables should be \*(L"little\*(R" or -\&\*(L"big\*(R". -.PP -For example, a \s-1PC\s0 can access data produced by a Sun using: -.PP -.Vb 7 -\& hrc.nepr[EVENTS(),bigendian=true] -\&or -\& hrc.nepr[EVENTS(),endian=big] -\&or -\& setenv EVENTS_BIGENDIAN true -\&or -\& setenv EVENTS_ENDIAN big -.Ve -.PP -If none of these are specified, the data are assumed to follow the -format for that platform and no byte-swapping is performed. -.PP -\&\fBNon-FITS Array Files\fR -.PP -In addition to \s-1FITS\s0 images, Funtools programs and libraries can operate -on non-FITS files containing arrays of homogeneous data. To specify -an array file, use: -.IP "\(bu" 4 -file[\s-1ARRAY\s0(array\-spec)] -.IP "\(bu" 4 -file[\s-1\fIARRAY\s0()\fR] -.PP -where array-spec is of the form: -.IP "\(bu" 4 -[type][dim1][.dim2][:skip][endian] -.PP -and where [type] is: -.IP "\(bu" 4 -b (8-bit unsigned char) -.IP "\(bu" 4 -s (16-bit short int) -.IP "\(bu" 4 -u (16-bit unsigned short int) -.IP "\(bu" 4 -i (32-bit int) -.IP "\(bu" 4 -r,f (32-bit float) -.IP "\(bu" 4 -d (64-bit float) -.PP -The dim1 specification is required, but dim2 is optional and defaults -to dim1. The skip specification is optional and defaults to 0. The -optional endian specification can be 'l' or 'b' and defaults to the -endian type for the current machine. -.PP -If no array specification is included within the \s-1\fIARRAY\s0()\fR operator, -then the array specification is taken from the \fB\s-1ARRAY\s0\fR environment -variable. For example: -.PP -.Vb 7 -\& foo.arr[ARRAY(r512)] # bitpix=-32 dim1=512 dim2=512 -\& foo.arr[ARRAY(r512.400)] # bitpix=-32 dim1=512 dim2=400 -\& foo.arr[ARRAY(r512.400]) # bitpix=-32 dim1=512 dim2=400 -\& foo.arr[ARRAY(r512.400:2880)] # bitpix=-32 dim1=512 dim2=400 skip=2880 -\& foo.arr[ARRAY(r512l)] # bitpix=-32 dim1=512 dim2=512 endian=little -\& setenv ARRAY "r512.400:2880" -\& foo.arr[ARRAY()] # bitpix=-32 dim1=512 dim2=400 skip=2880 -.Ve -.PP -\&\fBSpecifying Image Sections\fR -.PP -Once a data file (and possibly, a \s-1FITS\s0 extension) has been specified, -the next (optional) part of a bracket specification can be used to -select image \fBsection\fR information, i.e., to specify the x,y -limits of an image section, as well as the blocking factor to apply to -that section. This information can be added to any file specification but -only is used by Funtools image processing routines. -.PP -The format of the image section specification is one of the following: -.IP "\(bu" 4 -file[xy0:xy1,block] -.IP "\(bu" 4 -file[x0:x1,y0:y1,block] -.IP "\(bu" 4 -file[x0:x1,*,block] -.IP "\(bu" 4 -file[*,y0:y1,block] -.IP "\(bu" 4 -file[*,block] -.PP -where the limit values can be ints or \*(L"*\*(R" for default. A single \*(L"*\*(R" -can be used instead of val:val, as shown. Note that blocking is -applied to the section after it is extracted. -.PP -In addition to image sections specified by the lo and hi x,y limits, image -sections using center positions can be specified: -.IP "\(bu" 4 -file[dim1@xcen,dim2@ycen] -.IP "\(bu" 4 -file[xdim2@xcen@ycen] -.IP "\(bu" 4 -file[dim1@xcen,dim2@ycen,block] -.IP "\(bu" 4 -file[dim@xcen@ycen,block] -.PP -Note that the (float) values for dim, dim1, dim2, xcen, ycen must be -specified or else the expression does not make sense! -.PP -In all cases, block is optional and defaults to 1. An 's' or 'a' can -be appended to signify \*(L"sum\*(R" or \*(L"average\*(R" blocking (default is \*(L"sum\*(R"). -Section specifications are given in image coordinates by default. If you -wish to specify physical coordinates, add a 'p' as the last character -of the section specification, before the closing bracket. -For example: -.IP "\(bu" 4 -file[\-8:\-7,\-8:\-7p] -.IP "\(bu" 4 -file[\-8:\-7,\-8:\-7,2p] -.PP -A section can be specified in any Funtools file name. If the operation -to be applied to that file is an imaging operation, then the -specification will be utilized. If the operation is purely a table -operation, then the section specification is ignored. -.PP -Do not be confused by: -.PP -.Vb 2 -\& foo.fits[2] -\& foo.fits[*,2] -.Ve -.PP -The former specifies opening the second extension of the \s-1FITS\s0 file. -The latter specifies application of block 2 to the image section. -.PP -Note that the section specification must come after -any of \s-1FITS\s0 \fBext\fR name or \fBind\fR number, -but all sensible defaults are supported: -.IP "\(bu" 4 -file[ext] -.IP "\(bu" 4 -file[ext,index] -.IP "\(bu" 4 -file[index] -.IP "\(bu" 4 -file[ext,section] -.IP "\(bu" 4 -file[ext,index,section] -.IP "\(bu" 4 -file[index,section] -.IP "\(bu" 4 -file[section] -.PP -\&\fBBinning \s-1FITS\s0 Binary Tables and Non-FITS Event Files\fR -.PP -If a \s-1FITS\s0 binary table or a non-FITS raw event file is to be binned -into a 2D image (e.g., using the -funimage -program), it is necessary to specify the two columns to be used for the -binning, as well as the dimensions of the image. Funtools first looks -for a specifier of the form: -.PP -.Vb 1 -\& bincols=([xnam[:tlmin[:tlmax:[binsiz]]]],[ynam[:tlmin[:tlmax[:binsiz]]]]) -.Ve -.PP -in bracket syntax, and uses the column names thus specified. The tlmin, tlmax, -and binsiz specifiers determine the image binning dimensions using: -.PP -.Vb 2 -\& dim = (tlmax - tlmin)/binsiz (floating point data) -\& dim = (tlmax - tlmin)/binsiz + 1 (integer data) -.Ve -.PP -These tlmin, tlmax, and binsiz specifiers can be omitted if \s-1TLMIN\s0, -\&\s-1TLMAX\s0, and \s-1TDBIN\s0 header parameters are present in the \s-1FITS\s0 binary -table header, respectively. If only one parameter is specified, it is -assumed to be tlmax, and tlmin defaults to 1. If two parameters are -specified, they are assumed to be tlmin and tlmax. -.PP -For example, to bin an \s-1HRC\s0 event list columns \*(L"\s-1VPOS\s0\*(R" and \*(L"\s-1UPOS\s0\*(R", use: -.PP -.Vb 1 -\& hrc.nepr[bincols=(VPOS,UPOS)] -.Ve -.PP -or -.PP -.Vb 1 -\& hrc.nepr[bincols=(VPOS:49152,UPOS:4096)] -.Ve -.PP -Note that you can optionally specify the dimensions of these columns -to cover cases where neither \s-1TLMAX\s0 keywords are defined in -the header. If either dimension is specified, then both must be specified. -.PP -You can set the \s-1FITS_BINCOLS\s0 or \s-1EVENTS_BINCOLS\s0 environment variable as -an alternative to adding the \*(L"bincols=\*(R" specifier to each file name -for \s-1FITS\s0 binary tables and raw event files, respectively. If no -binning keywords or environment variables are specified, or if the -specified columns are not in the binary table, the Chandra parameters -\&\s-1CPREF\s0 (or \s-1PREFX\s0) are searched for in the \s-1FITS\s0 binary table header. -Failing this, columns named \*(L"X\*(R" and \*(L"Y\*(R" are sought. If these are not -found, the code looks for columns containing the characters \*(L"X\*(R" and -\&\*(L"Y\*(R". Thus, you can bin on \*(L"\s-1DETX\s0\*(R" and \*(L"\s-1DETX\s0\*(R" columns without -specifying them, if these are the only column names containing the \*(L"X\*(R" -and \*(L"Y\*(R" characters. -.PP -Ordinarily, each event or row contributes one count to an image pixel -during the 2D binning process. Thus, if five events all have the same -(x,y) position, the image pixel value for that position will have a -value of five. It is possible to specify a variable contribution -for each event by using the vcol=[colname] filter spec: -.PP -.Vb 1 -\& vcol=[colname] -.Ve -.PP -The vcol colname is a column containing a numeric value in each event row -that will be used as the contribution of the given event to its image -pixel. For example, consider an event file that has the following content: -.PP -.Vb 10 -\& x:e:4 y:e:4 v:e -\& ------ ------ ---- -\& 1 1 1.0 -\& 2 2 2.0 -\& 3 3 3.0 -\& 4 4 0.0 -\& 1 1 1.0 -\& 2 2 2.0 -\& 3 3 3.0 -\& 4 4 4.0 -.Ve -.PP -There are two events with x,y value of (1,1) so ordinarily a 2D image will -have a value of 2 in the (1,1) pixel. If the v column is specified as the -value column: -.PP -.Vb 1 -\& foo.fits'[vcol=v]' -.Ve -.PP -then each pixel will contain the additive sum of the associated (x,y) -column values from the v column. For example, image pixel (1,1) will -contain 1. + 1. = 2, image pixel (2,2) will contain (2 + 2) = 4, etc. -.PP -An important variation on the use of a value column to specify the -contribution an event makes to an image pixel is when the value column -contains the reciprocal of the event contribution. For this case, the -column name should be prefixed with a / (divide sign) thus: -.PP -.Vb 1 -\& foo.fits'[vcol=/v]' -.Ve -.PP -Each image pixel value will then be the sum of the reciprocals of the value -column. A zero in the value column results in NaN (not a number). -Thus, in the above example, image pixel (1.1) will contain 1/1 + 1/1 = 2, -image pixel (2,2) will contain (1/2 + 1/2) = 1, etc. Image pixel (4,4) -will contain (1/0 + 1/4) = NaN. -.PP -You can set the \s-1FITS_VCOL\s0 or \s-1EVENTS_VCOL\s0 environment variable as -an alternative to adding the \*(L"vcol=\*(R" specifier to each file name -for \s-1FITS\s0 binary tables and raw event files, respectively. -.PP -Finally, when binning events, the data type of the resulting 2D image -must be specified. This can be done with the \*(L"bitpix=[n]\*(R" keyword in -the bracket specification. For example: -.PP -.Vb 1 -\& events.fits[bincols=(VPOS,UPOS),bitpix=-32] -.Ve -.PP -will create a floating point image binned on columns \s-1VPOS\s0 and \s-1UPOS\s0. -If no bitpix keyword is specified, bitpix=32 is assumed. As with -bincols values, you also can use the \s-1FITS_BITPIX\s0 and \s-1EVENTS_BITPIX\s0 -environment variables to set this value for \s-1FITS\s0 binary tables and -raw event files, respectively. -.PP -The \fBfunimage\fR program also allows you to create a 1D image projection -along any column of a table by using the \fBbincols=[column]\fR -filter specification and specifying a single column. -For example, the following command projects a 1D image along -the chipx column of a table: -.PP -.Vb 1 -\& funimage ev.fits'[bincols=chipx]' im.fits -.Ve -.PP -See funimage for more -information about creating 1D and 2D images. -.PP -Finally, please note that Funtools supports most \s-1FITS\s0 standards. -We will add missing support as required by the community. In general, -however, we do not support non-standard extensions. For example, we -sense the presence of the binary table 'variable length array' -proposed extension and we pass it along when copying and filtering -files, but we do not process it. We will add support for new standards -as they become official. -.PP -\&\fBTable and Spatial Region Filters\fR -.PP -Note that, in addition extensions and image sections, Funtools bracket -notation can be used to specify table and spatial region filters. These -filters are always placed after the image section information. They -can be specified in the same bracket or in a separate bracket -immediately following: -.IP "\(bu" 4 -file[ext|ind|\fIARRAY()\fR|\fIEVENTS()\fR,section][filters] -.IP "\(bu" 4 -file[ext|ind|\fIARRAY()\fR|\fIEVENTS()\fR,section,filters] -.PP -where: -.IP "\(bu" 4 -\&\fBfile\fR is the Funtools file name -.IP "\(bu" 4 -\&\fB\s-1\f(BIARRAY\s0()\fB\fR is an array specification -.IP "\(bu" 4 -\&\fB\s-1\f(BIEVENTS\s0()\fB\fR is an event list specification -.IP "\(bu" 4 -\&\fBext\fR is the \s-1FITS\s0 extension name -.IP "\(bu" 4 -\&\fBind\fR is the \s-1FITS\s0 extension number -.IP "\(bu" 4 -\&\fBsection\fR is the image section to extract -.IP "\(bu" 4 -\&\fBfilters\fR are spatial region and table (row) filters to apply -.PP -The topics of table and region filtering are covered in detail in: -.IP "\(bu" 4 -Table Filtering -.IP "\(bu" 4 -Spatial Region Filtering -.PP -\&\fBDisk Files and Other Supported File Types\fR -.PP -The specified \fBfile\fR usually is an ordinary disk file. In -addition, gzip'ed files are supported in Funtools: gzip'ed input files -are automatically uncompressed as they are read, and gzip'ed output -files are compressed as they are written. \s-1NB:\s0 if a \s-1FITS\s0 binary table -is written in gzip format, the number of rows in the table will be set -to \-1. Such a file will work with Funtools programs but will not work -with other \s-1FITS\s0 programs such as ds9. -.PP -The special keywords \*(L"stdin\*(R" and \*(L"stdout\*(R" designate Unix standard -input and standard output, respectively. The string \*(L"\-\*(R" (hyphen) will -be taken to mean \*(L"stdin\*(R" if the file is opened for reading and -\&\*(L"stdout\*(R" if the file is opened for writing. -.PP -A file also can be an \s-1INET\s0 socket on the same or another machine using -the syntax: -.PP -.Vb 1 -\& machine:port -.Ve -.PP -Thus, for example: -.PP -.Vb 1 -\& karapet:1428 -.Ve -.PP -specifies that I/O should be performed to/from port 1428 on the -machine karapet. If no machine name is specified, the default is to -use the current machine: -.PP -.Vb 1 -\& :1428 -.Ve -.PP -This means to open port 1428 on the current machine. Socket support -allows you to generate a distributed pipe: -.PP -.Vb 2 -\& on karapet: funtask1 in.fits bynars:1428 -\& on bynars: funtask2 :1428 out.fits -.Ve -.PP -The socket mechanism thus supports simple parallel processing using -\&\fBprocess decomposition\fR. Note that parallel processing using -\&\fBdata decomposition\fR is supported via the \fBsection\fR specifier (see -below), and the \fBrow#\fR specifier, which is part of -Table Filtering. -.PP -A file also can be a pointer to shared memory using the syntax: -.PP -.Vb 1 -\& shm:[id|@key][:size] -.Ve -.PP -A shared memory segment is specified with a \fBshm:\fR prefix, -followed by either the shared memory id or the shared memory key -(where the latter is prefixed by the '@' character). The size (in -bytes) of the shared memory segment can then be appended (preceded by -the ':' character). If the size specification is absent, the code will -attempt to determine the length automatically. -.PP -If the open mode contains the string \*(L"w+\*(R", then the memory segment will be -created if it does not exist. (It also will be released and deleted when the -file is closed.) In the case where a memory segment is being created, the -length of the segment is required. -.PP -A file also can be Unix piped command (i.e. a program to run) using the syntax: -.PP -.Vb 1 -\& "pipe: command arg1 ... argn" -.Ve -.PP -The output from the command must be a valid \s-1FITS\s0 file. It is important -to use quotes to protect spaces so that command arguments are passed -correctly. A silly example is: -.PP -.Vb 1 -\& fundisp "pipe: funtable 'foo.fits[cir 512 512 .1]' stdout" -.Ve -.PP -This seemed like a good idea at the time ... -.PP -\&\fBLists of Files\fR -.PP -Funtools also will process a list of files as a single file using the -syntax: -.PP -.Vb 1 -\& "list: file1 file2 ... filen" -.Ve -.PP -The files in the list are separated by whitespace. Any of the -above file types can be used. For example, if two files, foo1.fits and -foo2.fits, are part of the same observation, they can be processed as -a single file (using their own filters): -.PP -.Vb 17 -\& fundisp "list: foo1.fits[cir(512,512,10)] foo2.fits[cir(511,511,10)]" -\& X Y PHA PI TIME DX DY -\& -------- -------- -------- -------- --------------------- -------- -------- -\& 512 512 6 7 79493997.45854475 578 574 -\& 512 512 8 9 79494575.58943175 579 573 -\& 512 512 5 6 79493631.03866175 578 575 -\& 512 512 5 5 79493290.86521725 578 575 -\& 512 512 8 9 79493432.00990875 579 573 -\& 511 511 5 5 79488631.09462625 580 575 -\& 511 511 10 11 79488780.60006675 580 573 -\& 511 511 4 4 79494562.35474326 580 575 -\& 511 511 6 6 79488203.01561825 580 575 -\& 511 511 6 6 79488017.99730176 580 575 -\& 511 511 4 4 79494332.45355175 580 575 -\& 511 511 9 10 79492685.94014275 581 574 -\& 511 511 5 5 79487708.71298325 580 575 -\& 511 511 8 9 79493719.00160225 581 573 -.Ve -.PP -Again, note that it is important to avoid spaces in the filters -because the list separator also is whitespace. To protect whitespace -in a filter, enclose the file specification in quotes: -.PP -.Vb 1 -\& fundisp "list: 'foo1.fits[cir 512 512 .1]' foo2.fits[cir(511,511,.1)]" -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funfilters.7 b/funtools/man/man7/funfilters.7 deleted file mode 100644 index 3c96e6d..0000000 --- a/funtools/man/man7/funfilters.7 +++ /dev/null @@ -1,464 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funfilters 7" -.TH funfilters 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -Funfilters \- Filtering Rows in a Table -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document contains a summary of the user interface for -filtering rows in binary tables. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Table filtering allows a program to select rows from an table (e.g., -X\-ray event list) by checking each row against one or more expressions -involving the columns in the table. When a table is filtered, only -valid rows satisfying these expressions are passed through for processing. -.PP -A filter expression is specified using bracket notation appended to -the filename of the data being processed: -.PP -.Vb 1 -\& foo.fits[pha==1&&pi==2] -.Ve -.PP -It is also possible to put region specification inside a file and -then pass the filename in bracket notation: -.PP -.Vb 1 -\& foo.fits[@my.reg] -.Ve -.PP -Filters must be placed after the extension and image section -information, when such information is present. The correct order is: -.IP "\(bu" 4 -file[fileinfo,sectioninfo][filters] -.IP "\(bu" 4 -file[fileinfo,sectioninfo,filters] -.PP -where: -.IP "\(bu" 4 -\&\fBfile\fR is the Funtools file name -.IP "\(bu" 4 -\&\fBfileinfo\fR is an \s-1ARRAY\s0, \s-1EVENT\s0, \s-1FITS\s0 extension, or \s-1FITS\s0 index -.IP "\(bu" 4 -\&\fBsectioninfo\fR is the image section to extract -.IP "\(bu" 4 -\&\fBfilters\fR are spatial region and table (row) filters to apply -.PP -See Funtools Files for more information -on file and image section specifications. -.PP -\&\fBFilter Expressions\fR -.PP -Table filtering can be performed on columns of data in a \s-1FITS\s0 -binary table or a raw event file. Table filtering is accomplished by -means of \fBtable filter specifications\fR. An table filter -specification consists of one or more \fBfilter expressions\fR Filter -specifications also can contain comments and local/global processing -directives. -.PP -More specifically, a filter specification consist of one or more lines -containing: -.PP -.Vb 13 -\& # comment until end of line -\& # include the following file in the table descriptor -\& @file -\& # each row expression can contain filters separated by operators -\& [filter_expression] BOOLOP [filter_expression2], ... -\& # each row expression can contain filters separated by the comma operator -\& [filter_expression1], [filter_expression2], ... -\& # the special row# keyword allows a range of rows to be processed -\& row#=m:n -\& # or a single row -\& row#=m -\& # regions are supported -- but are described elsewhere -\& [spatial_region_expression] -.Ve -.PP -A single filter expression consists of an arithmetic, logical, or -other operations involving one or more column values from a -table. Columns can be compared to other columns, to header values, -or to numeric constants. Standard math functions can be applied to -columns. Separate filter expressions can be combined using boolean operators. -Standard C semantics can be used when constructing expressions, with -the usual precedence and associativity rules holding sway: -.PP -.Vb 15 -\& Operator Associativity -\& -------- ------------- -\& () left to right -\& !! (logical not) right to left -\& ! (bitwise not) - (unary minus) right to left -\& * / left to right -\& + - left to right -\& < <= > >= left to right -\& == != left to right -\& & (bitwise and) left to right -\& ^ (bitwise exclusive or) left to right -\& | (bitwise inclusive or) left to right -\& && (logical and) left to right -\& || (logical or) left to right -\& = right to left -.Ve -.PP -For example, if energy and pha are columns in a table, -then the following are valid expressions: -.PP -.Vb 4 -\& pha>1 -\& energy == pha -\& (pha>1) && (energy<=2) -\& max(pha,energy)>=2.5 -.Ve -.PP -Comparison values can be integers or floats. Integer comparison values can be -specified in decimal, octal (using '0' as prefix), hex (using '0x' as prefix) -or binary (using '0b' as prefix). Thus, the following all specify the same -comparison test of a status mask: -.PP -.Vb 4 -\& (status & 15) == 8 # decimal -\& (status & 017) == 010 # octal -\& (status & 0xf) == 0x8 # hex -\& (status & 0b1111) == 0b1000 # binary -.Ve -.PP -The special keyword row# allows you to process a range of rows. -When row# is specified, the filter code skips to the designated -row and only processes the specified number of rows. The -\&\*(L"*\*(R" character can be utilized as the high limit value to denote -processing of the remaining rows. Thus: -.PP -.Vb 1 -\& row#=100:109 -.Ve -.PP -processes 10 rows, starting with row 100 (counting from 1), -while: -.PP -.Vb 1 -\& row#=100:* -.Ve -.PP -specifies that all but the first 99 rows are to be processed. -.PP -Spatial region filtering allows a program to select regions of an -image or rows of a table (e.g., X\-ray events) using simple geometric -shapes and boolean combinations of shapes. For a complete description -of regions, see Spatial Region Filtering. -.PP -\&\fBSeparators Also Are Operators\fR -.PP -As mentioned previously, multiple filter expressions can be specified -in a filter descriptor, separated by commas or new\-lines. -When such a comma or new-line separator is used, the boolean \s-1AND\s0 operator -is automatically generated in its place. Thus and expression such as: -.PP -.Vb 1 -\& pha==1,pi=2:4 -.Ve -.PP -is equivalent to: -.PP -.Vb 1 -\& (pha==1) && (pi>=2&&pi<=4) -.Ve -.PP -[Note that the behavior of separators is different for filter expressions -and spatial region expressions. The former uses \s-1AND\s0 as the operator, while -the latter user \s-1OR\s0. See -Combining Region and Table Filters -for more information about these conventions and how they are treated -when combined.] -.PP -\&\fBRange Lists\fR -.PP -Aside from the standard C syntax, filter expressions can make use of -IRAF-style \fBrange lists\fR which specify a range of values. The -syntax requires that the column name be followed by an '=' sign, which -is followed by one or more comma-delimited range expressions of the form: -.PP -.Vb 4 -\& col = vv # col == vv in range -\& col = :vv # col <= vv in range -\& col = vv: # col >= vv in range -\& col = vv1:vv2 # vv1 <= col <= vv2 in range -.Ve -.PP -The vv's above must be numeric constants; the right hand side of a -range list cannot contain a column name or header value. -.PP -Note that, unlike an ordinary comma separator, the comma separator used -between two or more range expressions denotes \s-1OR\s0. Thus, when two or -more range expressions are combined with a comma separator, the resulting -expression is a shortcut for more complicated boolean logic. For example: -.PP -.Vb 1 -\& col = :3,6:8,10: -.Ve -.PP -is equivalent to: -.PP -.Vb 1 -\& (col=6 && col =10) -.Ve -.PP -Note also that the single-valued rangelist: -.PP -.Vb 1 -\& col = val -.Ve -.PP -is equivalent to the C\-based filter expression: -.PP -.Vb 1 -\& col == val -.Ve -.PP -assuming, of course, that val is a numeric constant. -.PP -\&\fBMath Operations and Functions\fR -.PP -It is permissible to specify C math functions as part of the filter syntax. -When the filter parser recognizes a function call, it automatically -includes the math.h and links in the C math library. Thus, it is -possible to filter rows by expressions such as these: -.IP "\(bu" 4 -(pi+pha)>(2+log(pi)\-pha) -.IP "\(bu" 4 -min(pi,pha)*14>x -.IP "\(bu" 4 -max(pi,pha)==(pi+1) -.IP "\(bu" 4 -feq(pi,pha) -.IP "\(bu" 4 -div(pi,pha)>0 -.PP -The function feq(a,b) returns true (1) if the difference between a and b -(taken as double precision values) is less than approximately 10E\-15. -The function div(a,b) divides a by b, but returns NaN (not a number) -if b is 0. It is a safe way to avoid floating point errors when -dividing one column by another. -.PP -\&\fBInclude Files\fR -.PP -The special \fB@filename\fR directive specifies an include file -containing filter expressions. This file is processed as part of -the overall filter descriptor: -.PP -.Vb 1 -\& foo.fits[pha==1,@foo] -.Ve -.PP -\&\fBHeader Parameters\fR -.PP -The filter syntax supports comparison between a column value and a -header parameter value of a \s-1FITS\s0 binary tables (raw event files have no -such header). The header parameters can be taken from the binary -table header or the primary header. For example, assuming there is a -header value \s-1MEAN_PHA\s0 in one of these headers, you can select photons -having exactly this value using: -.IP "\(bu" 4 -pha==MEAN_PHA -.PP -Table filtering is more easily described by means of examples. -Consider data containing the following table structure: -.IP "\(bu" 4 -double \s-1TIME\s0 -.IP "\(bu" 4 -int X -.IP "\(bu" 4 -int Y -.IP "\(bu" 4 -short \s-1PI\s0 -.IP "\(bu" 4 -short \s-1PHA\s0 -.IP "\(bu" 4 -int \s-1DX\s0 -.IP "\(bu" 4 -int \s-1DY\s0 -.PP -Tables can be filtered on these columns using \s-1IRAF/QPOE\s0 range syntax or -any valid C syntax. The following examples illustrate the possibilities: -.IP "\(bu" 4 -pha=10 -.IP "\(bu" 4 -pha==10 -.Sp -select rows whose pha value is exactly 10 -.IP "\(bu" 4 -pha=10:50 -.Sp -select rows whose pha value is in the range of 10 to 50 -.IP "\(bu" 4 -pha=10:50,100 -.Sp -select rows whose pha value is in the range of 10 to 50 or is -equal to 100 -.IP "\(bu" 4 -pha>=10 && pha<=50 -.Sp -select rows whose pha value is in the range of 10 to 50 -.IP "\(bu" 4 -pi=1,2&&pha>3 -.Sp -select rows whose pha value is 1 or 2 and whose pi value is 3 -.IP "\(bu" 4 -pi=1,2 || pha>3 -.Sp -select rows whose pha value is 1 or 2 or whose pi value is 3 -.IP "\(bu" 4 -pha==pi+1 -.Sp -select rows whose pha value is 1 less than the pi value -.IP "\(bu" 4 -(pha==pi+1) && (time>50000.0) -.Sp -select rows whose pha value is 1 less than the pi value -and whose time value is greater than 50000 -.IP "\(bu" 4 -(pi+pha)>20 -.Sp -select rows in which the sum of the pi and pha values is greater -than 20 -.IP "\(bu" 4 -pi%2==1 -.Sp -select rows in which the pi value is odd -.PP -Currently, integer range list limits cannot be specified in binary -notation (use decimal, hex, or octal instead). Please contact us if -this is a problem. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funidx.7 b/funtools/man/man7/funidx.7 deleted file mode 100644 index bf87bb8..0000000 --- a/funtools/man/man7/funidx.7 +++ /dev/null @@ -1,327 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funidx 7" -.TH funidx 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -Funidx \- Using Indexes to Filter Rows in a Table -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document contains a summary of the user interface for -filtering rows in binary tables with indexes. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Funtools Table Filtering allows rows in a -table to be selected based on the values of one or more columns in the -row. Because the actual filter code is compiled on the fly, it is very -efficient. However, for very large files (hundreds of Mb or larger), -evaluating the filter expression on each row can take a long time. Therefore, -funtools supports index files for columns, which are used automatically during -filtering to reduce dramatically the number of row evaluations performed. -The speed increase for indexed filtering can be an order of magnitude or -more, depending on the size of the file. -.PP -The funindex program creates an -index on one or more columns in a binary table. For example, to create an index -for the column pi in the file huge.fits, use: -.PP -.Vb 1 -\& funindex huge.fits pi -.Ve -.PP -This will create an index named huge_pi.idx. -.PP -When a filter expression is initialized for row evaluation, funtools -looks for an index file for each column in the filter expression. If -found, and if the file modification date of the index file is later -than that of the data file, then the index will be used to reduce the -number of rows that are evaluated in the filter. When -Spatial Region Filtering is part of the -expression, the columns associated with the region are checked for index -files. -.PP -If an index file is not available for a given column, then in general, -all rows must be checked when that column is part of a filter -expression. This is not true, however, when a non-indexed column is -part of an \s-1AND\s0 expression. In this case, only the rows that pass the -other part of the \s-1AND\s0 expression need to be checked. Thus, in some cases, -filtering speed can increase significantly even if all columns are not -indexed. -.PP -Also note that certain types of filter expression syntax cannot make -use of indices. For example, calling functions with column names as -arguments implies that all rows must be checked against the function -value. Once again, however, if this function is part of an \s-1AND\s0 -expression, then a significant improvement in speed still is possible -if the other part of the \s-1AND\s0 expression is indexed. -.PP -For example, note below the dramatic speedup in searching a 1 Gb -file using an \s-1AND\s0 filter, even when one of the columns (pha) has no -index: -.PP -.Vb 22 -\& time fundisp \e -\& huge.fits'[idx_activate=0,idx_debug=1,pha=2348&&cir 4000 4000 1]' \e -\& "x y pha" -\& x y pha -\& ---------- ----------- ---------- -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 42.36u 13.07s 6:42.89 13.7% -.Ve -.PP -.Vb 26 -\& time fundisp \e -\& huge.fits'[idx_activate=1,idx_debug=1,pha=2348&&cir 4000 4000 1]' \e -\& "x y pha" -\& x y pha -\& ---------- ----------- ---------- -\& idxeq: [INDEF] -\& idxand sort: x[ROW 8037025:8070128] y[ROW 5757665:5792352] -\& idxand(1): INDEF [IDX_OR_SORT] -\& idxall(1): [IDX_OR_SORT] -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 1.55u 0.37s 1:19.80 2.4% -.Ve -.PP -When all columns are indexed, the increase in speed can be even more dramatic: -.PP -.Vb 22 -\& time fundisp \e -\& huge.fits'[idx_activate=0,idx_debug=1,pi=770&&cir 4000 4000 1]' \e -\& "x y pi" -\& x y pi -\& ---------- ----------- ---------- -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 42.60u 12.63s 7:28.63 12.3% -.Ve -.PP -.Vb 27 -\& time fundisp \e -\& huge.fits'[idx_activate=1,idx_debug=1,pi=770&&cir 4000 4000 1]' \e -\& "x y pi" -\& x y pi -\& ---------- ----------- ---------- -\& idxeq: pi start=9473025,stop=9492240 => pi[ROW 9473025:9492240] -\& idxand sort: x[ROW 8037025:8070128] y[ROW 5757665:5792352] -\& idxor sort/merge: pi[ROW 9473025:9492240] [IDX_OR_SORT] -\& idxmerge(5): [IDX_OR_SORT] pi[ROW] -\& idxall(1): [IDX_OR_SORT] -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 1.67u 0.30s 0:24.76 7.9% -.Ve -.PP -The miracle of indexed filtering (and indeed, of any indexing) is the -speed of the binary search on the index, which is of order log2(n) -instead of n. (The funtools binary search method is taken from -http://www.tbray.org/ongoing/When/200x/2003/03/22/Binary, to whom -grateful acknowledgement is made.) This means that the larger the -file, the better the performance. Conversely, it also means that for -small files, using an index (and the overhead involved) can slow -filtering down somewhat. Our tests indicate that on a file containing -a few tens of thousands of rows, indexed filtering can be 10 to 20 -percent slower than non-indexed filtering. Of course, your mileage -will vary with conditions (disk access speed, amount of available -memory, process load, etc.) -.PP -Any problem encountered during index processing will result in -indexing being turned off, and replaced by filtering all rows. You can turn -filtering off manually by setting the idx_activate variable to 0 (in a filter -expression) or the \s-1FILTER_IDX_ACTIVATE\s0 environment variable to 0 (in the global -environment). Debugging output showing how the indexes are being processed can -be displayed to stderr by setting the idx_debug variable to 1 (in a filter -expression) or the \s-1FILTER_IDX_DEBUG\s0 environment variable to 1 (in the global -environment). -.PP -Currently, indexed filtering only works with \s-1FITS\s0 binary tables and raw -event files. It does not work with text files. This restriction might be -removed in a future release. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funregions.7 b/funtools/man/man7/funregions.7 deleted file mode 100644 index 5c17572..0000000 --- a/funtools/man/man7/funregions.7 +++ /dev/null @@ -1,678 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funregions 7" -.TH funregions 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunRegions \- Spatial Region Filtering -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document contains a summary of the user interface for spatial -region filtering images and tables. -.SH "DESCRIPTION" -.IX Header "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. -.PP -Spatial region filtering for images and tables is accomplished by -means of \fBregion specifications\fR. A region specification -consists of one or more \fBregion expressions\fR, which are geometric -shapes,combined according to the rules of boolean algebra. Region -specifications also can contain comments and local/global processing -directives. -.PP -Typically, region specifications are specified using bracket notation -appended to the filename of the data being processed: -.PP -.Vb 1 -\& foo.fits[circle(512,512,100)] -.Ve -.PP -It is also possible to put region specification inside a file and -then pass the filename in bracket notation: -.PP -.Vb 1 -\& foo.fits[@my.reg] -.Ve -.PP -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 \s-1API\s0 to open filters explicitly. -.PP -\&\fBRegion Expressions\fR -.PP -More specifically, region specifications consist of one or more lines -containing: -.PP -.Vb 9 -\& # 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], ... -.Ve -.PP -A single region expression consists of: -.PP -.Vb 2 -\& # parens and commas are optional, as is the + sign -\& [+-]shape(num , num , ...) OP1 shape num num num OP2 shape ... -.Ve -.PP -e.g.: -.PP -.Vb 3 -\& ([+-]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 -.Ve -.PP -Thus, a region descriptor consists of one or more region -expressions or \fBregions\fR, separated by comas, new\-lines, or -semi\-colons. Each \fBregion\fR consists of one or more geometric -shapes combined using standard boolean operation. Several types -of shapes are supported, including: -.PP -.Vb 11 -\& 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 -.Ve -.PP -In addition, the following regions accept \fBaccelerator\fR syntax: -.PP -.Vb 13 -\& 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 -.Ve -.PP -Note that the circle accelerators are simply aliases for the annulus -accelerators. See region geometry -for more information about accelerators. -.PP -Finally, the following are combinations of pie with different shapes -(called \*(L"panda\*(R" for \*(L"Pie \s-1AND\s0 Annulus\*(R") allow for easy specification of -radial sections: -.PP -.Vb 6 -\& 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 -.Ve -.PP -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. -.PP -The following \*(L"shapes\*(R" are ignored by funtools (generated by ds9): -.PP -.Vb 8 -\& 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 -.Ve -.PP -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 \s-1WCS\s0 header, that -angle is added implicitly as well. -.PP -Note that 3\-letter abbreviations are supported for all shapes, so that -you can specify \*(L"circle\*(R" or \*(L"cir\*(R". -.PP -\&\fBColumns Used in Region Filtering\fR -.PP -By default, the x,y values in a region expression refer to the two -\&\*(L"image binning\*(R" 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. -.PP -Alternate columns for region filtering can be specified by the syntax: -.PP -.Vb 1 -\& (col1,col2)=region(...) -.Ve -.PP -e.g.: -.PP -.Vb 3 -\& (X,Y)=annulus(x,y,ri,ro) -\& (PHA,PI)=circle(x,y,r) -\& (DX,DY)=ellipse(x,y,a,b[,angle]) -.Ve -.PP -\&\fBRegion Algebra\fR -.PP -(See also Region Algebra for more complete -information.) -.PP -Region shapes can be combined together using Boolean operators: -.PP -.Vb 6 -\& 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 -.Ve -.PP -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, -.PP -.Vb 1 -\& !circle(512,512,10) -.Ve -.PP -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 \fIfield()\fR, -as in: -.PP -.Vb 1 -\& field() && !circle(512,512,10) -.Ve -.PP -\&\fB Region Separators Also Are Operators\fR -.PP -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 \s-1OR\s0 operator -is automatically generated in its place but, unlike explicit use of -the \s-1OR\s0 operator, the region \s-1ID\s0 is incremented (starting from 1). -.PP -For example, the two shapes specified in this example are given the -same region value: -.PP -.Vb 1 -\& foo.fits[circle(512,512,10)||circle(400,400,20)] -.Ve -.PP -On the other hand, the two shapes defined in the following example are -given different region values: -.PP -.Vb 1 -\& foo.fits[circle(512,512,10),circle(400,400,20)] -.Ve -.PP -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 \s-1OR\s0 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. -.PP -In general, commas are used to separate region expressions entered -in bracket notation on the command line: -.PP -.Vb 2 -\& # regions are added to the filename in bracket notation -\& foo.fits[circle(512,512,100),circle(400,400,20)] -.Ve -.PP -New-lines are used to separate region -expressions in a file: -.PP -.Vb 4 -\& # 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) -.Ve -.PP -Semi-colons are provided for backward compatibility with the original -\&\s-1IRAF/PROS\s0 implementation and can be used in either case. -.PP -If a pixel is covered by two different regions expressions, it is -given the mask value of the \fBfirst\fR region that contains that -pixel. That is, successive regions \fBdo not\fR overwrite previous -regions in the mask, as was the case with the original \s-1PROS\s0 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 \fBbefore\fR M, or else it will be -\&\*(L"covered up\*(R" by the latter. -.PP -\&\fBRegion Exclusion\fR -.PP -Shapes also can be globally excluded from all the region specifiers in -a region descriptor by using a minus sign before a region: -.PP -.Vb 4 -\& operator arguments: -\& -------- ----------- -\& - Globally exclude the region expression following '-' sign -\& from ALL regions specified in this file -.Ve -.PP -The global exclude region can be used by itself; in such a case, \fIfield()\fR is -implied. -.PP -A global exclude differs from the local exclude (i.e. a shape prefixed -by the logical not \*(L"!\*(R" 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. -.PP -\&\fBInclude Files\fR -.PP -The \fB@filename\fR directive specifies an include file -containing region expressions. This file is processed as part of -the overall region descriptor: -.PP -.Vb 1 -\& foo.fits[circle(512,512,10),@foo] -.Ve -.PP -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 \*(L"pi==1\*(R" and foo2 contains \*(L"pha==2\*(R" then -the following expressions are equivalent: -.PP -.Vb 3 -\& "[@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]" -.Ve -.PP -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: -.PP -.Vb 2 -\& circle 512 512 10 -\& circle 520 520 10 -.Ve -.PP -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: -.PP -.Vb 1 -\& pi==4&&(@foo) -.Ve -.PP -since this is equivalent to: -.PP -.Vb 1 -\& pi==4 && (circle 512 512 10 || circle 520 520 10) -.Ve -.PP -If you leave out the parenthesis, you are filtering this statement: -.PP -.Vb 1 -\& pi==4 && circle 512 512 10 || circle 520 520 10) -.Ve -.PP -which is equivalent to: -.PP -.Vb 1 -\& (pi==4 && circle 512 512 10) || circle 520 520 10) -.Ve -.PP -The latter syntax only applies the pi test to the first region. -.PP -For image-style filtering, the \fB@filename\fR can specify an 8-bit -or 16-bit \s-1FITS\s0 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.) -.PP -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 -\&\s-1FITS\s0 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. -.PP -\&\fBGlobal and Local Properties of Regions\fR -.PP -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 \fBglobal\fR keyword specifies properties and qualifiers for all -regions, while local properties are specified in comments on the same -line as the region: -.PP -.Vb 4 -\& global color=red -\& circle(10,10,2) -\& circle(20,20,3) # color=blue -\& circle(30,30,4) -.Ve -.PP -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. -.PP -\&\fB Coordinate Systems\fR -.PP -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: -.PP -.Vb 12 -\& 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 -.Ve -.PP -\&\fBSpecifying Positions, Sizes, and Angles\fR -.PP -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: -.PP -.Vb 11 -\& 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 -.Ve -.PP -.Vb 9 -\& 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 -.Ve -.PP -When a \*(L"pure number\*(R" (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: -.PP -All pure numbers have implied units corresponding to the current -coordinate system. -.PP -If no such system is explicitly specified, the default system is -implicitly assumed to be \s-1PHYSICAL\s0. -.PP -In practice this means that for \s-1IMAGE\s0 and \s-1PHYSICAL\s0 systems, pure -numbers are pixels. Otherwise, for all systems other than linear, -pure numbers are degrees. For \s-1LINEAR\s0 systems, pure numbers are in the -units of the linear system. This rule covers both positions and -sizes. -.PP -The input values to each shape can be specified in several coordinate -systems including: -.PP -.Vb 12 -\& 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 -.Ve -.PP -If no coordinate system is specified, \s-1PHYSICAL\s0 is assumed. \s-1PHYSICAL\s0 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., -.PP -.Vb 2 -\& global coordsys physical -\& circle 6500 9320 200 -.Ve -.PP -The use of celestial input units automatically implies \s-1WORLD\s0 -coordinates of the reference image. Thus, if the world coordinate -system of the reference image is J2000, then -.PP -.Vb 1 -\& circle 10:10:0 20:22:0 3' -.Ve -.PP -is equivalent to: -.PP -.Vb 1 -\& circle 10:10:0 20:22:0 3' # j2000 -.Ve -.PP -Note that by using units as described above, you may mix coordinate -systems within a region specifier; e.g., -.PP -.Vb 1 -\& circle 6500 9320 3' # physical -.Ve -.PP -Note that, for regions which accept a rotation angle: -.PP -ellipse (x, y, r1, r2, angle) -box(x, y, w, h, angle) -.PP -the angle is relative to the specified coordinate system. In -particular, if the region is specified in \s-1WCS\s0 coordinates, the angle -is related to the \s-1WCS\s0 system, not x/y image coordinate axis. For \s-1WCS\s0 -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 -\&\s-1CROTA\s0 value in the \s-1WCS\s0 parameters) and for these images, the angle -will be relative to the \s-1WCS\s0 axes. In such case, a region specification -such as: -.PP -fk4;ellipse(22:59:43.985, +58:45:26.92,320\*(L", 160\*(R", 30) -.PP -will not, in general, be the same region specified as: -.PP -physical;ellipse(465, 578, 40, 20, 30) -.PP -even when positions and sizes match. The angle is relative to \s-1WCS\s0 axes -in the first case, and relative to physical x,y axes in the second. -.PP -More detailed descriptions are available for: -Region Geometry, -Region Algebra, -Region Coordinates, and -Region Boundaries. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funtext.7 b/funtools/man/man7/funtext.7 deleted file mode 100644 index b24b317..0000000 --- a/funtools/man/man7/funtext.7 +++ /dev/null @@ -1,713 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funtext 7" -.TH funtext 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -Funtext \- Support for Column\-based Text Files -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document contains a summary of the options for processing column-based -text files. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Funtools will automatically sense and process \*(L"standard\*(R" -column-based text files as if they were \s-1FITS\s0 binary tables without any -change in Funtools syntax. In particular, you can filter text files -using the same syntax as \s-1FITS\s0 binary tables: -.PP -.Vb 3 -\& fundisp foo.txt'[cir 512 512 .1]' -\& fundisp \-T foo.txt > foo.rdb -\& funtable foo.txt'[pha=1:10,cir 512 512 10]' foo.fits -.Ve -.PP -The first example displays a filtered selection of a text file. The -second example converts a text file to an \s-1RDB\s0 file. The third example -converts a filtered selection of a text file to a \s-1FITS\s0 binary table. -.PP -Text files can also be used in Funtools image programs. In this case, -you must provide binning parameters (as with raw event files), using -the bincols keyword specifier: -.PP -.Vb 1 -\& bincols=([xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]] -.Ve -.PP -For example: -.PP -.Vb 1 -\& funcnts foo'[bincols=(x:1024,y:1024)]' "ann 512 512 0 10 n=10" -.Ve -.PP -\&\fBStandard Text Files\fR -.PP -Standard text files have the following characteristics: -.IP "\(bu" 4 -Optional comment lines start with # -.IP "\(bu" 4 -Optional blank lines are considered comments -.IP "\(bu" 4 -An optional table header consists of the following (in order): -.RS 4 -.IP "\(bu" 4 -a single line of alpha-numeric column names -.IP "\(bu" 4 -an optional line of unit strings containing the same number of cols -.IP "\(bu" 4 -an optional line of dashes containing the same number of cols -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Data lines follow the optional header and (for the present) consist of - the same number of columns as the header. -.IP "\(bu" 4 -Standard delimiters such as space, tab, comma, semi\-colon, and bar. -.PP -Examples: -.PP -.Vb 5 -\& # rdb file -\& foo1 foo2 foo3 foos -\& ---- ---- ---- ---- -\& 1 2.2 3 xxxx -\& 10 20.2 30 yyyy -.Ve -.PP -.Vb 5 -\& # multiple consecutive whitespace and dashes -\& foo1 foo2 foo3 foos -\& --- ---- ---- ---- -\& 1 2.2 3 xxxx -\& 10 20.2 30 yyyy -.Ve -.PP -.Vb 2 -\& # comma delims and blank lines -\& foo1,foo2,foo3,foos -.Ve -.PP -.Vb 2 -\& 1,2.2,3,xxxx -\& 10,20.2,30,yyyy -.Ve -.PP -.Vb 4 -\& # bar delims with null values -\& foo1|foo2|foo3|foos -\& 1||3|xxxx -\& 10|20.2||yyyy -.Ve -.PP -.Vb 3 -\& # header-less data -\& 1 2.2 3 xxxx -\& 10 20.2 30 yyyy -.Ve -.PP -The default set of token delimiters consists of spaces, tabs, commas, -semi\-colons, and vertical bars. Several parsers are used -simultaneously to analyze a line of text in different ways. One way -of analyzing a line is to allow a combination of spaces, tabs, and -commas to be squashed into a single delimiter (no null values between -consecutive delimiters). Another way is to allow tab, semi\-colon, and -vertical bar delimiters to support null values, i.e. two consecutive -delimiters implies a null value (e.g. \s-1RDB\s0 file). A successful parser -is one which returns a consistent number of columns for all rows, with -each column having a consistent data type. More than one parser can -be successful. For now, it is assumed that successful parsers all -return the same tokens for a given line. (Theoretically, there are -pathological cases, which will be taken care of as needed). Bad parsers -are discarded on the fly. -.PP -If the header does not exist, then names \*(L"col1\*(R", \*(L"col2\*(R", etc. are -assigned to the columns to allow filtering. Furthermore, data types -for each column are determined by the data types found in the columns -of the first data line, and can be one of the following: string, int, -and double. Thus, all of the above examples return the following -display: -.PP -.Vb 4 -\& fundisp foo'[foo1>5]' -\& FOO1 FOO2 FOO3 FOOS -\& ---------- --------------------- ---------- ------------ -\& 10 20.20000000 30 yyyy -.Ve -.PP -\&\fBComments Convert to Header Params\fR -.PP -Comments which precede data rows are converted into header parameters and -will be written out as such using funimage or funhead. Two styles of comments -are recognized: -.PP -1. FITS-style comments have an equal sign \*(L"=\*(R" between the keyword and -value and an optional slash \*(L"/\*(R" to signify a comment. The strict \s-1FITS\s0 -rules on column positions are not enforced. In addition, strings only -need to be quoted if they contain whitespace. For example, the following -are valid FITS-style comments: -.PP -.Vb 5 -\& # fits0 = 100 -\& # fits1 = /usr/local/bin -\& # fits2 = "/usr/local/bin /opt/local/bin" -\& # fits3c = /usr/local/bin /opt/local/bin /usr/bin -\& # fits4c = "/usr/local/bin /opt/local/bin" / path dir -.Ve -.PP -Note that the fits3c comment is not quoted and therefore its value is the -single token \*(L"/usr/local/bin\*(R" and the comment is \*(L"opt/local/bin /usr/bin\*(R". -This is different from the quoted comment in fits4c. -.PP -2. Free-form comments can have an optional colon separator between the -keyword and value. In the absence of quote, all tokens after the -keyword are part of the value, i.e. no comment is allowed. If a string -is quoted, then slash \*(L"/\*(R" after the string will signify a comment. -For example: -.PP -.Vb 4 -\& # com1 /usr/local/bin -\& # com2 "/usr/local/bin /opt/local/bin" -\& # com3 /usr/local/bin /opt/local/bin /usr/bin -\& # com4c "/usr/local/bin /opt/local/bin" / path dir -.Ve -.PP -.Vb 4 -\& # com11: /usr/local/bin -\& # com12: "/usr/local/bin /opt/local/bin" -\& # com13: /usr/local/bin /opt/local/bin /usr/bin -\& # com14c: "/usr/local/bin /opt/local/bin" / path dir -.Ve -.PP -Note that com3 and com13 are not quoted, so the whole string is part of -the value, while comz4c and com14c are quoted and have comments following -the values. -.PP -Some text files have column name and data type information in the header. -You can specify the format of column information contained in the -header using the \*(L"hcolfmt=\*(R" specification. See below for a detailed -description. -.PP -\&\fBMultiple Tables in a Single File\fR -.PP -Multiple tables are supported in a single file. If an RDB-style file -is sensed, then a ^L (vertical tab) will signify end of -table. Otherwise, an end of table is sensed when a new header (i.e., -all alphanumeric columns) is found. (Note that this heuristic does not -work for single column tables where the column type is \s-1ASCII\s0 and the -table that follows also has only one column.) You also can specify -characters that signal an end of table condition using the \fBeot=\fR -keyword. See below for details. -.PP -You can access the nth table (starting from 1) in a multi-table file -by enclosing the table number in brackets, as with a \s-1FITS\s0 extension: -.PP -.Vb 1 -\& fundisp foo'[2]' -.Ve -.PP -The above example will display the second table in the file. -(Index values start at 1 in oder to maintain logical compatibility -with \s-1FITS\s0 files, where extension numbers also start at 1). -.PP -\&\fB\s-1\f(BITEXT\s0()\fB Specifier\fR -.PP -As with \s-1\fIARRAY\s0()\fR and \s-1\fIEVENTS\s0()\fR specifiers for raw image arrays and raw -event lists respectively, you can use \s-1\fITEXT\s0()\fR on text files to pass -key=value options to the parsers. An empty set of keywords is -equivalent to not having \s-1\fITEXT\s0()\fR at all, that is: -.PP -.Vb 2 -\& fundisp foo -\& fundisp foo'[TEXT()]' -.Ve -.PP -are equivalent. A multi-table index number is placed before the \s-1\fITEXT\s0()\fR -specifier as the first token, when indexing into a multi\-table: -.PP -.Vb 1 -\& fundisp foo'[2,TEXT(...)]' -.Ve -.PP -The filter specification is placed after the \s-1\fITEXT\s0()\fR specifier, separated -by a comma, or in an entirely separate bracket: -.PP -.Vb 2 -\& fundisp foo'[TEXT(...),circle 512 512 .1]' -\& fundisp foo'[2,TEXT(...)][circle 512 512 .1]' -.Ve -.PP -\&\fB\f(BIText()\fB Keyword Options\fR -.PP -The following is a list of keywords that can be used within the \s-1\fITEXT\s0()\fR -specifier (the first three are the most important): -.IP "\(bu" 4 -delims=\*(L"[delims]\*(R" -.Sp -Specify token delimiters for this file. Only a single parser having these -delimiters will be used to process the file. -.Sp -.Vb 2 -\& fundisp foo.fits'[TEXT(delims="!")]' -\& fundisp foo.fits'[TEXT(delims="\et%")]' -.Ve -.IP "\(bu" 4 -comchars=\*(L"[comchars]\*(R" -.Sp -Specify comment characters. You must include \*(L"\en\*(R" to allow blank lines. -These comment characters will be used for all standard parsers (unless delims -are also specified). -.Sp -.Vb 1 -\& fundisp foo.fits'[TEXT(comchars="!\en")]' -.Ve -.IP "\(bu" 4 -cols=\*(L"[name1:type1 ...]\*(R" -.Sp -Specify names and data type of columns. This overrides header -names and/or data types in the first data row or default names and -data types for header-less tables. -.Sp -.Vb 1 -\& fundisp foo.fits'[TEXT(cols="x:I,y:I,pha:I,pi:I,time:D,dx:E,dy:e")]' -.Ve -.Sp -If the column specifier is the only keyword, then the cols= is not -required (in analogy with \s-1\fIEVENTS\s0()\fR): -.Sp -.Vb 1 -\& fundisp foo.fits'[TEXT(x:I,y:I,pha:I,pi:I,time:D,dx:E,dy:e)]' -.Ve -.Sp -Of course, an index is allowed in this case: -.Sp -.Vb 1 -\& fundisp foo.fits'[2,TEXT(x:I,y:I,pha:I,pi:I,time:D,dx:E,dy:e)]' -.Ve -.IP "\(bu" 4 -eot=\*(L"[eot delim]\*(R" -.Sp -Specify end of table string specifier for multi-table files. \s-1RDB\s0 -files support ^L. The end of table specifier is a string and the whole -string must be found alone on a line to signify \s-1EOT\s0. For example: -.Sp -.Vb 1 -\& fundisp foo.fits'[TEXT(eot="END")]' -.Ve -.Sp -will end the table when a line contains \*(L"\s-1END\s0\*(R" is found. Multiple lines -are supported, so that: -.Sp -.Vb 1 -\& fundisp foo.fits'[TEXT(eot="END\enGAME")]' -.Ve -.Sp -will end the table when a line contains \*(L"\s-1END\s0\*(R" followed by a line -containing \*(L"\s-1GAME\s0\*(R". -.Sp -In the absence of an \s-1EOT\s0 delimiter, a new table will be sensed when a new -header (all alphanumeric columns) is found. -.IP "\(bu" 4 -null1=\*(L"[datatype]\*(R" -.Sp -Specify data type of a single null value in row 1. -Since column data types are determined by the first row, a null value -in that row will result in an error and a request to specify names and -data types using cols=. If you only have a one null in row 1, you don't -need to specify all names and columns. Instead, use null1=\*(L"type\*(R" to -specify its data type. -.IP "\(bu" 4 -alen=[n] -.Sp -Specify size in bytes for \s-1ASCII\s0 type columns. -\&\s-1FITS\s0 binary tables only support fixed length \s-1ASCII\s0 columns, so a -size value must be specified. The default is 16 bytes. -.IP "\(bu" 4 -nullvalues=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Specify whether to expect null values. -Give the parsers a hint as to whether null values should be allowed. The -default is to try to determine this from the data. -.IP "\(bu" 4 -whitespace=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Specify whether surrounding white space should be kept as part of -string tokens. By default surrounding white space is removed from -tokens. -.IP "\(bu" 4 -header=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Specify whether to require a header. This is needed by tables -containing all string columns (and with no row containing dashes), in -order to be able to tell whether the first row is a header or part of -the data. The default is false, meaning that the first row will be -data. If a row dashes are present, the previous row is considered the -column name row. -.IP "\(bu" 4 -units=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Specify whether to require a units line. -Give the parsers a hint as to whether a row specifying units should be -allowed. The default is to try to determine this from the data. -.IP "\(bu" 4 -i2f=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Specify whether to allow int to float conversions. -If a column in row 1 contains an integer value, the data type for that -column will be set to int. If a subsequent row contains a float in -that same column, an error will be signaled. This flag specifies that, -instead of an error, the float should be silently truncated to -int. Usually, you will want an error to be signaled, so that you can -specify the data type using cols= (or by changing the value of -the column in row 1). -.IP "\(bu" 4 -comeot=[\*(L"true\*(R"|\*(L"false\*(R"|0|1|2] -.Sp -Specify whether comment signifies end of table. -If comeot is 0 or false, then comments do not signify end of table and -can be interspersed with data rows. If the value is true or 1 (the -default for standard parsers), then non-blank lines (e.g. lines -beginning with '#') signify end of table but blanks are allowed -between rows. If the value is 2, then all comments, including blank -lines, signify end of table. -.IP "\(bu" 4 -lazyeot=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Specify whether \*(L"lazy\*(R" end of table should be permitted (default is -true for standard formats, except rdb format where explicit ^L is required -between tables). A lazy \s-1EOT\s0 can occur when a new table starts directly -after an old one, with no special \s-1EOT\s0 delimiter. A check for this \s-1EOT\s0 -condition is begun when a given row contains all string tokens. If, in -addition, there is a mismatch between the number of tokens in the -previous row and this row, or a mismatch between the number of string -tokens in the prev row and this row, a new table is assumed to have -been started. For example: -.Sp -.Vb 4 -\& ival1 sval3 -\& ----- ----- -\& 1 two -\& 3 four -.Ve -.Sp -.Vb 4 -\& jval1 jval2 tval3 -\& ----- ----- ------ -\& 10 20 thirty -\& 40 50 sixty -.Ve -.Sp -Here the line \*(L"jval1 ...\*(R" contains all string tokens. In addition, -the number of tokens in this line (3) differs from the number of -tokens in the previous line (2). Therefore a new table is assumed -to have started. Similarly: -.Sp -.Vb 4 -\& ival1 ival2 sval3 -\& ----- ----- ----- -\& 1 2 three -\& 4 5 six -.Ve -.Sp -.Vb 4 -\& jval1 jval2 tval3 -\& ----- ----- ------ -\& 10 20 thirty -\& 40 50 sixty -.Ve -.Sp -Again, the line \*(L"jval1 ...\*(R" contains all string tokens. The number of -string tokens in the previous row (1) differs from the number of -tokens in the current \fIrow\fR\|(3). We therefore assume a new table as been -started. This lazy \s-1EOT\s0 test is not performed if lazyeot is explicitly -set to false. -.IP "\(bu" 4 -hcolfmt=[header column format] -.Sp -Some text files have column name and data type information in the header. -For example, VizieR catalogs have headers containing both column names -and data types: -.Sp -.Vb 3 -\& #Column e_Kmag (F6.3) ?(k_msigcom) K total magnitude uncertainty (4) [ucd=ERROR] -\& #Column Rflg (A3) (rd_flg) Source of JHK default mag (6) [ucd=REFER_CODE] -\& #Column Xflg (I1) [0,2] (gal_contam) Extended source contamination (10) [ucd=CODE_MISC] -.Ve -.Sp -while Sextractor files have headers containing column names alone: -.Sp -.Vb 4 -\& # 1 X_IMAGE Object position along x [pixel] -\& # 2 Y_IMAGE Object position along y [pixel] -\& # 3 ALPHA_J2000 Right ascension of barycenter (J2000) [deg] -\& # 4 DELTA_J2000 Declination of barycenter (J2000) [deg] -.Ve -.Sp -The hcolfmt specification allows you to describe which header lines -contain column name and data type information. It consists of a string -defining the format of the column line, using \*(L"$col\*(R" (or \*(L"$name\*(R") to -specify placement of the column name, \*(L"$fmt\*(R" to specify placement of the -data format, and \*(L"$skip\*(R" to specify tokens to ignore. You also can -specify tokens explicitly (or, for those users familiar with how -sscanf works, you can specify scanf skip specifiers using \*(L"%*\*(R"). -For example, the VizieR hcolfmt above might be specified in several ways: -.Sp -.Vb 3 -\& Column $col ($fmt) # explicit specification of "Column" string -\& $skip $col ($fmt) # skip one token -\& %*s $col ($fmt) # skip one string (using scanf format) -.Ve -.Sp -while the Sextractor format might be specified using: -.Sp -.Vb 2 -\& $skip $col # skip one token -\& %*d $col # skip one int (using scanf format) -.Ve -.Sp -You must ensure that the hcolfmt statement only senses actual column -definitions, with no false positives or negatives. For example, the -first Sextractor specification, \*(L"$skip \f(CW$col\fR\*(R", will consider any header -line containing two tokens to be a column name specifier, while the -second one, \*(L"%*d \f(CW$col\fR\*(R", requires an integer to be the first token. In -general, it is preferable to specify formats as explicitly as -possible. -.Sp -Note that the VizieR-style header info is sensed automatically by the -funtools standard VizieR-like parser, using the hcolfmt \*(L"Column \f(CW$col\fR -($fmt)\*(R". There is no need for explicit use of hcolfmt in this case. -.IP "\(bu" 4 -debug=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Display debugging information during parsing. -.PP -\&\fBEnvironment Variables\fR -.PP -Environment variables are defined to allow many of these \s-1\fITEXT\s0()\fR values to be -set without having to include them in \s-1\fITEXT\s0()\fR every time a file is processed: -.PP -.Vb 10 -\& keyword environment variable -\& ------- -------------------- -\& delims TEXT_DELIMS -\& comchars TEXT_COMCHARS -\& cols TEXT_COLUMNS -\& eot TEXT_EOT -\& null1 TEXT_NULL1 -\& alen TEXT_ALEN -\& bincols TEXT_BINCOLS -\& hcolfmt TEXT_HCOLFMT -.Ve -.PP -\&\fBRestrictions and Problems\fR -.PP -As with raw event files, the '+' (copy extensions) specifier is not -supported for programs such as funtable. -.PP -String to int and int to string data conversions are allowed by the -text parsers. This is done more by force of circumstance than by -conviction: these transitions often happens with VizieR catalogs, -which we want to support fully. One consequence of allowing these -transitions is that the text parsers can get confused by columns which -contain a valid integer in the first row and then switch to a -string. Consider the following table: -.PP -.Vb 4 -\& xxx yyy zzz -\& ---- ---- ---- -\& 111 aaa bbb -\& ccc 222 ddd -.Ve -.PP -The xxx column has an integer value in row one a string in row two, -while the yyy column has the reverse. The parser will erroneously -treat the first column as having data type int: -.PP -.Vb 5 -\& fundisp foo.tab -\& XXX YYY ZZZ -\& ---------- ------------ ------------ -\& 111 'aaa' 'bbb' -\& 1667457792 '222' 'ddd' -.Ve -.PP -while the second column is processed correctly. This situation can be avoided -in any number of ways, all of which force the data type of the first column -to be a string. For example, you can edit the file and explicitly quote the -first row of the column: -.PP -.Vb 4 -\& xxx yyy zzz -\& ---- ---- ---- -\& "111" aaa bbb -\& ccc 222 ddd -.Ve -.PP -.Vb 5 -\& [sh] fundisp foo.tab -\& XXX YYY ZZZ -\& ------------ ------------ ------------ -\& '111' 'aaa' 'bbb' -\& 'ccc' '222' 'ddd' -.Ve -.PP -You can edit the file and explicitly set the data type of the first column: -.PP -.Vb 4 -\& xxx:3A yyy zzz -\& ------ ---- ---- -\& 111 aaa bbb -\& ccc 222 ddd -.Ve -.PP -.Vb 5 -\& [sh] fundisp foo.tab -\& XXX YYY ZZZ -\& ------------ ------------ ------------ -\& '111' 'aaa' 'bbb' -\& 'ccc' '222' 'ddd' -.Ve -.PP -You also can explicitly set the column names and data types of all columns, -without editing the file: -.PP -.Vb 5 -\& [sh] fundisp foo.tab'[TEXT(xxx:3A,yyy:3A,zzz:3a)]' -\& XXX YYY ZZZ -\& ------------ ------------ ------------ -\& '111' 'aaa' 'bbb' -\& 'ccc' '222' 'ddd' -.Ve -.PP -The issue of data type transitions (which to allow and which to disallow) -is still under discussion. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funtools.7 b/funtools/man/man7/funtools.7 deleted file mode 100644 index 6d188be..0000000 --- a/funtools/man/man7/funtools.7 +++ /dev/null @@ -1,379 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funtools 7" -.TH funtools 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -Funtools \- FITS Users Need Tools -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document is the Table of Contents for Funtools. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Funtools, is a \*(L"minimal buy\-in\*(R" \s-1FITS\s0 library and utility package developed -at the the High Energy Astrophysics Division of \s-1SAO\s0. The Funtools -library provides simplified access to a wide array of file types: -standard astronomical \s-1FITS\s0 images and binary tables, raw arrays and -binary event lists, and even tables of \s-1ASCII\s0 column data. A -sophisticated region filtering library (compatible with ds9) filters -images and tables using boolean operations between geometric shapes, -support world coordinates, etc. Funtools also supports advanced -capabilities such as optimized data searching using index files. -.PP -The main goal of the Funtools project has been to develop a minimal buy-in -\&\s-1FITS\s0 library for researchers who are occasional (but serious) coders. In -this case, \*(L"minimal buy\-in\*(R" means \*(L"easy to learn, easy to use, and easy to -re-learn next month\*(R". We have tried to achieve this goal by emphasizing two -essential capabilities. The first is the ability to develop \s-1FITS\s0 programs -without knowing much about \s-1FITS\s0, i.e., without having to deal with the -arcane rules for generating a properly formatted \s-1FITS\s0 file. The second is -to support the use of already-familiar C/Unix facilities, especially C -structs and Unix stdio. Taken together, these two capabilities should allow -researchers to leverage their existing programming expertise while -minimizing the need to learn new and complex coding rules. -.PP -Choose from the following topics: -.IP "\(bu" 4 -Funtools User Programs -.RS 4 -.IP "\(bu" 4 -funcalc: Funtools calculator (for binary tables) -[\fIfuncalc\fR\|(1)] -.IP "\(bu" 4 -funcen: find centroid (for binary tables) -[\fIfuncen\fR\|(1)] -.IP "\(bu" 4 -funcnts: count photons in specified regions -[\fIfuncnts\fR\|(1)] -.IP "\(bu" 4 -funcone: cone search on \s-1RA\s0, Dec columns -[\fIfuncone\fR\|(1)] -.IP "\(bu" 4 -fundisp: display data in a Funtools data file -[\fIfundisp\fR\|(1)] -.IP "\(bu" 4 -funhead: display a header in a Funtools file -[\fIfunhead\fR\|(1)] -.IP "\(bu" 4 -funhist: create a 1D histogram of a column -[\fIfunhist\fR\|(1)] -.IP "\(bu" 4 -funimage: create a \s-1FITS\s0 image from a Funtools data file -[\fIfunimage\fR\|(1)] -.IP "\(bu" 4 -funindex: create an index on a column in a binary table -[\fIfunindex\fR\|(1)] -.IP "\(bu" 4 -funjoin: join two or more \s-1FITS\s0 binary tables on specified columns -[\fIfunjoin\fR\|(1)] -.IP "\(bu" 4 -funmerge: merge one or more Funtools table files -[\fIfunmerge\fR\|(1)] -.IP "\(bu" 4 -funsky: convert between image and sky coordinates, using \s-1WCS\s0 info from a \s-1FITS\s0 header -[\fIfunsky\fR\|(1)] -.IP "\(bu" 4 -funtable: copy selected rows from a Funtools file to a \s-1FITS\s0 binary table -[\fIfuntable\fR\|(1)] -.IP "\(bu" 4 -funtbl: extract a table from -Funtools \s-1ASCII\s0 output -[\fIfuntbl\fR\|(1)] -.IP "\(bu" 4 -funtools and ds9 image display -[funds9(7)] -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Funtools Programming -.RS 4 -.IP "\(bu" 4 -Funtools Programming Summary -[\fIfunlib\fR\|(3)] -.IP "\(bu" 4 -Funtools Programming Tutorial -[\fIfunlib\fR\|(3)] -.IP "\(bu" 4 -A Short Digression on Subroutine Order -[\fIfunlib\fR\|(3)] -.IP "\(bu" 4 -Compiling and Linking -[\fIfunlib\fR\|(3)] -.IP "\(bu" 4 -The Funtools Reference Handle -[\fIfunlib\fR\|(3)] -.IP "\(bu" 4 -The Funtools Programming Reference Manual -.RS 4 -.IP "\(bu" 4 -FunOpen: open a Funtools file -[\fIfunopen\fR\|(3)] -.IP "\(bu" 4 -FunImageGet: retrieve image data -[\fIfunimageget\fR\|(3)] -.IP "\(bu" 4 -FunImagePut: output image data -[\fIfunimageput\fR\|(3)] -.IP "\(bu" 4 -FunImageRowGet: retrieve image data by row -[\fIfunimagerowget\fR\|(3)] -.IP "\(bu" 4 -FunImageRowPut: output image data by row -[\fIfunimagerowput\fR\|(3)] -.IP "\(bu" 4 -FunTableRowGet: retrieve rows from a table -[\fIfuntablerowget\fR\|(3)] -.IP "\(bu" 4 -FunTableRowPut: output rows to a table -[\fIfuntablerowput\fR\|(3)] -.IP "\(bu" 4 -FunColumnSelect: select columns in a table for access -[\fIfuncolumnselect\fR\|(3)] -.IP "\(bu" 4 -FunColumnActivate: activate columns in a table for read/write -[\fIfuncolumnactivate\fR\|(3)] -.IP "\(bu" 4 -FunColumnLookup: lookup info about the columns in a table -[\fIfuncolumnlookup\fR\|(3)] -.IP "\(bu" 4 -FunInfoGet: get info about an image or table -[\fIfuninfoget\fR\|(3)] -.IP "\(bu" 4 -FunInfoPut: put info about an image or table -[\fIfuninfoput\fR\|(3)] -.IP "\(bu" 4 -FunParamGet: get header param -[\fIfunparamget\fR\|(3)] -.IP "\(bu" 4 -FunParamPut: put header param -[\fIfunparamput\fR\|(3)] -.IP "\(bu" 4 -FunFlush: flush I/O in a Funtools file -[\fIfunflush\fR\|(3)] -.IP "\(bu" 4 -FunClose: close a Funtools file -[\fIfunclose\fR\|(3)] -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Funtools Programming Examples -[\fIfunlib\fR\|(3)] -.RS 4 -.IP "\(bu" 4 -evmerge: merge new columns with existing columns -.IP "\(bu" 4 -evcols: add column and rows to binary tables -.IP "\(bu" 4 -imblank: blank out image values below a threshold -.RE -.RS 4 -.RE -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Funtools Data Files -[funfiles(7)] -.RS 4 -.IP "\(bu" 4 -Supported Data Formats -.RS 4 -.IP "\(bu" 4 -\&\s-1FITS\s0 File and Extensions -.IP "\(bu" 4 -Non-FITS Raw Event Files -.IP "\(bu" 4 -Non-FITS Array Files -.IP "\(bu" 4 -Column-based Text (\s-1ASCII\s0) Files -.IP "\(bu" 4 -Database Views of Tables -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Image Sections and Blocking -.IP "\(bu" 4 -Binning \s-1FITS\s0 Binary Tables and Non-FITS Event Files -.IP "\(bu" 4 -Disk Files and Other Supported File Types -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Funtools Data Filtering -.RS 4 -.IP "\(bu" 4 -Table Filtering -[funfilters(7)] -.IP "\(bu" 4 -Fast Table Filtering using Indexes -[funidx(7)] -.IP "\(bu" 4 -Spatial Region Filtering -[funregions(7)] -.RS 4 -.IP "\(bu" 4 -Region Geometry -[reggeometry(7)] -.IP "\(bu" 4 -Region Algebra -[regalgebra(7)] -.IP "\(bu" 4 -Region Coordinates -[regcoords(7)] -.IP "\(bu" 4 -Region Boundaries -[regbounds(7)] -.IP "\(bu" 4 -Differences Between Funtools and \s-1IRAF\s0 Regions -[regdiff(7)] -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Combining Table and Region Filters -[funcombine(7)] -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Miscellaneous -.RS 4 -.IP "\(bu" 4 -Funtools Environment Variables -[funenv(7)] -.IP "\(bu" 4 -Funtools ChangeLog -.RE -.RS 4 -.RE diff --git a/funtools/man/man7/funview.7 b/funtools/man/man7/funview.7 deleted file mode 100644 index 06a0d56..0000000 --- a/funtools/man/man7/funview.7 +++ /dev/null @@ -1,523 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funview 7" -.TH funview 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -Funview \- Database View Support for Tables -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document contains a summary of the options for utilizing -database-inspired Views of tables. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBDatabase Views\fR -.PP -In database parlance, a \fBView\fR defines a \*(L"virtual table\*(R", i.e., -a description of row and/or column selection filters (but with no -permanent storage space allocated). When used in place of a table, a -View selects the specified rows and/or columns from one or more real -tables. Views enable you to see complicated data tables in a more -convenient format. They also can be used as a security mechanism, by -restricting user access to specific columns and/or rows. [See: -.PP -http://www.cs.unibo.it/~ciaccia/COURSES/RESOURCES/SQLTutorial/sqlch5.htm -.PP -for a good discussion of \s-1SQL\s0 Views.] -.PP -Funtools supports an expanded notion of Views for all tabular data -(\s-1FITS\s0 tables, raw binary tables, and \s-1ASCII\s0 column files). Funtools -Views allow you to pre-set values for the filter specification, the -columns to activate, and display format (though the latter is for -fundisp only). Setting the filter and column activation values -provides functionality equivalent to that of a classical database -View, while the ability to set the format is similar to classical -report writing capabilities. -.PP -\&\fBFuntools View Attributes\fR -.PP -A Funtools View is a text file containing one or more of the following -columns: -.PP -.Vb 7 -\& column description -\& ------ ----------------------------- -\& view name of view -\& file data file name or template -\& filter filter specification -\& columns columns to activate -\& format fundisp format specification -.Ve -.PP -All of the attribute columns are optional, including -the \fBview\fR name itself. This means that a View can be named or -unnamed. Unnamed Views can refer to a specific file or a template of -files (obviously if neither the view or the file column is specified, -the input View specification will never be used). You can specify any -combination of filter, column, and format parameters. (It also is -possible to apply file-specific View to other files; see the discussion -on \fBView Lists\fR below). Each column has a size limit of 1024 characters. -.PP -For example, consider the following View file: -.PP -.Vb 13 -\& view file format columns filter -\& ---- ---------------------- ------ ------------ ------- -\& x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1 -\& x2 ${HOME}/data/snr.ev x y pi pha cir 512 512 .1 -\& x1 ${HOME}/data/snr.ev cir 512 512 .1 -\& x1a ${HOME}/data/snr.ev x y pi pha -\& x0 ${HOME}/data/snr.ev -\& xf I=%4d -\& xc x y pi pha -\& xr cir 512 512 .1 -\& *.ev x y pi pha -\& *.fit x y dx dy cir 400 400 3 -\& *.fits I=%3d x y dx dy cir 400 400 3 -.Ve -.PP -This database example is in rdb format, i.e. using tab delimiters and -permitting null values. Any valid \s-1ASCII\s0 table format is acceptable, -but if you use a format that does not permit null values, it will be -necessary to quote the null strings. -.PP -The first five entries (x3, x2, x1, x1a, x0) are named entries defining -default values specifically for the snr.ev data file. Typically, you -would use these Views by specifying View name, and the corresponding -file, filter, column, and format values would be used. Note that the x0 -View is essentially an alias for the pathname of this file. -.PP -The next three entries define defaults that can be applied to any -file. You typically would use these View names in conjunction with -a specific file name (see \fBView Lists\fR below) so that the associated -parameter(s) were applied to that file. -.PP -The last three entry in the database define unnamed Views that -pertains to all files ending with the specified templates. In these -cases, any View that specifies a file name matching the file template -would be processed with the associated parameter attributes. -.PP -\&\fBInvoking a Funtools View (in Place of an Input File)\fR -.PP -To use a Funtools View, you simply pre-pend the \*(L"v:\*(R" prefix to a View name or -a file name where an input file name usually is specified. For example: -.PP -.Vb 1 -\& fundisp v:x3 -.Ve -.PP -specifies that the View named x3 (with its file name and associated -parameters) is processed as the input file to fundisp. Using the -example database, above, this is equivalent to: -.PP -.Vb 1 -\& fundisp \-f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha" -.Ve -.PP -That is, the format is used with fundisp's \-f (format) switch, while the -filename and extension are composed of the x3 View's filename and -region filter. -.PP -Similarly, executing a command such as: -.PP -.Vb 1 -\& fundisp v:foo.fit -.Ve -.PP -will match the unnamed View associated with the template \*(L"*.fit\*(R". -This is equivalent to executing: -.PP -.Vb 1 -\& fundisp foo.fit'[cir 400 400 3]' "x y dx dy" -.Ve -.PP -Of course, if you omit the \*(L"v:\*(R" prefix, then no View processing takes place: -.PP -.Vb 2 -\& fundisp foo.fit # process foo.fit without any View parameters -\& fundisp x3 # error (assuming there is no file named x3) -.Ve -.PP -\&\fBBasic View Matching Rules\fR -.PP -When a \*(L"v:\*(R" prefix is recognized, Funtools searches for a View database -file in the following order: -.PP -.Vb 5 -\& location description -\& ------------ ------------------------------------ -\& FUN_VIEWFILE environment variable (any file name) -\& ./.funtools.vu hidden file, default name -\& $HOME/.funtools.vu hidden file, default name -.Ve -.PP -The first View database file located is used to construct a new -filename, as well as an activation column specification and a format -specification. The following rules are used: -.PP -1. An attempt is made to match the input name (i.e., the part of the -input View after the \*(L"v:\*(R" prefix) against the \fBview\fR column value -(if present) of each row in the database. If a match is found, the -values of all non-blank columns are saved for later use. Also note -that the first match terminates the search: i.e., the order of the -database rows matters. -.PP -2. If no \fBview\fR match is made, an attempt is made to match the input -name against the \fBfile\fR column value (if present). Matching is -performed on the full pathname of both the input name and the -database file name, and on the non-directory (root) part of these -files. This means that the root specification: -.PP -.Vb 1 -\& fundisp v:snr.ev -.Ve -.PP -will match a row in the database that has a full pathname in the file, -allowing you to use a \fBfile\fR\-matched View without having to -specify the full pathname. In this example, the \*(L"v:snr.ev\*(R" View -specification will match the first row (v:x3) in the database: -.PP -.Vb 1 -\& x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1 -.Ve -.PP -even though the row contains a fully qualified pathname as the file -value. Once again, values of all non-blank columns are saved, and the -first match terminates the search. -.PP -3. If neither a \fBview\fR or a \fBview\fR match has been found, -then a simple template match is attempted against the \fBview\fR -values. Template matching supports a simplified version of file -globbing (not a regular expression), with support for a single \*(L"*\*(R" -(all characters), \*(L"?\*(R" (single character), or \*(L"[...]\*(R" (range) specification. -.PP -4. If no template match was found on the \fBview\fR column, then a -simple template match is attempted against the \fBfile\fR columns. -.PP -5. If no match is found, then the filename (minus the \*(L"v:\*(R" prefix) is -returned. -.PP -More on View Matching Rules - Single vs. Multiple Matches -.PP -The matching rules described above stop after the first match, -regardless of whether that match provides values for all three -parameters (filter, columns, and format). In cases where a \fBview\fR -or \fBfile\fR match does not provide all three values, it is possible -that a template match might do so. With regard to the example View -database above, the x1 View provides only a filter, while omitting -both the format and columns values. But note that the final rows in -the database could provide the values via a template match on the -filename. This sort of multiple matching is especially valuable in -order to provide \*(L"global\*(R" values to several Views. -.PP -Obviously, multiple matching might not be wanted in every -case. Therefore, we support both multiple matching and single matching -according to the value of the \s-1FUN_VIEWMATCH\s0 environment variable. If -the \s-1FUN_VIEWMATCH\s0 environment variable exists and if its value begins -with \*(L"s\*(R", then a single match is used and missing parameters are not -filled in with subsequent template matches on the file name. That is, -matching rules above are followed exactly as explained above. If the -value of this environment variable begins with \*(L"m\*(R" (or does not exist), -then multiple matches are used to try to fill in missing parameters. -In this case, template matching always takes place and missing values are -taken from these template matches. -.PP -Thus, in the example above, the View specification: -.PP -.Vb 1 -\& fundisp v:x1 -.Ve -.PP -will take the file name and filter value from the x1 View: -.PP -.Vb 1 -\& x1 ${HOME}/data/snr.ev cir 512 512 .1 -.Ve -.PP -The column value then will be taken from the \*(L"*.ev\*(R" file template match -against the x1 file name: -.PP -.Vb 1 -\& *.ev x y pi pha -.Ve -.PP -Note once again that order is important: missing values are taken in the -order in which the template matches are processed. -.PP -View Lists - Applying a View to Any File -.PP -It is possible to apply a named View, or even several Views, to any -data file by appending a \fBviewlist\fR immediately after the standard \*(L"v:\*(R" -prefix. A viewlist takes the form: -.PP -.Vb 1 -\& :v1,v2,...vn: -.Ve -.PP -where v1, v2, etc. are named Views. The two \*(L":\*(R" colon characters surrounding -the list are required. Thus, the syntax for applying a viewlist to a file is: -.PP -.Vb 1 -\& v::view1,view2,...viewn:filename -.Ve -.PP -Note that the name after the last \*(L":\*(R" is assumed to be a file; it is -not permissible (or sensible) to use a View name. -.PP -For example, the View specification: -.PP -.Vb 1 -\& fundisp v::x2:foo -.Ve -.PP -applies the x2 View to the file foo (even if there is a View named foo) -and (in using our example database) is equivalent to: -.PP -.Vb 1 -\& ./fundisp foo'[cir 512 512 .1] "x y pi pha" -.Ve -.PP -The same command can be effected using a list of Views: -.PP -.Vb 1 -\& fundisp v::x1,x1a:foo -.Ve -.PP -What happens if a viewlist is used and the file also matches a -template? Consider, for example, this View specification: -.PP -.Vb 1 -\& fundisp v::x2:foo.fit -.Ve -.PP -Here, the x2 View will supply filter and column values, while the -template *.fit can also supply (different) filter and column -values. In this case, the explicitly specified Views of the viewlist -trump the matched view values. -.PP -On the other hand, if a file template match can supply a View value -that is not supplied by the viewlist, then that value will be taken -from the file template match. For example: -.PP -.Vb 1 -\& fundisp v::x2:foo.fits -.Ve -.PP -does not explicitly supply a format value, but the file match on *.fits -can and does. You can avoid supplying missing values using file template -matching by replacing the first \*(L":\*(R" with a \*(L"\-\*(R" in a viewlist -specification: -.PP -.Vb 1 -\& fundisp v:-x2:foo.fits -.Ve -.PP -The use of \*(L":+\*(R" to explicitly allow file template matching is also -supported, but is the same as the default case. Note that the nuances -of viewlist support are subject to change as our experience and -understanding grow. -.PP -\&\fBOverriding Values Associated with a View\fR -.PP -To override values associated with a View, simply supply the override -values in the correct place on the command line. Thus, given -the example database described above, the command: -.PP -.Vb 1 -\& fundisp v:x3 -.Ve -.PP -specifies that the View named x3, along with its file name and -associated parameters, be processed as the input file to fundisp in -this way: -.PP -.Vb 1 -\& fundisp \-f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha" -.Ve -.PP -To override one or more of these values, simply specify a new value -for the format, filter, or columns. For example, if your input View file -contains a filter, then the View will use that filter as an override -of the View filter: -.PP -.Vb 1 -\& fundisp v:x3'[cir 400 400 3]' -.Ve -.PP -will use the columns and format of the x3 View but not the x3 filter. Further -examples are: -.PP -.Vb 2 -\& fundisp v:x3 "x y dx dy" # activate a different set of columns -\& fundisp \-f "I=%3d" v:x3 # use a different format statement -.Ve -.PP -Note that extension names, extension index values, and other -non-filter specifications \fBdo not\fR override the View -filter. Thus: -.PP -.Vb 1 -\& fundisp v:foo.fit[3] -.Ve -.PP -will still use the filter associated with the .fit template (see above), since -the \*(L"3\*(R" is an extension index, not a filter. -.PP -\&\fBEnvironment Variables\fR -.PP -The following environment variables are used by Funtools Views: -.IP "\(bu" 4 -\&\fB\s-1FUN_VIEWNAME\s0\fR -.Sp -The \fB\s-1FUN_VIEWNAME\s0\fR environment variable specifies the -name and location of the View database file. If not present, the -files ./.funtools.vu and \f(CW$HOME\fR/.funtools.vu are searched for, in -that order. -.IP "\(bu" 4 -\&\fB\s-1FUN_VIEWMATCH\s0\fR -.Sp -The \fB\s-1FUN_VIEWMATCH\s0\fR environment variable specifies whether a -single match or multiple match algorithm is used to locate parameter -values. If the value of this environment variable begins with \*(L"s\*(R", -then a single match is used and missing parameters are not filled in -with subsequent template matches on the file name. If the value begins -with \*(L"m\*(R", then multiple matches are used to try to fill in missing -parameters. The default is to use multiple matches. -.PP -\&\fBRestrictions and Problems\fR -.PP -Support for overriding a filter (while not overriding extension names, -extension indexes, etc.) requires that we can sense the presence of a -filter in a bracket specification. It is unclear yet whether our -algorithm is perfect. -.PP -Go to Funtools Help Index -.PP -Last updated: August 3, 2007 diff --git a/funtools/man/man7/regalgebra.7 b/funtools/man/man7/regalgebra.7 deleted file mode 100644 index 93cb985..0000000 --- a/funtools/man/man7/regalgebra.7 +++ /dev/null @@ -1,400 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "regalgebra 7" -.TH regalgebra 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -RegAlgebra \- Boolean Algebra on Spatial Regions -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document describes the boolean arithmetic defined for -region expressions. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -When defining a region, several shapes can be combined using boolean -operations. The boolean operators are (in order of precedence): -.PP -.Vb 6 -\& Symbol Operator Associativity -\& ------ -------- ------------- -\& ! not right to left -\& & and left to right -\& ^ exclusive or left to right -\& | inclusive or left to right -.Ve -.PP -For example, to create a mask consisting of a large circle with a -smaller box removed, one can use the \fBand\fR and \fBnot\fR -operators: -.PP -.Vb 1 -\& CIRCLE(11,11,15) & !BOX(11,11,3,6) -.Ve -.PP -and the resulting mask is: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 1:1111111111111111111111.................. -\& 2:1111111111111111111111.................. -\& 3:11111111111111111111111................. -\& 4:111111111111111111111111................ -\& 5:111111111111111111111111................ -\& 6:1111111111111111111111111............... -\& 7:1111111111111111111111111............... -\& 8:1111111111111111111111111............... -\& 9:111111111...1111111111111............... -\& 10:111111111...1111111111111............... -\& 11:111111111...1111111111111............... -\& 12:111111111...1111111111111............... -\& 13:111111111...1111111111111............... -\& 14:111111111...1111111111111............... -\& 15:1111111111111111111111111............... -\& 16:1111111111111111111111111............... -\& 17:111111111111111111111111................ -\& 18:111111111111111111111111................ -\& 19:11111111111111111111111................. -\& 20:1111111111111111111111.................. -\& 21:1111111111111111111111.................. -\& 22:111111111111111111111................... -\& 23:..11111111111111111..................... -\& 24:...111111111111111...................... -\& 25:.....11111111111........................ -\& 26:........................................ -\& 27:........................................ -\& 28:........................................ -\& 29:........................................ -\& 30:........................................ -\& 31:........................................ -\& 32:........................................ -\& 33:........................................ -\& 34:........................................ -\& 35:........................................ -\& 36:........................................ -\& 37:........................................ -\& 38:........................................ -\& 39:........................................ -\& 40:........................................ -.Ve -.PP -A three-quarter circle can be defined as: -.PP -.Vb 1 -\& CIRCLE(20,20,10) & !PIE(20,20,270,360) -.Ve -.PP -and looks as follows: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 1:........................................ -\& 2:........................................ -\& 3:........................................ -\& 4:........................................ -\& 5:........................................ -\& 6:........................................ -\& 7:........................................ -\& 8:........................................ -\& 9:........................................ -\& 10:........................................ -\& 11:...............111111111................ -\& 12:..............11111111111............... -\& 13:............111111111111111............. -\& 14:............111111111111111............. -\& 15:...........11111111111111111............ -\& 16:..........1111111111111111111........... -\& 17:..........1111111111111111111........... -\& 18:..........1111111111111111111........... -\& 19:..........1111111111111111111........... -\& 20:..........1111111111111111111........... -\& 21:..........1111111111.................... -\& 22:..........1111111111.................... -\& 23:..........1111111111.................... -\& 24:..........1111111111.................... -\& 25:...........111111111.................... -\& 26:............11111111.................... -\& 27:............11111111.................... -\& 28:..............111111.................... -\& 29:...............11111.................... -\& 30:........................................ -\& 31:........................................ -\& 32:........................................ -\& 33:........................................ -\& 34:........................................ -\& 35:........................................ -\& 36:........................................ -\& 37:........................................ -\& 38:........................................ -\& 39:........................................ -\& 40:........................................ -.Ve -.PP -Two non-intersecting ellipses can be made into the same region: -.PP -.Vb 1 -\& ELL(20,20,10,20,90) | ELL(1,1,20,10,0) -.Ve -.PP -and looks as follows: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 1:11111111111111111111.................... -\& 2:11111111111111111111.................... -\& 3:11111111111111111111.................... -\& 4:11111111111111111111.................... -\& 5:1111111111111111111..................... -\& 6:111111111111111111...................... -\& 7:1111111111111111........................ -\& 8:111111111111111......................... -\& 9:111111111111............................ -\& 10:111111111............................... -\& 11:...........11111111111111111............ -\& 12:........111111111111111111111111........ -\& 13:.....11111111111111111111111111111...... -\& 14:....11111111111111111111111111111111.... -\& 15:..11111111111111111111111111111111111... -\& 16:.1111111111111111111111111111111111111.. -\& 17:111111111111111111111111111111111111111. -\& 18:111111111111111111111111111111111111111. -\& 19:111111111111111111111111111111111111111. -\& 20:111111111111111111111111111111111111111. -\& 21:111111111111111111111111111111111111111. -\& 22:111111111111111111111111111111111111111. -\& 23:111111111111111111111111111111111111111. -\& 24:.1111111111111111111111111111111111111.. -\& 25:..11111111111111111111111111111111111... -\& 26:...11111111111111111111111111111111..... -\& 27:.....11111111111111111111111111111...... -\& 28:.......111111111111111111111111......... -\& 29:...........11111111111111111............ -\& 30:........................................ -\& 31:........................................ -\& 32:........................................ -\& 33:........................................ -\& 34:........................................ -\& 35:........................................ -\& 36:........................................ -\& 37:........................................ -\& 38:........................................ -\& 39:........................................ -\& 40:........................................ -.Ve -.PP -You can use several boolean operations in a single region expression, -to create arbitrarily complex regions. With the important exception -below, you can apply the operators in any order, using parentheses if -necessary to override the natural precedences of the operators. -.PP -\&\s-1NB:\s0 Using a panda shape is always much more efficient than explicitly -specifying \*(L"pie & annulus\*(R", due to the ability of panda to place a -limit on the number of pixels checked in the pie shape. If you are -going to specify the intersection of pie and annulus, use panda -instead. -.PP -As described in \*(L"help regreometry\*(R", the \fB\s-1PIE\s0\fR slice goes to the -edge of the field. To limit its scope, \fB\s-1PIE\s0\fR usually is is -combined with other shapes, such as circles and annuli, using boolean -operations. In this context, it is worth noting that that there is a -difference between \fB\-PIE\fR and \fB&!PIE\fR. The former is a -global exclude of all pixels in the \fB\s-1PIE\s0\fR slice, while the latter -is a local excludes of pixels affecting only the region(s) with which -the \fB\s-1PIE\s0\fR is combined. For example, the following region uses -\&\fB&!PIE\fR as a local exclude of a single circle. Two other circles -are also defined and are unaffected by the local exclude: -.PP -.Vb 3 -\& CIRCLE(1,8,1) -\& CIRCLE(8,8,7)&!PIE(8,8,60,120)&!PIE(8,8,240,300) -\& CIRCLE(15,8,2) -.Ve -.PP -.Vb 17 -\& 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 -\& - - - - - - - - - - - - - - - -\& 15: . . . . . . . . . . . . . . . -\& 14: . . . . 2 2 2 2 2 2 2 . . . . -\& 13: . . . 2 2 2 2 2 2 2 2 2 . . . -\& 12: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 11: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 10: . . . . 2 2 2 2 2 2 2 . . . . -\& 9: . . . . . . 2 2 2 . . . . 3 3 -\& 8: 1 . . . . . . . . . . . . 3 3 -\& 7: . . . . . . 2 2 2 . . . . 3 3 -\& 6: . . . . 2 2 2 2 2 2 2 . . . . -\& 5: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 4: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 3: . . . 2 2 2 2 2 2 2 2 2 . . . -\& 2: . . . . 2 2 2 2 2 2 2 . . . . -\& 1: . . . . . . . . . . . . . . . -.Ve -.PP -Note that the two other regions are not affected by the \fB&!PIE\fR, -which only affects the circle with which it is combined. -.PP -On the other hand, a \fB\-PIE\fR is an global exclude that does -affect other regions with which it overlaps: -.PP -.Vb 5 -\& CIRCLE(1,8,1) -\& CIRCLE(8,8,7) -\& \-PIE(8,8,60,120) -\& \-PIE(8,8,240,300) -\& CIRCLE(15,8,2) -.Ve -.PP -.Vb 17 -\& 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 -\& - - - - - - - - - - - - - - - -\& 15: . . . . . . . . . . . . . . . -\& 14: . . . . 2 2 2 2 2 2 2 . . . . -\& 13: . . . 2 2 2 2 2 2 2 2 2 . . . -\& 12: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 11: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 10: . . . . 2 2 2 2 2 2 2 . . . . -\& 9: . . . . . . 2 2 2 . . . . . . -\& 8: . . . . . . . . . . . . . . . -\& 7: . . . . . . 2 2 2 . . . . . . -\& 6: . . . . 2 2 2 2 2 2 2 . . . . -\& 5: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 4: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 3: . . . 2 2 2 2 2 2 2 2 2 . . . -\& 2: . . . . 2 2 2 2 2 2 2 . . . . -\& 1: . . . . . . . . . . . . . . . -.Ve -.PP -The two smaller circles are entirely contained within the two exclude -\&\fB\s-1PIE\s0\fR slices and therefore are excluded from the region. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/regbounds.7 b/funtools/man/man7/regbounds.7 deleted file mode 100644 index 40a1648..0000000 --- a/funtools/man/man7/regbounds.7 +++ /dev/null @@ -1,305 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "regbounds 7" -.TH regbounds 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -RegBounds \- Region Boundaries -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -Describes how spatial region boundaries are handled. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The golden rule for spatial region filtering was first enunciated by -Leon VanSpeybroeck in 1986: -.PP -Each photon will be counted once, and no photon will be counted -more than once. -.PP -This means that we must be careful about boundary -conditions. For example, if a circle is contained in an annulus such -that the inner radius of the annulus is the same as the radius of the -circle, then photons on that boundary must always be assigned to one -or the other region. That is, the number of photons in both regions -must equal the sum of the number of photons in each region taken -separately. -.PP -With this in mind, the rules for determining whether a boundary image -pixel or table row are assigned to a region are defined below. -.PP -\&\fBImage boundaries - radially-symmetric shapes (circle, annuli, ellipse)\fR -.PP -For image filtering, pixels whose center is inside the boundary are -included. This also applies non-radially-symmetric shapes. When a -pixel center is exactly on the boundary, the pixel assignment rule is: -.IP "\(bu" 4 -the outer boundary of a symmetric shape does not include such pixels -.IP "\(bu" 4 -the inner boundary of a symmetric shape (annulus) includes such pixels -.PP -In this way, an annulus with radius from 0 to 1, centered exactly on a -pixel, includes the pixel on which it is centered, but none of its -neighbors. -.PP -These rules ensure that when defining concentric shapes, no pixels are -omitted between concentric regions and no pixels are claimed by two -regions. When applied to small symmetric shapes, the shape is less -likely to be skewed, as would happen with non-radially-symmetric -rules. These rules differ from the rules for box-like shapes, which -are more likely to be positioned adjacent to one another. -.PP -\&\fBImage Boundaries: non-radially symmetric shapes (polygons, boxes)\fR -.PP -For image filtering, pixels whose center is inside the boundary are -included. This also applies radially-symmetric shapes. When a pixel -center is exactly on the boundary of a non-radially symmetric region, -the pixel is included in the right or upper region, but not the left -or lower region. This ensures that geometrically adjoining regions -touch but don't overlap. -.PP -\&\fBRow Boundaries are Analytic\fR -.PP -When filtering table rows, the boundary rules are the same as for -images, except that the calculation is not done on the center of a -pixel, (since table rows, especially X\-ray events rows, often have -discrete, floating point positions) but are calculated exactly. That -is, an row is inside the boundary without regard to its integerized -pixel value. For rows that are exactly on a region boundary, the -above rules are applied to ensure that all rows are counted once and -no row is counted more than once. -.PP -Because row boundaries are calculated differently from image boundaries, -certain programs will give different results when filtering the same -region file. In particular, fundisp/funtable (which utilize analytic -row filtering) perform differently from funcnts (which performs image -filtering, even on tables). -.PP -\&\fBImage Boundaries vs. Row Boundaries: Practical Considerations\fR -.PP -You will sometimes notice a discrepancy between running funcnts on an -binary table file and running fundisp on the same file with the same filter. -For example, consider the following: -.PP -.Vb 2 -\& fundisp test1.fits"[box(4219,3887,6,6,0)]" | wc -\& 8893 320148 3752846 -.Ve -.PP -Since fundisp has a 2\-line header, there are actually 8891 photons -that pass the filter. But then run funtable and select only the -rows that pass this filter, placing them in a new file: -.PP -.Vb 1 -\& ./funtable test1.fits"[box(4219,3887,6,6,0)]" test2.fits -.Ve -.PP -Now run funcnts using the original filter on the derived file: -.PP -.Vb 1 -\& ./funcnts test2.fits "physical; box(4219,3887,6,6,0)" -.Ve -.PP -.Vb 1 -\& [... lot of processed output ...] -.Ve -.PP -.Vb 4 -\& # the following source and background components were used: -\& source region(s) -\& ---------------- -\& physical; box(4219,3887,6,6,0) -.Ve -.PP -.Vb 3 -\& reg counts pixels -\& ---- ------------ --------- -\& 1 7847.000 36 -.Ve -.PP -There are 1044 rows (events) that pass the row filter in fundisp (or -funtable) but fail to make it through funcnts. Why? -.PP -The reason can be traced to how analytic row filtering (fundisp, funtable) -differs from integerized pixel filtering(funcnts, funimage). Consider the -region: -.PP -.Vb 1 -\& box(4219,3887,6,6,0) -.Ve -.PP -Analytically (i.e., using row filtering), positions will pass this -filter successfully if: -.PP -.Vb 2 -\& 4216 <= x <= 4222 -\& 3884 <= y <= 3890 -.Ve -.PP -For example, photons with position values of x=4216.4 or y=3884.08 will pass. -.PP -Integerized image filtering is different in that the pixels that will -pass this filter have centers at: -.PP -.Vb 2 -\& x = 4217, 4218, 4219, 4220, 4221, 4222 -\& y = 3885, 3886, 3887, 3888, 3889, 3890 -.Ve -.PP -Note that there are 6 pixels in each direction, as specified by the region. -That means that positions will pass the filter successfully if: -.PP -.Vb 2 -\& 4217 <= (int)x <= 4222 -\& 3885 <= (int)y <= 3890 -.Ve -.PP -Photons with position values of x=4216.4 or y=3884.08 will \s-1NOT\s0 pass. -.PP -Note that the position values are integerized, in effect, binned into -image values. This means that x=4222.4 will pass this filter, but not -the analytic filter above. We do this to maintain the design goal that -either all counts in a pixel are included in an integerized filter, or -else none are included. -.PP -[It could be argued that the correct photon limits for floating point -row data really should be: -.PP -.Vb 2 -\& 4216.5 <= x <= 4222.5 -\& 3884.5 <= y <= 3890.5 -.Ve -.PP -since each pixel extends for .5 on either side of the center. We chose -to the maintain integerized algorithm for all image-style filtering so -that funcnts would give the exact same results regardless of whether -a table or a derived non-blocked binned image is used.] -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/regcoords.7 b/funtools/man/man7/regcoords.7 deleted file mode 100644 index fd7615e..0000000 --- a/funtools/man/man7/regcoords.7 +++ /dev/null @@ -1,345 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "regcoords 7" -.TH regcoords 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -RegCoords \- Spatial Region Coordinates -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document describes the specification of coordinate systems, and the -interpretation of coordinate values, for spatial region filtering. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBPixel coordinate systems\fR -.PP -The default coordinate system for regions is \s-1PHYSICAL\s0, which means -that region position and size values are taken from the original -data. (Note that this is a change from the original \s-1IRAF/PROS\s0 -implementation, in which the \s-1IMAGE\s0 coordinate system was the default.) -\&\s-1PHYSICAL\s0 coordinates always refer to pixel positions on the original -image (using \s-1IRAF\s0 \s-1LTM\s0 and \s-1LTV\s0 keywords). With \s-1PHYSICAL\s0 coordinates, -if a set of coordinates specifies the position of an object in an -original \s-1FITS\s0 file, the same coordinates will specify the same object -in any \s-1FITS\s0 derived from the original. Physical coordinates are -invariant with blocking of \s-1FITS\s0 files or taking sections of images, -even when a blocked section is written to a new file. -.PP -Thus, although a value in pixels refers, by default, to the \s-1PHYSICAL\s0 -coordinate system, you may specify that position values refer to the -image coordinate system using the \fBglobal\fR or \fBlocal\fR -properties commands: -.PP -.Vb 2 -\& global coordsys image -\& circle 512 512 100 -.Ve -.PP -The \fBglobal\fR command changes the coordinate system for all -regions that follow, while the \fBlocal\fR command changes the -coordinate system only for the region immediately following: -.PP -.Vb 3 -\& local coordsys image -\& circle 512 512 100 -\& circle 1024 1024 200 -.Ve -.PP -This changes the coordinate system only for the region that follows. -In the above example, the second region uses the global coordinate -system (\s-1PHYSICAL\s0 by default). -.PP -\&\fBWorld Coordinate Systems\fR -.PP -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: -.PP -.Vb 10 -\& 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 -.Ve -.PP -In addition, two mosaic coordinate systems have been defined that -utilize the (evolving) \s-1IRAF\s0 mosaic keywords: -.PP -.Vb 4 -\& name description -\& ---- ----------- -\& AMPLIFIER mosaic coords of original file using ATM/ATV -\& DETECTOR mosaic coords of original file using DTM/DTV -.Ve -.PP -Again, to use one of these coordinate systems, the \fBglobal\fR or -\&\fBlocal\fR properties commands are used: -.PP -.Vb 1 -\& global coordsys galactic -.Ve -.PP -\&\fB\s-1WCS\s0 Positions and Sizes\fR -.PP -In addition to pixels, positional values in a WCS-enabled region can -be specified using sexagesimal or degrees format: -.PP -.Vb 11 -\& 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 -.Ve -.PP -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): -.PP -.Vb 7 -\& 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 -.Ve -.PP -Similarly, the units of size values are defined by the formating -character(s) attached to a number: -.PP -.Vb 9 -\& 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 -.Ve -.PP -For example: -.PP -.Vb 8 -\& 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 -.Ve -.PP -An example of using sky coordinate systems follows: -.PP -.Vb 4 -\& 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 -.Ve -.PP -At the \s-1FK4\s0 1950 coordinates 175.54d \s-1RA\s0, 20.01156d \s-1DEC\s0 exclude a 10 -minute by 10 minute box. Then at the \s-1FK5\s0 2000 coordinates 179.57d \s-1RA\s0 -22.4d \s-1DEC\s0 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. -.PP -\&\fB\s-1NB:\s0 The Meaning of Pure Numbers Are Context Sensitive\fR -.PP -When a \*(L"pure number\*(R" (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: -.PP -All pure numbers have implied units corresponding to the current -coordinate system. -.PP -If no coordinate system is explicitly specified, the default system is -implicitly assumed to be \s-1PHYSICAL\s0. In practice this means that for -\&\s-1IMAGE\s0 and \s-1PHYSICAL\s0 systems, pure numbers are pixels. Otherwise, -for all systems other than \s-1LINEAR\s0, pure numbers are degrees. For -\&\s-1LINEAR\s0 systems, pure numbers are in the units of the linear system. -This rule covers both positions and sizes. -.PP -As a corollary, when a sky-formatted number is used with the \s-1IMAGE\s0 -or \s-1PHYSICAL\s0 coordinate system (which includes the default case of no -coordsys being specified), the formatted number is assumed to be in -the units of the \s-1WCS\s0 contained in the current file. If no sky \s-1WCS\s0 is -specified, an error results. -.PP -Examples: -.PP -.Vb 2 -\& circle(512,512,10) -\& ellipse 202.44382d 47.181656d 0.01d 0.02d -.Ve -.PP -In the absence of a specified coordinate system, the circle uses the -default \s-1PHYSICAL\s0 units of pixels, while the ellipse explicitly uses degrees, -presumably to go with the \s-1WCS\s0 in the current file. -.PP -.Vb 5 -\& 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) -.Ve -.PP -Here, the circles use the \s-1FK5\s0 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. -.PP -Note that Chandra data format appears to use \*(L"coordsys=physical\*(R" -implicitly. Therefore, for most Chandra applications, valid regions -can be generated safely by asking ds9 to save/display regions in -pixels using the \s-1PHYSICAL\s0 coordsys. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/regdiff.7 b/funtools/man/man7/regdiff.7 deleted file mode 100644 index c9f6f6a..0000000 --- a/funtools/man/man7/regdiff.7 +++ /dev/null @@ -1,181 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "regdiff 7" -.TH regdiff 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -RegDiff \- Differences Between Funtools and IRAF Regions -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -Describes the differences between Funtools/ds9 regions and the old \s-1IRAF/PROS\s0 -regions. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -We have tried to make Funtools regions compatible with their -predecessor, \s-1IRAF/PROS\s0 regions. For simple regions and simple boolean -algebra between regions, there should be no difference between the two -implementations. The following is a list of differences and -incompatibilities between the two: -.IP "\(bu" 4 -If a pixel is covered by two different regions expressions, -Funtools assigns the mask value of the \fBfirst\fR region that -contains that pixel. That is, successive regions \fBdo not\fR -overwrite previous regions in the mask, as was the case with the -original \s-1PROS\s0 regions. This means that one must define overlapping -regions in the reverse order in which they were defined in \s-1PROS\s0. If -region N is fully contained within region M, then N should be defined -\&\fBbefore\fR M, or else it will be \*(L"covered up\*(R" by the latter. This -change is necessitated by the use of optimized filter compilation, i.e., -Funtools only tests individual regions until a proper match is made. -.IP "\(bu" 4 -The \fB\s-1PANDA\s0\fR region has replaced the old \s-1PROS\s0 syntax in which -a \fB\s-1PIE\s0\fR accelerator was combined with an \fB\s-1ANNULUS\s0\fR accelerator -using \fB\s-1AND\s0\fR. That is, -.Sp -.Vb 1 -\& ANNULUS(20,20,0,15,n=4) & PIE(20,20,0,360,n=3) -.Ve -.Sp -has been replaced by: -.Sp -.Vb 1 -\& PANDA(20,20,0,360,3,0,15,4) -.Ve -.Sp -The \s-1PROS\s0 syntax was inconsistent with the meaning of the \fB\s-1AND\s0\fR operator. -.IP "\(bu" 4 -The meaning of pure numbers (i.e., without format specifiers) in -regions has been clarified, as has the syntax for specifying coordinate -systems. See the general discussion on -Spatial Region Filtering -for more information. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/reggeometry.7 b/funtools/man/man7/reggeometry.7 deleted file mode 100644 index 8eb15e7..0000000 --- a/funtools/man/man7/reggeometry.7 +++ /dev/null @@ -1,1271 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "reggeometry 7" -.TH reggeometry 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -RegGeometry \- Geometric Shapes in Spatial Region Filtering -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document describes the geometry of regions available for spatial -filtering in \s-1IRAF/PROS\s0 analysis. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBGeometric shapes\fR -.PP -Several geometric shapes are used to describe regions. The valid -shapes are: -.PP -.Vb 11 -\& 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 -.Ve -.PP -All arguments are real values; integer values are automatically -converted to real where necessary. All angles are in degrees and -specify angles that run counter-clockwise from the positive y\-axis. -.PP -Shapes can be specified using \*(L"command\*(R" syntax: -.PP -.Vb 1 -\& [shape] arg1 arg2 ... -.Ve -.PP -or using \*(L"routine\*(R" syntax: -.PP -.Vb 1 -\& [shape](arg1, arg2, ...) -.Ve -.PP -or by any combination of the these. (Of course, the parentheses must -balance and there cannot be more commas than necessary.) The shape -keywords are case\-insensitive. Furthermore, any shape can be -specified by a three-character unique abbreviation. For example, one -can specify three circular regions as: -.PP -.Vb 1 -\& "foo.fits[CIRCLE 512 512 50;CIR(128 128, 10);cir(650,650,20)]" -.Ve -.PP -(Quotes generally are required to protect the region descriptor -from being processed by the Unix shell.) -.PP -The \fBannulus\fR shape specifies annuli, centered at xcenter, -ycenter, with inner and outer radii (r1, r2). For example, -.PP -.Vb 1 -\& ANNULUS 25 25 5 10 -.Ve -.PP -specifies an annulus centered at 25.0 25.0 with an inner radius of 5.0 and -an outer radius of 10. Assuming (as will be done for all examples in this -document, unless otherwise noted) this shape is used in a mask of size 40x40, -it will look like this: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:....................111111111........... -\& 33:...................11111111111.......... -\& 32:.................111111111111111........ -\& 31:.................111111111111111........ -\& 30:................11111111111111111....... -\& 29:...............1111111.....1111111...... -\& 28:...............111111.......111111...... -\& 27:...............11111.........11111...... -\& 26:...............11111.........11111...... -\& 25:...............11111.........11111...... -\& 24:...............11111.........11111...... -\& 23:...............11111.........11111...... -\& 22:...............111111.......111111...... -\& 21:...............1111111.....1111111...... -\& 20:................11111111111111111....... -\& 19:.................111111111111111........ -\& 18:.................111111111111111........ -\& 17:...................11111111111.......... -\& 16:....................111111111........... -\& 15:........................................ -\& 14:........................................ -\& 13:........................................ -\& 12:........................................ -\& 11:........................................ -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:........................................ -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -The \fBbox\fR shape specifies an orthogonally oriented box, -centered at xcenter, ycenter, of size xwidth, yheight. It requires four -arguments and accepts an optional fifth argument to specify a rotation angle. -When the rotation angle is specified (in degrees), the box is rotated by -an angle that runs counter-clockwise from the positive y\-axis. -.PP -The \fBbox\fR shape specifies a rotated box, centered at -xcenter, ycenter, of size xwidth, yheight. The box is rotated by an angle -specified in degrees that runs counter-clockwise from the positive y\-axis. -If the angle argument is omitted, it defaults to 0. -.PP -The \fBcircle\fR shape specifies a circle, centered at xcenter, -ycenter, of radius r. It requires three arguments. -.PP -The \fBellipse\fR shape specifies an ellipse, centered at -xcenter, ycenter, with y\-axis width a and the y\-axis length b defined such -that: -.PP -.Vb 1 -\& x**2/a**2 + y**2/b**2 = 1 -.Ve -.PP -Note that a can be less than, equal to, or greater than b. The ellipse -is rotated the specified number of degrees. The rotation is done according -to astronomical convention, counter-clockwise from the positive y\-axis. -An ellipse defined by: -.PP -.Vb 1 -\& ELLIPSE 20 20 5 10 45 -.Ve -.PP -will look like this: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:........................................ -\& 33:........................................ -\& 32:........................................ -\& 31:........................................ -\& 30:........................................ -\& 29:........................................ -\& 28:........................................ -\& 27:............111111...................... -\& 26:............11111111.................... -\& 25:............111111111................... -\& 24:............11111111111................. -\& 23:............111111111111................ -\& 22:............111111111111................ -\& 21:.............111111111111............... -\& 20:.............1111111111111.............. -\& 19:..............111111111111.............. -\& 18:...............111111111111............. -\& 17:...............111111111111............. -\& 16:................11111111111............. -\& 15:..................111111111............. -\& 14:...................11111111............. -\& 13:.....................111111............. -\& 12:........................................ -\& 11:........................................ -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:........................................ -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -The \fBfield\fR shape specifies the entire field as a -region. It is not usually specified explicitly, but is used implicitly in the -case where no regions are specified, that is, in cases where either a null -string or some abbreviation of the string \*(L"none\*(R" is input. -\&\fBField\fR takes no arguments. -.PP -The \fBpie\fR shape specifies an angular wedge of the entire field, -centered at xcenter, ycenter. The wedge runs between the two specified angles. -The angles are given in degrees, running counter-clockwise from the positive -x\-axis. For example, -.PP -.Vb 1 -\& PIE 20 20 90 180 -.Ve -.PP -defines a region from 90 degrees to 180 degrees, i.e., quadrant 2 of the -Cartesian plane. The display of such a region looks like this: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:11111111111111111111.................... -\& 39:11111111111111111111.................... -\& 38:11111111111111111111.................... -\& 37:11111111111111111111.................... -\& 36:11111111111111111111.................... -\& 35:11111111111111111111.................... -\& 34:11111111111111111111.................... -\& 33:11111111111111111111.................... -\& 32:11111111111111111111.................... -\& 31:11111111111111111111.................... -\& 30:11111111111111111111.................... -\& 29:11111111111111111111.................... -\& 28:11111111111111111111.................... -\& 27:11111111111111111111.................... -\& 26:11111111111111111111.................... -\& 25:11111111111111111111.................... -\& 24:11111111111111111111.................... -\& 23:11111111111111111111.................... -\& 22:11111111111111111111.................... -\& 21:11111111111111111111.................... -\& 20:........................................ -\& 19:........................................ -\& 18:........................................ -\& 17:........................................ -\& 16:........................................ -\& 15:........................................ -\& 14:........................................ -\& 13:........................................ -\& 12:........................................ -\& 11:........................................ -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:........................................ -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -The pie slice specified is always a counter-clockwise sweep between -the angles, starting at the first angle and ending at the second. Thus: -.PP -.Vb 1 -\& PIE 10 15 30 60 -.Ve -.PP -describes a 30 degree sweep from 2 o'clock to 1 o'clock, while: -.PP -.Vb 1 -\& PIE 10 15 60 30 -.Ve -.PP -describes a 330 degree counter-clockwise sweep from 1 o'clock to 2 o'clock -passing through 12 o'clock (0 degrees). Note in both of these examples that -the center of the slice can be anywhere on the plane. The second mask looks -like this: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:111111111111111111111111................ -\& 39:11111111111111111111111................. -\& 38:11111111111111111111111................. -\& 37:1111111111111111111111.................. -\& 36:1111111111111111111111.................. -\& 35:111111111111111111111................... -\& 34:11111111111111111111.................... -\& 33:11111111111111111111.................... -\& 32:1111111111111111111....................1 -\& 31:1111111111111111111..................111 -\& 30:111111111111111111.................11111 -\& 29:111111111111111111................111111 -\& 28:11111111111111111...............11111111 -\& 27:1111111111111111..............1111111111 -\& 26:1111111111111111.............11111111111 -\& 25:111111111111111............1111111111111 -\& 24:111111111111111..........111111111111111 -\& 23:11111111111111.........11111111111111111 -\& 22:11111111111111........111111111111111111 -\& 21:1111111111111.......11111111111111111111 -\& 20:111111111111......1111111111111111111111 -\& 19:111111111111....111111111111111111111111 -\& 18:11111111111....1111111111111111111111111 -\& 17:11111111111..111111111111111111111111111 -\& 16:1111111111.11111111111111111111111111111 -\& 15:1111111111111111111111111111111111111111 -\& 14:1111111111111111111111111111111111111111 -\& 13:1111111111111111111111111111111111111111 -\& 12:1111111111111111111111111111111111111111 -\& 11:1111111111111111111111111111111111111111 -\& 10:1111111111111111111111111111111111111111 -\& 9:1111111111111111111111111111111111111111 -\& 8:1111111111111111111111111111111111111111 -\& 7:1111111111111111111111111111111111111111 -\& 6:1111111111111111111111111111111111111111 -\& 5:1111111111111111111111111111111111111111 -\& 4:1111111111111111111111111111111111111111 -\& 3:1111111111111111111111111111111111111111 -\& 2:1111111111111111111111111111111111111111 -\& 1:1111111111111111111111111111111111111111 -.Ve -.PP -The pie slice goes to the edge of the field. To limit its scope, pie -usually is is combined with other shapes, such as circles and annuli, -using boolean operations. (See below and in \*(L"help regalgebra\*(R"). -.PP -Pie Performance Notes: -.PP -Pie region processing time is proportional to the size of the image, -and not the size of the region. This is because the pie shape is the -only infinite length shape, and we essentially must check all y rows -for inclusion (unlike other regions, where the y limits can be -calculated beforehand). Thus, pie can run very slowly on large images. -In particular, it will run \s-1MUCH\s0 more slowly than the panda shape in -image-based region operations (such as funcnts). We recommend use of -panda over pie where ever possible. -.PP -If you must use pie, always try to put it last in a boolean && -expression. The reason for this is that the filter code is optimized -to exit as soon as the result is know. Since pie is the slowest -region, it is better to avoid executing it if another region can decide -the result. Consider, for example, the difference in time required to -process a Chandra \s-1ACIS\s0 file when a pie and circle are combined in -two different orders: -.PP -.Vb 2 -\& time ./funcnts nacis.fits "circle 4096 4096 100 && pie 4096 4096 10 78" -\&2.87u 0.38s 0:35.08 9.2% -.Ve -.PP -.Vb 2 -\& time ./funcnts nacis.fits "pie 4096 4096 10 78 && circle 4096 4096 100 " -\&89.73u 0.36s 1:03.50 141.8% -.Ve -.PP -Black-magic performance note: -.PP -Panda region processing uses a \fBquick test\fR pie region instead of -the normal pie region when combining its annulus and pie shapes. This -\&\fBqtpie\fR shape differs from the normal pie in that it utilizes the -y limits from the previous region with which it is combined. In a -panda shape, which is a series of annuli combined with pies, the -processing time is thus reduced to that of the annuli. -.PP -You can use the qtpie shape instead of pie in cases where you are -combining pie with another shape using the && operator. This will -cause the pie limits to be set using limits from the other shape, and -will speed up the processing considerably. For example, the above -execution of funcnts can be improved considerably using this technique: -.PP -.Vb 2 -\& time ./funcnts nacis.fits "circle 4096 4096 100 && qtpie 4096 4096 10 78" -\&4.66u 0.33s 0:05.87 85.0% -.Ve -.PP -We emphasize that this is a quasi-documented feature and might change in -the future. The qtpie shape is not recognized by ds9 or other programs. -.PP -The \fBline\fR shape allows single pixels in a line between (x1,y1) and -(x2,y2) to be included or excluded. For example: -.PP -.Vb 1 -\& LINE (5,6, 24,25) -.Ve -.PP -displays as: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:........................................ -\& 33:........................................ -\& 32:........................................ -\& 31:........................................ -\& 30:........................................ -\& 29:........................................ -\& 28:........................................ -\& 27:........................................ -\& 26:........................................ -\& 25:.......................1................ -\& 24:......................1................. -\& 23:.....................1.................. -\& 22:....................1................... -\& 21:...................1.................... -\& 20:..................1..................... -\& 19:.................1...................... -\& 18:................1....................... -\& 17:...............1........................ -\& 16:..............1......................... -\& 15:.............1.......................... -\& 14:............1........................... -\& 13:...........1............................ -\& 12:..........1............................. -\& 11:.........1.............................. -\& 10:........1............................... -\& 9:.......1................................ -\& 8:......1................................. -\& 7:.....1.................................. -\& 6:....1................................... -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -The \fBpoint\fR shape allows single pixels to be included or -excluded. Although the (x,y) values are real numbers, they are truncated -to integer and the corresponding pixel is included or excluded, as specified. -.PP -Several points can be put in one region declaration; unlike the -original \s-1IRAF\s0 implementation, each now is given a different region mask value. -This makes it easier, for example, for funcnts to determine the number of -photons in the individual pixels. For example, -.PP -.Vb 1 -\& POINT (5,6, 10,11, 20,20, 35,30) -.Ve -.PP -will give the different region mask values to all four points, as shown below: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:........................................ -\& 33:........................................ -\& 32:........................................ -\& 31:........................................ -\& 30:..................................4..... -\& 29:........................................ -\& 28:........................................ -\& 27:........................................ -\& 26:........................................ -\& 25:........................................ -\& 24:........................................ -\& 23:........................................ -\& 22:........................................ -\& 21:........................................ -\& 20:...................3.................... -\& 19:........................................ -\& 18:........................................ -\& 17:........................................ -\& 16:........................................ -\& 15:........................................ -\& 14:........................................ -\& 13:........................................ -\& 12:........................................ -\& 11:.........2.............................. -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:....1................................... -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -The \fBpolygon\fR shape specifies a polygon with vertices -(x1, y1) ... (xn, yn). The polygon is closed automatically: one should -not specify the last vertex to be the same as the first. Any number of -vertices are allowed. For example, the following polygon defines a -right triangle as shown below: -.PP -.Vb 1 -\& POLYGON (10,10, 10,30, 30,30) -.Ve -.PP -looks like this: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:........................................ -\& 33:........................................ -\& 32:........................................ -\& 31:........................................ -\& 30:..........11111111111111111111.......... -\& 29:..........1111111111111111111........... -\& 28:..........111111111111111111............ -\& 27:..........11111111111111111............. -\& 26:..........1111111111111111.............. -\& 25:..........111111111111111............... -\& 24:..........11111111111111................ -\& 23:..........1111111111111................. -\& 22:..........111111111111.................. -\& 21:..........11111111111................... -\& 20:..........1111111111.................... -\& 19:..........111111111..................... -\& 18:..........11111111...................... -\& 17:..........1111111....................... -\& 16:..........111111........................ -\& 15:..........11111......................... -\& 14:..........1111.......................... -\& 13:..........111........................... -\& 12:..........11............................ -\& 11:..........1............................. -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:........................................ -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -Note that polygons can get twisted upon themselves if edge lines -cross. Thus: -.PP -.Vb 1 -\& POL (10,10, 20,20, 20,10, 10,20) -.Ve -.PP -will produce an area which is two triangles, like butterfly wings, as shown -below: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:........................................ -\& 33:........................................ -\& 32:........................................ -\& 31:........................................ -\& 30:........................................ -\& 29:........................................ -\& 28:........................................ -\& 27:........................................ -\& 26:........................................ -\& 25:........................................ -\& 24:........................................ -\& 23:........................................ -\& 22:........................................ -\& 21:........................................ -\& 20:........................................ -\& 19:..........1........1.................... -\& 18:..........11......11.................... -\& 17:..........111....111.................... -\& 16:..........1111..1111.................... -\& 15:..........1111111111.................... -\& 14:..........1111..1111.................... -\& 13:..........111....111.................... -\& 12:..........11......11.................... -\& 11:..........1........1.................... -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:........................................ -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -The following are combinations of pie with different shapes -(called \*(L"panda\*(R" for \*(L"Pie \s-1AND\s0 Annulus\*(R") allow for easy specification of -radial sections: -.PP -.Vb 6 -\& 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 -.Ve -.PP -The \fBpanda\fR (\fBP\fRies \fB\s-1AND\s0\fR \fBA\fRnnuli) shape can be -used to create combinations of pie and annuli markers. It is analogous -to a Cartesian product on those shapes, i.e., the result is several -shapes generated by performing a boolean \s-1AND\s0 between pies and -annuli. Thus, 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. -.PP -Consider the example shown below: -.PP -.Vb 1 -\& PANDA(20,20, 0,360,3, 0,15,4) -.Ve -.PP -Here, 3 pie slices centered at 20, 20 are combined with 4 annuli, also -centered at 20, 20. The result is a mask with 12 regions (displayed in -base 16 to save characters): -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:..............44444444444............... -\& 33:............444444444444444............. -\& 32:...........88444444444444444............ -\& 31:.........888844443333344444444.......... -\& 30:........88888833333333333444444......... -\& 29:........88888733333333333344444......... -\& 28:.......8888877733333333333344444........ -\& 27:......888887777332222233333344444....... -\& 26:......888877777622222222333334444....... -\& 25:.....88887777766622222222333334444...... -\& 24:.....88887777666622222222233334444...... -\& 23:.....88887777666651111222233334444...... -\& 22:.....88877776666551111122223333444...... -\& 21:.....88877776666555111122223333444...... -\& 20:.....888777766665559999aaaabbbbccc...... -\& 19:.....888777766665559999aaaabbbbccc...... -\& 18:.....888777766665599999aaaabbbbccc...... -\& 17:.....88887777666659999aaaabbbbcccc...... -\& 16:.....888877776666aaaaaaaaabbbbcccc...... -\& 15:.....888877777666aaaaaaaabbbbbcccc...... -\& 14:......8888777776aaaaaaaabbbbbcccc....... -\& 13:......888887777bbaaaaabbbbbbccccc....... -\& 12:.......88888777bbbbbbbbbbbbccccc........ -\& 11:........888887bbbbbbbbbbbbccccc......... -\& 10:........888888bbbbbbbbbbbcccccc......... -\& 9:.........8888ccccbbbbbcccccccc.......... -\& 8:...........88ccccccccccccccc............ -\& 7:............ccccccccccccccc............. -\& 6:..............ccccccccccc............... -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -Several regions with different mask values can be combined in the -same mask. This supports comparing data from the different regions. -(For information on how to combine different shapes into a single -region, see \*(L"help regalgebra\*(R".) For example, consider the following -set of regions: -.PP -.Vb 3 -\& ANNULUS 25 25 5 10 -\& ELLIPSE 20 20 5 10 315 -\& BOX 15 15 5 10 -.Ve -.PP -The resulting mask will look as follows: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:....................111111111........... -\& 33:...................11111111111.......... -\& 32:.................111111111111111........ -\& 31:.................111111111111111........ -\& 30:................11111111111111111....... -\& 29:...............1111111.....1111111...... -\& 28:...............111111.......111111...... -\& 27:...............11111.222222..11111...... -\& 26:...............111112222222..11111...... -\& 25:...............111112222222..11111...... -\& 24:...............111112222222..11111...... -\& 23:...............111112222222..11111...... -\& 22:...............111111222222.111111...... -\& 21:..............211111112222.1111111...... -\& 20:............322211111111111111111....... -\& 19:............32222111111111111111........ -\& 18:............22222111111111111111........ -\& 17:............222222211111111111.......... -\& 16:............22222222111111111........... -\& 15:............222222222................... -\& 14:............22222222.................... -\& 13:............222222...................... -\& 12:............33333....................... -\& 11:............33333....................... -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:........................................ -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -Note that when a pixel is in 2 or more regions, it is arbitrarily -assigned to a one of the regions in question (often based on how a -give C compiler optimizes boolean expressions). -.PP -\&\fBRegion accelerators\fR -.PP -Two types of \efBaccelerators, to simplify region specification, -are provided as natural extensions to the ways shapes are described. -These are: extended lists of parameters, specifying multiple regions, -valid for annulus, box, circle, ellipse, pie, and points; and -\&\fBn=\fR, valid for annulus, box, circle, ellipse, and pie (not -point). In both cases, one specification is used to define several -different regions, that is, to define shapes with different mask -values in the region mask. -.PP -The following regions accept \fBaccelerator\fR syntax: -.PP -.Vb 13 -\& 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 -.Ve -.PP -Note that the circle accelerators are simply aliases for the annulus -accelerators. -.PP -For example, several annuli at the same center can be specified in one -region expression by specifying more than two radii. If \fBN\fR -radii are specified, then \fBN\fR\-1 annuli result, with the outer -radius of each preceding annulus being the inner radius of the -succeeding annulus. Each annulus is considered a separate region, and -is given a separate mask value. For example, -.PP -.Vb 1 -\& ANNULUS 20 20 0 2 5 10 15 20 -.Ve -.PP -specifies five different annuli centered at 20 20, and is equivalent to: -.PP -.Vb 5 -\& ANNULUS 20.0 20.0 0 2 -\& ANNULUS 20.0 20.0 2 5 -\& ANNULUS 20.0 20.0 5 10 -\& ANNULUS 20.0 20.0 10 15 -\& ANNULUS 20.0 20.0 15 20 -.Ve -.PP -The mask is shown below: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:.............5555555555555.............. -\& 38:...........55555555555555555............ -\& 37:.........555555555555555555555.......... -\& 36:........55555555555555555555555......... -\& 35:......555555555555555555555555555....... -\& 34:.....55555555544444444444555555555...... -\& 33:....5555555544444444444444455555555..... -\& 32:....5555555444444444444444445555555..... -\& 31:...555555444444444444444444444555555.... -\& 30:..55555544444444444444444444444555555... -\& 29:..55555544444443333333334444444555555... -\& 28:.5555554444444333333333334444444555555.. -\& 27:.5555544444433333333333333344444455555.. -\& 26:555555444444333333333333333444444555555. -\& 25:555554444443333333333333333344444455555. -\& 24:555554444433333332222233333334444455555. -\& 23:555554444433333322222223333334444455555. -\& 22:555554444433333222222222333334444455555. -\& 21:555554444433333222111222333334444455555. -\& 20:555554444433333222111222333334444455555. -\& 19:555554444433333222111222333334444455555. -\& 18:555554444433333222222222333334444455555. -\& 17:555554444433333322222223333334444455555. -\& 16:555554444433333332222233333334444455555. -\& 15:555554444443333333333333333344444455555. -\& 14:555555444444333333333333333444444555555. -\& 13:.5555544444433333333333333344444455555.. -\& 12:.5555554444444333333333334444444555555.. -\& 11:..55555544444443333333334444444555555... -\& 10:..55555544444444444444444444444555555... -\& 9:...555555444444444444444444444555555.... -\& 8:....5555555444444444444444445555555..... -\& 7:....5555555544444444444444455555555..... -\& 6:.....55555555544444444444555555555...... -\& 5:......555555555555555555555555555....... -\& 4:........55555555555555555555555......... -\& 3:.........555555555555555555555.......... -\& 2:...........55555555555555555............ -\& 1:.............5555555555555.............. -.Ve -.PP -For boxes and ellipses, if an odd number of arguments is specified, -then the last argument is assumed to be an angle. Otherwise, the -angle is assumed to be zero. For example: -.PP -.Vb 1 -\& ellipse 20 20 3 5 6 10 9 15 12 20 45 -.Ve -.PP -specifies an 3 ellipses at a 45 degree angle: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........33333333........................ -\& 35:......333333333333...................... -\& 34:.....3333333333333333................... -\& 33:....333333333333333333.................. -\& 32:....33333332222233333333................ -\& 31:...3333332222222222333333............... -\& 30:...33333222222222222233333.............. -\& 29:...333332222222222222223333............. -\& 28:...3333222222211112222223333............ -\& 27:...33332222211111111222223333........... -\& 26:...333322222111111111122223333.......... -\& 25:...3333222211111111111122223333......... -\& 24:....3332222111111..1111122223333........ -\& 23:....333322211111.....11112222333........ -\& 22:....33332222111.......11112223333....... -\& 21:.....33322221111.......11122223333...... -\& 20:.....33332221111.......11112223333...... -\& 19:.....33332222111.......11112222333...... -\& 18:......33332221111.......11122223333..... -\& 17:.......33322221111.....111112223333..... -\& 16:.......3333222211111..1111112222333..... -\& 15:........3333222211111111111122223333.... -\& 14:.........333322221111111111222223333.... -\& 13:..........33332222211111111222223333.... -\& 12:...........3333222222111122222223333.... -\& 11:............333322222222222222233333.... -\& 10:.............33333222222222222233333.... -\& 9:..............3333332222222222333333.... -\& 8:...............33333333222223333333..... -\& 7:.................333333333333333333..... -\& 6:..................3333333333333333...... -\& 5:.....................333333333333....... -\& 4:.......................33333333......... -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -Note in the above example that the lower limit is not part of the -region for boxes, circles, and ellipses. This makes circles and annuli -equivalent, i.e.: -.PP -.Vb 2 -\& circle 20 20 5 10 15 20 -\& annulus 20 20 5 10 15 20 -.Ve -.PP -both give the following region mask: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:.............3333333333333.............. -\& 38:...........33333333333333333............ -\& 37:.........333333333333333333333.......... -\& 36:........33333333333333333333333......... -\& 35:......333333333333333333333333333....... -\& 34:.....33333333322222222222333333333...... -\& 33:....3333333322222222222222233333333..... -\& 32:....3333333222222222222222223333333..... -\& 31:...333333222222222222222222222333333.... -\& 30:..33333322222222222222222222222333333... -\& 29:..33333322222221111111112222222333333... -\& 28:.3333332222222111111111112222222333333.. -\& 27:.3333322222211111111111111122222233333.. -\& 26:333333222222111111111111111222222333333. -\& 25:333332222221111111111111111122222233333. -\& 24:33333222221111111.....11111112222233333. -\& 23:3333322222111111.......1111112222233333. -\& 22:333332222211111.........111112222233333. -\& 21:333332222211111.........111112222233333. -\& 20:333332222211111.........111112222233333. -\& 19:333332222211111.........111112222233333. -\& 18:333332222211111.........111112222233333. -\& 17:3333322222111111.......1111112222233333. -\& 16:33333222221111111.....11111112222233333. -\& 15:333332222221111111111111111122222233333. -\& 14:333333222222111111111111111222222333333. -\& 13:.3333322222211111111111111122222233333.. -\& 12:.3333332222222111111111112222222333333.. -\& 11:..33333322222221111111112222222333333... -\& 10:..33333322222222222222222222222333333... -\& 9:...333333222222222222222222222333333.... -\& 8:....3333333222222222222222223333333..... -\& 7:....3333333322222222222222233333333..... -\& 6:.....33333333322222222222333333333...... -\& 5:......333333333333333333333333333....... -\& 4:........33333333333333333333333......... -\& 3:.........333333333333333333333.......... -\& 2:...........33333333333333333............ -\& 1:.............3333333333333.............. -.Ve -.PP -As a final example, specifying several angles in one pie slice -expression is equivalent to specifying several separate slices with -the same center. As with the annulus, if \fBN\fR angles are -specified, then \fBN\fR\-1 slices result, with the ending angle of -each preceding slice being the starting angle of the succeeding slice. -Each slice is considered a separate region, and is given a separate -mask value. For example, -.PP -.Vb 1 -\& PIE 12 12 315 45 115 270 -.Ve -.PP -specifies three regions as shown below: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:2222222222222222222222222222222222222222 -\& 39:2222222222222222222222222222222222222221 -\& 38:2222222222222222222222222222222222222211 -\& 37:2222222222222222222222222222222222222111 -\& 36:2222222222222222222222222222222222221111 -\& 35:3222222222222222222222222222222222211111 -\& 34:3222222222222222222222222222222222111111 -\& 33:3322222222222222222222222222222221111111 -\& 32:3322222222222222222222222222222211111111 -\& 31:3332222222222222222222222222222111111111 -\& 30:3332222222222222222222222222221111111111 -\& 29:3333222222222222222222222222211111111111 -\& 28:3333222222222222222222222222111111111111 -\& 27:3333322222222222222222222221111111111111 -\& 26:3333322222222222222222222211111111111111 -\& 25:3333322222222222222222222111111111111111 -\& 24:3333332222222222222222221111111111111111 -\& 23:3333332222222222222222211111111111111111 -\& 22:3333333222222222222222111111111111111111 -\& 21:3333333222222222222221111111111111111111 -\& 20:3333333322222222222211111111111111111111 -\& 19:3333333322222222222111111111111111111111 -\& 18:3333333332222222221111111111111111111111 -\& 17:3333333332222222211111111111111111111111 -\& 16:3333333333222222111111111111111111111111 -\& 15:3333333333222221111111111111111111111111 -\& 14:3333333333322211111111111111111111111111 -\& 13:3333333333322111111111111111111111111111 -\& 12:33333333333.1111111111111111111111111111 -\& 11:3333333333331111111111111111111111111111 -\& 10:333333333333.111111111111111111111111111 -\& 9:333333333333..11111111111111111111111111 -\& 8:333333333333...1111111111111111111111111 -\& 7:333333333333....111111111111111111111111 -\& 6:333333333333.....11111111111111111111111 -\& 5:333333333333......1111111111111111111111 -\& 4:333333333333.......111111111111111111111 -\& 3:333333333333........11111111111111111111 -\& 2:333333333333.........1111111111111111111 -\& 1:333333333333..........111111111111111111 -.Ve -.PP -The annulus, box, circle, ellipse, and pie shapes also accept an -\&\fBn=[int]\fR syntax for specifying multiple regions. The -\&\fBn=[int]\fRsyntax interprets the previous (shape\-dependent) -arguments as lower and upper limits for the region and creates n -shapes with evenly spaced boundaries. For example, if \fBn=[int]\fR -is specified in an annulus, the two immediately preceding radii -(\fBrn\fR and \fBrm\fR) are divided into \fBint\fR annuli, such -that the inner radius of the first is \fBrn\fR and the outer radius -of the last is \fBrm\fR. For example, -.PP -.Vb 1 -\& ANNULUS 20 20 5 20 n=3 -.Ve -.PP -is equivalent to: -.PP -.Vb 1 -\& ANNULUS 20 20 5 10 15 20 -.Ve -.PP -If this syntax is used with an ellipse or box, then the two preceding -pairs of values are taken to be lower and upper limits for a set of -ellipses or boxes. A circle uses the two preceding arguments for upper -and lower radii. For pie, the two preceding angles are divided into n -wedges such that the starting angle of the first is the lower bound -and the ending angle of the last is the upper bound. In all cases, -the \fBn=[int]\fR syntax allows any single alphabetic character -before the \*(L"=\*(R", i.e, i=3, z=3, etc. are all equivalent. -.PP -Also note that for boxes and ellipses, the optional angle argument is -always specified after the \fBn=[int]\fR syntax. For example: -.PP -.Vb 1 -\& ellipse 20 20 4 6 16 24 n=3 45 -.Ve -.PP -specifies 3 elliptical regions at an angle of 45 degrees: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........33333333........................ -\& 39:.....33333333333333..................... -\& 38:....33333333333333333................... -\& 37:...33333333333333333333................. -\& 36:..33333333333333333333333............... -\& 35:.3333333333222223333333333.............. -\& 34:3333333322222222222233333333............ -\& 33:33333332222222222222223333333........... -\& 32:333333222222222222222222333333.......... -\& 31:3333322222222222222222222333333......... -\& 30:33333222222222111122222222333333........ -\& 29:333332222222111111112222222333333....... -\& 28:3333222222211111111111222222333333...... -\& 27:3333222222111111111111112222233333...... -\& 26:33332222221111111111111112222233333..... -\& 25:33332222211111111.111111112222233333.... -\& 24:333322222111111......111111222223333.... -\& 23:333322222111111.......111112222233333... -\& 22:33333222221111.........11111222223333... -\& 21:333332222211111.........11112222233333.. -\& 20:.33332222211111.........11111222223333.. -\& 19:.33333222221111.........111112222233333. -\& 18:..33332222211111.........11112222233333. -\& 17:..333332222211111.......111111222233333. -\& 16:...333322222111111......111111222223333. -\& 15:...333332222211111111.111111112222233333 -\& 14:....333332222211111111111111122222233333 -\& 13:.....33333222221111111111111122222233333 -\& 12:.....33333322222211111111111222222233333 -\& 11:......3333332222222111111112222222333333 -\& 10:.......333333222222221111222222222333333 -\& 9:........33333322222222222222222222333333 -\& 8:.........333333222222222222222222333333. -\& 7:..........33333332222222222222223333333. -\& 6:...........3333333322222222222233333333. -\& 5:.............3333333333222223333333333.. -\& 4:..............33333333333333333333333... -\& 3:................33333333333333333333.... -\& 2:..................33333333333333333..... -\& 1:....................33333333333333...... -.Ve -.PP -Both the variable argument syntax and the \fBn=[int]\fR syntax must -occur alone in a region descriptor (aside from the optional angle for -boxes and ellipses). They cannot be combined. Thus, it is not valid -to precede or follow an \fBn=[int]\fR accelerator with more angles or -radii, as in this example: -.PP -.Vb 3 -\& # INVALID -- one too many angles before a=5 ... -\& # and no angles are allowed after a=5 -\& PIE 12 12 10 25 50 a=5 85 135 -.Ve -.PP -Instead, use three separate specifications, such as: -.PP -.Vb 3 -\& PIE 12 12 10 25 -\& PIE 12 12 25 50 a=5 -\& PIE 12 12 85 135 -.Ve -.PP -The original (\s-1IRAF\s0) implementation of region filtering permitted this -looser syntax, but we found it caused more confusion than it was worth -and therefore removed it. -.PP -\&\s-1NB:\s0 Accelerators may be combined with other shapes in a boolean -expression in any order. (This is a change starting with funtools -v1.1.1. Prior to this release, the accelerator shape had to be -specified last). The actual region mask id values returned depend on the -order in which the shapes are specified, although the total number of -pixels or rows that pass the filter will be consistent. For this -reason, use of accelerators in boolean expressions is discouraged in -programs such as funcnts, where region mask id values are used -to count events or image pixels. -.PP -[All region masks displayed in this document were generated using the -\&\fBfundisp\fR routine and the undocumented \*(L"mask=all\*(R" argument (with -spaced removed using sed ): -.PP -.Vb 2 -\& fundisp "funtools/funtest/test40.fits[ANNULUS 25 25 5 10]" mask=all |\e -\& sed 's/ //g' -.Ve -.PP -Note that you must supply an image of the appropriate size \*(-- in this case, -a \s-1FITS\s0 image of dimension 40x40 is used.] -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages |