diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2016-10-25 20:57:49 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2016-10-25 20:57:49 (GMT) |
commit | d1c4bf158203c4e8ec29fdeb83fd311e36320885 (patch) | |
tree | 15874534e282f67505ce4af5ba805a1ff70ec43e /funtools/man/man7 | |
parent | e19a18e035dc4d0e8e215f9b452bb9ef6f58b9d7 (diff) | |
parent | 339420dd5dd874c41f6bab5808291fb4036dd022 (diff) | |
download | blt-d1c4bf158203c4e8ec29fdeb83fd311e36320885.zip blt-d1c4bf158203c4e8ec29fdeb83fd311e36320885.tar.gz blt-d1c4bf158203c4e8ec29fdeb83fd311e36320885.tar.bz2 |
Merge commit '339420dd5dd874c41f6bab5808291fb4036dd022' as 'funtools'
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, 7204 insertions, 0 deletions
diff --git a/funtools/man/man7/funcombine.7 b/funtools/man/man7/funcombine.7 new file mode 100644 index 0000000..b2e5dc4 --- /dev/null +++ b/funtools/man/man7/funcombine.7 @@ -0,0 +1,248 @@ +.\" 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 new file mode 100644 index 0000000..963084a --- /dev/null +++ b/funtools/man/man7/funds9.7 @@ -0,0 +1,216 @@ +.\" 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 new file mode 100644 index 0000000..4b29218 --- /dev/null +++ b/funtools/man/man7/funenv.7 @@ -0,0 +1,352 @@ +.\" 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 new file mode 100644 index 0000000..f401833 --- /dev/null +++ b/funtools/man/man7/funfiles.7 @@ -0,0 +1,802 @@ +.\" 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 new file mode 100644 index 0000000..3c96e6d --- /dev/null +++ b/funtools/man/man7/funfilters.7 @@ -0,0 +1,464 @@ +.\" 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 new file mode 100644 index 0000000..bf87bb8 --- /dev/null +++ b/funtools/man/man7/funidx.7 @@ -0,0 +1,327 @@ +.\" 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 new file mode 100644 index 0000000..5c17572 --- /dev/null +++ b/funtools/man/man7/funregions.7 @@ -0,0 +1,678 @@ +.\" 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 new file mode 100644 index 0000000..b24b317 --- /dev/null +++ b/funtools/man/man7/funtext.7 @@ -0,0 +1,713 @@ +.\" 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 new file mode 100644 index 0000000..6d188be --- /dev/null +++ b/funtools/man/man7/funtools.7 @@ -0,0 +1,379 @@ +.\" 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 new file mode 100644 index 0000000..06a0d56 --- /dev/null +++ b/funtools/man/man7/funview.7 @@ -0,0 +1,523 @@ +.\" 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 new file mode 100644 index 0000000..93cb985 --- /dev/null +++ b/funtools/man/man7/regalgebra.7 @@ -0,0 +1,400 @@ +.\" 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 new file mode 100644 index 0000000..40a1648 --- /dev/null +++ b/funtools/man/man7/regbounds.7 @@ -0,0 +1,305 @@ +.\" 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 new file mode 100644 index 0000000..fd7615e --- /dev/null +++ b/funtools/man/man7/regcoords.7 @@ -0,0 +1,345 @@ +.\" 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 new file mode 100644 index 0000000..c9f6f6a --- /dev/null +++ b/funtools/man/man7/regdiff.7 @@ -0,0 +1,181 @@ +.\" 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 new file mode 100644 index 0000000..8eb15e7 --- /dev/null +++ b/funtools/man/man7/reggeometry.7 @@ -0,0 +1,1271 @@ +.\" 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 |