diff options
Diffstat (limited to 'funtools/doc/funtools.ps')
| -rw-r--r-- | funtools/doc/funtools.ps | 11446 |
1 files changed, 11446 insertions, 0 deletions
diff --git a/funtools/doc/funtools.ps b/funtools/doc/funtools.ps new file mode 100644 index 0000000..210149e --- /dev/null +++ b/funtools/doc/funtools.ps @@ -0,0 +1,11446 @@ +%!PS +%%Title: The Funtools Help Facility +%%Creator: html2ps version 1.0 beta5 +%%EndComments +save +2000 dict begin +/d {bind def} bind def +/D {def} d +/t true D +/f false D +/FL [/Times-Roman +/Times-Italic +/Times-Bold +/Times-BoldItalic +/Courier +/Courier-Oblique +/Courier-Bold +/Courier-BoldOblique +/Helvetica +/Helvetica-Oblique +/Helvetica-Bold +/Helvetica-BoldOblique] D +/WF t D +/WI 0 D +/F 1 D +/IW 471 F div D +/IL 621 F div D +/PS 791 D +/EF [0 1 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 2 2] D +/EZ [11 9 19 17 15 13 12 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 8 8] D +/Ey [0 0 2 2 2 2 2 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0] D +/EG [-1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1] D +/Tm [1 1 0.8 0.8 0.8 0.8 0.8 0.8 0 0 0 0 0 0 0.5 1 1 1 1 0 0 1.3 0 0] D +/Bm [1 1 0.5 0.5 0.5 0.5 0.5 0.5 0 0 0 0 0 0 0.5 1 1 1 1 0 0 1 0 0] D +/Lm [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 2 2 0 0 2 0 0 0] D +/Rm [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0] D +/EU [-1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 0 0] D +/NO t D +/YY [[{()}1][{()}0][{()}2]] D +/ZZ [[{()}1][{()}0][{()}2]] D +/Ts EZ 0 get D +/TU f D +/Xp t D +/AU t D +/SN 0 D +/Cf f D +/Tp f D +/Fe f D +/TI 1 Ts mul D +/Fm 14 D +/xL 71 D +/xR 71 D +/yL 706 D +/yR 706 D +/Wl 471 F div D +/Wr 471 F div D +/hL 621 F div D +/hR 621 F div D +/FE {newpath Fm neg Fm M CP BB IW Fm add Fm L IW Fm add IL Fm add neg L CP BB + Fm neg IL Fm add neg L closepath} D +/LA {PM 0 eq{/IW Wl D /IL hL D}{/IW Wr D /IL hR D}ie /W IW D /LL W D /LS W D + TU PM 0 eq and{IW 56 F div add SA{Sf div}if 0 translate} + {PM 0 eq{xL yL}{xR yR}ie translate F SA{Sf mul}if dup scale + CS CF FS Cf{CA CL get VC}if /Bb f D}ie 0 0 M + TF not Tc or {Cf{gsave SA{1 Sf div dup scale}if Cb VC FE fill grestore}if}if}D +/Pi 0 Ts mul D +/SG [0.8 1 1] D +/Ab 15 D +/J 0 D +/Tc t D +/NH 6 D +/Nf f D +/Pa f D +/LH 1.2 D +/XR f D +/Xr {/pN E D ( [p ) WB pN WB (] )WB} D +/Db [16#FF 16#FF 16#FF] D +/Dt [16#00 16#00 16#00] D +/eA f D +/Fi f D +/bT f D +/Lc t D +/Dl [16#00 16#00 16#00] D +/LX f D +/Br 0.25 D +/IA ([IMAGE]) D +/DS {/PF f D()WB NL NP()pop RC ZF} D +/Gb f D +/Mb t D +/Hc [16#00 16#00 16#00] D +/Bl 3 D +/MI -15.2 D +/DX (DRAFT) D +/Di 0 D +/Tt 113.385826771654 D +/Th {()2 Al()BR ( + ) 0 1 -1 H()4 FZ Ti ES()EH ( + ) 0 2 -1 H() ME 0 get join EH()Ea()BR()} D +/tH {()0 1 -1 H (Table of Contents) EH()} D +/FD 2 D +/Dy 2 D +/cD [16#F0 16#F0 16#F0] D +/FW 0.6 D +/FU [16#00 16#00 16#00] D +/ET {/RM f D /A0 0 D /PN SN D /OU t D /Ou t D /W IW D /LL W D D1 + Ms not TP and{Ip}if /TF f D} D +[{true statusdict/setduplexmode get exec} stopped cleartomark +%-- End of variable part -- +/MySymbol 10 dict dup begin + /FontType 3 D /FontMatrix [.001 0 0 .001 0 0 ] D /FontBBox [25 -10 600 600] D + /Encoding 256 array D 0 1 255{Encoding exch /.notdef put}for + Encoding (e) 0 get /euro put + /Metrics 2 dict D Metrics begin + /.notdef 0 D + /euro 651 D + end + /BBox 2 dict D BBox begin + /.notdef [0 0 0 0] D + /euro [25 -10 600 600] D + end + /CharacterDefs 2 dict D CharacterDefs begin + /.notdef {} D + /euro{newpath 114 600 moveto 631 600 lineto 464 200 lineto 573 200 lineto + 573 0 lineto -94 0 lineto 31 300 lineto -10 300 lineto closepath clip + 50 setlinewidth newpath 656 300 moveto 381 300 275 0 360 arc stroke + -19 350 moveto 600 0 rlineto -19 250 moveto 600 0 rlineto stroke}d + end + /BuildChar{0 begin + /char E D /fontdict E D /charname fontdict /Encoding get char get D + fontdict begin + Metrics charname get 0 BBox charname get aload pop setcachedevice + CharacterDefs charname get exec + end + end}D + /BuildChar load 0 3 dict put /UniqueID 1 D +end +definefont pop + +/Cd {aload length 2 idiv dup dict begin {D} repeat currentdict end} D +/EX {EC cvx exec} D +/DU {} d +/BB {pop pop}d +/ie {ifelse} d +/E {exch} d +/M {moveto} d +/R {rmoveto} d +/L {lineto} d +/RL {rlineto} d +/CP {currentpoint} d +/SW {stringwidth} d +/GI {getinterval} d +/PI {putinterval} d +/Sg {setgray} d +/LW {setlinewidth} d +/S {dup () ne OU and{0 Co R AT 3 eq LB and HF not and A1 0 ne A2 0 ne or and + {A2 0 32 A1 0 6 -1 roll awidthshow}{show}ie 0 Co neg R}{pop}ie + OU PH 3 eq or{/Ms t D}if} D +/U {OU{gsave CP currentfont /FontInfo get /UnderlinePosition get + 0 E currentfont /FontMatrix get dtransform E pop add newpath M dup SW pop + CJ 0 RL stroke grestore}if} D +/B {OU Br 0 gt and{CP Ts neg Ts .33 mul R gsave 0 Sg + CP newpath Ts Br mul 0 360 arc closepath UI 2 mod 0 eq{stroke}{fill}ie + grestore M CP E Ts Br 1 add mul sub E BB /Ms t D}if}D +/NP {Ms TP not or PA and OU and{TP{OR}if f1{mF k2 /mF E D /YC 0 D}if + TP TU not PM 0 eq or and{showpage}if DU Ip TE not{LA}if 0.6 LW + /CI 0 D /TP t D /Hs f D /hl 6 D /Hv 6 D /HI hi D /Ms f D}if Bs XO BO M} D +/Np {LE sub CP E pop gt PL 0 eq and{NP}if}D +/Ip {/PN PN 1 add D /Pn RM{1}{4}ie PN Ns D /PM PN SN sub 2 mod D} D +/GP {E dup 3 -1 roll get PN 1 add 2 mod get dup type /integertype eq + {get 0 get}{E pop}ie}d +/Fc {dup 2 GP exec SW pop /S1 E D dup 1 GP exec SW pop /S2 E D 0 GP exec SW + pop /S3 E D S1 0 gt{S2 2 mul S1 add S3 2 mul S1 add 2 copy lt{E}if pop}{0}ie + S2 S3 add 2 copy lt{E}if pop IW .9 mul div dup 1 gt{1 E div}{pop 1}ie}D +/OR {Df{Sd}if tp not{gsave SA{1 Sf div dup scale}if Fe{Cf{FU VC}if FW LW + 1 setlinejoin FE stroke}if /YO {60 F div dup 40 gt{pop 40}if}D /cs CS D + /cf CF D /CF 0 D /pf PF D /PF f D /Fn FN D /At AT D /AT 0 D /FN EF Hf 1 add + get D Fz Fs FS ZZ Fc Fz mul Fs FS EU Hf 1 add get dup type /arraytype eq + Cf and{VC}{pop 0 Sg}ie IW IL neg YO sub M ZZ 1 GP exec dup SW pop neg 0 R Sh + 0 IL neg YO sub M ZZ 0 GP exec Sh ZZ 2 GP exec dup SW pop IW E sub 2 div + IL neg YO sub M Sh Fz Fs FS NO{/AW IW Pn SW pop sub D AW 2 div IL neg YO sub + S1 0 gt S2 AW .45 mul gt or S3 AW .45 mul gt or{Fz 2 mul sub}if M Pn Sh}if + EU Hf get dup type /arraytype eq Cf and{VC}{pop 0 Sg}ie YY Fc /FN EF Hf get D + Hz mul HS FS IW YO M YY 1 GP exec dup SW pop neg 0 R Sh 0 YO M YY 0 GP exec Sh + YY 2 GP exec dup SW pop IW E sub 2 div YO M Sh /FN Fn D /AT At D t Pb XO SZ + SL get neg R /PF pf D grestore /CF 0 D cs cf FS}if}D +/Sh {dup () ne{CP Hz 4 div sub BB show CP CS add BB}{pop}ie}D +/Pb {/OU E D /Ou OU D /PB t D 0 0 M Ba{/Sa save D /BP t D /Fl t D RC /PL 0 D + /PH 0 D /W IW D /LE IL .7 mul D /EO 0 D SI ZF /YA 0 D /BO 0 D /C1 () D + BA 0 Ts neg R Bb{Xl Yl Xh Yh}if Bb CP Sa restore M + {/Yh E D /Xh E D /Yl E D /Xl E D}if /Fl t D}if + BL /OU t D /HM f D /Ou t D /PB f D} D +/Bs {/BP Ba not D}D +/reencodeISO { + dup dup findfont dup length dict begin{1 index /FID ne{D}{pop pop}ie}forall + /Encoding ISOLatin1Encoding D currentdict end definefont} D +/ISOLatin1Encoding [ +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/space/exclam/quotedbl/numbersign/dollar/percent/ampersand/quoteright +/parenleft/parenright/asterisk/plus/comma/hyphen/period/slash +/zero/one/two/three/four/five/six/seven/eight/nine/colon/semicolon +/less/equal/greater/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N +/O/P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash/bracketright +/asciicircum/underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m +/n/o/p/q/r/s/t/u/v/w/x/y/z/braceleft/bar/braceright/asciitilde +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/space/exclamdown/cent/sterling/currency/yen/brokenbar +/section/dieresis/copyright/ordfeminine/guillemotleft/logicalnot +/hyphen/registered/macron/degree/plusminus/twosuperior/threesuperior +/acute/mu/paragraph/periodcentered/cedilla/onesuperior/ordmasculine +/guillemotright/onequarter/onehalf/threequarters/questiondown +/Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE/Ccedilla +/Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex +/Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis +/multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute +/Thorn/germandbls/agrave/aacute/acircumflex/atilde/adieresis +/aring/ae/ccedilla/egrave/eacute/ecircumflex/edieresis/igrave +/iacute/icircumflex/idieresis/eth/ntilde/ograve/oacute/ocircumflex +/otilde/odieresis/divide/oslash/ugrave/uacute/ucircumflex/udieresis +/yacute/thorn/ydieresis +] D +[128/backslash 129/parenleft 130/parenright 141/circumflex 142/tilde +143/perthousand 144/dagger 145/daggerdbl 146/Ydieresis 147/scaron 148/Scaron +149/oe 150/OE 151/guilsinglleft 152/guilsinglright 153/quotesinglbase +154/quotedblbase 155/quotedblleft 156/quotedblright 157/endash 158/emdash +159/trademark] +aload length 2 idiv 1 1 3 -1 roll{pop ISOLatin1Encoding 3 1 roll put}for +/colorimage where{pop}{ + /colorimage { + pop pop /Pr E D {/Cv Pr D /Gr Cv length 3 idiv string D 0 1 Gr length 1 sub + {Gr E dup /i E 3 mul D Cv i get 0.299 mul Cv i 1 add get 0.587 mul add + Cv i 2 add get 0.114 mul add cvi put}for Gr} image} D +}ie +/pdfmark where{pop}{userdict /pdfmark /cleartomark load put}ie +WF{FL{reencodeISO D}forall}{4 1 FL length 1 sub{FL E get reencodeISO D}for}ie +/Symbol dup dup findfont dup length dict begin + {1 index /FID ne{D}{pop pop}ie}forall /Encoding [Encoding aload pop] + dup 128 /therefore put D currentdict end definefont D + +/SF {/CS E D SZ SL CS put FO SL FN put /YI CS LH neg mul D dup ST cvs ( ) join + CS ST cvs join C1 E join ( NF ) join /C1 E D CS NF /Wf WF FN 0 gt or D + /BW Wf{( ) SW pop}{0}ie D}D +/NF {/cS E D /cF E D cF 0 ge{FL cF get}{cF -1 eq{/Symbol}{/MySymbol}ie}ie + findfont cS scalefont setfont} D +/FS {CF or /CF E D FR SL CF put CF CF 0 ge{FN 4 mul add}if E SF} D +/PC {SH /BP f D fin not GL not and{NL}if /HM t D /LL LS D} D +/BS {/TX E D Wf{/fin f D /CW 0 D /LK 0 D /SC 0 D + /RT TX D {RT ( ) search{/NW E D pop /RT E D /WH NW SW pop D CW WH add LL gt + {TX SC LK SC sub 1 sub NN GI GL{SH cF cS OC + 2 copy cS ne E cF ne or{NF}{pop pop}ie}{PC /CW WH BW add D}ie + /SC LK D} + {GL{JC}if + /CW CW WH add BW add D /HM t D}ie /GL f D /Ph f D + /LK LK NW length 1 add add D}{pop exit}ie}loop + /fin t D TX SC LK SC sub GI SH RT () ne{GL not{CC}if}if + /LC TX length D /WH RT SW pop D CW WH add Hy{HC SW pop add}if LL gt + {RT GL{SH cF cS OC 2 copy cS ne E cF ne or{NF}{pop pop}ie + Hy{/Ph t D}if /LL LS D}{NL /LL LS D SH}ie} + {RT PC Hy{CC}if /Ph Ph Hy or D}ie RT () ne{/GL t D /HM t D}if} + {TX SW pop LL le{TX SH}{/NW () D 0 2 TX length 1 sub + {/CW E D TX 0 CW GI dup SW pop LL gt{pop NW SH /HM t D NL/LL W XO sub MR sub D + /CW CW 2 sub NN D /TX TX CW TX length CW sub GI D TX BS exit} + {/NW E D}ie}for}ie}ie /HM t D}D +/CC {C0 length 0 gt{JC}if /C0 [C1 L1 YA YB Mf NS NB TB AF Bw] D + /C1 () D /L0 L1 D /YA 0 D /YB 0 D /Mf 0 D /NS 0 D /NB 0 D}D +/JC {C0 aload length 0 gt{pop pop pop NB add /NB E D NS add /NS E D + dup Mf gt{/Mf E D}{pop}ie dup YB gt{/YB E D}{pop}ie + dup YA gt{/YA E D}{pop}ie pop C1 join /C1 E D /C0 [] D}if}D +/OC {C0 length 0 gt{C1 L1 L0 sub YA YB Mf NS NB TB AF Bw GL C0 aload pop + /Bw E D /AF E D /TB E D /NB E D /NS E D /Mf E D /YB E D /YA E D /C0 [] D + /L1 E D /C1 E D Ph{HC SH}if NL /GL E D /Bw E D /AF E D /TB E D /NB E D /NS E D + /Mf E D /YB E D /YA E D /L1 E D /LL W L1 sub XO sub MR sub WH sub D /CW 0 D + C1 E join /C1 E D}if}D +/BT {/LB t D dup length string copy RS dup dup () ne E ( ) ne and + {/CI 0 D /LS LL D /LL W L1 sub XO sub MR sub D BS} + {dup ( ) eq{/GL f D}if dup () eq L1 0 eq or{pop}{SH /BP f D /Ph f D}ie}ie + /LB f D} D +/BL {CP E pop XO E M} D +/NL {JC /GL f D /SK W XO sub MR sub L1 sub TB{Bw add}if D + /YA LF{Mf HM Fl not and PF or{LH mul}if}{0 /LF t D}ie YA 2 copy lt{E}if pop D + C1 () ne{/FB YB Mf SA{Sf mul}if 4 div 2 copy lt{E}if pop D}if Fl{/Ya YA D}if + CP E pop YA sub YB sub LE neg lt Fl not and PB not and{NP}if NT TL BL + OU PF not and PB or{/RE L1 TB{Bw sub}if + W XO sub MR sub div YA YB add LE BO add div 2 copy lt{E}if pop D + RE 1 gt{BL 1 RE div dup scale}if}if + AT 2 le{SK AT mul 2 div YA neg R}if + AT 3 eq{0 YA neg R TB{/NB NB 1 sub D /NS NS 1 sub D}if /NB NB 1 sub NN D + /A3 NS 6 mul NB add D NS NB add 0 eq + {/A1 0 D /A2 0 D} + {NS 0 eq{/A1 SK NB div dup J gt{pop 0}if D /A2 0 D}{J A3 mul SK lt + {/A1 J D /A2 SK J NB mul sub NS div dup Ab gt{/A1 0 D pop 0}if D} + {/A1 SK A3 div D /A2 A1 6 mul D}ie}ie}ie /A1 A1 NN D /A2 A2 NN D}if + AT 4 eq{0 YA neg R PH 2 le{PD 0 lt{/PD L1 D}if PD M1 gt{/M1 PD D}if + L1 PD sub M2 gt{/M2 L1 PD sub D}if}{DV ID 1 sub get 0 ge{Lo 0 R}if}ie}if + F0 cF ne Cs cS ne or{F0 Cs NF}if + /ms Ms D /Ms f D CP FB sub + C1 cvx exec XO EO sub L1 add TB{BW sub}if dup LM gt{/LM E D}{pop}ie + PH 0 eq PH 4 eq or Ms and{HF not{/PO t D /AH t D}if + BB CP YA add E AT 3 eq LB and{A1 sub}if TB{BW sub}if E BB} + {pop pop}ie Ms HM PH 3 eq and or{/BP f D /Fl f D}if + /Lo 0 D /L1 0 D /F0 cF D /Cs cS D BP not{0 YB NN neg R}if + OU f1 and mF not and{k2 /f1 f D}if + OU PF not and PB or{RE 1 gt{RE dup scale}if}if /Ms ms Ms or D + /C1 AF{(Cp )}{()}ie D /YA 0 D /YB 0 D BL + AT 4 eq LB not and PH 3 ge and + {ID DV length lt{DV ID get dup 0 ge{DO E sub /Lo E D /L1 Lo D}{pop}ie + /ID ID 1 add D}if}if /T t D CD{/LN LN 1 add D PD}if + /PD -1 D /NS 0 D /NB 0 D /TB f D /Ph f D /Mf 0 D /HM f D} D +/RS {/TM E D /CN 0 D TM{10 eq{TM CN ( ) PI}if /CN CN 1 add D}forall + /CN 0 D /BK HM EN and{0}{1}ie D TM + {dup 32 ne{TM CN 3 2 roll put /CN CN 1 add D /BK 0 D} + {pop BK 0 eq{TM CN 32 put /CN CN 1 add D}if /BK 1 D}ie}forall + TM 0 CN GI dup dup () ne E ( ) ne and + {dup CN 1 sub get 32 eq{/EN f D}{/EN t D}ie}if} D +/join {2 copy length E length add string dup 4 2 roll 2 index 0 3 index + PI E length E PI}d +/WR {(\n) search{dup () ne BP not or + {Li 4 le CP E pop YI Li mul add LE add 0 lt and PL 0 eq and{NP}if + SH NL pop /Li Li 1 sub D WR}{pop pop WR}ie}{SH}ie /CI 0 D /BP f D} D +/SH {dup dup () ne E ( ) ne and PF or CS Mf gt and{/Mf CS D}if + T not Wf and{( ) E join /T t D}if dup BP{/MF CS D}if + AT 3 eq{2 copy length dup 0 gt{/NB E NB add D + {( ) search{/NS NS 1 add D pop pop}{pop exit}ie}loop}{pop pop}ie}if + CD PD 0 lt and{dup DC search{SW pop /PD E L1 add D pop pop}{pop}ie}if + 0 Np dup SW pop L1 add /L1 E D dup () ne + {C1 (\() join E join (\)) join AU AF and UF or Wf and{( U ) join}if + sF{( s ) join}if ( S ) join + /C1 E D dup length 1 sub get 32 eq /TB E D /Bw BW D}{pop pop}ie} D +/BG {AI LG BC add add 0 eq} D +/ON {OU{Ty AR AI NN get dup 1 add Ln Ns Ty 2 mod 0 eq{(. )}{(\) )}ie join + dup SW pop neg 0 R CP E 0 lt{0 E M}{pop}ie CP BB show /Ms t D}if} D +/Ln {AR AI 3 -1 roll put}D +/SP {dup CI lt BP not and{dup CI sub 0 E R /CI E D}{pop}ie} D +/BN {PF{WR /HM f D}{BT NL}ie} D +/NN {dup 0 lt{pop 0}if} D +/h {(h) HI ST cvs join cvx exec dup 1 get E Nf{0 get E join}{pop}ie} D +/H {/fn FN D /Hi E 1 add D 1 sub /HL E D /H2 HL 2 add D /GS EZ H2 get D + E Tm H2 get GS mul BE dup 0 gt{1 sub}{pop EG H2 get dup 0 lt{pop AT}if}ie NA + WW Np /SL SL 1 add D /FN EF H2 get D GS Ey H2 get FS + EU H2 get Sc Hs not HL Hl lt and Hs HL hl lt and or Hi 0 eq or + {/HI Hi D /Hs t D /hl HL D /Hv HL D}if HL Hl lt{/hi Hi D}if + Nf HI 0 gt and{(h) Hi ST cvs join cvx exec 0 get WB}if + /HF t D /AH f D /PO f D} D +/EH {Bm H2 get GS mul BE OA /SL SL 1 sub NN D /CF 0 D /FN fn D + SZ SL get FR SL get FS /HF f D /GS Ts D ()Ec} D +/P {E PF{WR}{PO{EP}{BN}ie Ts 4 mul Np AE not{Tm 0 get Ts mul neg SP}if + dup 0 ge AH and{Pi Pd}if}ie 1 sub dup 0 lt{pop AV AL get}if /AT E D /PO t D} D +/EP {PF{WR}{BN Ts 4 mul Np}ie AE not{Bm 0 get Ts mul neg SP}if + /AT AV AL get D /PO f D} D +/BE {E PO{EP}{BN}ie Ts 4 mul Np neg SP} D +/HR {/Aw W EO sub D /RW E dup 0 gt{Aw mul}{neg}ie dup Aw gt{pop Aw}if D /RZ E D + E BN Ts neg SP 1 sub 2 div Aw RW sub mul EO add CP E pop M PF{0 Ps neg R}if + 0 Np OU{gsave RZ LW Cf{Hc VC}{0 Sg}ie CP BB RW 0 RL CP BB stroke grestore}if + /CI 0 D /BP f D PF not{Ts neg SP}if /Ms t D} D +/AD {I NL EG 14 get dup 0 lt{pop AT}if NA /AE t D Tm 14 get Ts mul neg SP + Cf{EU 14 get dup -1 eq{pop CA CL get}if Sc}if} D +/DA {BN ()ES OA /AE f D ()Ec Bm 14 get Ts mul neg SP} D +/PR {/MW E D /Li E D Tm 1 get Ps mul BE 0 NA /FN Fp D /PF t D SI /SL SL 1 add D + /CF 0 D Ps CS mul Ts div MW WC mul CS mul Ts div dup LL gt PL 0 eq and + {LL div div}{pop}ie Ey 1 get FS CP E pop LE add YI neg div cvi dup Li lt + AH and{4 lt YI Li mul 5 mul LE add 0 gt or PL 0 eq and{NP}if}{pop}ie + EU 1 get Sc /GS Ps D}D +/RP {WR NL () /PF f D SI /FN 0 D ES Bm 1 get Ps mul neg SP OA /GS Ts D} D +/SI {/XO Lm 15 get BC NN mul Lm 16 get AI UI sub NN mul add + Lm 17 get UI NN mul add Lm 20 get LG NN mul add Ts mul + PF{Lm 1 get Ps mul add}if EO add D + /MR Rm 15 get BC NN mul Rm 16 get AI UI sub NN mul add + Rm 17 get UI NN mul add Rm 20 get LG NN mul add Ts mul + PF{Rm 1 get Ps mul add}if D /LL W XO sub MR sub D} D +/DT {/cC E D BN /LG LG 1 sub D SI /LG LG 1 add D WW 2 div Np BL} D +/DD {WB Cc 0 eq cC 0 eq and L1 0 eq or Lm 20 get Ts mul L1 sub TB{BW add}if + Ts 2 div lt or NL /LF E D SI BL /cC 0 D} D +/DL {Dc LG Cc put /Cc E D BG{Tm 18 get Ts mul BE}{BN}ie /LG LG 1 add D BL} D +/LD {BN LG 0 gt{/LG LG 1 sub D}if /Cc Dc LG get D SI + BG{()Bm 18 get Ts mul BE}if BL} D +/UL {BG{Tm 17 get Ts mul BE}{BN}ie NR AI NN 0 put /UI UI 1 add D + /AI AI 1 add D SI BL} D +/LU {BN /UI UI 1 sub D /AI AI 1 sub D SI BG{()Bm 17 get Ts mul BE}if BL} D +/OL {E BG{Tm 16 get Ts mul BE}{BN}ie TR AI NN Ty put /Ty E D NR AI NN 1 put + /AI AI 1 add D SI BL 1 Ln} D +/LO {BN /AI AI 1 sub D /Ty TR AI get D SI BG{()Bm 16 get Ts mul BE}if BL} D +/LI {E BN -1 SP /BP f D /CI 0 D 0 Np NR AI 1 sub NN get 1 eq + {dup dup 0 gt E 4 le and{/Ty E D}{pop}ie + /L1 L1 Ty AR AI NN get Ns SW pop XO sub dup 0 lt{pop 0}if add D ( ON )} + {pop ( B )}ie C1 E join /C1 E D CS Mf gt{/Mf CS D}if BL} D +/BQ {Tm 15 get Ts mul BE /BC BC 1 add D SI BL} D +/QB {Bm 15 get Ts mul BE /BC BC 1 sub D SI BL} D +/Al {E EP 1 sub dup 0 lt{pop AV AL get}if NA} D +/Ea {EP OA} D +/WB {PF{WR}{BT}ie} D +/F1 {WB /FN 0 D CS 0 FS} D +/F2 {WB /FN WI D CS 0 FS} D +/HY {/Hy t D WB /Hy f D} D +/YH {WB} D +/A {/LT E D LT 1 eq{/RN E D}if /Lh E D WB /C1 C1 ( Cp ) join D + Lc AF not and{Cl Sc}if /AF t D} D +/EA {Lc AF and{Ec}{WB}ie TL Pa AF and Lh 0 ne and + {( \() Lh join (\)) join /AF f D WB}if /AF f D} D +/TL {C1 ( Tl ) apa /C1 E D} d +/apa {AF OU and Lh 0 ne LT 1 eq or and{LT 1 eq{RN ( /) E ST cvs join} + {(\() Lh join (\)) join}ie E join join}{pop}ie} d +/Cp {/Xc CP /Yc E D D} D +/SS {Cf{dup 0 ge{EU E get dup -1 eq{pop CA CL get}if}{pop CA CL get}ie Sc} + {pop}ie SZ SL get /SL SL 1 add D} D +/I {WB 8 SS 1 FS} D +/EM {WB 8 SS /CF CF 1 xor D 0 FS} D +/BD {WB 9 SS 2 FS} D +/TT {WB 10 SS /FN Fp D 0 FS} D +/KB {WB 11 SS /FN Fp D 2 FS} D +/CT {WB 12 SS 1 FS} D +/SM {WB 13 SS /FN Fp D 0 FS} D +/Q {/QL QL 1 add D QO QL 2 mod get La get join WB} D +/EQ {QC QL 2 mod get La get join WB /QL QL 1 sub D} D +/RO {WB -1 SS /CF 0 D 0 FS} D +/SY {WB -1 SS -1 FS} D +/MY {WB -1 SS -2 FS} D +/ES {WB /SL SL 1 sub NN D /CF 0 D /FN FO SL get D SZ SL get FR SL get FS ()Ec}D +/FZ {3 sub 1.2 E exp GS mul E WB TL /C1 C1 ( Cp ) join D /SL SL 1 add D 0 FS} D +/Ef {WB TL ()ES /C1 C1 ( Cp ) join D} D +/BZ {dup /Bf E D FZ}D +/Sc {dup -1 ne Cf and{/CL CL 1 add D dup 0 eq{pop [0 0 0]}if + dup CA E CL E put VS ( VC ) join C1 E join /C1 E D}{pop}ie} D +/Ec {WB Cf{/CL CL 1 sub NN D CA CL get VS ( VC ) join C1 E join /C1 E D}if} D +/VS {dup type /arraytype eq{([) E {ST cvs join ( ) join}forall (]) join}if} D +/VC {{255 div}forall setrgbcolor} D +/Sl {dup type /integertype ne{Ds}if /La E D WB}d +/UN {WB /UF t D} D +/NU {WB /UF f D} D +/SE {WB /sF t D} D +/XE {WB /sF f D} D +/sM {/C1 C1 ( k1 ) join D}d +/eM {/C1 C1 ( k2 ) join D}d +/k1 {/YC CP E pop Ts add D /mF t D /f1 t D}d +/k2 {gsave 3 LW -9 CP E pop Ts 0.2 mul sub M -9 YC L stroke grestore /mF f D}d +/Ac {/AC E D WB}d +/Ca {eA{( \()join AC join(\) )join}if WB}d +/s {OU{gsave 0 CS .25 mul R dup SW pop CJ 0 RL stroke grestore}if}D +/CJ {AT 3 eq LB and{E dup dup length 1 sub A1 mul E + {( ) search{pop pop E A2 add E}{pop exit}ie}loop 3 -1 roll add + W CP pop sub 2 copy gt{E}if pop}if}D +/So {/Co E D} D +/SO {C1 Yo ST cvs join ( So ) join /C1 E D (j) SW pop 2 div Pd} D +/Se {E WB CS E div Pd}D +/Pd {dup type /stringtype eq{SW pop}if dup /L1 E L1 add D + ST cvs ( 0 R ) join C1 E join /C1 E D} D +/Sp {0.35 CO} D +/Sb {-0.2 CO} D +/CO {OV Io Yo put /Yo E CS mul Yo add D /Io Io 1 add D -1.5 Io mul 3 add FZ SO + CS Yo add dup YA gt{/YA E D}{pop}ie + Yo neg dup YB gt{/YB E D}{pop}ie} D +/Es {ES /Io Io 1 sub NN D /Yo OV Io get D SO} D +/SB {/N2 0 D 0 1 NI{/N E D{IX N2 get 0 lt{/N2 N2 1 add D}{exit}ie}loop + /K WS N get FC N get mul D /NY AY N2 get D /BV NY array D + 0 1 NY 1 sub{/TM K string D currentfile TM readhexstring pop pop BV E TM put} + for BM N BV put /N2 N2 1 add D}for} D +/IC [{/MA E D /MB 0 D}{2 div /MA E D /MB MA D}{/MB E CS sub D /MA CS D} + {pop /MA YS AB mul D /MB 1 AB sub YS mul D}{pop /MA 0 D /MB 0 D}] D +/IP {BV N get /N N 1 add D} D +/II {/K E D IX K get 0 lt{/EC E D}if /TY E D + TY 4 eq{/Y E D /X E D}if TY 3 eq{/AB E D}if + /XW AX K get D /YW AY K get D /IS SG IT K get get D /XS XW IS mul D + /YS YW IS mul D YS IC TY get exec /MA MA Fl not{3 add}if D} D +/IM {II /ty TY D /xs XS D /ys YS D /ya YA D /yb YB D /ma MA D /mb MB D /k K D + /ec EC D /BP f D /CI 0 D WB TL L1 xs add dup XO add MR add W gt + {pop /ma ma Fl{3 add}if D NL /YA ma D /YB mb D /YS ys D /L1 xs D} + {/L1 E D ma YA gt{/YA ma D}if mb YB gt{/YB mb D}if}ie /TB f D + OU{CP E pop YS sub LE neg lt Fl not and PB not and{NP /YA ma D /YB mb D}if + /BP f D ty ST cvs ( ) join IX k get 0 lt{(\() join ec join (\) ) join}if + k ST cvs join ty 3 eq{AB ST cvs ( ) join E join}if + ty 4 eq{X ST cvs ( ) join Y ST cvs join ( ) join E join}if C1 E join + ( DI ) join FP 2 eq FP 1 eq AF and or{( FM ) join}if + ( Il Cp ) apa /C1 E D /EN f D}if /HM t D /T f D} D +/DI {II /Xc CP /Yc E D D /YN YW neg D /HM t D /CI 0 D /K2 IX K get D gsave + TY 4 eq{OX X IS mul add OY FY add YS sub Y IS mul sub} + {/FY YS D CP MB sub 2 copy /OY E D /OX E D}ie + translate K2 0 ge{/DP AZ K2 get D /BV BM K2 get D XS YS scale /N 0 D XW YW DP + [XW 0 0 YN 0 YW] {IP} FC K2 get 1 eq{image}{f 3 colorimage}ie} + {EX}ie grestore XS 0 R /Ms t D} D +/FM {gsave 0 Sg CP MB sub translate XS neg 0 M 0 YS RL XS 0 RL 0 YS neg RL + XS neg 0 RL stroke grestore} D +/NA {/AT E D /AL AL 1 add D AV AL AT put} D +/OA {AL 0 gt{/AL AL 1 sub D /AT AV AL get D}if} D +/D1 {/BR {CP E pop E BN Mb{CP E pop eq{0 YI R}if}{pop}ie} D + /Sn {OU{C1 E ST cvs join ( Ld ) join /C1 E D}{pop}ie} D} D +/D1 {/BR {BN} D /Sn {OU {C1 E ST cvs join ( Ld ) join /C1 E D} {pop} ie} D} D +/TC {/TF t D /ML 0 D HN{SW pop dup ML gt{/ML E D}{pop}ie}forall NP /RM RM not D + RC /OU Tc D Ep /PN 0 D Ms not TP and{Ip}if /W IW ML sub Ts sub D + /A0 0 D TH{/BR {( ) join BT} D /Sn {pop} D /Au () D}if} D +/TN {0 eq{E EA PF HF or not XR and{HN E get Xr}{pop}ie} + {OU{Tn 0 ge{() BN}if /Tn E D}{pop}ie WB}ie} D +/NT {OU LB not and Tn 0 ge and{PL 0 eq{Ms not{CS CF FS}if CP dup + /y E YA sub D W 9 sub CS -1.8 mul XO L1 add 2 add{y M (.) show}for + HN Tn get dup SW pop IW E sub y M show CP BB M}if /Tn -1 D}if} D +/Ld {/DN E D HN DN Pn put [/View [/XYZ -4 Fl{PS}{CP YA add US E pop}ie null] + /Dest DN ST cvs cvn /DEST pdfmark} D +/C {ND 1 eq{1 sub}if TI mul /XO E D NL Nf not{pop()}if 0 3 -1 roll 1 A} D +/OP {BP not{NP}if PN 2 mod 0 eq{/Ms t D NP}if}D +/Ep {Xp PN 2 mod 0 eq and OU and{/Pn (-) D showpage /PM 1 D LA}if}D +/Dg [73 86 88 76 67 68 77] D +/Rd [0 [1 1 0][2 1 0][3 1 0][2 1 1][1 1 1][2 2 1][3 3 1][4 4 1][2 1 2]] D +/Ns {/m E D /c E 32 mul D /j m 1000 idiv D /p j 12 add string D + c 96 le m 0 gt and{c 32 le {/i 0 D /d 77 D /l 100 D /m m j 1000 mul sub D + j -1 1 {pop p i d c add put /i i 1 add D}for + 4 -2 0 {/j E D /n m l idiv D /m m n l mul sub D /d Dg j get D + n 0 gt {/x Rd n get D x 0 get -1 1 {pop p i d c add put /i i 1 add D}for + p i x 1 get sub Dg x 2 get j add get c add put}if /l l 10 idiv D + }for p 0 i GI} + {/i ST length 1 sub D m {1 sub dup 0 ge{dup 26 mod c add 1 add + ST i 3 -1 roll put 26 idiv dup 0 eq{pop exit}if}if /i i 1 sub D}loop + ST i ST length i sub GI}ie} + {m p cvs}ie} D +/US {matrix currentmatrix matrix defaultmatrix matrix invertmatrix + matrix concatmatrix transform} D +/GB {Gb{US}if}D +/Tl {/Rn E D Xc CP pop ne{ + [/Rect [Xc 1 sub Yc cS 0.25 mul sub GB CP E 1 add E cS 0.85 mul add GB] + /Subtype /Link /Border [0 0 Cf Lc and LX and AU or{0}{1}ie] Rn type + /nametype eq {/Dest Rn}{/Action [/Subtype /URI /URI Rn] Cd}ie + /ANN pdfmark}if} D +/Il {/Rn E D [/Rect [Xc Yc GB Xc XS add Yc YS add GB] /Subtype /Link + /Border [0 0 0] Rn type /nametype eq{/Dest Rn} + {/Action [/Subtype /URI /URI Rn] Cd}ie /ANN pdfmark} D +/XP {[{/Z Bz 2 div D Z 0 R Z Z RL Z neg Z RL Z neg Z neg RL Z Z neg RL + Fi cH 1 eq and{fill}if} {Bz 0 RL 0 Bz RL Bz neg 0 RL 0 Bz neg RL + Fi cH 1 eq and{fill}if} {0 -5 R Bz 0 RL 0 21 RL Bz neg 0 RL 0 -21 RL}]} D +/MS {/Sm E D WB}D +/O {BN()Sm BX} D +/O {BN()0 Sm BX} D +/BX {/Bt E D Bt 2 lt{/Ch E D CS 0.8 mul}{11 mul}ie W XO sub MR sub + 2 copy gt{E}if pop /HZ E D Bt 2 eq{Fi not{pop()}if ( )E join /Ft E D TT + /PF t D /MW 1 D /Li 1 D /Fw Ft SW pop D Fw HZ gt{/HZ Fw 8 add D}if + HZ ST cvs( )join}{WB Ch ST cvs( )join}ie L1 HZ add XO add MR add W gt{NL}if + Bt 2 eq{Ft ES Fw neg HM{CS sub}if Pd}if Bt ST cvs join( Bx )join + Bt 2 eq HM and{CS Pd}if C1 E join /C1 E D /L1 L1 HZ add D /T f D + ( ) Pd /PF f D Bt 2 lt{YA CS .8 mul lt{/YA CS .8 mul D}if} + {YB 5 lt{/YB 5 D}if YA 21 lt{/YA 21 D}if}ie /CI 0 D} D +/Bx {dup 2 eq{E /Bz E D}{E /cH E D /Bz CS .8 mul D}ie + OU {gsave 0 Sg XP E get exec stroke grestore}{pop}ie Bz 0 R /Ms t D}D +/SD {FD 4 mul Dy add DZ NF newpath 0 0 M DX t charpath pathbbox + 3 -1 roll sub /DY E D E dup /X1 E D sub WM mul WX DY mul add WM DG mul E div + /DF E D /DR WX DF mul DY mul WM div 2 div D} d +/Sd {gsave 0 IL Di mul neg translate IL IW atan Di 0 eq{neg}if rotate + FD 4 mul Dy add DZ NF DR X1 sub DY 2 div neg M cD VC DX show grestore} d +/Pt {/tp t D Tp{NP /Pn (TP) D 0 Tt neg R Th BN NP Ep ET RC ZF}if /tp f D} D +/RC {/AI 0 D /LG 0 D /BC 0 D /UI 0 D /PF f D /Cc 0 D /cC 0 D /Dc 10 array D + /NR [0 1 9{pop 0}for] D /La Ds D /AR 10 array D /TR 10 array D /AV 30 array D + SI /AL -1 D /AT A0 D AT NA /OV 9 array D /Yo 0 D /Co 0 D /Io 0 D /Hy f D + /Ph f D /CL -1 D Ct Sc}D +/ZF {/FR [0 1 30{pop 0}for] D /SZ [0 1 30{pop 0}for] D /FO [0 1 30{pop 0}for] D + /SL 0 D /CF 0 D /FN 0 D 0 Ts SF}D +/QO [[(\234)(\233)(\253\240)(\232)(\273)(\253)][(')(`)(\253\240)(\231)(\273)(\253)]] D +/QC [[(\234)(\234)(\240\273)(\233)(\253)(\273)][(')(')(\240\273)(`)(\253)(\273)]] D +/Hf EF length 2 sub D +/Hz EZ Hf get D +/HS Ey Hf get D +/Fz EZ Hf 1 add get D +/Fs Ey Hf 1 add get D +/LE IL D +/Ps EZ 1 get D +/Fp EF 1 get D +/XO 0 D +/YI 0 D +/CI 0 D +/FP 0 D +/WW Ts 7 mul D +/Mf 0 D +/YA 0 D +/YB 0 D +/Cs Ts D +/GS Ts D +/F0 0 D +/NS 0 D +/NB 0 D +/N 0 D +/C0 [] D +/C1 () D +/Lo 0 D +/L1 0 D +/LM 0 D +/PH 0 D +/EC 0 D +/Lh 0 D +/LT 0 D +/CH 1 string D +/ST 16 string D +/CA 9 array D +/HC (\255) D +/HM f D +/PF f D +/EN f D +/TB f D +/UF f D +/sF f D +/AE f D +/AF f D +/BP t D +/CD f D +/PA t D +/GL f D +/T t D +/HF f D +/AH f D +/SA f D +/PB f D +/f1 f D +/mF f D +/OX 0 D +/OY 0 D +/FY 0 D +/EO 0 D +/FB 0 D +/PL 0 D +/Bw 0 D +/PD -1 D +/TP f D +/tp f D +/TH f D +/Ty 4 D +/Tn -1 D +/Fl t D +/LB t D +/PM 1 D +/Ms f D +/Ba f D +/Bb f D +/Hl 3 D +/hl 6 D +/Hv 6 D +/Hs f D +/HI 0 D +/hi 0 D +/PO t D +/TE f D +/LF t D +/BO 0 D +/Sm 1 D +/Bf 3 D +/A1 0 D +/A2 0 D +/Ds 1 D +/QL -1 D +/Cb Db D +/Ct Dt D +/Cl Dl D +[/Creator (html2ps version 1.0 beta5) /Author () /Keywords () /Subject () + /Title (The Funtools Help Facility) /DOCINFO pdfmark +/ND 18 D +/HN [(1) (1) (1) (1) (8) (9) (19) (21) (28) (30) (33) (37) (38) (41) (42) (45) +(48) (51) (53) (??) (54) (56) (56) (87) (57) (58) (60) (62) (64) (65) (76) +(77) (66) (73) (75) (82) (85) (78) (80) (86) (87) (57) (91) (91) (92) (92) +(94) (102) (111) (95) (96) (100) (117) (123) (127) (136) (152) (157) (161) +(164) (165) (167) (171) (1) (1) (1) (3) (1) (1) (1) (8) (9) (19) (21) (28) +(30) (33) (37) (38) (41) (42) (45) (48) (50) (51) (51) (51) (51) (52) (53) +(53) (53) (53) (53) (54) (56) (56) (57) (57) (58) (60) (62) (64) (65) (66) +(73) (75) (76) (77) (80) (82) (85) (86) (87) (87) (87) (88) (90) (91) (98) +(91) (91) (91) (91) (92) (92) (94) (95) (96) (98) (99) (100) (101) (102) +(102) (102) (102) (102) (103) (104) (105) (105) (108) (109) (110) (111) +(111) (111) (111) (111) (111) (112) (113) (114) (114) (115) (116) (116) +(116) (117) (119) (119) (120) (120) (120) (117) (117) (117) (117) (119) +(119) (120) (120) (120) (121) (122) (123) (123) (123) (123) (126) (127) +(127) (127) (127) (127) (129) (129) (130) (131) (131) (132) (132) (133) +(135) (136) (136) (136) (136) (146) (151) (152) (152) (152) (152) (156) +(157) (157) (157) (157) (157) (158) (159) (160) (161) (161) (161) (161) +(161) (161) (162) (162) (163) (164) (164) (164) (164) (164) (165) (165) +(165) (165) (165) (166) (167) (167) (167) (167) (170) (171) (171) (171) +(171) (171) (172) (172) (172) (175) (178) (178) (179) (180) (181) (181) +(182) (182) (183) (183) (184) (184) (184) (184) (185) (185) (185) (186) +(187) (187)] D +/h0 [()(Table of Contents)] D +/h1 [(0.1\240\240)(Funtools: FITS Users Need Tools)] D +/h2 [(0.2\240\240)(Summary)] D +/h3 [(0.3\240\240)(Description)] D +/h4 [(0.3.0.0.1\240\240)(Last updated: January 6, 2006)] D +/h5 [(0.4\240\240)(Funtools Programs)] D +/h6 [(0.5\240\240)(Summary)] D +/h7 [(0.6\240\240)(funcalc - Funtools calculator \(for binary tables\))] D +/h8 [(0.7\240\240)(funcen - find centroid \(for binary tables\))] D +/h9 [(0.8\240\240)(funcnts - count photons in specified regions, with bkgd subtraction)] D +/h10 [(0.9\240\240)(funcone - cone search of a binary table containing RA, Dec columns)] D +/h11 [(0.10\240\240)(fundisp - display data in a Funtools data file)] D +/h12 [(0.11\240\240)(funhead - display a header in a Funtools file)] D +/h13 [(0.12\240\240)(funhist - create a 1D histogram of a column \(from a FITS binary table or raw event file\) or an image)] D +/h14 [(0.13\240\240)(funimage - create a FITS image from a Funtools data file)] D +/h15 [(0.14\240\240)(funindex - create an index for a column of a FITS binary table)] D +/h16 [(0.15\240\240)(funjoin - join two or more FITS binary tables on specified columns)] D +/h17 [(0.16\240\240)(funmerge - merge one or more Funtools table files)] D +/h18 [(0.17\240\240)(funsky - convert between image and sky coordinates)] D +/h19 [(0.18\240\240)(funtable - copy selected rows from a Funtools file to a FITS binary table)] D +/h20 [(0.19\240\240)(funtbl - extract a table from Funtools ASCII output)] D +/h21 [(0.19.0.0.1\240\240)(Last updated: April 1, 2007)] D +/h22 [(0.20\240\240)(FunDS9: Funtools and DS9 Image Display)] D +/h23 [(0.21\240\240)(Summary)] D +/h24 [(0.22\240\240)(Description)] D +/h25 [(0.22.0.0.1\240\240)(Last updated: November 16, 2005)] D +/h26 [(0.23\240\240)(FunLib: the Funtools Programming Interface)] D +/h27 [(0.24\240\240)(Summary)] D +/h28 [(0.25\240\240)(Introduction to the Funtools Programming Interface)] D +/h29 [(0.26\240\240)(Funtools Programming Tutorial)] D +/h30 [(0.27\240\240)(Compiling and Linking)] D +/h31 [(0.28\240\240)(A Short Digression on Subroutine Order)] D +/h32 [(0.29\240\240)(Funtools Programming Examples)] D +/h33 [(0.30\240\240)(The Funtools Programming Reference Manual)] D +/h34 [(0.31\240\240)(FunOpen - open a Funtools data file)] D +/h35 [(0.32\240\240)(FunImageGet - get an image or image section)] D +/h36 [(0.33\240\240)(FunImagePut - put an image to a Funtools file)] D +/h37 [(0.34\240\240)(FunImageRowGet - get row\(s\) of an image)] D +/h38 [(0.35\240\240)(FunImageRowPut - put row\(s\) of an image)] D +/h39 [(0.36\240\240)(FunColumnSelect - select Funtools columns)] D +/h40 [(0.37\240\240)(FunColumnActivate - activate Funtools columns)] D +/h41 [(0.38\240\240)(FunColumnLookup - lookup a Funtools column)] D +/h42 [(0.39\240\240)(FunTableRowGet - get Funtools rows)] D +/h43 [(0.40\240\240)(FunTableRowPut - put Funtools rows)] D +/h44 [(0.41\240\240)(FunParamPut - put a Funtools param value)] D +/h45 [(0.42\240\240)(FunInfoGet - get information from Funtools struct)] D +/h46 [(0.43\240\240)(FunInfoPut - put information into a Funtools struct)] D +/h47 [(0.44\240\240)(FunFlush - flush data to output file)] D +/h48 [(0.45\240\240)(FunClose - close a Funtools data file)] D +/h49 [(0.46\240\240)(FunRef: the Funtools Reference Handle)] D +/h50 [(0.47\240\240)(Summary)] D +/h51 [(0.48\240\240)(Description)] D +/h52 [(0.48.0.0.1\240\240)(Last updated: December 1, 2005)] D +/h53 [(0.49\240\240)(FunFiles: Funtools Data Files)] D +/h54 [(0.50\240\240)(Summary)] D +/h55 [(0.51\240\240)(Description)] D +/h56 [(0.52\240\240)(Supported Data Formats)] D +/h57 [(0.53\240\240)(FITS Images and Binary Tables)] D +/h58 [(0.54\240\240)(Non-FITS Raw Event Files)] D +/h59 [(0.55\240\240)(Non-FITS Array Files)] D +/h60 [(0.56\240\240)(Specifying Image Sections)] D +/h61 [(0.57\240\240)(Binning FITS Binary Tables and Non-FITS Event Files)] D +/h62 [(0.58\240\240)(Table and Spatial Region Filters)] D +/h63 [(0.59\240\240)(Disk Files and Other Supported File Types)] D +/h64 [(0.60\240\240)(Lists of Files)] D +/h65 [(0.60.0.0.1\240\240)(Last updated: February 15, 2006)] D +/h66 [(0.61\240\240)(Funtext: Support for Column-based Text Files)] D +/h67 [(0.62\240\240)(Summary)] D +/h68 [(0.63\240\240)(Description)] D +/h69 [(0.64\240\240)(Standard Text Files)] D +/h70 [(0.65\240\240)(Comments Convert to Header Params)] D +/h71 [(0.66\240\240)(Multiple Tables in a Single File)] D +/h72 [(0.67\240\240)(TEXT\(\) Specifier)] D +/h73 [(0.68\240\240)(Text\(\) Keyword Options)] D +/h74 [(0.69\240\240)(Environment Variables)] D +/h75 [(0.70\240\240)(Restrictions and Problems)] D +/h76 [(0.70.0.0.1\240\240)(Last updated: August 3, 2007)] D +/h77 [(0.71\240\240)(Funview: Database View Support for Tables)] D +/h78 [(0.72\240\240)(Summary)] D +/h79 [(0.73\240\240)(Description)] D +/h80 [(0.74\240\240)(Database Views)] D +/h81 [(0.75\240\240)(Funtools View Attributes)] D +/h82 [(0.76\240\240)(Invoking a Funtools View \(in Place of an Input File\))] D +/h83 [(0.77\240\240)(Basic View Matching Rules)] D +/h84 [(0.78\240\240)(More on View Matching Rules: Single vs. Multiple Matches)] D +/h85 [(0.79\240\240)(View Lists: Applying a View to Any File)] D +/h86 [(0.80\240\240)(Overriding Values Associated with a View)] D +/h87 [(0.81\240\240)(Environment Variables)] D +/h88 [(0.82\240\240)(Restrictions and Problems)] D +/h89 [(0.82.0.0.1\240\240)(Last updated: August 3, 2007)] D +/h90 [(0.83\240\240)(Funfilters: Filtering Rows in a Table)] D +/h91 [(0.84\240\240)(Summary)] D +/h92 [(0.85\240\240)(Description)] D +/h93 [(0.86\240\240)(Filter Expressions)] D +/h94 [(0.87\240\240)(Separators Also Are Operators)] D +/h95 [(0.88\240\240)(Range Lists)] D +/h96 [(0.89\240\240)(Math Operations and Functions)] D +/h97 [(0.90\240\240)(Include Files)] D +/h98 [(0.91\240\240)(Header Parameters)] D +/h99 [(0.92\240\240)(Examples)] D +/h100 [(0.92.0.0.1\240\240)(Last updated: November 17, 2005)] D +/h101 [(0.93\240\240)(Funidx: Using Indexes to Filter Rows in a Table)] D +/h102 [(0.94\240\240)(Summary)] D +/h103 [(0.95\240\240)(Description)] D +/h104 [(0.95.0.0.1\240\240)(Last updated: August 3, 2007)] D +/h105 [(0.96\240\240)(Regions: Spatial Region Filtering)] D +/h106 [(0.97\240\240)(Summary)] D +/h107 [(0.98\240\240)(Description)] D +/h108 [(0.99\240\240)(Region Expressions)] D +/h109 [(0.100\240\240)(Columns Used in Region Filtering)] D +/h110 [(0.101\240\240)(Region Algebra)] D +/h111 [(0.102\240\240)(Region Separators Also Are Operators)] D +/h112 [(0.103\240\240)(Region Exclusion)] D +/h113 [(0.104\240\240)(Include Files)] D +/h114 [(0.105\240\240)(Global and Local Properties of Regions)] D +/h115 [(0.106\240\240)(Coordinate Systems)] D +/h116 [(0.107\240\240)(Specifying Positions, Sizes, and Angles)] D +/h117 [(0.107.0.0.1\240\240)(Last updated: November 17, 2005)] D +/h118 [(0.108\240\240)(RegGeometry: Geometric Shapes in Spatial Region Filtering)] D +/h119 [(0.109\240\240)(Summary)] D +/h120 [(0.110\240\240)(Geometric shapes)] D +/h121 [(0.111\240\240)(Region accelerators)] D +/h122 [(0.111.0.0.1\240\240)(Last updated: March 12, 2007)] D +/h123 [(0.112\240\240)(RegAlgebra: Boolean Algebra on Spatial Regions)] D +/h124 [(0.113\240\240)(Summary)] D +/h125 [(0.114\240\240)(Description)] D +/h126 [(0.114.0.0.1\240\240)(Last updated: November 17, 2005)] D +/h127 [(0.115\240\240)(RegCoords: Spatial Region Coordinates)] D +/h128 [(0.116\240\240)(Summary)] D +/h129 [(0.117\240\240)(Pixel coordinate systems)] D +/h130 [(0.118\240\240)(World Coordinate Systems)] D +/h131 [(0.119\240\240)(WCS Positions and Sizes)] D +/h132 [(0.120\240\240)(NB: The Meaning of Pure Numbers Are Context Sensitive)] D +/h133 [(0.120.0.0.1\240\240)(Last updated: November 17, 2005)] D +/h134 [(0.121\240\240)(RegBounds: Region Boundaries)] D +/h135 [(0.122\240\240)(Summary)] D +/h136 [(0.123\240\240)(Description)] D +/h137 [(0.124\240\240)(Image boundaries : radially-symmetric shapes \(circle, annuli, ellipse\))] D +/h138 [(0.125\240\240)(Image Boundaries: non-radially symmetric shapes \(polygons, boxes\))] D +/h139 [(0.126\240\240)(Row Boundaries are Analytic)] D +/h140 [(0.127\240\240)(Image Boundaries vs. Row Boundaries: Practical Considerations)] D +/h141 [(0.127.0.0.1\240\240)(Last updated: November 16, 2005)] D +/h142 [(0.128\240\240)(RegDiff:Differences Between Funtools and IRAF Regions)] D +/h143 [(0.129\240\240)(Summary)] D +/h144 [(0.130\240\240)(Description)] D +/h145 [(0.130.0.0.1\240\240)(Last updated: November 16, 2005)] D +/h146 [(0.131\240\240)(FunCombine: Combining Region and Table Filters)] D +/h147 [(0.132\240\240)(Summary)] D +/h148 [(0.133\240\240)(Comma Conventions)] D +/h149 [(0.133.0.0.1\240\240)(Last updated: November 16, 2005)] D +/h150 [(0.134\240\240)(FunEnv: Funtools Environment Variables)] D +/h151 [(0.135\240\240)(Summary)] D +/h152 [(0.136\240\240)(Description)] D +/h153 [(0.136.0.0.1\240\240)(Last updated: November 16, 2005)] D +/h154 [(0.137\240\240)(Funtools ChangeLog)] D +/h155 [(0.138\240\240)(Patch Release 1.4.5 \(internal ds9 release\))] D +/h156 [(0.139\240\240)(Patch Release 1.4.4 \(internal ds9 release\))] D +/h157 [(0.140\240\240)(Patch Release 1.4.3 \(internal ds9 release\))] D +/h158 [(0.141\240\240)(Patch Release 1.4.2 \(internal ds9 release\))] D +/h159 [(0.142\240\240)(Patch Release 1.4.1 \(internal ds9 release\))] D +/h160 [(0.143\240\240)(Public Release 1.4.0 \(15 August 2007\))] D +/h161 [(0.144\240\240)(Release 1.3.0b[n] \(mainly internal SAO beta releases\))] D +/h162 [(0.145\240\240)(Patch Release 1.2.4 \(internal SAO and beta release only\))] D +/h163 [(0.146\240\240)(Patch Release 1.2.3 \(12 January 2004\))] D +/h164 [(0.147\240\240)(Patch Release 1.2.3b1 \(19 August 2003\))] D +/h165 [(0.148\240\240)(Patch Release 1.2.2 \(18 May 2003\))] D +/h166 [(0.149\240\240)(Patch Release 1.2.1 \(24 April 2003\))] D +/h167 [(0.150\240\240)(Public Release 1.2.0 \(24 March 2003\))] D +/h168 [(0.151\240\240)(Beta Release 1.2.b3 \(4 February 2003\))] D +/h169 [(0.152\240\240)(Beta Release 1.2.b2 \(7 October 2002\))] D +/h170 [(0.153\240\240)(Beta Release 1.2.b1 \(24 September 2002\))] D +/h171 [(0.154\240\240)(Public Release 1.1.0 \(22 April 2002\))] D +/h172 [(0.155\240\240)(Pre-Release 1.1.0e \(10 April 2002\))] D +/h173 [(0.156\240\240)(Pre-Release 1.1.0e \(19 March 2002\))] D +/h174 [(0.157\240\240)(Pre-Release 1.1.0e \(27 February 2002\))] D +/h175 [(0.158\240\240)(Pre-Release 1.1.0e \(11 February 2002\))] D +/h176 [(0.159\240\240)(Beta Release 1.0.1b5 \(31 January 2002\))] D +/h177 [(0.160\240\240)(Beta Release 1.0.1b4 \(26 January 2002\))] D +/h178 [(0.161\240\240)(Beta Release 1.0.1b3 \(4 January 2002\))] D +/h179 [(0.162\240\240)(Beta Release 1.0.1b2 \(14 November 2001\))] D +/h180 [(0.163\240\240)(Beta Release 1.0.1b1 \(6 November 2001\))] D +/h181 [(0.164\240\240)(Public Release 1.0.0 \(31 July 2001\))] D +/h182 [(0.164.0.0.1\240\240)(Last updated: 22 April 2002)] D +/Hr [-63 63 64 65 -66 -66 66 -67 67 68 69 70 71 72 73 74 75 76 77 78 79 +80 81 82 -83 -83 83 -85 85 86 87 -88 -88 88 -91 91 92 93 94 95 96 97 98 +99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 -117 +-117 117 -120 120 121 122 123 124 125 126 127 128 129 130 131 -132 -132 +132 -134 134 135 136 137 138 139 140 141 142 143 -144 -144 144 -146 146 +147 148 149 150 151 152 153 154 155 156 157 -158 -158 158 -165 165 166 167 +168 169 170 171 172 173 174 -175 -175 175 -177 177 178 179 -180 -180 180 +-182 182 183 184 185 186 187 188 189 190 191 192 193 -194 -194 194 -196 +196 197 198 199 -200 -200 200 -202 202 203 204 -205 -205 205 -207 207 208 +209 210 211 212 -213 -213 213 -215 215 216 217 218 219 220 221 -222 -222 +222 -224 224 225 226 -227 -227 227 -230 230 231 232 -233 -233 233 -235 235 +236 237 -238 -238 238 -239 239 240 241 242 243 244 245 246 247 248 249 250 +251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 -267 -267 +267]D +/HV [1 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 3 4 +5 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 2 +2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 +2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 2 +2 2 2 3 4 5 1 2 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 2 2 2 3 4 5 1 2 2 2 2 +2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 3 4 5 1 2 2 2 2 2 2 2 2 +2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 4 5]D +/Cn [3 0 0 1 1 1 0 16 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 3 0 0 1 1 1 +0 26 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 12 0 0 0 +0 0 0 0 0 0 0 0 1 1 1 0 10 0 0 0 0 0 0 0 0 0 1 1 1 0 12 0 0 0 0 0 0 0 0 +0 0 0 1 1 1 0 10 0 0 0 0 0 0 0 0 0 1 1 1 0 3 0 0 1 1 1 0 12 0 0 0 0 0 0 +0 0 0 0 0 1 1 1 0 4 0 0 0 1 1 1 0 3 0 0 1 1 1 0 6 0 0 0 0 0 1 1 1 0 7 0 +0 0 0 0 0 1 1 1 0 3 0 0 1 1 1 0 3 0 0 1 1 1 0 3 0 0 1 1 1 0 28 0 0 0 0 0 +0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0]D +Hr length 0 gt{[/PageMode /UseOutlines /DOCVIEW pdfmark}if +/Hn 1 D +0 1 Hr length 1 sub{ + /Bn E D [Cn Bn get dup 0 gt{/Count E HV Bn get Bl ge{neg}if}{pop}ie + /Dest Hr Bn get dup abs ST cvs cvn E 0 ge{(h)Hn ST cvs join cvx exec + dup 1 get E Nf{0 get E join}{pop}ie /Hn Hn 1 add D}{()}ie + /Title E dup length 255 gt{0 255 getinterval}if /OUT pdfmark}for +ZF /FN Fp D Ps 0 FS /WC Wf{( )}{<A1A1>}ie SW pop D +ET RC ZF +/Df f D +/R1 (http://hea-www.harvard.edu/saord/ds9/index.html) D +/R2 (http://hea-www.harvard.edu/saord/xpa/index.html) D +/R3 (ftp://cfa-ftp.harvard.edu/pub/gsc/WCSTools/home.html) D +/R4 (http://tdc-www.harvard.edu/software/wcstools/) D +/R5 (http://hea-www.harvard.edu/RD/funtools/changelog.html) D +/R6 (http://hea-www.harvard.edu/RD/funtools/changelog_beta.html) D +/Ba f D /BO 0 D Bs +/UR (help.html) D +/Ti (The Funtools Help Facility) D +/Au () D +/Df f D +/ME [()] D + TC + +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc + +/Ba f D /BO 0 D Bs +/UR (help.html) D +/Ti (The Funtools Help Facility) D +/Au () D +/Df f D +/ME [()] D + TC + +NP RC ZF +()1 Sl()WB 0 Sn( + + +)0 2 0 H(Funtools:)WB 63 Sn()WB 1 Sn( FITS Users Need Tools)EA()EH( + + +)0 2 1 H(Summary)WB 64 Sn()EH( +This document is the Table of Contents for Funtools. + + +)0 2 2 H(Description)WB 65 Sn()EH( +Funtools, is a "minimal buy-in" FITS library and utility package developed +at the the High Energy Astrophysics Division of SAO. The Funtools +library provides simplified access to a wide array of file types: +standard astronomical FITS images and binary tables, raw arrays and +binary event lists, and even tables of ASCII column data. A +sophisticated region filtering library \201compatible with ds9\202 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. + +The main goal of the Funtools project has been to develop a minimal buy-in +FITS library for researchers who are occasional \201but serious\202 coders. In +this case, "minimal buy-in" means "easy to learn, easy to use, and easy to +re-learn next month". We have tried to achieve this goal by emphasizing two +essential capabilities. The first is the ability to develop FITS programs +without knowing much about FITS, i.e., without having to deal with the +arcane rules for generating a properly formatted FITS 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. + + +)0 P(Choose from the following topics: + +)0 P()UL()-1 LI()0 2 1 A(Funtools User Programs)2 1 TN TL()Ec /AF f D( +)UL()-1 LI()0 3 1 A(funcalc: Funtools calculator \201for binary tables\202)3 1 TN TL()Ec /AF f D( + +)-1 LI()0 4 1 A(funcen: find centroid \201for binary tables\202)4 1 TN TL()Ec /AF f D( + +)-1 LI()0 5 1 A(funcnts: count photons in specified regions)5 1 TN TL()Ec /AF f D( + +)-1 LI()0 6 1 A(funcone: cone search on RA, Dec columns)6 1 TN TL()Ec /AF f D( + +)-1 LI()0 7 1 A(fundisp: display data in a Funtools data file)7 1 TN TL()Ec /AF f D( + +)-1 LI()0 8 1 A(funhead: display a header in a Funtools file)8 1 TN TL()Ec /AF f D( + +)-1 LI()0 9 1 A(funhist: create a 1D histogram of a column)9 1 TN TL()Ec /AF f D( + +)-1 LI()0 10 1 A(funimage: create a FITS image from a Funtools data file)10 1 TN TL()Ec /AF f D( + +)-1 LI()0 11 1 A(funindex: create an index on a column in a binary table)11 1 TN TL()Ec /AF f D( + +)-1 LI()0 12 1 A(funjoin: join two or more FITS binary tables on specified columns)12 1 TN TL()Ec /AF f D( + +)-1 LI()0 13 1 A(funmerge: merge one or more Funtools table files)13 1 TN TL()Ec /AF f D( + +)-1 LI()0 14 1 A(funsky: convert between image and sky coordinates, using WCS info from a FITS header)14 1 TN TL()Ec /AF f D( + +)-1 LI()0 15 1 A(funtable: copy selected rows from a Funtools file to a FITS binary table)15 1 TN TL()Ec /AF f D( + +)-1 LI()0 16 1 A(funtbl: extract a table from +Funtools ASCII output)16 1 TN TL()Ec /AF f D( + +)-1 LI()0 17 1 A(funtools and ds9 image display)17 1 TN TL()Ec /AF f D( +)LU( + +)-1 LI()0 18 1 A(Funtools Programming)18 1 TN TL()Ec /AF f D( +)UL()-1 LI()0 19 1 A(Funtools Programming Summary)19 1 TN TL()Ec /AF f D( + +)-1 LI()0 20 1 A(Funtools Programming Tutorial)20 1 TN TL()Ec /AF f D( + +)-1 LI()0 21 1 A(A Short Digression on Subroutine Order)21 1 TN TL()Ec /AF f D( + +)-1 LI()0 22 1 A(Compiling and Linking)22 1 TN TL()Ec /AF f D( + +)-1 LI()0 23 1 A(The Funtools Reference Handle)23 1 TN TL()Ec /AF f D( + +)-1 LI()0 24 1 A(The Funtools Programming Reference Manual)24 1 TN TL()Ec /AF f D( +)UL()-1 LI( )0 25 1 A(FunOpen: open a Funtools file)25 1 TN TL()Ec /AF f D( + +)-1 LI()0 26 1 A(FunImageGet: retrieve image data)26 1 TN TL()Ec /AF f D( + +)-1 LI()0 27 1 A(FunImagePut: output image data)27 1 TN TL()Ec /AF f D( + +)-1 LI()0 28 1 A(FunImageRowGet: retrieve image data by row)28 1 TN TL()Ec /AF f D( + +)-1 LI()0 29 1 A(FunImageRowPut: output image data by row)29 1 TN TL()Ec /AF f D( + +)-1 LI()0 30 1 A(FunTableRowGet: retrieve rows from a table)30 1 TN TL()Ec /AF f D( + +)-1 LI()0 31 1 A(FunTableRowPut: output rows to a table)31 1 TN TL()Ec /AF f D( + +)-1 LI()0 32 1 A(FunColumnSelect: select columns in a table for access)32 1 TN TL()Ec /AF f D( + +)-1 LI()0 33 1 A(FunColumnActivate: activate columns in a table for read/write)33 1 TN TL()Ec /AF f D( + +)-1 LI()0 34 1 A(FunColumnLookup: lookup info about the columns in a table)34 1 TN TL()Ec /AF f D( + +)-1 LI()0 35 1 A(FunInfoGet: get info about an image or table)35 1 TN TL()Ec /AF f D( + +)-1 LI()0 36 1 A(FunInfoPut: put info about an image or table)36 1 TN TL()Ec /AF f D( + +)-1 LI()0 37 1 A(FunParamGet: get header param)37 1 TN TL()Ec /AF f D( + +)-1 LI()0 38 1 A(FunParamPut: put header param)38 1 TN TL()Ec /AF f D( + +)-1 LI()0 39 1 A(FunFlush: flush I/O in a Funtools file)39 1 TN TL()Ec /AF f D( + +)-1 LI()0 40 1 A(FunClose: close a Funtools file)40 1 TN TL()Ec /AF f D( +)LU( + +)-1 LI()0 41 1 A(Funtools Programming Examples)41 1 TN TL()Ec /AF f D( + +)UL( +)-1 LI()0 2 A(evmerge: merge new columns with existing columns)EA( +)-1 LI()0 2 A(evcols: add column and rows to binary tables)EA( +)-1 LI()0 2 A(imblank: blank out image values below a threshold)EA()LU()LU( + +)-1 LI()0 42 1 A(Funtools Data Files)42 1 TN TL()Ec /AF f D( + +)UL( +)-1 LI()0 43 1 A(Supported Data Formats)43 1 TN TL()Ec /AF f D( +)UL()-1 LI()0 44 1 A(FITS File and Extensions)44 1 TN TL()Ec /AF f D( +)-1 LI()0 45 1 A(Non-FITS Raw Event Files)45 1 TN TL()Ec /AF f D( +)-1 LI()0 46 1 A(Non-FITS Array Files)46 1 TN TL()Ec /AF f D( +)-1 LI()0 47 1 A(Column-based Text \201ASCII\202 Files)47 1 TN TL()Ec /AF f D( +)-1 LI()0 48 1 A(Database Views of Tables)48 1 TN TL()Ec /AF f D()LU( +)-1 LI()0 49 1 A(Image Sections and Blocking)49 1 TN TL()Ec /AF f D( +)-1 LI()0 50 1 A(Binning FITS Binary Tables and Non-FITS Event Files)EH( +)-1 LI()0 51 1 A(Disk Files and Other Supported File Types)50 1 TN TL()Ec /AF f D()LU( + +)-1 LI(Funtools Data Filtering +)UL()-1 LI()0 52 1 A(Table Filtering)51 1 TN TL()Ec /AF f D( + +)-1 LI()0 53 1 A(Fast Table Filtering using Indexes)52 1 TN TL()Ec /AF f D( + +)-1 LI()0 54 1 A(Spatial Region Filtering)53 1 TN TL()Ec /AF f D( + +)UL()-1 LI()0 55 1 A(Region Geometry)54 1 TN TL()Ec /AF f D( + +)-1 LI()0 56 1 A(Region Algebra)55 1 TN TL()Ec /AF f D( + +)-1 LI()0 57 1 A(Region Coordinates)56 1 TN TL()Ec /AF f D( + +)-1 LI()0 58 1 A(Region Boundaries)57 1 TN TL()Ec /AF f D( + +)-1 LI()0 59 1 A(Differences Between Funtools and IRAF Regions)58 1 TN TL()Ec /AF f D( +)LU( +)-1 LI()0 60 1 A(Combining Table and Region Filters)59 1 TN TL()Ec /AF f D( +)LU( + +)-1 LI( Miscellaneous +)UL()-1 LI()0 61 1 A(Funtools Environment Variables)60 1 TN TL()Ec /AF f D( + +)-1 LI()0 62 1 A(Funtools ChangeLog)61 1 TN TL()Ec /AF f D()LU( +)LU( + + + +)0 5 3 H(Last)WB 66 Sn( updated: January 6, 2006)EH( + + +)WB NL NP Ep ET /Tc f D +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (programs.html) D +/Ti (Funtools Programs) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 2 Sn( +)0 2 4 H(Funtools)WB 67 Sn( Programs)EH( + +)0 2 5 H(Summary)WB 68 Sn()EH( + +)0 P() 27 129 PR()0 3 1 A(funcalc)3 0 TN TL()Ec /AF f D( [-n] [-a argstr] [-e expr] [-f file] [-l link] [-p prog] [-u] <iname> [oname [columns]] + +)0 4 1 A(funcen)4 0 TN TL()Ec /AF f D( [-i] [-n iter] [-t tol] [-v lev] <iname> <region> + +)0 5 1 A(funcnts)5 0 TN TL()Ec /AF f D( [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_cnts] + +)0 6 1 A(funcone)6 0 TN TL()Ec /AF f D( [-n] [-x|-X|-j|-J] [[-l|-L] list] [-r ra_col] [-d dec_col] <iname> <oname> <ra[hdr]> <dec[hdr]> <radius[dr'"]> [columns] + +)0 7 1 A(fundisp)7 0 TN TL()Ec /AF f D( [-f format] [-l] [-n] [-T] <iname> [columns|bitpix=n] + +)0 8 1 A(funhead)8 0 TN TL()Ec /AF f D( [-a] [-l] [-s] [-t] [-L] <iname> [oname ename] + +)0 9 1 A(funhist)9 0 TN TL()Ec /AF f D( [-n|-w|-T] <iname> [column] [[lo_edge:hi_edge:]bins] + +)0 10 1 A(funimage)10 0 TN TL()Ec /AF f D( [-a] [-l] [-p x|y] <iname> <oname> [bitpix=n] + +)0 11 1 A(funindex)11 0 TN TL()Ec /AF f D( <iname> <key> [oname] + +)0 12 1 A(funjoin)12 0 TN TL()Ec /AF f D( [switches] <ifile1> <ifile2> ... <ifilen> <ofile> + +)0 13 1 A(funmerge)13 0 TN TL()Ec /AF f D( <iname1> <iname2> ... <oname> + +)0 14 1 A(funsky)14 0 TN TL()Ec /AF f D( [switches] <iname1> [<lname2> <col1> <col2>] + +)0 15 1 A(funtable)15 0 TN TL()Ec /AF f D( [-a] [-i|-z] [-m] [-s cols] <iname> <oname> [columns] + +)0 16 1 A(funtbl)16 0 TN TL()Ec /AF f D( [-c cols] [-h] [-n table] [-p prog] [-s sep] [-T] <iname>)RP( + + + + +)0 2 6 H(funcalc)WB 69 Sn()WB 3 Sn( - Funtools calculator \201for binary tables\202)EA()EH( + +)BD() 1 90 PR(funcalc [-n] [-a argstr] [-e expr] [-f file] [-l link] [-p prog] <iname> [oname [columns]])RP()ES( + + +)0 P() 7 73 PR( -a argstr # user arguments to pass to the compiled program + -e expr # funcalc expression + -f file # file containing funcalc expression + -l libs # libs to add to link command + -n # output generated code instead of compiling and executing + -p prog # generate named program, no execution + -u # die if any variable is undeclared \201don't auto-declare\202)RP( + + +)0 P()BD(funcalc)ES( is a calculator program that allows arbitrary +expressions to be constructed, compiled, and executed on columns in a +Funtools table \201FITS binary table or raw event file\202. It works by +integrating user-supplied expression\201s\202 into a template C program, +then compiling and executing the program. )BD(funcalc)ES( expressions +are C statements, although some important simplifications \201such +as automatic declaration of variables\202 are supported. + +)0 P()BD(funcalc)ES( expressions can be specified in three ways: on the +command line using the )BD(-e [expression])ES( switch, in a file using +the )BD(-f [file])ES( switch, or from stdin \201if neither )BD(-e)ES( nor +)BD(-f)ES( is specified\202. Of course a file containing )BD(funcalc)ES( +expressions can be read from stdin. + +)0 P(Each invocation of )BD(funcalc)ES( requires an input Funtools table +file to be specified as the first command line argument. The output +Funtools table file is the second optional argument. It is needed only +if an output FITS file is being created \201i.e., in cases where the +)BD(funcalc)ES( expression only prints values, no output file is +needed\202. If input and output file are both specified, a third optional +argument can specify the list of columns to activate \201using +)0 33 1 A(FunColumnActivate\201\202)33 0 TN TL()Ec /AF f D(\202. Note +that )BD(funcalc)ES( determines whether or not to generate code for +writing an output file based on the presence or absence of an +output file argument. + +)0 P(A )BD(funcalc)ES( expression executes on each row of a table and +consists of one or more C statements that operate on the columns of +that row \201possibly using temporary variables\202. Within an expression, +reference is made to a column of the )BD(current)ES( row using the C +struct syntax )BD(cur->[colname])ES(, e.g. cur->x, cur->pha, etc. +Local scalar variables can be defined using C declarations at very the +beginning of the expression, or else they can be defined automatically +by )BD(funcalc)ES( \201to be of type double\202. Thus, for example, a swap of +columns x and y in a table can be performed using either of the +following equivalent )BD(funcalc)ES( expressions: + +) 4 18 PR( double temp; + temp = cur->x; + cur->x = cur->y; + cur->y = temp;)RP( + +or: + +) 3 18 PR( temp = cur->x; + cur->x = cur->y; + cur->y = temp;)RP( + +When this expression is executed using a command such as: +) 1 40 PR( funcalc -f swap.expr itest.ev otest.ev)RP( +the resulting file will have values of the x and y columns swapped. + +)0 P(By default, the data type of the variable for a column is the same as +the data type of the column as stored in the file. This can be changed +by appending ":[dtype]" to the first reference to that column. In the +example above, to force x and y to be output as doubles, specify the +type 'D' explicitly: +) 3 20 PR( temp = cur->x:D; + cur->x = cur->y:D; + cur->y = temp;)RP( + +Data type specifiers follow standard FITS table syntax for defining +columns using TFORM: +)UL()-1 LI(A: ASCII characters +)-1 LI(B: unsigned 8-bit char +)-1 LI(I: signed 16-bit int +)-1 LI(U: unsigned 16-bit int \201not standard FITS\202 +)-1 LI(J: signed 32-bit int +)-1 LI(V: unsigned 32-bit int \201not standard FITS\202 +)-1 LI(E: 32-bit float +)-1 LI(D: 64-bit float +)-1 LI(X: bits \201treated as an array of chars\202)LU( +Note that only the first reference to a column should contain the +explicit data type specifier. + +)0 P(Of course, it is important to handle the data type of the columns +correctly. One of the most frequent cause of error in )BD(funcalc)ES( +programming is the implicit use of the wrong data type for a column in +expression. For example, the calculation: +) 1 43 PR( dx = \201cur->x - cur->y\202/\201cur->x + cur->y\202;)RP( +usually needs to be performed using floating point arithmetic. In +cases where the x and y columns are integers, this can be done by +reading the columns as doubles using an explicit type specification: +) 1 47 PR( dx = \201cur->x:D - cur->y:D\202/\201cur->x + cur->y\202;)RP( + +Alternatively, it can be done using C type-casting in the expression: +) 1 75 PR( dx = \201\201double\202cur->x - \201double\202cur->y\202/\201\201double\202cur->x + \201double\202cur->y\202;)RP( + +)0 P(In addition to accessing columns in the current row, reference also +can be made to the )BD(previous)ES( row using )BD(prev->[colname])ES(, +and to the )BD(next)ES( row using )BD(next->[colname])ES(. Note that if +)BD(prev->[colname])ES( is specified in the )BD(funcalc)ES( +expression, the very first row is not processed. If +)BD(next->[colname])ES( is specified in the )BD(funcalc)ES( +expression, the very last row is not processed. In this way, +)BD(prev)ES( and )BD(next)ES( are guaranteed always to point to valid +rows. For example, to print out the values of the current x column +and the previous y column, use the C fprintf function in a +)BD(funcalc)ES( expression: +) 1 46 PR( fprintf\201stdout, "%d %d\200n", cur->x, prev->y\202;)RP( + +)0 P(New columns can be specified using the same )BD(cur->[colname])ES( +syntax by appending the column type \201and optional tlmin/tlmax/binsiz +specifiers\202, separated by colons. For example, cur->avg:D will define +a new column of type double. Type specifiers are the same those +used above to specify new data types for existing columns. + +)0 P(For example, to create and output a new column that is the average value of the +x and y columns, a new "avg" column can be defined: +) 1 36 PR( cur->avg:D = \201cur->x + cur->y\202/2.0)RP( +Note that the final ';' is not required for single-line expressions. + +)0 P(As with FITS TFORM data type specification, the column data type +specifier can be preceded by a numeric count to define an array, e.g., +"10I" means a vector of 10 short ints, "2E" means two single precision +floats, etc. A new column only needs to be defined once in a +)BD(funcalc)ES( expression, after which it can be used without +re-specifying the type. This includes reference to elements of a +column array: + +) 2 41 PR( cur->avg[0]:2D = \201cur->x + cur->y\202/2.0; + cur->avg[1] = \201cur->x - cur->y\202/2.0;)RP( + +)0 P(The 'X' \201bits\202 data type is treated as a char array of dimension +\201numeric_count/8\202, i.e., 16X is processed as a 2-byte char array. Each +8-bit array element is accessed separately: +) 2 24 PR( cur->stat[0]:16X = 1; + cur->stat[1] = 2;)RP( +Here, a 16-bit column is created with the MSB is set to 1 and the LSB set to 2. + +)0 P(By default, all processed rows are written to the specified output +file. If you want to skip writing certain rows, simply execute the C +"continue" statement at the end of the )BD(funcalc)ES( expression, +since the writing of the row is performed immediately after the +expression is executed. For example, to skip writing rows whose +average is the same as the current x value: + +) 4 41 PR( cur->avg[0]:2D = \201cur->x + cur->y\202/2.0; + cur->avg[1] = \201cur->x - cur->y\202/2.0; + if\201 cur->avg[0] == cur->x \202 + continue;)RP( + +)0 P(If no output file argument is specified on the )BD(funcalc)ES( command +line, no output file is opened and no rows are written. This is useful +in expressions that simply print output results instead of generating +a new file: +) 5 73 PR( fpv = \201cur->av3:D-cur->av1:D\202/\201cur->av1+cur->av2:D+cur->av3\202; + fbv = cur->av2/\201cur->av1+cur->av2+cur->av3\202; + fpu = \201\201double\202cur->au3-cur->au1\202/\201\201double\202cur->au1+cur->au2+cur->au3\202; + fbu = cur->au2/\201double\202\201cur->au1+cur->au2+cur->au3\202; + fprintf\201stdout, "%f\200t%f\200t%f\200t%f\200n", fpv, fbv, fpu, fbu\202;)RP( +In the above example, we use both explicit type specification +\201for "av" columns\202 and type casting \201for "au" columns\202 to ensure that +all operations are performed in double precision. + +)0 P(When an output file is specified, the selected input table is +processed and output rows are copied to the output file. Note that +the output file can be specified as "stdout" in order to write the +output rows to the standard output. If the output file argument is +passed, an optional third argument also can be passed to specify which +columns to process. + +)0 P(In a FITS binary table, it sometimes is desirable to copy all of the +other FITS extensions to the output file as well. This can be done by +appending a '+' sign to the name of the extension in the input file +name. See )BD(funtable)ES( for a related example. + +)0 P()BD(funcalc)ES( works by integrating the user-specified expression +into a template C program called )0 2 A(tabcalc.c)EA(. +The completed program then is compiled and executed. Variable +declarations that begin the )BD(funcalc)ES( expression are placed in +the local declaration section of the template main program. All other +lines are placed in the template main program's inner processing +loop. Other details of program generation are handled +automatically. For example, column specifiers are analyzed to build a +C struct for processing rows, which is passed to +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( and used +in )0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D(. If +an unknown variable is used in the expression, resulting in a +compilation error, the program build is retried after defining the +unknown variable to be of type double. + +)0 P(Normally, )BD(funcalc)ES( expression code is added to +)BD(funcalc)ES( row processing loop. It is possible to add code +to other parts of the program by placing this code inside +special directives of the form: +) 3 26 PR( [directive name] + ... code goes here ... + end)RP( + +The directives are: +)UL()-1 LI()BD(global)ES( add code and declarations in global space, before the main routine. + +)-1 LI()BD(local)ES( add declarations \201and code\202 just after the local declarations in +main + +)-1 LI()BD(before)ES( add code just before entering the main row processing loop + +)-1 LI()BD(after)ES( add code just after exiting the main row processing loop)LU( + +Thus, the following )BD(funcalc)ES( expression will declare global +variables and make subroutine calls just before and just after the +main processing loop: +) 16 62 PR( global + double v1, v2; + double init\201void\202; + double finish\201double v\202; + end + before + v1 = init\201\202; + end + ... process rows, with calculations using v1 ... + after + v2 = finish\201v1\202; + if\201 v2 < 0.0 \202{ + fprintf\201stderr, "processing failed %g -> %g\200n", v1, v2\202; + exit\2011\202; + } + end)RP( +Routines such as init\201\202 and finish\201\202 above are passed to the generated +program for linking using the )BD(-l [link directives ...])ES( +switch. The string specified by this switch will be added to the link +line used to build the program \201before the funtools library\202. For +example, assuming that init\201\202 and finish\201\202 are in the library +libmysubs.a in the /opt/special/lib directory, use: +) 1 47 PR( funcalc -l "-L/opt/special/lib -lmysubs" ...)RP( + +)0 P(User arguments can be passed to a compiled funcalc program using a string +argument to the "-a" switch. The string should contain all of the +user arguments. For example, to pass the integers 1 and 2, use: +) 1 22 PR( funcalc -a "1 2" ...)RP( +The arguments are stored in an internal array and are accessed as +strings via the ARGV\201n\202 macro. For example, consider the following +expression: +) 11 60 PR( local + int pmin, pmax; + end + + before + pmin=atoi\201ARGV\2010\202\202; + pmax=atoi\201ARGV\2011\202\202; + end + + if\201 \201cur->pha >= pmin\202 && \201cur->pha <= pmax\202 \202 + fprintf\201stderr, "%d %d %d\200n", cur->x, cur->y, cur->pha\202;)RP( +This expression will print out x, y, and pha values for all rows in which +the pha value is between the two user-input values: +) 11 51 PR( funcalc -a '1 12' -f foo snr.ev'[cir 512 512 .1]' + 512 512 6 + 512 512 8 + 512 512 5 + 512 512 5 + 512 512 8 + + funcalc -a '5 6' -f foo snr.ev'[cir 512 512 .1]' + 512 512 6 + 512 512 5 + 512 512 5)RP( + +)0 P(Note that it is the user's responsibility to ensure that the correct +number of arguments are passed. The ARGV\201n\202 macro returns a NULL if a +requested argument is outside the limits of the actual number of args, +usually resulting in a SEGV if processed blindly. To check the +argument count, use the ARGC macro: +) 12 42 PR( local + long int seed=1; + double limit=0.8; + end + + before + if\201 ARGC >= 1 \202 seed = atol\201ARGV\2010\202\202; + if\201 ARGC >= 2 \202 limit = atof\201ARGV\2011\202\202; + srand48\201seed\202; + end + + if \201 drand48\201\202 > limit \202 continue;)RP( + +)0 P(The macro WRITE_ROW expands to the FunTableRowPut\201\202 call that writes +the current row. It can be used to write the row more than once. In +addition, the macro NROW expands to the row number currently being +processed. Use of these two macros is shown in the following example: +) 7 41 PR( if\201 cur->pha:I == cur->pi:I \202 continue; + a = cur->pha; + cur->pha = cur->pi; + cur->pi = a; + cur->AVG:E = \201cur->pha+cur->pi\202/2.0; + cur->NR:I = NROW; + if\201 NROW < 10 \202 WRITE_ROW;)RP( + +)0 P(If the )BD(-p [prog])ES( switch is specified, the expression is not +executed. Rather, the generated executable is saved with the specified +program name for later use. + +)0 P(If the )BD(-n)ES( switch is specified, the expression is not +executed. Rather, the generated code is written to stdout. This is +especially useful if you want to generate a skeleton file and add your +own code, or if you need to check compilation errors. Note that the +comment at the start of the output gives the compiler command needed +to build the program on that platform. \201The command can change from +platform to platform because of the use of different libraries, +compiler switches, etc.\202 + +)0 P(As mentioned previously, )BD(funcalc)ES( will declare a scalar +variable automatically \201as a double\202 if that variable has been used +but not declared. This facility is implemented using a sed script +named )0 2 A(funcalc.sed)EA(, which processes the +compiler output to sense an undeclared variable error. This script +has been seeded with the appropriate error information for gcc, and for +cc on Solaris, DecAlpha, and SGI platforms. If you find that automatic +declaration of scalars is not working on your platform, check this sed +script; it might be necessary to add to or edit some of the error +messages it senses. + +)0 P(In order to keep the lexical analysis of )BD(funcalc)ES( expressions +\201reasonably\202 simple, we chose to accept some limitations on how +accurately C comments, spaces, and new-lines are placed in the +generated program. In particular, comments associated with local +variables declared at the beginning of an expression \201i.e., not in a +)BD(local...end)ES( block\202 will usually end up in the inner loop, not +with the local declarations: +) 8 69 PR( /* this comment will end up in the wrong place \201i.e, inner loop\202 */ + double a; /* also in wrong place */ + /* this will be in the the right place \201inner loop\202 */ + if\201 cur->x:D == cur->y:D \202 continue; /* also in right place */ + a = cur->x; + cur->x = cur->y; + cur->y = a; + cur->avg:E = \201cur->x+cur->y\202/2.0;)RP( +Similarly, spaces and new-lines sometimes are omitted or added in a +seemingly arbitrary manner. Of course, none of these stylistic +blemishes affect the correctness of the generated code. + +)0 P(Because )BD(funcalc)ES( must analyze the user expression using the data +file\201s\202 passed on the command line, the input file\201s\202 must be opened +and read twice: once during program generation and once during +execution. As a result, it is not possible to use stdin for the +input file: )BD(funcalc)ES( cannot be used as a filter. We will +consider removing this restriction at a later time. + +)0 P(Along with C comments, )BD(funcalc)ES( expressions can have one-line +internal comments that are not passed on to the generated C +program. These internal comment start with the )BD(#)ES( character and +continue up to the new-line: +) 7 56 PR( double a; # this is not passed to the generated C file + # nor is this + a = cur->x; + cur->x = cur->y; + cur->y = a; + /* this comment is passed to the C file */ + cur->avg:E = \201cur->x+cur->y\202/2.0;)RP( + +)0 P(As previously mentioned, input columns normally are identified by +their being used within the inner event loop. There are rare cases +where you might want to read a column and process it outside the main +loop. For example, qsort might use a column in its sort comparison +routine that is not processed inside the inner loop \201and therefore not +implicitly specified as a column to be read\202. To ensure that such a +column is read by the event loop, use the )BD(explicit)ES( keyword. +The arguments to this keyword specify columns that should be read into +the input record structure even though they are not mentioned in the +inner loop. For example: + ) 1 17 PR( explicit pi pha)RP( +will ensure that the pi and pha columns are read for each row, +even if they are not processed in the inner event loop. The )BD(explicit)ES( +statement can be placed anywhere. + +)0 P(Finally, note that )BD(funcalc)ES( currently works on expressions +involving FITS binary tables and raw event files. We will consider +adding support for image expressions at a later point, if there is +demand for such support from the community. + + + + +)0 2 7 H(funcen)WB 70 Sn()WB 4 Sn( - find centroid \201for binary tables\202)EA()EH( + +)BD() 1 56 PR(funcen [-i] [-n iter] [-t tol] [-v lev] <iname> <region>)RP()ES( + + +)0 P() 4 64 PR( -i # use image filtering \201default: event filtering\202 + -n iter # max number of iterations \201default: 0\202 + -t tol # pixel tolerance distance \201default: 1.0\202 + -v [0,1,2,3] # output verbosity level \201default: 0\202)RP( + + +)0 P()BD(funcen)ES( iteratively calculates the centroid position within one +or more regions of a Funtools table \201FITS binary table or raw event +file\202. Starting with an input table, an initial region specification, +and an iteration count, the program calculates the average x and y +position within the region and then uses this new position as the +region center for the next iteration. Iteration terminates when the +maximum number of iterations is reached or when the input tolerance +distance is met for that region. A count of events in the final region +is then output, along with the pixel position value \201and, where +available, WCS position\202. + +)0 P(The first argument to the program specifies the Funtools table file to +process. Since the file must be read repeatedly, a value of "stdin" +is not permitted when the number of iterations is non-zero. Use +)0 42 1 A(Funtools Bracket Notation)42 0 TN TL()Ec /AF f D( to specify FITS +extensions and filters. + +)0 P(The second required argument is the initial region descriptor. Multiple +regions are permitted. However, compound regions \201accelerators, +variable argument regions and regions connected via boolean algebra\202 +are not permitted. Points and polygons also are illegal. These +restrictions might be lifted in a future version, if warranted. + +)0 P(The )BD(-n)ES( \201iteration number\202 switch specifies the maximum number of +iterations to perform. The default is 0, which means that the program will +simply count and display the number of events in the initial region\201s\202. +Note that when iterations is 0, the data can be input via stdin. + +)0 P(The )BD(-t)ES( \201tolerance\202 switch specifies a floating point tolerance +value. If the distance between the current centroid position value and +the last position values is less than this value, iteration terminates. +The default value is 1 pixel. + +)0 P(The )BD(-v)ES( \201verbosity\202 switch specifies the verbosity level of the +output. The default is 0, which results in a single line of output for +each input region consisting of the following values: +) 1 30 PR( counts x y [ra dec coordsys])RP( +The last 3 WCS values are output if WCS information is available in the +data file header. Thus, for example: +) 5 47 PR( [sh] funcen -n 0 snr.ev "cir 505 508 5" + 915 505.00 508.00 345.284038 58.870920 j2000 + + [sh] funcen -n 3 snr.ev "cir 505 508 5" + 1120 504.43 509.65 345.286480 58.874587 j2000)RP( +The first example simply counts the number of events in the initial region. +The second example iterates the centroid calculation three times to determine +a final "best" position. + +)0 P( +Higher levels of verbosity obviously imply more verbose output. At +level 1, the output essentially contains the same information as level +0, but with keyword formatting: + + [sh] funcen -v 1 -n 3 snr.ev "cir 505 508 5" + event_file: snr.ev + initial_region: cir 505 508 5 + tolerance: 1.0000 + iterations: 1 + + events: 1120 + x,y\201physical\202: 504.43 509.65 + ra,dec\201j2000\202: 345.286480 58.874587 + final_region1: cir 504.43 509.65 5)RP( +Level 2 outputs results from intermediate calculations as well. + +)0 P(Ordinarily, region filtering is performed using analytic \201event\202 +filtering, i.e. that same style of filtering as is performed by +)BD(fundisp)ES( and )BD(funtable)ES(. Use the )BD(-i)ES( switch to specify image +filtering, i.e. the same style filtering as is performed by )BD(funcnts)ES(. +Thus, you can perform a quick calculation of counts in regions, using +either the analytic or image filtering method, by specifying the + )BD(-n 0)ES( and optional )BD(-i)ES( switches. These two method often +give different results because of how boundary events are processed: +) 5 46 PR( [sh] funcen snr.ev "cir 505 508 5" + 915 505.00 508.00 345.284038 58.870920 j2000 + + [sh] funcen -i snr.ev "cir 505 508 5" + 798 505.00 508.00 345.284038 58.870920 j2000)RP( +See )0 58 1 A(Region Boundaries)58 0 TN TL()Ec /AF f D( for more information +about how boundaries are calculated using these two methods. + + + + +)0 2 8 H(funcnts)WB 71 Sn()WB 5 Sn( - count photons in specified regions, with bkgd subtraction)EA()EH( + + +)BD() 1 86 PR(funcnts [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_value])RP()ES( + + +)0 P() 16 79 PR( -e "source_exposure[;bkgd_exposure]" + # source \201bkgd\202 FITS exposure image using matching files + -w "source_exposure[;bkgd_exposure]" + # source \201bkgd\202 FITS exposure image using WCS transform + -t "source_timecorr[;bkgd_timecorr]" + # source \201bkgd\202 time correction value or header parameter name + -g # output using nice g format + -G # output using %.14g format \201maximum precision\202 + -i "[column;]int1;int2..." # column-based intervals + -m # match individual source and bkgd regions + -p # output in pixels, even if wcs is present + -r # output inner/outer radii \201and angles\202 for annuli \201and pandas\202 + -s # output summed values + -v "scol[;bcol]" # src and bkgd value columns for tables + -T # output in starbase/rdb format + -z # output regions with zero area)ES()RP( + + +)0 P()BD(funcnts)ES( counts photons in the specified source regions and +reports the results for each region. Regions are specified using the +)0 54 1 A(Spatial Region Filtering)54 0 TN TL()Ec /AF f D( mechanism. +Photons are also counted in the specified bkgd regions applied to the +same data file or a different data file. \201Alternatively, a constant +background value in counts/pixel**2 can be specified.\202 The bkgd regions +are either paired one-to-one with source regions or pooled and +normalized by area, and then subtracted from the source counts in each +region. Displayed results include the bkgd-subtracted counts in each +region, as well as the error on the counts, the area in +each region, and the surface brightness \201cnts/area**2\202 calculated for +each region. + +)0 P(The first argument to the program specifies the FITS input image, array, or +raw event file to process. If "stdin" is specified, data are read from +the standard input. Use )0 42 1 A(Funtools Bracket +Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions, image sections, and filters. + +)0 P(The optional second argument is the source region descriptor. If no +region is specified, the entire field is used. + +)0 P(The background arguments can take one of two forms, depending on +whether a separate background file is specified. If the source +file is to be used for background as well, the third argument can be +either the background region, or a constant value denoting background +cnts/pixel. Alternatively, the third argument can be a background +data file, in which case the fourth argument is the background region. +If no third argument is specified, a constant value of 0 is used +\201i.e., no background\202. + +)0 P(In summary, the following command arguments are valid: +) 5 77 PR( [sh] funcnts sfile # counts in source file + [sh] funcnts sfile sregion # counts in source region + [sh] funcnts sfile sregion bregion # bkgd reg. is from source file + [sh] funcnts sfile sregion bvalue # bkgd reg. is constant + [sh] funcnts sfile sregion bfile bregion # bkgd reg. is from separate file)RP( + +)0 P(NB: unlike other Funtools programs, source and background regions are +specified as separate arguments on the command line, rather than being +placed inside brackets as part of the source and background filenames. +This is because regions in funcnts are not simply used as data +filters, but also are used to calculate areas, exposure, etc. If you +put the source region inside the brackets \201i.e. use it simply as a +filter\202 rather than specifying it as argument two, the program still +will only count photons that pass the region filter. However, the area +calculation will be performed on the whole field, since field\201\202 is the +default source region. This rarely is the desired behavior. On the +other hand, with FITS binary tables, it often is useful to put a column +filter in the filename brackets, so that only events matching the +column filter are counted inside the region. + +)0 P(For example, to extract the counts within a radius of 22 pixels from the +center of the FITS binary table snr.ev and subtract the background determined +from the same image within an annulus of radii 50-100 pixels: +) 33 82 PR( [sh] funcnts snr.ev "circle\201502,512,22\202" "annulus\201502,512,50,100\202" + # source + # data file: snr.ev + # degrees/pix: 0.00222222 + # background + # data file: snr.ev + # column units + # area: arcsec**2 + # surf_bri: cnts/arcsec**2 + # surf_err: cnts/arcsec**2 + + # background-subtracted results + reg net_counts error background berror area surf_bri surf_err + ---- ------------ --------- ------------ --------- --------- --------- --------- + 1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001 + + + # the following source and background components were used: + source region\201s\202 + ---------------- + circle\201502,512,22\202 + + reg counts pixels + ---- ------------ --------- + 1 4382.000 1513 + + background region\201s\202 + -------------------- + annulus\201502,512,50,100\202 + + reg counts pixels)WR( + ---- ------------ --------- + all 8656.000 23572)RP( +The area units for the output columns labeled "area", "surf_bri" +\201surface brightness\202 and "surf_err" will be given either in +arc-seconds \201if appropriate WCS information is in the data file +header\201s\202\202 or in pixels. If the data file has WCS info, but you do not +want arc-second units, use the )BD(-p)ES( switch to force output in +pixels. Also, regions having zero area are not normally included in +the primary \201background-subtracted\202 table, but are included in the +secondary source and bkgd tables. If you want these regions to be +included in the primary table, use the )BD(-z)ES( switch. + +)0 P(Note that a simple sed command will extract the background-subtracted results +for further analysis: +) 6 79 PR( [sh] cat funcnts.sed + 1,/---- .*/d + /^$/,$d + + [sh] sed -f funcnts.sed funcnts.out + 1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001)RP( + +)0 P(If separate source and background files are specified, )BD(funcnts)ES( will +attempt to normalize the the background area so that the background +pixel size is the same as the source pixel size. This normalization +can only take place if the appropriate WCS information is contained in +both files \201e.g. degrees/pixel values in CDELT\202. If either +file does not contain the requisite size information, the normalization +is not performed. In this case, it is the user's responsibility to +ensure that the pixel sizes are the same for the two files. + +)0 P(Normally, if more than one background region is specified, )BD(funcnts)ES( +will combine them all into a single region and use this background +region to produce the background-subtracted results for each source +region. The )BD(-m)ES( \201match multiple backgrounds\202 switch tells +)BD(funcnts)ES( to make a one to one correspondence between background and +source regions, instead of using a single combined background region. +For example, the default case is to combine 2 background +regions into a single region and then apply that region to each of the +source regions: + +) 35 82 PR( [sh] funcnts snr.ev "annulus\201502,512,0,22,n=2\202" "annulus\201502,512,50,100,n=2\202" + # source + # data file: snr.ev + # degrees/pix: 0.00222222 + # background + # data file: snr.ev + # column units + # area: arcsec**2 + # surf_bri: cnts/arcsec**2 + # surf_err: cnts/arcsec**2 + + # background-subtracted results + reg net_counts error background berror area surf_bri surf_err + ---- ------------ --------- ------------ --------- --------- --------- --------- + 1 3101.029 56.922 136.971 1.472 23872.00 0.130 0.002 + 2 725.375 34.121 418.625 4.500 72959.99 0.010 0.000 + + + # the following source and background components were used: + source region\201s\202 + ---------------- + annulus\201502,512,0,22,n=2\202 + + reg counts pixels + ---- ------------ --------- + 1 3238.000 373 + 2 1144.000 1140 + + background region\201s\202 + -------------------- + annulus\201502,512,50,100,n=2\202)WR( + + reg counts pixels + ---- ------------ --------- + all 8656.000 23572)RP( +Note that the basic region filter rule "each photon is counted once +and no photon is counted more than once" still applies when using The +)BD(-m)ES( to match background regions. That is, if two background +regions overlap, the overlapping pixels will be counted in only one of +them. In a worst-case scenario, if two background regions are the same +region, the first will get all the counts and area and the second +will get none. + +)0 P(Using the )BD(-m)ES( switch causes )BD(funcnts)ES( to use each of the two +background regions independently with each of the two source regions: + +) 36 82 PR( [sh] funcnts -m snr.ev "annulus\201502,512,0,22,n=2\202" "ann\201502,512,50,100,n=2\202" + # source + # data file: snr.ev + # degrees/pix: 0.00222222 + # background + # data file: snr.ev + # column units + # area: arcsec**2 + # surf_bri: cnts/arcsec**2 + # surf_err: cnts/arcsec**2 + + # background-subtracted results + reg net_counts error background berror area surf_bri surf_err + ---- ------------ --------- ------------ --------- --------- --------- --------- + 1 3087.015 56.954 150.985 2.395 23872.00 0.129 0.002 + 2 755.959 34.295 388.041 5.672 72959.99 0.010 0.000 + + + # the following source and background components were used: + source region\201s\202 + ---------------- + annulus\201502,512,0,22,n=2\202 + + reg counts pixels + ---- ------------ --------- + 1 3238.000 373 + 2 1144.000 1140 + + background region\201s\202 + -------------------- + ann\201502,512,50,100,n=2\202)WR( + + reg counts pixels + ---- ------------ --------- + 1 3975.000 9820 + 2 4681.000 13752)RP( + +)0 P(Note that most floating point quantities are displayed using "f" +format. You can change this to "g" format using the )BD(-g)ES( +switch. This can be useful when the counts in each pixel is very +small or very large. If you want maximum precision and don't care +about the columns lining up nicely, use )BD(-G)ES(, which outputs +all floating values as %.14g. + +)0 P(When counting photons using the annulus and panda \201pie and annuli\202 +shapes, it often is useful to have access to the radii \201and panda +angles\202 for each separate region. The )BD(-r)ES( switch will add radii +and angle columns to the output table: + +) 37 122 PR( [sh] funcnts -r snr.ev "annulus\201502,512,0,22,n=2\202" "ann\201502,512,50,100,n=2\202" + # source + # data file: snr.ev + # degrees/pix: 0.00222222 + # background + # data file: snr.ev + # column units + # area: arcsec**2 + # surf_bri: cnts/arcsec**2 + # surf_err: cnts/arcsec**2 + # radii: arcsecs + # angles: degrees + + # background-subtracted results + reg net_counts error background berror area surf_bri surf_err radius1 radius2 angle1 angle2 + ---- ------------ --------- ------------ --------- --------- --------- --------- --------- --------- --------- --------- + 1 3101.029 56.922 136.971 1.472 23872.00 0.130 0.002 0.00 88.00 NA NA + 2 725.375 34.121 418.625 4.500 72959.99 0.010 0.000 88.00 176.00 NA NA + + + # the following source and background components were used: + source region\201s\202 + ---------------- + annulus\201502,512,0,22,n=2\202 + + reg counts pixels + ---- ------------ --------- + 1 3238.000 373 + 2 1144.000 1140 + + background region\201s\202)WR( + -------------------- + ann\201502,512,50,100,n=2\202 + + reg counts pixels + ---- ------------ --------- + all 8656.000 23572)RP( + +)0 P(Radii are given in units of pixels or arc-seconds \201depending on the +presence of WCS info\202, while the angle values \201when present\202 are in +degrees. These columns can be used to plot radial profiles. For +example, the script )BD(funcnts.plot)ES( in the funtools +distribution\202 will plot a radial profile using gnuplot \201version 3.7 or +above\202. A simplified version of this script is shown below: + +) 74 79 PR( #!/bin/sh + + if [ x"$1" = xgnuplot ]; then + if [ x`which gnuplot 2>/dev/null` = x ]; then + echo "ERROR: gnuplot not available" + exit 1 + fi + awk ' + BEGIN{HEADER=1; DATA=0; FILES=""; XLABEL="unknown"; YLABEL="unknown"} + HEADER==1{ + if\201 $1 == "#" && $2 == "data" && $3 == "file:" \202{ + if\201 FILES != "" \202 FILES = FILES "," + FILES = FILES $4 + } + else if\201 $1 == "#" && $2 == "radii:" \202{ + XLABEL = $3 + } + else if\201 $1 == "#" && $2 == "surf_bri:" \202{ + YLABEL = $3 + } + else if\201 $1 == "----" \202{ + printf "set nokey; set title \200"funcnts\201%s\202\200"\200n", FILES + printf "set xlabel \200" radius\201%s\202\200"\200n", XLABEL + printf "set ylabel \200"surf_bri\201%s\202\200"\200n", YLABEL + print "plot \200"-\200" using 3:4:6:7:8 with boxerrorbars" + HEADER = 0 + DATA = 1 + next + } + } + DATA==1{)WR( + if\201 NF == 12 \202{ + print $9, $10, \201$9+$10\202/2, $7, $8, $7-$8, $7+$8, $10-$9 + } + else{ + exit + } + } + ' | gnuplot -persist - 1>/dev/null 2>&1 + + elif [ x"$1" = xds9 ]; then + awk ' + BEGIN{HEADER=1; DATA=0; XLABEL="unknown"; YLABEL="unknown"} + HEADER==1{ + if\201 $1 == "#" && $2 == "data" && $3 == "file:" \202{ + if\201 FILES != "" \202 FILES = FILES "," + FILES = FILES $4 + } + else if\201 $1 == "#" && $2 == "radii:" \202{ + XLABEL = $3 + } + else if\201 $1 == "#" && $2 == "surf_bri:" \202{ + YLABEL = $3 + } + else if\201 $1 == "----" \202{ + printf "funcnts\201%s\202 radius\201%s\202 surf_bri\201%s\202 3\200n", FILES, XLABEL, YLABEL + HEADER = 0 + DATA = 1 + next + } + })WR( + DATA==1{ + if\201 NF == 12 \202{ + print $9, $7, $8 + } + else{ + exit + } + } + ' + else + echo "funcnts -r ... | funcnts.plot [ds9|gnuplot]" + exit 1 + fi)RP( + +Thus, to run )BD(funcnts)ES( and plot the results using gnuplot \201version 3.7 +or above\202, use: +) 1 75 PR( funcnts -r snr.ev "annulus\201502,512,0,50,n=5\202" ... | funcnts.plot gnuplot)RP( + +)0 P(The )BD(-s)ES( \201sum\202 switch causes )BD(funcnts)ES( to produce an +additional table of summed \201integrated\202 background subtracted values, +along with the default table of individual values: + +) 51 82 PR( [sh] funcnts -s snr.ev "annulus\201502,512,0,50,n=5\202" "annulus\201502,512,50,100\202" + # source + # data file: snr.ev + # degrees/pix: 0.00222222 + # background + # data file: snr.ev + # column units + # area: arcsec**2 + # surf_bri: cnts/arcsec**2 + # surf_err: cnts/arcsec**2 + + # summed background-subtracted results + upto net_counts error background berror area surf_bri surf_err + ---- ------------ --------- ------------ --------- --------- --------- --------- + 1 2880.999 54.722 112.001 1.204 19520.00 0.148 0.003 + 2 3776.817 65.254 457.183 4.914 79679.98 0.047 0.001 + 3 4025.492 71.972 1031.508 11.087 179775.96 0.022 0.000 + 4 4185.149 80.109 1840.851 19.786 320831.94 0.013 0.000 + 5 4415.540 90.790 2873.460 30.885 500799.90 0.009 0.000 + + + # background-subtracted results + reg counts error background berror area surf_bri surf_err + ---- ------------ --------- ------------ --------- --------- --------- --------- + 1 2880.999 54.722 112.001 1.204 19520.00 0.148 0.003 + 2 895.818 35.423 345.182 3.710 60159.99 0.015 0.001 + 3 248.675 29.345 574.325 6.173 100095.98 0.002 0.000 + 4 159.657 32.321 809.343 8.699 141055.97 0.001 0.000 + 5 230.390 37.231 1032.610 11.099 179967.96 0.001 0.000 + + )WR( + # the following source and background components were used: + source region\201s\202 + ---------------- + annulus\201502,512,0,50,n=5\202 + + reg counts pixels sumcnts sumpix + ---- ------------ --------- ------------ --------- + 1 2993.000 305 2993.000 305 + 2 1241.000 940 4234.000 1245 + 3 823.000 1564 5057.000 2809 + 4 969.000 2204 6026.000 5013 + 5 1263.000 2812 7289.000 7825 + + background region\201s\202 + -------------------- + annulus\201502,512,50,100\202 + + reg counts pixels + ---- ------------ --------- + all 8656.000 23572)RP( + +)0 P(The )BD(-t)ES( and )BD(-e)ES( switches can be used to apply timing and +exposure corrections, respectively, to the data. Please note that +these corrections are meant to be used qualitatively, since +application of more accurate correction factors is a complex and +mission-dependent effort. The algorithm for applying these simple +corrections is as follows: +) 9 63 PR( C = Raw Counts in Source Region + Ac= Area of Source Region + Tc= Exposure time for Source Data + Ec= Average exposure in Source Region, from exposure map + + B= Raw Counts in Background Region + Ab= Area of Background Region + Tb= \201Exposure\202 time for Background Data + Eb= Average exposure in Background Region, from exposure map)RP( +Then, Net Counts in Source region is +) 1 37 PR( Net= C - B * \201Ac*Tc*Ec\202/\201Ab*Tb*Eb\202)RP( +with the standard propagation of errors for the Error on Net. +The net rate would then be +) 1 27 PR( Net Rate = Net/\201Ac*Tc*Ec\202)RP( +The average exposure in each region is calculated by summing up the +pixel values in the exposure map for the given region and then +dividing by the number of pixels in that region. Exposure maps often +are generated at a block factor > 1 \201e.g., block 4 means that each +exposure pixel contains 4x4 pixels at full resolution\202 and +)BD(funcnts)ES( will deal with the blocking automatically. Using the +)BD(-e)ES( switch, you can supply both source and background exposure +files \201separated by ";"\202, if you have separate source and background +data files. If you do not supply a background exposure file to go with +a separate background data file, )BD(funcnts)ES( assumes that exposure +already has been applied to the background data file. In addition, it +assumes that the error on the pixels in the background data file is +zero. + +)0 P(NB: The )BD(-e)ES( switch assumes that the exposure map overlays the +image file )BD(exactly)ES(, except for the block factor. Each pixel in +the image is scaled by the block factor to access the corresponding +pixel in the exposure map. If your exposure map does not line up +exactly with the image, )BD(do not use)ES( the )BD(-e)ES( exposure +correction. In this case, it still is possible to perform exposure +correction )BD(if)ES( both the image and the exposure map have valid +WCS information: use the )BD(-w)ES( switch so that the transformation +from image pixel to exposure pixel uses the WCS information. That is, +each pixel in the image region will be transformed first from image +coordinates to sky coordinates, then from sky coordinates to exposure +coordinates. Please note that using )BD(-w)ES( can increase the time +required to process the exposure correction considerably. + +)0 P(A time correction can be applied to both source and +background data using the )BD(-t)ES( switch. The value for the correction can +either be a numeric constant or the name of a header parameter in +the source \201or background\202 file: +) 2 74 PR( [sh] funcnts -t 23.4 ... # number for source + [sh] funcnts -t "LIVETIME;23.4" ... # param for source, numeric for bkgd)RP( +When a time correction is specified, it is applied to the net counts +as well \201see algorithm above\202, so that the units of surface brightness +become cnts/area**2/sec. + +)0 P(The )BD(-i)ES( \201interval\202 switch is used to run )BD(funcnts)ES( on multiple +column-based intervals with only a single pass through the data. It is +equivalent to running )BD(funcnts)ES( several times with a different column +filter added to the source and background data each time. For each +interval, the full )BD(funcnts)ES( output is generated, with a linefeed +character \201^L\202 inserted between each run. In addition, the output for +each interval will contain the interval specification in its header. +Intervals are very useful for generating X-ray hardness ratios +efficiently. Of course, they are only supported when the input data +are contained in a table. + +)0 P(Two formats are supported for interval specification. The most general +format is semi-colon-delimited list of filters to be used as intervals: +) 1 73 PR( funcnts -i "pha=1:5;pha=6:10;pha=11:15" snr.ev "circle\201502,512,22\202" ...)RP( +Conceptually, this will be equivalent to running )BD(funcnts)ES( three times: +) 3 50 PR( funcnts snr.ev'[pha=1:5]' "circle\201502,512,22\202" + funcnts snr.ev'[pha=6:10]' "circle\201502,512,22\202" + funcnts snr.ev'[pha=11:15]' "circle\201502,512,22\202")RP( +However, using the )BD(-i)ES( switch will require only one pass through +the data. + +)0 P(Note that complex filters can be used to specify intervals: +) 1 64 PR( funcnts -i "pha=1:5&)SY(\160)ES(=4;pha=6:10&)SY(\160)ES(=5;pha=11:15&)SY(\160)ES(=6" snr.ev ...)RP( +The program simply runs the data through each filter in turn and generates +three )BD(funcnts)ES( outputs, separated by the line-feed character. + +)0 P(In fact, although the intent is to support intervals for hardness ratios, +the specified filters do not have to be intervals at all. Nor does one +"interval" filter have to be related to another. For example: +) 1 75 PR( funcnts -i "pha=1:5;pi=6:10;energy=11:15" snr.ev "circle\201502,512,22\202" ...)RP( +is equivalent to running )BD(funcnts)ES( three times with unrelated filter +specifications. + +)0 P(A second interval format is supported for the simple case in which a +single column is used to specify multiple homogeneous intervals for +that column. In this format, a column name is specified first, +followed by intervals: +) 1 65 PR( funcnts -i "pha;1:5;6:10;11:15" snr.ev "circle\201502,512,22\202" ...)RP( +This is equivalent to the first example, but requires less typing. The +)BD(funcnts)ES( program will simply prepend "pha=" before each of the specified +intervals. \201Note that this format does not contain the "=" character in +the column argument.\202 + +)0 P(Ordinarily, when )BD(funcnts)ES( is run on a FITS binary table \201or a +raw event table\202, one integral count is accumulated for each row +\201event\202 contained within a given region. The )BD(-v "scol[;bcol]")ES( +\201value column\202 switch will accumulate counts using the value from the +specified column for the given event. If only a single column is +specified, it is used for both the source and background regions. Two +separate columns, separated by a semi-colon, can be specified for source +and background. The special token '$none' can be used to specify that +a value column is to be used for one but not the other. For example, +'pha;$none' will use the pha column for the source but use integral +counts for the background, while '$none;pha' will do the converse. +If the value column is of type logical, then the value used will be 1 +for T and 0 for F. Value columns are used, for example, to integrate +probabilities instead of integral counts. + +)0 P(If the )BD(-T)ES( \201rdb table\202 switch is used, the output will conform +to starbase/rdb data base format: tabs will be inserted between +columns rather than spaces and line-feed will be inserted between +tables. + +)0 P(Finally, note that )BD(funcnts)ES( is an image program, even though it +can be run directly on FITS binary tables. This means that image +filtering is applied to the rows in order to ensure that the same +results are obtained regardless of whether a table or the equivalent +binned image is used. Because of this, however, the number of counts +found using )BD(funcnts)ES( can differ from the number of events found +using row-filter programs such as )BD(fundisp)ES( or )BD(funtable)ES( +For more information about these difference, see the discussion of +)0 58 1 A(Region Boundaries)58 0 TN TL()Ec /AF f D(. + + + + +)0 2 9 H(funcone)WB 72 Sn()WB 6 Sn( - cone search of a binary table containing RA, Dec columns)EA()EH( + + +)BD() 1 81 PR(funcone <switches> <iname> <oname> <ra[hdr]> <dec[hdr]> <radius[dr'"]> [columns])RP()ES( + + +)0 P() 9 84 PR( -d deccol:[hdr] # Dec column name, units \201def: DEC:d\202 + -j # join columns from list file + -J # join columns from list file, output all rows + -l listfile # read centers and radii from a list + -L listfile # read centers and radii from a list, output list rows + -n # don't use cone limits as a filter + -r racol:[hdr] # RA column name, units \201def: RA:h\202 + -x # append RA_CEN, DEC_CEN, RAD_CEN, CONE_KEY cols + -X # append RA_CEN, DEC_CEN, RAD_CEN, CONE_KEY cols, output all rows)RP( + + +)0 P(Funcone performs a cone search on the RA and Dec columns of a FITS +binary table. The distance from the center RA, Dec position to the RA, +Dec in each row in the table is calculated. Rows whose distance is +less than the specified radius are output. + +)0 P(The first argument to the program specifies the FITS file, raw event +file, or raw array file. If "stdin" is specified, data are read from +the standard input. Use )0 42 1 A(Funtools Bracket +Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions, and filters. The second +argument is the output FITS file. If "stdout" is specified, the FITS +binary table is written to the standard output. + +)0 P( +The third and fourth required arguments are the RA and Dec center +position. By default, RA is specified in hours while Dec is specified +in degrees. You can change the units of either of these by appending +the character "d" \201degrees\202, "h" \201hours\202 or "r" \201radians\202. Sexagesimal +notation is supported, with colons or spaces separating hms and dms. +\201When using spaces, please ensure that the entire string is quoted.\202 + +)0 P(The fifth required argument is the radius of the cone search. By default, +the radius value is given in degrees. The units can be changed by appending +the character "d" \201degrees\202, "r" \201radians\202, "'" \201arc minutes\202 or +'"' \201arc seconds\202. + +)0 P(By default, all +columns of the input file are copied to the output file. Selected +columns can be output using an optional sixth argument in the form: +) 1 31 PR( "column1 column1 ... columnN")RP( +A seventh argument allows you to output selected columns from the list +file when )BD(-j)ES( switch is used. Note that the RA and Dec columns +used in the cone calculation must not be de-selected. + +)0 P(Also by default, the RA and Dec column names are named "RA" and "Dec", +and are given in units of hours and degrees respectively. You can +change both the name and the units using the -r [RA] and/or -d [Dec] +switches. Once again, one of "h", "d", or "r" is appended to the +column name to specify units but in this case, there must be a colon ":" +between the name and the unit specification. + +)0 P(If the )BD(-l [listfile])ES( switch is used, then one or more of the +center RA, center Dec, and radius can be taken from a list file \201which +can be a FITS table or an ASCII column text file\202. In this case, the +third \201center RA\202, fourth \201center Dec\202, and fifth \201radius\202 command +line arguments can either be a column name in the list file \201if that +parameter varies\202 or else a numeric value \201if that parameter is +static\202. When a column name is specified for the RA, Dec, or radius, +you can append a colon followed by "h", "d", or "r" to specify units +\201also ' and " for radius\202. The cone search algorithm is run once for +each row in the list, taking RA, Dec, and radius values from the +specified columns or from static numeric values specified on the +command line. + +)0 P(When using a list, all valid rows from each iteration are written to a +single output file. Use the )BD(-x)ES( switch to help delineate which +line of the list file was used to produce the given output row\201s\202. +This switch causes the values for the center RA, Dec, radius, and row +number to be appended to the output file, in columns called RA_CEN, +DEC_CEN, RAD_CEN and CONE_KEY, respectively. Alternatively, the +)BD(-j)ES( \201join\202 switch will append all columns from the list row to +the output row \201essentially a join of the list row and input row\202, +along with the CONE_KEY row number. These two switches are mutually +exclusive. + +)0 P(The )BD(-X)ES( and )BD(-J)ES( switches write out the same data as their +lower case counterparts for each row satisfying a cone search. In +addition, these switches also write out rows from the event file that +do not satisfy any cone search. In such cases, that CONE_KEY column +will be given a value of -1 and the center and list position information +will be set to zero for the given row. Thus, all rows of the input +event file are guaranteed to be output, with rows satisfying at least +one cone search having additional search information. + +)0 P(The )BD(-L)ES( switch acts similarly to the )BD(-l)ES( switch in that it +takes centers from a list file. However, it also implicitly sets the +-j switch, so that output rows are the join of the input event row and +the center position row. In addition, this switch also writes out all +center position rows for which no event satisfies the cone search +criteria of that row. The CONE_KEY column will be given a value of -2 +for center rows that were not close to any data row and the event +columns will be zeroed out for such rows. In this way, all centers +rows are guaranteed to be output at least once. + +)0 P(If any of "all row" switches \201)BD(-X)ES(, )BD(-J)ES(, or )BD(-L)ES(\202 are +specified, then a new column named JSTAT is added to the output table. +The positive values in this column indicate the center position row number +\201starting from 1\202 in the list file that this data row successful matched +in a cone search. A value of -1 means that the data row did not match +any center position. A value of -2 means that the center position was +not matched by any data row. + +)0 P(Given a center position and radius, the cone search algorithm +calculates limit parameters for a box enclosing the specified cone, +and only tests rows whose positions values lie within those limits. +For small files, the overhead associated with this cone limit +filtering can cause the program to run more slowly than if all events +were tested. You can turn off cone limit filtering using the )BD(-n)ES( +switch to see if this speeds up the processing \201especially useful when +processing a large list of positions\202. + +)0 P(For example, the default cone search uses columns "RA" and "Dec" in hours +and degrees \201respectively\202 and RA position in hours, Dec and radius in degrees: +) 1 42 PR( funone in.fits out.fits 23.45 34.56 0.01)RP( +To specify the RA position in degrees: +) 1 44 PR( funcone in.fits out.fits 23.45d 34.56 0.01)RP( +To get RA and Dec from a list but use a static value for radius \201and +also write identifying info for each row in the list\202: +) 1 57 PR( funcone -x -l list.txt in.fits out.fits MYRA MYDec 0.01)RP( +User specified columns in degrees, RA position in hours \201sexagesimal +notation\202, Dec position in degrees \201sexagesimal notation\202 and radius +in arc minutes: +) 1 66 PR( funcone -r myRa:d -d myDec in.fits out.fits 12:30:15.5 30:12 15')RP( + + + + +)0 2 10 H(fundisp)WB 73 Sn()WB 7 Sn( - display data in a Funtools data file)EA()EH( + + +)BD() 1 62 PR(fundisp [-f format] [-l] [-n] [-T] <iname> [columns|bitpix=n])RP()ES( + + +)0 P() 5 68 PR( -f # format string for display + -l # display image as a list containing the columns X, Y, VAL + -n # don't output header + -F [c] # use specified character as column separator \201def: space\202 + -T # output in rdb/starbase format \201tab separators\202)RP( + + +)0 P()BD(fundisp)ES( displays the data in the specified +)0 42 1 A(FITS Extension)42 0 TN TL()Ec /AF f D( +and/or +)0 49 1 A(Image Section)49 0 TN TL()Ec /AF f D( +of a FITS file, or in a +)0 49 1 A(Section)49 0 TN TL()Ec /AF f D( +of a non-FITS array or raw event file. +)0 P(The first argument to the program specifies the FITS input image, array, or +raw event file to display. If "stdin" is specified, data are read from +the standard input. Use )0 42 1 A(Funtools Bracket +Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions, image sections, and filters. + +)0 P(If the data being displayed are columns \201either in a FITS binary table +or a raw event file\202, the individual rows are listed. Filters can be +added using bracket notation. Thus: +) 13 75 PR( [sh] fundisp "test.ev[time-\201int\202time>.15]" + X Y PHA PI TIME DX DY + ------- ------- ------- --------- ---------------- ---------- ---------- + 10 8 10 8 17.1600 8.50 10.50 + 9 9 9 9 17.1600 9.50 9.50 + 10 9 10 9 18.1600 9.50 10.50 + 10 9 10 9 18.1700 9.50 10.50 + 8 10 8 10 17.1600 10.50 8.50 + 9 10 9 10 18.1600 10.50 9.50 + 9 10 9 10 18.1700 10.50 9.50 + 10 10 10 10 19.1600 10.50 10.50 + 10 10 10 10 19.1700 10.50 10.50 + 10 10 10 10 19.1800 10.50 10.50)RP( +[NB: The FITS binary table test file test.ev, as well as the FITS +image test.fits, are contained in the funtools funtest directory.] + +)0 P(When a table is being displayed using )BD(fundisp)ES(, a second optional +argument can be used to specify the columns to display. For example: +) 12 56 PR( [sh] fundisp "test.ev[time-\201int\202time>=.99]" "x y time" + X Y TIME + -------- -------- --------------------- + 5 -6 40.99000000 + 4 -5 59.99000000 + -1 0 154.99000000 + -2 1 168.99000000 + -3 2 183.99000000 + -4 3 199.99000000 + -5 4 216.99000000 + -6 5 234.99000000 + -7 6 253.99000000)RP( + +)0 P(The special column )BD($REGION)ES( can be specified to display the +region id of each row: +) 12 89 PR( [sh $] fundisp "test.ev[time-\201int\202time>=.99&&annulus\2010 0 0 10 n=3\202]" 'x y time $REGION' + X Y TIME REGION + -------- -------- --------------------- ---------- + 5 -6 40.99000000 3 + 4 -5 59.99000000 2 + -1 0 154.99000000 1 + -2 1 168.99000000 1 + -3 2 183.99000000 2 + -4 3 199.99000000 2 + -5 4 216.99000000 2 + -6 5 234.99000000 3 + -7 6 253.99000000 3)RP( +)0 P(Here only rows with the proper fractional time and whose position also is +within one of the three annuli are displayed. +)0 P(Columns can be excluded from display using a minus sign before the +column: +) 12 64 PR( [sh $] fundisp "test.ev[time-\201int\202time>=.99]" "-time" + X Y PHA PI DX DY + -------- -------- -------- ---------- ----------- ----------- + 5 -6 5 -6 5.50 -6.50 + 4 -5 4 -5 4.50 -5.50 + -1 0 -1 0 -1.50 0.50 + -2 1 -2 1 -2.50 1.50 + -3 2 -3 2 -3.50 2.50 + -4 3 -4 3 -4.50 3.50 + -5 4 -5 4 -5.50 4.50 + -6 5 -6 5 -6.50 5.50 + -7 6 -7 6 -7.50 6.50)RP( +All columns except the time column are displayed. +)0 P(The special column )BD($N)ES( can be specified to display the +ordinal value of each row. Thus, continuing the previous example: +) 12 74 PR( fundisp "test.ev[time-\201int\202time>=.99]" '-time $n' + X Y PHA PI DX DY N + ------- -------- -------- ---------- ----------- ----------- ---------- + 5 -6 5 -6 5.50 -6.50 337 + 4 -5 4 -5 4.50 -5.50 356 + -1 0 -1 0 -1.50 0.50 451 + -2 1 -2 1 -2.50 1.50 465 + -3 2 -3 2 -3.50 2.50 480 + -4 3 -4 3 -4.50 3.50 496 + -5 4 -5 4 -5.50 4.50 513 + -6 5 -6 5 -6.50 5.50 531 + -7 6 -7 6 -7.50 6.50 550)RP( +Note that the column specification is enclosed in single quotes to protect +'$n' from begin expanded by the shell. + +)0 P(In general, the rules for activating and de-activating columns are: +)UL()-1 LI( If only exclude columns are specified, then all columns but +the exclude columns will be activated. +)-1 LI( If only include columns are specified, then only the specified columns +are activated. +)-1 LI( If a mixture of include and exclude columns are specified, then +all but the exclude columns will be active; this last case +is ambiguous and the rule is arbitrary.)LU( +In addition to specifying columns names explicitly, the special +symbols )BD(+)ES( and )BD(-)ES( can be used to activate and +de-activate )BD(all)ES( columns. This is useful if you want to +activate the $REGION column along with all other columns. According +to the rules, the syntax "$REGION" only activates the region column +and de-activates the rest. Use "+ $REGION" to activate all +columns as well as the region column. + +)0 P(If the data being displayed are image data \201either in a FITS primary +image, a FITS image extension, or an array file\202, an mxn pixel display +is produced, where m and n are the dimensions of the image. By +default, pixel values are displayed using the same data type as in the +file. However, for integer data where the BSCALE and BZERO header parameters +are present, the data is displayed as floats. In either case, the +display data type can be overridden using an optional second argument +of the form: +) 1 10 PR( bitpix=n)RP( +where n is 8,16,32,-32,-64, for unsigned char, short, int, float and double, +respectively. + +)0 P(Of course, running )BD(fundisp)ES( on anything but the smallest image +usually results in a display whose size makes it unreadable. +Therefore, one can uses bracket notation \201see below\202 +to apply section and/or blocking to the image before generating a +display. For example: +) 9 66 PR( [sh] fundisp "test.fits[2:6,2:7]" bitpix=-32 + 2 3 4 5 6 + ---------- ---------- ---------- ---------- ---------- + 2: 3.00 4.00 5.00 6.00 7.00 + 3: 4.00 5.00 6.00 7.00 8.00 + 4: 5.00 6.00 7.00 8.00 9.00 + 5: 6.00 7.00 8.00 9.00 10.00 + 6: 7.00 8.00 9.00 10.00 11.00 + 7: 8.00 9.00 10.00 11.00 12.00)RP( + +)0 P(Note that is is possible to display a FITS binary table as an image +simply by passing the table through )BD(funimage)ES( first: +) 9 68 PR( [sh] ./funimage test.ev stdout | fundisp "stdin[2:6,2:7]" bitpix=8 + 2 3 4 5 6 + ------- ------- ------- ------- ------- + 2: 3 4 5 6 7 + 3: 4 5 6 7 8 + 4: 5 6 7 8 9 + 5: 6 7 8 9 10 + 6: 7 8 9 10 11 + 7: 8 9 10 11 12)RP( + +If the )BD(-l)ES( \201list\202 switch is used, then an image is displayed as a +list containing the columns: X, Y, VAL. For example: +) 33 45 PR( fundisp -l "test1.fits[2:6,2:7]" bitpix=-32 + X Y VAL + ---------- ---------- ----------- + 2 2 6.00 + 3 2 1.00 + 4 2 1.00 + 5 2 1.00 + 6 2 1.00 + 2 3 1.00 + 3 3 5.00 + 4 3 1.00 + 5 3 1.00 + 6 3 1.00 + 2 4 1.00 + 3 4 1.00 + 4 4 4.00 + 5 4 1.00 + 6 4 1.00 + 2 5 1.00 + 3 5 1.00 + 4 5 1.00 + 5 5 3.00 + 6 5 1.00 + 2 6 1.00 + 3 6 1.00 + 4 6 1.00 + 5 6 1.00 + 6 6 2.00 + 2 7 1.00 + 3 7 1.00 + 4 7 1.00)WR( + 5 7 1.00 + 6 7 1.00)RP( + +)0 P(If the )BD(-n)ES( \201nohead\202 switch is used, then no header is output for +tables. This is useful, for example, when fundisp output is being +directed into gnuplot. + +)0 P(The )BD(fundisp)ES( program uses a default set of display formats: +) 10 33 PR( datatype TFORM format + -------- ----- -------- + double D "%21.8f" + float E "%11.2f" + int J "%10d" + short I "%8d" + byte B "%6d" + string A "%12.12s" + bits X "%8x" + logical L "%1x")RP( +Thus, the default display of 1 double and 2 shorts gives: +) 7 42 PR( [sh] fundisp snr.ev "time x y" + + TIME X Y + --------------------- -------- -------- + 79494546.56818075 546 201 + 79488769.94469175 548 201 + ...)RP( +You can change the display format for individual columns or for all +columns of a given data types by means of the -f switch. The format +string that accompanies -f is a space-delimited list of keyword=format +values. The keyword values can either be column names \201in which case +the associated format pertains only to that column\202 or FITS table +TFORM specifiers \201in which case the format pertains to all columns +having that data type\202. For example, you can change the double and +short formats for all columns like this: +) 7 53 PR( [sh] fundisp -f "D=%22.11f I=%3d" snr.ev "time x y" + + TIME X Y + ---------------------- --- --- + 79494546.56818075478 546 201 + 79488769.94469174743 548 201 + ...)RP( + +)0 P(Alternatively, you can change the format of the time and x columns like this: +) 7 56 PR( [sh] fundisp -f "time=%22.11f x=%3d" snr.ev "time x y" + + TIME X Y + ---------------------- --- -------- + 79494546.56818075478 546 201 + 79488769.94469174743 548 201 + ...)RP( +Note that there is a potential conflict if a column has the same name +as one of the TFORM specifiers. In the examples above, the the "X" +column in the table has the same name as the X \201bit\202 datatype. To +resolve this conflict, the format string is processed such that +TFORM datatype specifiers are checked for first, using a +case-sensitive comparison. If the specified format value is not an +upper case TFORM value, then a case-insensitive check is made on the +column name. This means that, in the examples above, "X=%3d" will refer +to the X \201bit\202 datatype, while "x=%3d" will refer to the X column: +) 15 38 PR( [sh] fundisp -f "X=%3d" snr.ev "x y" + + X Y + -------- -------- + 546 201 + 548 201 + ... + + [sh] fundisp -f "x=%3d" snr.ev "x y" + + X Y + --- -------- + 546 201 + 548 201 + ...)RP( +As a rule, therefore, it is best always to specify the column name in +lower case and TFORM data types in upper case. + +)0 P(The )BD(-f [format])ES( will change the format for a single execution +of fundisp. You also can use the )BD(FUN_FORMAT)ES( envronment variable +to change the format for all invocations of fundisp. The format of this +environment variable's value is identical to that used with +the )BD(-f)ES( switch. This global value can be overridden in +individual cases by use of the )BD(-f [format])ES( switch. + +)0 P(Caveats: Please also note that it is the user's responsibility to +match the format specifier to the column data type correctly. Also +note that, in order to maintain visual alignment between names and +columns, the column name will be truncated \201on the left\202 if the +format width is less than the length of the name. However, truncation +is not performed if the output is in RDB format \201using the -T switch\202. + +)0 P([An older-style format string is supported but deprecated. It +consists of space-delimited C format statements for all data types, +specified in the following order: +) 1 40 PR( double float int short byte string bit.)RP( +This order of the list is based on the assumption that people generally +will want to change the float formats. +)0 P(If "-" is entered instead of a format statement for a given data type, the +default format is used. Also, the format string can be terminated without +specifying all formats, and defaults will be used for the rest of the +list. Note that you must supply a minimum field width, i.e., "%6d" and +"%-6d" are legal, "%d" is not legal. + +By using -f [format], you can change the double and short formats like this: +) 7 51 PR( [sh] fundisp -f "22.11f - - 3d" snr.ev "time x y" + + TIME X Y + ---------------------- --- --- + 79494546.56818075478 546 201 + 79488769.94469174743 548 201 + ...)RP( +NB: This format is deprecated and will be removed in a future release.] + +)0 P(The )BD(-F[c])ES( switch can be used to specify a \201single-character\202 +column separator \201where the default is a space\202. Note that column +formatting will almost certainly also add spaces to pad individual +columns to the required width. These can be removed with a program +such as sed, at the cost of generating unaligned columns. For example: +) 26 117 PR(fundisp -F',' snr.ev'[cir 512 512 .1]' + 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 + +fundisp -F',' snr.ev'[cir 512 512 .1]' | sed 's/ *, */,/g' + 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 + +fundisp -f "x=%3d y=%3d pi=%1d pha=%1d time=%20.11f dx=%3d dy=%3d" -F',' snr.ev'[cir 512 512 .1]' | sed 's/ *, */,/g' + X,Y,A,I,TIME,DX,DY +---,---,-,-,--------------------,---,--- +512,512,6,7,79493997.45854474604,578,574 +512,512,8,9,79494575.58943174779,579,573 +512,512,5,6,79493631.03866174817,578,575 +512,512,5,5,79493290.86521725357,578,575 +512,512,8,9,79493432.00990875065,579,573)RP( + +)0 P(If the )BD(-T)ES( \201rdb table\202 switch is used, the output will conform +to starbase/rdb data base format: tabs will be inserted between +columns rather than spaces. This format is not available when +displaying image pixels \201except in conjunction with the )BD(-l)ES( +switch\202. + +)0 P(Finally, note that )BD(fundisp)ES( can be used to create column filters from +the auxiliary tables in a FITS file. For example, the following shell code +will generate a good-time interval \201GTI\202 filter for X-ray data files that +contain a standard GTI extension: +) 3 68 PR( #!/bin/sh + sed '1,/---- .*/d + /^$/,$d' | awk 'tot>0{printf "||"};{printf "time="$1":"$2; tot++}')RP( +If this script is placed in a file called "mkgti", it can be used in a +command such as: +) 1 46 PR( fundisp foo.fits"[GTI]" | mkgti > gti.filter)RP( +The resulting filter file can then be used in various funtools programs: +) 1 37 PR( funcnts foo.fits"[@gti.filter]" ...)RP( +to process only the events in the good-time intervals. + + + + +)0 2 11 H(funhead)WB 74 Sn()WB 8 Sn( - display a header in a Funtools file)EA()EH( + + +)BD() 1 50 PR(funhead [-a] [-s] [-t] [-L] <iname> [oname ename])RP()ES( + + +)0 P() 4 60 PR( -a # display all extension headers + -s # display 79 chars instead of 80 before the new-line + -t # prepend data type char to each line of output + -L # output in rdb/starbase list format)RP( + + +)0 P()BD(funhead)ES( displays the FITS header parameters in the specified +)0 42 1 A(FITS Extension)42 0 TN TL()Ec /AF f D(. +)0 P(The first argument to the program specifies the Funtools input file +to display. If "stdin" is specified, data are read from +the standard input. )0 42 1 A(Funtools Bracket +Notation)42 0 TN TL()Ec /AF f D( is used to specify particular FITS extension to process. +Normally, the full 80 characters of each header card is output, +followed by a new-line. + +)0 P(If the )BD(-a)ES( switch is specified, the header from each FITS +extensions in the file is displayed. Note, however, that the )BD(-a)ES( +switch does not work with FITS files input via stdin. We hope to +remove this restriction in a future release. + +)0 P(If the )BD(-s)ES( switch is specified, only 79 characters are output +before the new-line. This helps the display on 80 character terminals. + +)0 P(If the )BD(-t)ES( switch is specified, the data type of the parameter +is output as a one character prefix, followed by 77 characters of the +param. The parameter data types are defined as: FUN_PAR_UNKNOWN +\201'u'\202, FUN_PAR_COMMENT \201'c'\202, FUN_PAR_LOGICAL \201'l'\202, FUN_PAR_INTEGER +\201'i'\202, FUN_PAR_STRING \201's'\202, FUN_PAR_REAL \201'r'\202, FUN_PAR_COMPLEX \201'x'\202. + +)0 P(If the )BD(-L)ES( \201rdb table\202 switch is used, the output will conform +to starbase/rdb data base list format. + +)0 P(For example to display the EVENTS extension \201binary table\202: +) 17 65 PR( [sh] funhead "foo.fits[EVENTS]" + XTENSION= 'BINTABLE' / FITS 3D BINARY TABLE + BITPIX = 8 / Binary data + NAXIS = 2 / Table is a matrix + NAXIS1 = 20 / Width of table in bytes + NAXIS2 = 30760 / Number of entries in table + PCOUNT = 0 / Random parameter count + GCOUNT = 1 / Group count + TFIELDS = 7 / Number of fields in each row + EXTNAME = 'EVENTS ' / Table name + EXTVER = 1 / Version number of table + TFORM1 = '1I ' / Data type for field + TTYPE1 = 'X ' / Label for field + TUNIT1 = ' ' / Physical units for field + TFORM2 = '1I ' / Data type for field + etc. ... + END)RP( + +)0 P(To display the third header: +) 14 65 PR( [sh] funhead "foo.fits[3]" + XTENSION= 'BINTABLE' / FITS 3D BINARY TABLE + BITPIX = 8 / Binary data + NAXIS = 2 / Table is a matrix + NAXIS1 = 32 / Width of table in bytes + NAXIS2 = 40 / Number of entries in table + PCOUNT = 0 / Random parameter count + GCOUNT = 1 / Group count + TFIELDS = 7 / Number of fields in each row + EXTNAME = 'TGR ' / Table name + EXTVER = 1 / Version number of table + TFORM1 = '1D ' / Data type for field + etc. ... + END)RP( + +)0 P(To display the primary header \201i.e., extension 0\202: +) 8 59 PR( sh> funhead "coma.fits[0]" + SIMPLE = T /STANDARD FITS FORMAT + BITPIX = 16 /2-BYTE TWOS-COMPL INTEGER + NAXIS = 2 /NUMBER OF AXES + NAXIS1 = 800 / + NAXIS2 = 800 / + DATATYPE= 'INTEGER*2' /SHORT INTEGER + END)RP( + +)0 P(The funhead program also can edit \201i.e. add, delete, or modify\202 or +display individual headers parameters. Edit mode is signalled by the +presence of two additional command-line arguments: output file and +edit command file, in that order. Edit mode acts as a filter: the +output file will contain the entire input FITS file, including other +extensions. The edit command file can be "stdin", in which case edit +command are read from the standard input. + +)0 P(The edit command file contains parameter comments \201having '#' in the +first column\202 and delete and assignment\201modify or add\202 operations. A +delete operation is specified by preceding the parameter name with a +minus sign "-". A display operation \201very useful in interactive +sessions, i.e., where the edit commands are taken from stdin\202 is +specified by preceding the parameter name with a question mark "?". In +either case, a parameter value need not be specified. An assignment +operation is specified in the same two ways that a parameter is +specified in a text header \201but without the comment character that +precedes header params\202, i.e.: + +)UL()-1 LI( FITS-style comments have an equal sign "=" between the keyword and +value and an optional slash "/" to signify a comment. The strict FITS +rules on column positions are not enforced. + +)-1 LI( 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.)LU( + +)0 P(For example, the following interactive session checks for the +existence of parameters, adds new parameters, modifies them, and +modifies and deletes existing parameters: +) 20 55 PR( sh$ ./funhead snr.ev foo.fits - + # look for FOO1 + ? FOO1 + WARNING: FOO1 not found + # add new foo1 + FOO1 = 100 + # add foo2 + FOO2 = 200 + # reset foo1 to a different value + FOO1 -1 + # delete foo2 + -FOO2 + # change existing value + EXTVER 2 + ? XS-SORT + XS-SORT = 'EOF ' / type of event sort + # delete existing value + -XS-SORT + # exit + ^D)RP( + +)0 P(See )0 47 1 A(Column-based Text Files)47 0 TN TL()Ec /AF f D( +for more information about header parameter format. + +)0 P( +)0 P( + + +)0 2 12 H(funhist)WB 75 Sn()WB 9 Sn( - create a 1D histogram of a column \201from a FITS binary table or raw event file\202 or an image)EA()EH( + + +)BD() 1 51 PR(funhist [-n|-w|-T] <iname> [column] [[lo:hi:]bins])RP()ES( + + +)0 P() 3 61 PR( -n # normalize bin value by the width of each bin + -w # specify bin width instead of number of bins in arg3 + -T # output in rdb/starbase format \201tab separators\202)RP( + + +)0 P()BD(funhist)ES( creates a one-dimensional histogram from the specified +columns of a )0 42 1 A(FITS Extension)42 0 TN TL()Ec /AF f D( +binary table of a FITS file \201or from a non-FITS raw event file\202, or +from a FITS image or array, and writes that histogram as an ASCII +table. Alternatively, the program can perform a 1D projection of one +of the image axes. + +)0 P(The first argument to the program is required, and specifies the +Funtools file: FITS table or image, raw event file, or array. If +"stdin" is specified, data are read from the standard input. Use +)0 42 1 A(Funtools Bracket Notation)42 0 TN TL()Ec /AF f D( to specify FITS +extensions, and filters. + +)0 P(For a table, the second argument also is required. It specifies the +column to use in generating the histogram. If the data file is of +type image \201or array\202, the column is optional: if "x" \201or "X"\202, "y" +\201or "Y"\202 is specified, then a projection is performed over the x +\201dim1\202 or y \201dim2\202 axes, respectively. \201That is, this projection will +give the same results as a histogram performed on a table containing +the equivalent x,y event rows.\202 If no column name is specified or +"xy" \201or "XY"\202 is specified for the image, then a histogram is +performed on the values contained in the image pixels. + +)0 P(The argument that follows is optional and specifies the number of bins +to use in creating the histogram and, if desired, the range of bin +values. For image and table histograms, the range should specify the +min and max data values. For image histograms on the x and y axes, +the range should specify the min and max image bin values. If this +argument is omitted, the number of output bins for a table is +calculated either from the TLMIN/TLMAX headers values \201if these exist +in the table FITS header for the specified column\202 or by going through +the data to calculate the min and max value. For an image, the number +of output bins is calculated either from the DATAMIN/DATAMAX header +values, or by going through the data to calculate min and max value. +\201Note that this latter calculation might fail if the image cannot be +fit in memory.\202 If the data are floating point \201table or image\202 and +the number of bins is not specified, an arbitrary default of 128 is +used. + +)0 P(For binary table processing, the )BD(-w)ES( \201bin width\202 switch can be used +to specify the width of each bin rather than the number of bins. Thus: +) 1 29 PR( funhist test.ev pha 1:100:5)RP( +means that 5 bins of width 20 are used in the histogram, while: +) 1 32 PR( funhist -w test.ev pha 1:100:5)RP( +means that 20 bins of width 5 are used in the histogram. + +)0 P(The data are divvied up into the specified number of bins and the +resulting 1D histogram \201or projection\202 is output in ASCII table +format. For a table, the output displays the low_edge \201inclusive\202 and +hi_edge \201exclusive\202 values for the data. For example, a 15-row table +containing a "pha" column whose values range from -7.5 to 7.5 +can be processed thus: + +) 47 62 PR( [sh] funhist test.ev pha + # data file: /home/eric/data/test.ev + # column: pha + # min,max,bins: -7.5 7.5 15 + + bin value lo_edge hi_edge + ------ --------- --------------------- --------------------- + 1 22 -7.50000000 -6.50000000 + 2 21 -6.50000000 -5.50000000 + 3 20 -5.50000000 -4.50000000 + 4 19 -4.50000000 -3.50000000 + 5 18 -3.50000000 -2.50000000 + 6 17 -2.50000000 -1.50000000 + 7 16 -1.50000000 -0.50000000 + 8 30 -0.50000000 0.50000000 + 9 16 0.50000000 1.50000000 + 10 17 1.50000000 2.50000000 + 11 18 2.50000000 3.50000000 + 12 19 3.50000000 4.50000000 + 13 20 4.50000000 5.50000000 + 14 21 5.50000000 6.50000000 + 15 22 6.50000000 7.50000000 + + [sh] funhist test.ev pha 1:6 + # data file: /home/eric/data/test.ev + # column: pha + # min,max,bins: 0.5 6.5 6 + + bin value lo_edge hi_edge + ------ --------- --------------------- --------------------- + 1 16 0.50000000 1.50000000)WR( + 2 17 1.50000000 2.50000000 + 3 18 2.50000000 3.50000000 + 4 19 3.50000000 4.50000000 + 5 20 4.50000000 5.50000000 + 6 21 5.50000000 6.50000000 + + [sh] funhist test.ev pha 1:6:3 + # data file: /home/eric/data/test.ev + # column: pha + # min,max,bins: 0.5 6.5 3 + + bin value lo_edge hi_edge + ------ --------- --------------------- --------------------- + 1 33 0.50000000 2.50000000 + 2 37 2.50000000 4.50000000 + 3 41 4.50000000 6.50000000)RP( + +)0 P(For a table histogram, the )BD(-n)ES(\201normalize\202 switch can be used to +normalize the bin value by the width of the bin \201i.e., hi_edge-lo_edge\202: +) 11 74 PR( [sh] funhist -n test.ev pha 1:6:3 + # data file: test.ev + # column: pha + # min,max,bins: 0.5 6.5 3 + # width normalization \201val/\201hi_edge-lo_edge\202\202 is applied + + bin value lo_edge hi_edge + ------ --------------------- --------------------- --------------------- + 1 16.50000000 0.50000000 2.50000000 + 2 6.16666667 2.50000000 4.50000000 + 3 4.10000000 4.50000000 6.50000000)RP( +This could used, for example, to produce a light curve with values +having units of counts/second instead of counts. + +)0 P(For an image histogram, the output displays the low and high image +values \201both inclusive\202 used to generate the histogram. For example, +in the following example, 184 pixels had a value of 1, 31 had a value +of 2, while only 2 had a value of 3,4,5,6, or 7: +) 13 74 PR( [sh] funhist test.fits + # data file: /home/eric/data/test.fits + # min,max,bins: 1 7 7 + + bin value lo_val hi_val + ------ --------------------- --------------------- --------------------- + 1 184.00000000 1.00000000 1.00000000 + 2 31.00000000 2.00000000 2.00000000 + 3 2.00000000 3.00000000 3.00000000 + 4 2.00000000 4.00000000 4.00000000 + 5 2.00000000 5.00000000 5.00000000 + 6 2.00000000 6.00000000 6.00000000 + 7 2.00000000 7.00000000 7.00000000)RP( + +)0 P(For the axis projection of an image, the output displays the low and +high image bins \201both inclusive\202 used to generate the projection. For +example, in the following example, 21 counts had their X bin value of +2, etc.: +) 23 74 PR( [sh] funhist test.fits x 2:7 + # data file: /home/eric/data/test.fits + # column: X + # min,max,bins: 2 7 6 + + bin value lo_bin hi_bin + ------ --------------------- --------------------- --------------------- + 1 21.00000000 2.00000000 2.00000000 + 2 20.00000000 3.00000000 3.00000000 + 3 19.00000000 4.00000000 4.00000000 + 4 18.00000000 5.00000000 5.00000000 + 5 17.00000000 6.00000000 6.00000000 + 6 16.00000000 7.00000000 7.00000000 + + [sh] funhist test.fits x 2:7:2 + # data file: /home/eric/data/test.fits + # column: X + # min,max,bins: 2 7 2 + + bin value lo_bin hi_bin + ------ --------------------- --------------------- --------------------- + 1 60.00000000 2.00000000 4.00000000 + 2 51.00000000 5.00000000 7.00000000)RP( + +)0 P(You can use gnuplot or other plotting programs to graph the +results, using a script such as: +) 7 119 PR( #!/bin/sh + sed -e '1,/---- .*/d + /^$/,$d' | \200 + awk '\200 + BEGIN{print "set nokey; set title \200"funhist\200"; set xlabel \200"bin\200"; set ylabel \200"counts\200"; plot \200"-\200" with boxes"} \200 + {print $3, $2, $4-$3}' | \200 + gnuplot -persist - 1>/dev/null 2>&1)RP( + +Similar plot commands are supplied in the script )BD(funhist.plot)ES(: +) 1 49 PR( funhist test.ev pha ... | funhist.plot gnuplot)RP( + + + + +)0 2 13 H(funimage)WB 76 Sn()WB 10 Sn( - create a FITS image from a Funtools data file)EA()EH( + + +)BD() 3 73 PR(funimage [-a] <iname> <oname> [bitpix=n] +funimage [-l] <iname> <oname> <xcol:xdims> <ycol:ydims> <vcol> [bitpix=n] +funimage [-p x|y] <iname> <oname> [bitpix=n])RP()ES( + + +)0 P() 3 65 PR( -a # append to existing output file as an image extension + -l # input is a list file containing xcol, ycol, value + -p [x|y] # project along x or y axis to create a 1D image)RP( + + +)0 P()BD(funimage)ES( creates a primary FITS image from the specified +)0 42 1 A(FITS Extension)42 0 TN TL()Ec /AF f D( +and/or +)0 49 1 A(Image Section)49 0 TN TL()Ec /AF f D( +of a FITS file, or from an +)0 49 1 A(Image Section)49 0 TN TL()Ec /AF f D( +of a non-FITS array, or from a raw event file. +)0 P(The first argument to the program specifies the FITS input image, +array, or raw event file to process. If "stdin" is specified, data are +read from the standard input. Use )0 42 1 A(Funtools +Bracket Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions, image sections, and +filters. The second argument is the output FITS file. If "stdout" is +specified, the FITS image is written to the standard output. By +default, the output pixel values are of the same data type as those of the +input file \201or type "int" when binning a table\202, but this can be +overridden using an optional third argument of the form: +) 1 10 PR( bitpix=n)RP( +where n is 8,16,32,-32,-64, for unsigned char, short, int, float and double, +respectively. + +)0 P(If the input data are of type image, the appropriate section is +extracted and blocked \201based on how the +)0 49 1 A(Image Section)49 0 TN TL()Ec /AF f D( is specified\202, and +the result is written to the FITS primary image. When an integer +image containing the BSCALE and BZERO keywords is converted to float, +the pixel values are scaled and the scaling keywords are deleted from the +output header. When converting integer scaled data to integer +\201possibly of a different size\202, the pixels are not scaled and the +scaling keywords are retained. + +)0 P(If the input data is a binary table or raw event file, these are +binned into an image, from which a section is extracted and blocked, +and written to a primary FITS image. In this case, it is necessary to +specify the two columns that will be used in the 2D binning. This can +be done on the command line using the )BD(bincols=\201x,y\202)ES( keyword: +) 1 46 PR( funcnts "foo.ev[EVENTS,bincols=\201detx,dety\202]")RP( +The full form of the )BD(bincols=)ES( specifier is: +) 1 77 PR( bincols=\201[xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]]]\202)RP( +where the tlmin, tlmax, and binsiz specifiers determine the image binning +dimensions: +) 2 56 PR( dim = \201tlmax - tlmin\202/binsiz \201floating point data\202 + dim = \201tlmax - tlmin\202/binsiz + 1 \201integer data\202)RP( +Using this syntax, it is possible to bin any two columns of a binary +table at any bin size. Note that the tlmin, tlmax, and binsiz +specifiers can be omitted if TLMIN, TLMAX, and TDBIN header parameters +\201respectively\202 are present in the FITS binary table header for the +column in question. Note also that 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. +See )0 50 1 A(Binning FITS Binary Tables and Non-FITS +Event Files)50 0 TN TL()Ec /AF f D( for more information about binning parameters. + +)0 P(By default, a new 2D FITS image file is created and the image is written +to the primary HDU. If the )BD(-a)ES( \201append\202 switch is specified, +the image is appended to an existing FITS file as an IMAGE extension. +\201If the output file does not exist, the switch is effectively ignored +and the image is written to the primary HDU.\202 This can be useful in a +shell programming environment when processing multiple FITS images +that you want to combine into a single final FITS file. + +)0 P()BD(funimage)ES( also can take input from a table containing columns of +x, y, and value \201e.g., the output from )BD(fundisp -l)ES( which +displays each image x and y and the number of counts at that +position.\202 When the )BD(-l)ES( \201list\202 switch is used, the input file is +taken to be a FITS or ASCII table containing \201at least\202 three columns +that specify the x and y image coordinates and the value of that +image pixel. In this case, )BD(funimage)ES( requires four extra +arguments: xcolumn:xdims, ycolumn:ydims, vcolumn and bitpix=n. The x +and y col:dim information takes the form: +) 3 55 PR( name:dim # values range from 1 to dim + name:min:max # values range from min to max + name:min:max:binsiz # dimensions scaled by binsize)RP( +In particular, the min value should be used whenever the +minimum coordinate value is something other than one. For example: +) 2 69 PR( + funimage -l foo.lst foo.fits xcol:0:512 ycol:0:512 value bitpix=-32)RP( + +)0 P(The list feature also can be used to read unnamed columns from standard +input: simply replace the column name with a null string. Note +that the dimension information is still required: +) 5 60 PR( funimage -l stdin foo.fits "":0:512 "":0:512 "" bitpix=-32 + 240 250 1 + 255 256 2 + ... + ^D)RP( + +)0 P(The list feature provides a simple way to generate a blank image. +If you pass a )0 47 1 A(Column-based Text File)47 0 TN TL()Ec /AF f D( +to funimage in which the text header contains the required image +information, then funimage will correctly make a blank image. For +example, consider the following text file \201called foo.txt\202: +) 3 20 PR( x:I:1:10 y:I:1:10 + ------ ------ + 0 0)RP( +This text file defines two columns, x and y, each of data type 32-bit int and +image dimension 10. The command: +) 1 36 PR( funimage foo.txt foo.fits bitpix=8)RP( +will create an empty FITS image called foo.fits containing a 10x10 +image of unsigned char: +) 13 75 PR( fundisp foo.fits + 1 2 3 4 5 6 7 8 9 10 + ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ + 10: 0 0 0 0 0 0 0 0 0 0 + 9: 0 0 0 0 0 0 0 0 0 0 + 8: 0 0 0 0 0 0 0 0 0 0 + 7: 0 0 0 0 0 0 0 0 0 0 + 6: 0 0 0 0 0 0 0 0 0 0 + 5: 0 0 0 0 0 0 0 0 0 0 + 4: 0 0 0 0 0 0 0 0 0 0 + 3: 0 0 0 0 0 0 0 0 0 0 + 2: 0 0 0 0 0 0 0 0 0 0 + 1: 1 0 0 0 0 0 0 0 0 0)RP( + +Note that the text file must contain at least +one row of data. However, in the present example, event position 0,0 is +outside the limits of the image and will be ignored. \201You can, of course, +use real x,y values to seed the image with data.\202 + +)0 P(Furthermore, you can use the TEXT filter specification to obviate the need for +an input text file altogether. The following command will create the same +10x10 char image without an actual input file: +) 3 69 PR( funimage stdin'[TEXT\201x:I:10,y:I:10\202]' foo.fits bitpix=8 < /dev/null +or + funimage /dev/null'[TEXT\201x:I:10,y:I:10\202]' foo.fits bitpix=8)RP( + +)0 P(You also can use either of these methods to generate a region mask simply +by appending a region inside the filter brackets and specfying )BD(mask=all)ES( +along with the bitpix. For example, the following command will generate a +10x10 char mask using 3 regions: +) 2 76 PR( funimage stdin'[TEXT\201x:I:10,y:I:10\202,cir\2015,5,4\202,point\20110,1\202,-cir\2015,5,2\202]' \200 + foo.fits bitpix=8,mask=all < /dev/null)RP( +The resulting mask looks like this: +) 13 75 PR( fundisp foo.fits + 1 2 3 4 5 6 7 8 9 10 + ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ + 10: 0 0 0 0 0 0 0 0 0 0 + 9: 0 0 0 0 0 0 0 0 0 0 + 8: 0 0 1 1 1 1 1 0 0 0 + 7: 0 1 1 1 1 1 1 1 0 0 + 6: 0 1 1 0 0 0 1 1 0 0 + 5: 0 1 1 0 0 0 1 1 0 0 + 4: 0 1 1 0 0 0 1 1 0 0 + 3: 0 1 1 1 1 1 1 1 0 0 + 2: 0 0 1 1 1 1 1 0 0 0 + 1: 0 0 0 0 0 0 0 0 0 2)RP( + +)0 P(You can use )BD(funimage)ES( to create 1D image projections along the x +or y axis using the )BD(-p [x|y])ES( switch. This capability works for +both images and tables. For example consider a FITS table named ev.fits +containing the following rows: +) 17 19 PR( X Y + -------- -------- + 1 1 + 1 2 + 1 3 + 1 4 + 1 5 + 2 2 + 2 3 + 2 4 + 2 5 + 3 3 + 3 4 + 3 5 + 4 4 + 4 5 + 5 5)RP( +A corresponding 5x5 image, called dim2.fits, would therefore contain: +) 7 59 PR( 1 2 3 4 5 + ---------- ---------- ---------- ---------- ---------- + 5: 1 1 1 1 1 + 4: 1 1 1 1 0 + 3: 1 1 1 0 0 + 2: 1 1 0 0 0 + 1: 1 0 0 0 0)RP( +A projection along the y axis can be performed on either the table or +the image: +) 9 59 PR( funimage -p y ev.fits stdout | fundisp stdin + 1 2 3 4 5 + ---------- ---------- ---------- ---------- ---------- + 1: 1 2 3 4 5 + + funimage -p y dim2.fits stdout | fundisp stdin + 1 2 3 4 5 + ---------- ---------- ---------- ---------- ---------- + 1: 1 2 3 4 5)RP( + +)0 P(Furthermore, you can create a 1D image projection along any column of +a table by using the )BD(bincols=[column])ES( filter specification and +specifying a single column. For example, the following command +projects the same 1D image along the y axis of a table as use of +the )BD(-p y)ES( switch: +) 4 59 PR( funimage ev.fits'[bincols=y]' stdout | fundisp stdin + 1 2 3 4 5 + ---------- ---------- ---------- ---------- ---------- + 1: 1 2 3 4 5)RP( + +)0 P(Examples: +)0 P(Create a FITS image from a FITS binary table: +) 1 33 PR( [sh] funimage test.ev test.fits)RP( + +)0 P(Display the FITS image generated from a blocked section of FITS binary table: +) 5 60 PR( [sh] funimage "test.ev[2:8,3:7,2]" stdout | fundisp stdin + 1 2 3 + --------- --------- --------- + 1: 20 28 36 + 2: 28 36 44)RP( + + + + +)0 2 14 H(funindex)WB 77 Sn()WB 11 Sn( - create an index for a column of a FITS binary table)EA()EH( + + +)BD() 1 42 PR(funindex <switches> <iname> <key> [oname])RP()ES( + + +)0 P() 7 71 PR( NB: these options are not compatible with Funtools processing. Please + use the defaults instead. + -c # compress output using gzip" + -a # ASCII output, ignore -c \201default: FITS table\202" + -f # FITS table output \201default: FITS table\202" + -l # long output, i.e. with key value\201s\202 \201default: long\202" + -s # short output, i.e. no key value\201s\202 \201default: long\202")RP( + + +)0 P(The funindex script creates an index for the specified column \201key\202 by +running funtable -s \201sort\202 and then saving the column value and the +record number for each sorted row. This index will be used automatically + by funtools filtering of that column, provided the index file's modification +date is later than that of the data file. + +)0 P( +The first required argument is the name of the FITS binary table +to index. Please note that text files cannot be indexed at this time. +The second required argument is the column \201key\202 name to index. While +multiple keys can be specified in principle, the funtools index processing +assume a single key and will not recognize files containing multiple keys. + +)0 P(By default, the output index file name is [root]_[key].idx, where [root] +is the root of the input file. Funtools looks for this specific file name +when deciding whether to use an index for faster filtering. Therefore, the +optional third argument \201output file name\202 should not be used for funtools +processing. + +)0 P(For example, to create an index on column Y for a given FITS file, use: +) 1 21 PR( funindex foo.fits Y)RP( +This will generate an index named foo_y.idx, which will be used by funtools +for filters involving the Y column. + + + + +)0 2 15 H(funjoin)WB 78 Sn()WB 12 Sn( - join two or more FITS binary tables on specified columns)EA()EH( + + +)BD() 1 57 PR(funjoin [switches] <ifile1> <ifile2> ... <ifilen> <ofile>)RP()ES( + + +)0 P() 11 74 PR( -a cols # columns to activate in all files + -a1 cols ... an cols # columns to activate in each file + -b 'c1:bvl,c2:bv2' # blank values for common columns in all files + -bn 'c1:bv1,c2:bv2' # blank values for columns in specific files + -j col # column to join in all files + -j1 col ... jn col # column to join in each file + -m min # min matches to output a row + -M max # max matches to output a row + -s # add 'jfiles' status column + -S col # add col as status column + -t tol # tolerance for joining numeric cols [2 files only])RP( + + +)BD(funjoin)ES( joins rows from two or more \201up to 32\202 +)0 42 1 A(FITS Binary Table files)42 0 TN TL()Ec /AF f D(, based on the values +of specified join columns in each file. NB: the join columns must have +an index file associated with it. These files are generated using the +)BD(funindex)ES( program. + +)0 P(The first argument to the program specifies the first input FITS table +or raw event file. If "stdin" is specified, data are read from the +standard input. Subsequent arguments specify additional event files +and tables to join. The last argument is the output FITS file. + +)0 P(NB: Do )BD(not)ES( use )0 42 1 A(Funtools Bracket +Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions and row filters when running +funjoin or you will get wrong results. Rows are accessed and joined +using the index files directly, and this bypasses all filtering. + +)0 P(The join columns are specified using the )BD(-j col)ES( switch \201which +specifies a column name to use for all files\202 or with )BD(-j1 col1)ES(, +)BD(-j2 col2)ES(, ... )BD(-jn coln)ES( switches \201which specify a column +name to use for each file\202. A join column must be specified for each file. +If both )BD(-j col)ES( and )BD(-jn coln)ES( are specified for a given +file, then the latter is used. Join columns must either be of type +string or type numeric; it is illegal to mix numeric and string +columns in a given join. For example, to join three files using the +same key column for each file, use: +) 1 52 PR( funjoin -j key in1.fits in2.fits in3.fits out.fits)RP( +A different key can be specified for the third file in this way: +) 1 65 PR( funjoin -j key -j3 otherkey in1.fits in2.fits in3.fits out.fits)RP( + +)0 P(The )BD(-a "cols")ES( switch \201and )BD(-a1 "col1")ES(, +)BD(-a2 "cols2")ES( counterparts\202 can be used to specify columns to +activate \201i.e. write to the output file\202 for each input file. By +default, all columns are output. + +)0 P(If two or more columns from separate files have the same name, the +second \201and subsequent\202 columns are renamed to have an underscore +and a numeric value appended. + +)0 P(The )BD(-m min)ES( and )BD(-M max)ES( switches specify the minimum +and maximum number of joins required to write out a row. The default +minimum is 0 joins \201i.e. all rows are written out\202 and the default maximum +is 63 \201the maximum number of possible joins with a limit of 32 input files\202. +For example, to write out only those rows in which exactly two files +have columns that match \201i.e. one join\202: +) 1 66 PR( funjoin -j key -m 1 -M 1 in1.fits in2.fits in3.fits ... out.fits)RP( + +)0 P(A given row can have the requisite number of joins without all of the +files being joined \201e.g. three files are being joined but only two +have a given join key value\202. In this case, all of the columns of the +non-joined file are written out, by default, using blanks \201zeros or NULLs\202. +The )BD(-b c1:bv1,c2:bv2)ES( and +)BD(-b1 'c1:bv1,c2:bv2' -b2 'c1:bv1,c2:bv2' ...)ES( +switches can be used to set the blank value for columns common to all +files and/or columns in a specified file, respectively. Each blank value +string contains a comma-separated list of column:blank_val specifiers. +For floating point values \201single or double\202, a case-insensitive string +value of "nan" means that the IEEE NaN \201not-a-number\202 should be +used. Thus, for example: +) 1 62 PR( funjoin -b "AKEY:???" -b1 "A:-1" -b3 "G:NaN,E:-1,F:-100" ...)RP( +means that a non-joined AKEY column in any file will contain the +string "???", the non-joined A column of file 1 will contain a value +of -1, the non-joined G column of file 3 will contain IEEE NaNs, while +the non-joined E and F columns of the same file will contain values -1 +and -100, respectively. Of course, where common and specific blank values +are specified for the same column, the specific blank value is used. + +)0 P(To distinguish which files are non-blank components of a given row, +the )BD(-s)ES( \201status\202 switch can be used to add a bitmask column named +"JFILES" to the output file. In this column, a bit is set for each +non-blank file composing the given row, with bit 0 corresponds to the +first file, bit 1 to the second file, and so on. The file names +themselves are stored in the FITS header as parameters named JFILE1, +JFILE2, etc. The )BD(-S col)ES( switch allows you to change the name +of the status column from the default "JFILES". + +)0 P(A join between rows is the Cartesian product of all rows in one file +having a given join column value with all rows in a second file having +the same value for its join column and so on. Thus, if file1 has 2 +rows with join column value 100, file2 has 3 rows with the same value, +and file3 has 4 rows, then the join results in 2*3*4=24 rows being output. + +)0 P(The join algorithm directly processes the index file associated with +the join column of each file. The smallest value of all the current +columns is selected as a base, and this value is used to join +equal-valued columns in the other files. In this way, the index files +are traversed exactly once. + +)0 P(The )BD(-t tol)ES( switch specifies a tolerance value for numeric +columns. At present, a tolerance value can join only two files at a +time. \201A completely different algorithm is required to join more than +two files using a tolerance, somethng we might consider implementing +in the future.\202 + +)0 P(The following example shows many of the features of funjoin. The input files +t1.fits, t2.fits, and t3.fits contain the following columns: +) 28 49 PR( [sh] fundisp t1.fits + AKEY KEY A B + ----------- ------ ------ ------ + aaa 0 0 1 + bbb 1 3 4 + ccc 2 6 7 + ddd 3 9 10 + eee 4 12 13 + fff 5 15 16 + ggg 6 18 19 + hhh 7 21 22 + +fundisp t2.fits + AKEY KEY C D + ----------- ------ ------ ------ + iii 8 24 25 + ggg 6 18 19 + eee 4 12 13 + ccc 2 6 7 + aaa 0 0 1 + +fundisp t3.fits + AKEY KEY E F G +------------ ------ -------- -------- ----------- + ggg 6 18 19 100.10 + jjj 9 27 28 200.20 + aaa 0 0 1 300.30 + ddd 3 9 10 400.40)RP( + +)0 P(Given these input files, the following funjoin command: +) 3 59 PR( funjoin -s -a1 "-B" -a2 "-D" -a3 "-E" -b \200 + "AKEY:???" -b1 "AKEY:XXX,A:255" -b3 "G:NaN,E:-1,F:-100" \200 + -j key t1.fits t2.fits t3.fits foo.fits)RP( +will join the files on the KEY column, outputting all columns except B +\201in t1.fits\202, D \201in t2.fits\202 and E \201in t3.fits\202, and setting blank +values for AKEY \201globally, but overridden for t1.fits\202 and A \201in file +1\202 and G, E, and F \201in file 3\202. A JFILES column will be output to +flag which files were used in each row: +) 12 105 PR( AKEY KEY A AKEY_2 KEY_2 C AKEY_3 KEY_3 F G JFILES + ------------ ------ ------ ------------ ------ ------ ------------ ------ -------- ----------- -------- + aaa 0 0 aaa 0 0 aaa 0 1 300.30 7 + bbb 1 3 ??? 0 0 ??? 0 -100 nan 1 + ccc 2 6 ccc 2 6 ??? 0 -100 nan 3 + ddd 3 9 ??? 0 0 ddd 3 10 400.40 5 + eee 4 12 eee 4 12 ??? 0 -100 nan 3 + fff 5 15 ??? 0 0 ??? 0 -100 nan 1 + ggg 6 18 ggg 6 18 ggg 6 19 100.10 7 + hhh 7 21 ??? 0 0 ??? 0 -100 nan 1 + XXX 0 255 iii 8 24 ??? 0 -100 nan 2 + XXX 0 255 ??? 0 0 jjj 9 28 200.20 4)RP( + + + +)0 2 16 H(funmerge)WB 79 Sn()WB 13 Sn( - merge one or more Funtools table files)EA()EH( + + +)BD() 1 61 PR(funmerge [-w|-x] -f [colname] <iname1> <iname2> ... <oname>)RP()ES( + + +)0 P() 3 68 PR( -f # output a column specifying file from which this event came + -w # adjust position values using WCS info + -x # adjust position values using WCS info and save old values)RP( + + +)0 P()BD(funmerge)ES( merges FITS data from one or more +)0 42 1 A(FITS Binary Table files)42 0 TN TL()Ec /AF f D( +or raw event files. +)0 P(The first argument to the program specifies the first input FITS table +or raw event file. If "stdin" is specified, data are read from the +standard input. Use )0 42 1 A(Funtools Bracket +Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions and row filters. Subsequent +arguments specify additional event files and tables to merge. \201NB: Stdin +cannot not be used for any of these additional input file arguments.\202 +The last argument is the output FITS file. The columns in each input table +must be identical. + +)0 P(If an input file begins with the '@' character, it is processed as an +include file, i.e., as a text file containing event file names \201as +well as blank lines and/or comment lines starting with the '#' sign\202. +If standard input is specified as an include file \201'@stdin'\202, then +file names are read from the standard input until EOF \201^D\202. Event +files and include files can be mixed on a command line. + +)0 P(Rows from each table are written sequentially to the output +file. If the switch )BD(-f [colname])ES( is specified on the command +line, an additional column is added to each row containing the number +of the file from which that row was taken \201starting from one\202. In +this case, the corresponding file names are stored in the header +parameters having the prefix )BD(FUNFIL)ES(, i.e., FUNFIL01, +FUNFIL02, etc. + +)0 P(Using the )BD(-w)ES( switch \201or )BD(-x)ES( switch as described +below\202, )BD(funmerge)ES( also can adjust the position column values +using the WCS information in each file. \201By position columns, we mean +the columns that the table is binned on, i.e., those columns defined +by the )BD(bincols=)ES( switch, or \201X,Y\202 by default.\202 To perform WCS +alignment, the WCS of the first file is taken as the base WCS. Each +position in subsequent files is adjusted by first converting it to the +sky coordinate in its own WCS coordinate system, then by converting +this sky position to the sky position of the base WCS, and finally +converting back to a pixel position in the base system. Note that in +order to perform WCS alignment, the appropriate WCS and TLMIN/TLMAX +keywords must already exist in each FITS file. +)0 P(When performing WCS alignment, you can save the original positions in +the output file by using the )BD(-x)ES( \201for "xtra"\202 switch instead +of the )BD(-w)ES( switch \201i.e., using this switch also implies using +)BD(-w)ES(\202 The old positions are saved in columns having the same +name as the original positional columns, with the added prefix "OLD_". +)0 P(Examples: + +)0 P(Merge two tables, and preserve the originating file number for +each row in the column called "FILE" \201along with the corresponding +file name in the header\202: +) 1 51 PR( [sh] funmerge -f "FILE" test.ev test2.ev merge.ev)RP( + +)0 P(Merge two tables with WCS alignment, saving the old position values in +2 additional columns: +) 1 44 PR( [sh] funmerge -x test.ev test2.ev merge.ev)RP( + +)0 P(This program only works on raw event files and binary tables. We have +not yet implemented image and array merging. + + + + +)0 2 17 H(funsky)WB 80 Sn()WB 14 Sn( - convert between image and sky coordinates)EA()EH( + + +)BD() 4 72 PR( funsky iname[ext] # RA,Dec \201deg\202 or image pix from stdin + funsky iname[ext] [lname] # RA, Dec \201deg\202 or image pix from list + funsky iname[ext] [col1] [col2] # named cols:units from stdin + funsky iname[ext] [lname] [col1] [col2] # named cols:units from list)RP()ES( + + +)0 P() 5 73 PR( -d # always use integer tlmin conversion \201as ds9 does\202 + -r # convert x,y to RA,Dec \201default: convert RA,Dec to x,y\202 + -o # include offset from the nominal target position \201in arcsec\202 + -v # display input values also \201default: display output only\202 + -T # output display in rdb format \201w/header,tab delimiters\202)RP( + + +)0 P(Funsky converts input sky coordinates \201RA, Dec\202 to image coordinates \201or vice +versa\202 using the WCS information contained in the specified FITS file. Several +calling sequences are supported in order to make it easy to specify +coordinate positions in different ways. + +)0 P(The first required argument is always the input FITS file \201or +extension\202 containing the WCS information in an extension header. Note +that the data from this file is not used. By default, the program +converts input RA and Dec values to X and Y using this WCS +information. If the WCS is associated with a FITS image, then the X,Y +values are image values. If the WCS is associated with a binary table, +then the X, Y values are physical values. To convert X,Y to RA and +Dec, use the )BD(-r)ES( \201reverse\202 switch. + +)0 P(If no other command arguments are supplied, then the input positions +are read from the standard input. Each line is assumed to contain a +single coordinate position consisting of an RA in degrees \201or X in +pixels\202 followed by a Dec in degrees \201or Y in pixels\202. The usual +delimiters are supported \201spaces, commas, tabs\202. For example: +) 9 52 PR( # read from stdin, default column names and units + [sh] funsky snr.ev + 22.982695 58.606523 # input RA \201hrs\202, Dec\201deg\202 + 510.00 510.00 + 22.982127 58.607634 # input + 512.00 510.50 + 22.981700 58.614301 # input + 513.50 513.50 + ^D # end of input)RP( + +)0 P(If a second argument is supplied, this argument is assumed to be +a file containing RA \201X\202 and Dec \201Y\202 positions. The file can either be +an ASCII table or a FITS binary table. The order of columns is +unimportant, if the table has a column header. In this case, the +names of the columns must be one of "RA", "DEC", or "X", "Y" for sky +to image and image to sky conversions, respectively. If the table has +no header, then once again, RA \201X\202 is assumed to first, followed +by DEC \201Y\202. +For example: +) 12 50 PR( # read from file, default column names and units + [sh] cat hd.in + RA DEC + --------- --------- + 22.982695 58.606523 + 22.982127 58.607634 + 22.981700 58.614301 + + [sh] funsky snr.ev hd.in + 510.00 510.00 + 512.00 510.50 + 513.50 513.50)RP( + +)0 P(If three arguments are supplied, then the input positions again are +read from the standard input. Each line is assumed to contain a single +coordinate position consisting of an RA \201or X in pixels\202 followed by a +Dec \201or Y in pixels\202, with the usual delimiters supported. However, +the second and third arguments now specify the column names and/or +sky units using a colon-delimited syntax: +) 1 19 PR( [colname]:[h|d|r])RP( +If the colname is omitted, the names default to "RA", "DEC", "X", "Y", +"COL1", or "COL2" as above. If the units are omitted, the default is degrees +for both RA and Dec. When the -r switch is used \201convert from image +to sky\202 the units are applied to the output instead of the input. The following +examples will serve to illustrate the options: +) 36 66 PR( # read from stdin, specifying column names \201def. units: degrees\202 + [sh] cat hd.in + MYRA MYDEC + --------- --------- + 22.982695 58.606523 + 22.982127 58.607634 + 22.981700 58.614301 + + [sh] funsky snr.ev MYRA MYDEC < hd.in + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + # read from stdin, specifying column names and units + [sh] cat dd.in + MYRA MYDEC + --------- --------- + 344.740432 58.606523 + 344.731900 58.607634 + 344.725500 58.614301 + + [sh] funsky snr.ev MYRA:d MYDEC:d < dd.in + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + # read stdin, convert image to sky, specifying output sky units + [sh] cat im.in + 510.00 510.00 + 512.00 510.50 + 513.50 513.50)WR( + + [sh] cat im.in | funsky -r snr.ev :d :d + 344.740432 58.606523 + 344.731900 58.607634 + 344.725500 58.614301)RP( + +)0 P(Finally, four command arguments specify both and input file and column names +and/or units: +) 22 64 PR( [sh] cat dd.in + MYRA MYDEC + --------- --------- + 344.740432 58.606523 + 344.731900 58.607634 + 344.725500 58.614301 + + [sh] funsky snr.ev dd.in MYRA:d MYDEC:d + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + # read file, convert image to sky, specifying output sky units + [sh] cat im.in + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + [sh] funsky -r snr.ev im.in :d :d + 344.740432 58.606523 + 344.731900 58.607634 + 344.725500 58.614301)RP( + +)0 P(By default, the output of funsky consists only of the converted coordinate +position\201s\202, one per output line. This makes parsing in shell scripts easy. +Use the )BD(-v)ES( \201verbose\202 switch to specify that the input +coordinates should be pre-pended to each line. For example: +) 16 53 PR( [sh] cat dd.in + MYRA MYDEC + --------- --------- + 344.740432 58.606523 + 344.731900 58.607634 + 344.725500 58.614301 + + [sh] funsky snr.ev dd.in MYRA:d MYDEC:d + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + [sh] funsky -v snr.ev dd.in MYRA:d MYDEC:d + 344.740432 58.606523 510.00 510.00 + 344.731900 58.607634 512.00 510.50 + 344.725500 58.614301 513.50 513.50)RP( + +)0 P(In addition, a full starbase table can be output using the )BD(-T)ES( +\201table\202 switch. This switch can be used with or without the -v +switch. If the -T and -v are both specified, then a descriptive header +parameters are output before the table \201mainly to remind you of the +sky units\202: +) 23 62 PR( # output table in non-verbose mode + [sh] funsky -T snr.ev dd.in MYRA:d MYDEC:d + X Y + ------------ ------------ + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + # output table in verbose mode + [sh] funsky -T -v snr.ev dd.in MYRA:d MYDEC:d + # IFILE = /Users/eric/data/snr.ev + # ICOL1 = MYRA + # ICOL2 = MYDEC + # IUNITS1 = d + # IUNITS2 = d + # OCOL1 = X + # OCOL2 = Y + + MYRA MYDEC X Y + ------------ ------------ ------------ ------------ + 344.740432 58.606523 510.00 510.00 + 344.731900 58.607634 512.00 510.50 + 344.725500 58.614301 513.50 513.50)RP( + +)0 P(Finally, the )BD(-d)ES( \201ds9\202 switch mimicks ds9's use of integer TLMIN +and TLMAX values for all coordinate transformations. FITS conventions +seem to call for use of floating point TLMIN and TLMAX when the data are +floats. This convention is followed by funsky but results in a +small discrepancy with ds9's converted values for floating point +data. We will remedy this conflict in the future, maybe. + + + + +)0 2 18 H(funtable)WB 81 Sn()WB 15 Sn( - copy selected rows from a Funtools file to a FITS binary table)EA()EH( + + +)BD() 1 62 PR(funtable [-a] [-i|-z] [-m] [-s cols] <iname> <oname> [columns])RP()ES( + + +)0 P() 5 61 PR( -a # append to existing output file as a table extension + -i # for image data, only generate X and Y columns + -m # for tables, write a separate file for each region + -s "col1 ..." # columns on which to sort + -z # for image data, output zero-valued pixels)RP( + + +)0 P()BD(funtable)ES( selects rows from the specified +)0 42 1 A(FITS Extension)42 0 TN TL()Ec /AF f D( +\201binary table only\202 of a FITS file, or from a non-FITS raw event +file, and writes those rows to a FITS binary table file. It also +will create a FITS binary table from an image or a raw array file. + +)0 P(The first argument to the program specifies the FITS file, raw event +file, or raw array file. If "stdin" is specified, data are read from +the standard input. Use )0 42 1 A(Funtools Bracket +Notation)42 0 TN TL()Ec /AF f D( to specify FITS extensions, and filters. The second +argument is the output FITS file. If "stdout" is specified, the FITS +binary table is written to the standard output. By default, all +columns of the input file are copied to the output file. Selected +columns can be output using an optional third argument in the form: +) 1 31 PR( "column1 column1 ... columnN")RP( + +)0 P(The )BD(funtable)ES( program generally is used to select rows from a +FITS binary table using +)0 52 1 A(Table Filters)52 0 TN TL()Ec /AF f D( +and/or +)0 54 1 A(Spatial Region Filters)54 0 TN TL()Ec /AF f D(. +For example, you can copy only selected rows \201and output only selected +columns\202 by executing in a command such as: +) 13 75 PR( [sh] funtable "test.ev[pha==1&)SY(\160)ES(==10]" stdout "x y pi pha" | fundisp stdin + X Y PHA PI + ------- ------- ------- --------- + 1 10 1 10 + 1 10 1 10 + 1 10 1 10 + 1 10 1 10 + 1 10 1 10 + 1 10 1 10 + 1 10 1 10 + 1 10 1 10 + 1 10 1 10 + 1 10 1 10)RP( +)0 P(The special column )BD($REGION)ES( can be specified to write the +region id of each row: +) 12 113 PR( [sh $] funtable "test.ev[time-\201int\202time>=.99&&annulus\2010 0 0 10 n=3\202]" stdout 'x y time $REGION' | fundisp stdin + X Y TIME REGION + -------- -------- --------------------- ---------- + 5 -6 40.99000000 3 + 4 -5 59.99000000 2 + -1 0 154.99000000 1 + -2 1 168.99000000 1 + -3 2 183.99000000 2 + -4 3 199.99000000 2 + -5 4 216.99000000 2 + -6 5 234.99000000 3 + -7 6 253.99000000 3)RP( +)0 P(Here only rows with the proper fractional time and whose position also is +within one of the three annuli are written. +)0 P(Columns can be excluded from display using a minus sign before the +column: +) 12 79 PR( [sh $] funtable "test.ev[time-\201int\202time>=.99]" stdout "-time" | fundisp stdin + X Y PHA PI DX DY + -------- -------- -------- ---------- ----------- ----------- + 5 -6 5 -6 5.50 -6.50 + 4 -5 4 -5 4.50 -5.50 + -1 0 -1 0 -1.50 0.50 + -2 1 -2 1 -2.50 1.50 + -3 2 -3 2 -3.50 2.50 + -4 3 -4 3 -4.50 3.50 + -5 4 -5 4 -5.50 4.50 + -6 5 -6 5 -6.50 5.50 + -7 6 -7 6 -7.50 6.50)RP( +All columns except the time column are written. +)0 P(In general, the rules for activating and de-activating columns are: +)UL()-1 LI( If only exclude columns are specified, then all columns but +the exclude columns will be activated. +)-1 LI( If only include columns are specified, then only the specified columns +are activated. +)-1 LI( If a mixture of include and exclude columns are specified, then +all but the exclude columns will be active; this last case +is ambiguous and the rule is arbitrary.)LU( +In addition to specifying columns names explicitly, the special +symbols )EM(+)ES( and )EM(-)ES( can be used to activate and +de-activate )EM(all)ES( columns. This is useful if you want to +activate the $REGION column along with all other columns. According +to the rules, the syntax "$REGION" only activates the region column +and de-activates the rest. Use "+ $REGION" to activate all +columns as well as the region column. + +)0 P(Ordinarily, only the selected table is copied to the output file. In +a FITS binary table, it sometimes is desirable to copy all of the +other FITS extensions to the output file as well. This can be done by +appending a '+' sign to the name of the extension in the input file +name. For example, the first command below copies only the EVENT table, +while the second command copies other extensions as well: +) 2 64 PR( [sh] funtable "/proj/rd/data/snr.ev[EVENTS]" events.ev + [sh] funtable "/proj/rd/data/snr.ev[EVENTS+]" eventsandmore.ev)RP( + +)0 P(If the input file is an image or a raw array file, then +)BD(funtable)ES( will generate a FITS binary table from the pixel +values in the image. Note that it is not possible to specify the +columns to output \201using command-line argument 3\202. Instead, there are +two ways to create such a binary table from an image. By default, a +3-column table is generated, where the columns are "X", "Y", and +"VALUE". For each pixel in the image, a single row \201event\202 is +generated with the "X" and "Y" columns assigned the dim1 and dim2 +values of the image pixel, respectively and the "VALUE" column +assigned the value of the pixel. With sort of table, running +)BD(funhist)ES( on the "VALUE" column will give the same results as +running )BD(funhist)ES( on the original image. + +)0 P(If the )BD(-i)ES( \201"individual" rows\202 switch is specified, then only +the "X" and "Y" columns are generated. In this case, each positive +pixel value in the image generates n rows \201events\202, where n is equal +to the integerized value of that pixel \201plus 0.5, for floating point +data\202. In effect, )BD(-i)ES( approximately recreates the rows of a +table that would have been binned into the input image. \201Of course, +this is only approximately correct, since the resulting x,y positions +are integerized.\202 + +)0 P(If the )BD(-s [col1 col2 ... coln])ES( \201"sort"\202 switch is specified, +the output rows of a binary table will be sorted using the +specified columns as sort keys. The sort keys must be scalar columns +and also must be part of the output file \201i.e. you cannot sort on a +column but not include it in the output\202. This facility uses the +)BD(_sort)ES( program \201included with funtools\202, which must be accessible +via your path. + +)0 P(For binary tables, the )BD(-m)ES( \201"multiple files"\202 switch will +generate a separate file for each region in the filter specification +i.e. each file contains only the rows from that region. Rows +which pass the filter but are not in any region also are put in a +separate file. + +)0 P(The separate output file names generated by the )BD(-m)ES( switch are +produced automatically from the root output file to contain the region id of +the associated region. \201Note that region ids start at 1, so that the +file name associated with id 0 contains rows that pass the filter but +are not in any given region.\202 Output file names are generated as follows: + +)UL()-1 LI( A $n specification can be used anywhere in the root file name \201suitably +quoted to protect it from the shell\202 and will be expanded to be the id +number of the associated region. For example: +) 1 78 PR( funtable -m input.fits'[cir\201512,512,1\202;cir\201520,520,1\202...]' 'foo.goo_$n.fits')RP( +will generate files named foo.goo_0.fits \201for rows not in any region but +still passing the filter\202, foo.goo_1.fits \201rows in region id #1, the first +region\202, foo.goo_2.fits \201rows in region id #2\202, etc. Note that single quotes +in the output root are required to protect the '$' from the shell. + +)-1 LI( If $n is not specified, then the region id will be placed before +the first dot \201.\202 in the filename. Thus: +) 1 73 PR( funtable -m input.fits'[cir\201512,512,1\202;cir\201520,520,1\202...]' foo.evt.fits)RP( +will generate files named foo0.evt.fits \201for rows not in any region but +still passing the filter\202, foo1.evt.fits \201rows in region id #1\202, +foo2.evt.fits \201rows in region id #2\202, etc. + +)-1 LI( If no dot is specified in the root output file name, then +the region id will be appended to the filename. Thus: +) 1 70 PR( funtable -m input.fits'[cir\201512,512,1\202;cir\201520,520,1\202...]' 'foo_evt')RP( +will generate files named foo_evt0 \201for rows not in any region but +still passing the filter\202, foo_evt1 \201rows in region id #1\202, +foo_evt2 \201rows in region id #2\202, etc.)LU( +The multiple file mechanism provide a simple way to generate +individual source data files with a single pass through the data. + +)0 P(By default, a new FITS file is created and the binary table is written +to the first extension. If the )BD(-a)ES( \201append\202 switch is specified, +the table is appended to an existing FITS file as a BINTABLE extension. +Note that the output FITS file must already exist. + +)0 P(If the )BD(-z)ES( \201"zero" pixel values\202 switch is specified and +)BD(-i)ES( is not specified, then pixels having a zero value will +be output with their "VALUE" column set to zero. Obviously, this +switch does not make sense when individual events are output. + + + + +)0 2 19 H(funtbl)WB 82 Sn()WB 16 Sn( - extract a table from Funtools ASCII output)EA()EH( + + +)BD() 1 61 PR(funtable [-c cols] [-h] [-n table] [-p prog] [-s sep] <iname>)RP()ES( + + +)0 P([NB: This program has been deprecated in favor of the ASCII text processing +support in funtools. You can now perform fundisp on funtools ASCII output +files \201specifying the table using bracket notation\202 to extract tables +and columns.] + +The )BD(funtbl)ES( script extracts a specified table \201without the +header and comments\202 from a funtools ASCII output file and writes the +result to the standard output. The first non-switch argument is the +ASCII input file name \201i.e. the saved output from funcnts, fundisp, +funhist, etc.\202. If no filename is specified, stdin is read. The +-n switch specifies which table \201starting from 1\202 to extract. The +default is to extract the first table. The -c switch is a +space-delimited list of column numbers to output, e.g. -c "1 3 5" +will extract the first three odd-numbered columns. The default is to +extract all columns. The -s switch specifies the separator string to +put between columns. The default is a single space. The -h switch +specifies that column names should be added in a header line before +the data is output. Without the switch, no header is prepended. The +-p program switch allows you to specify an awk-like program to run +instead of the default \201which is host-specific and is determined at +build time\202. The -T switch will output the data in rdb format \201i.e., +with a 2-row header of column names and dashes, and with data columns +separated by tabs\202. The -help switch will print out a message +describing program usage. + +)0 P(For example, consider the output from the following funcnts command: +) 37 82 PR( [sh] funcnts -sr snr.ev "ann 512 512 0 9 n=3" + # source + # data file: /proj/rd/data/snr.ev + # arcsec/pixel: 8 + # background + # constant value: 0.000000 + # column units + # area: arcsec**2 + # surf_bri: cnts/arcsec**2 + # surf_err: cnts/arcsec**2 + + # summed background-subtracted results + upto net_counts error background berror area surf_bri surf_err + ---- ------------ --------- ------------ --------- --------- --------- --------- + 1 147.000 12.124 0.000 0.000 1600.00 0.092 0.008 + 2 625.000 25.000 0.000 0.000 6976.00 0.090 0.004 + 3 1442.000 37.974 0.000 0.000 15936.00 0.090 0.002 + + + # background-subtracted results + reg net_counts error background berror area surf_bri surf_err + ---- ------------ --------- ------------ --------- --------- --------- --------- + 1 147.000 12.124 0.000 0.000 1600.00 0.092 0.008 + 2 478.000 21.863 0.000 0.000 5376.00 0.089 0.004 + 3 817.000 28.583 0.000 0.000 8960.00 0.091 0.003 + + + # the following source and background components were used: + source_region\201s\202 + ---------------- + ann 512 512 0 9 n=3)WR( + + reg counts pixels sumcnts sumpix + ---- ------------ --------- ------------ --------- + 1 147.000 25 147.000 25 + 2 478.000 84 625.000 109 + 3 817.000 140 1442.000 249)RP( +)0 P(There are four tables in this output. To extract the last one, you +can execute: +) 4 60 PR( [sh] funcnts -s snr.ev "ann 512 512 0 9 n=3" | funtbl -n 4 + 1 147.000 25 147.000 25 + 2 478.000 84 625.000 109 + 3 817.000 140 1442.000 249)RP( +Note that the output has been re-formatted so that only a single space +separates each column, with no extraneous header or comment information. + +)0 P(To extract only columns 1,2, and 4 from the last example \201but with a header +prepended and tabs between columns\202, you can execute: +) 5 82 PR( [sh] funcnts -s snr.ev "ann 512 512 0 9 n=3" | funtbl -c "1 2 4" -h -n 4 -s "\200t" + #reg counts sumcnts + 1 147.000 147.000 + 2 478.000 625.000 + 3 817.000 1442.000)RP( +)0 P(Of course, if the output has previously been saved in a file named +foo.out, the same result can be obtained by executing: +) 5 48 PR( [sh] funtbl -c "1 2 4" -h -n 4 -s "\200t" foo.out + #reg counts sumcnts + 1 147.000 147.000 + 2 478.000 625.000 + 3 817.000 1442.000)RP( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 20 H(Last)WB 83 Sn( updated: April 1, 2007)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (ds9.html) D +/Ti (Funtools and DS9 Image Display) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 17 Sn( + + +)0 2 21 H(FunDS9:)WB 85 Sn()WB 84 Sn( Funtools and DS9 Image Display)EA()EH( + + +)0 2 22 H(Summary)WB 86 Sn()EH( +Describes how funtools can be integrated into the ds9 Analysis menu. + + +)0 2 23 H(Description)WB 87 Sn()EH( +)0 P()R1 2 A(SAOImage/DS9)EA( is an astronomical imaging and data visualization +application used by astronomers around the world. DS9 can display +standard astronomical FITS images and binary tables, but also has +support for displaying raw array files, shared memory files, and data +files automatically retrieved via FTP and HTTP. Standard functional +capabilities include multiple frame buffers, colormap and region +manipulation, and many data scaling algorithms. DS9's advanced +features include TrueColor visuals, deep frame buffers, true +PostScript printing, and display of image mosaics. The program's +support of image tiling, "blinking", 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 \201using servers at SAO, StScI, or ESO\202. + +)0 P(DS9 can communicate with external programs such as Funtools using the +)R2 2 A(XPA)EA( +messaging system. In addition, programs can be integrated directly +into the DS9 GUI by means of a configurable Analysis menu. By +default, the DS9 Analysis menu contains algorithms deemed essential to +the core functions of DS9, e.g., display cross-cuts of data, +iso-intensity contours, and WCS grids. However, new programs can be +added to DS9 by creating a set-up file which can be loaded into DS9 +to reconfigure the Analysis menu. + +) 7 48 PR(The basic format of the analysis set-up file is: +)0 P( # + # Analysis command descriptions: + # menu label/description + # file templates for this command + # "menu" \201add to menu\202 |"bind" \201bind to key\202 + # analysis command line)RP( + +For example, the funcnts program can be specified in this way: +) 4 69 PR( Funcnts \201counts in source/bkgd regions; options: none\202 + * + menu + funcnts $filename $regions\201source,,\202 $regions\201background,,\202 | $text)RP( +As shown above, DS9 supports a macro facility to provide information +as well as task support to command lines. For example, the $regions +macro is expanded by DS9 to provide the current source and/or +background region to the analysis command. The $text macro is expanded +to generate a text window display. It also is possible to query for +parameters using a $param macro, plot data using a $plot macro, +etc. See the DS9 documentation for further details. + +)0 P(A set-up file called )0 2 A(funtools.ds9)EA( will +load some useful Funtools applications \201counts in regions, radial +profile, X-ray light curve and energy spectrum, 1D histogram\202 into the DS9 +Analysis menu \201version 2.1 and above\202. The file resides in the bin +directory where Funtools programs are installed. It can be manually +loaded into DS9 from the )BD(Load Analysis Commands ...)ES( option of +the )BD(Analysis)ES( menu. Alternatively, you can tell DS9 to load +this file automatically at start-up time by adding the pathname to the +)BD(Edit)ES(->)BD(Preferences)ES(->)BD(Analysis Menu)ES(->)BD(Analysis +File)ES( menu option. \201NB: make sure you select +)BD(Edit)ES(->)BD(Preferences)ES(->)BD(Save Preferences)ES( after setting +the pathname.\202 + +)0 P(The tasks in this setup file generally process the original disk-based +FITS file. Funcnts-based results \201radial profile, counts in regions\202 +are presented in WCS units, if present in the FITS header. For +situations where a disk file is not available \201e.g., image data +generated and sent to DS9's 'fits' XPA access point\202, versions of the +radial profile and counts in regions tasks also are also offered +utilizing DS9's internal image data. Results are presented in pixels. +Aside from the units, the results should be identical to the file-based +results. + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 24 H(Last)WB 88 Sn( updated: November 16, 2005)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (library.html) D +/Ti (Funtools Programming) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 18 Sn( + + +)0 2 25 H(FunLib:)WB 91 Sn()WB 89 Sn( the Funtools Programming Interface)EA()EH( + + +)0 2 26 H(Summary)WB 92 Sn()EH( +A description of the Funtools library. + + +)0 2 27 H(Introduction)WB 93 Sn()WB 90 Sn( to the Funtools Programming Interface)EH()EA( +)0 P(To create a Funtools application, you need to include +the funtools.h definitions file in your code: +) 1 23 PR( #include <funtools.h>)RP( + +You then call Funtools subroutines and functions to access Funtools data. +The most important routines are: +)UL( +)0 P()-1 LI( )0 25 1 A(FunOpen)25 0 TN TL()Ec /AF f D(: open a Funtools file +)-1 LI()0 35 1 A(FunInfoGet)35 0 TN TL()Ec /AF f D(: get info about an image or table +)-1 LI()0 26 1 A(FunImageGet)26 0 TN TL()Ec /AF f D(: retrieve image data +)-1 LI()0 28 1 A(FunImageRowGet)28 0 TN TL()Ec /AF f D(: retrieve image data by row +)-1 LI()0 27 1 A(FunImagePut)27 0 TN TL()Ec /AF f D(: output image data +)-1 LI()0 29 1 A(FunImageRowPut)29 0 TN TL()Ec /AF f D(: output image data by row +)-1 LI()0 32 1 A(FunColumnSelect)32 0 TN TL()Ec /AF f D(: select columns in a table for access +)-1 LI()0 30 1 A(FunTableRowGet)30 0 TN TL()Ec /AF f D(: retrieve rows from a table +)-1 LI()0 31 1 A(FunTableRowPut)31 0 TN TL()Ec /AF f D(: output rows to a table +)-1 LI( )0 40 1 A(FunClose)40 0 TN TL()Ec /AF f D(: close a Funtools file)LU( + +Your program must be linked against the libfuntools.a library, +along with the math library. The following libraries also might be required +on your system: +)UL()-1 LI( -lsocket -lnsl for socket support +)-1 LI( -ldl for dynamic loading)LU( +)0 P(For example, on a Solaris system using gcc, use the following link line: +) 1 53 PR( gcc -o foo foo.c -lfuntools -lsocket -lnsl -ldl -lm)RP( +On a Solaris system using Solaris cc, use the following link line: +) 1 48 PR( gcc -o foo foo.c -lfuntools -lsocket -lnsl -lm)RP( +On a Linux system using gcc, use the following link line: +) 1 38 PR( gcc -o foo foo.c -lfuntools -ldl -lm)RP( +Once configure has built a Makefile on your platform, the required +"extra" libraries \201aside from -lm, which always is required\202 are +specified in that file's EXTRA_LIBS variable. For example, under +Linux you will find: +) 3 26 PR( grep EXTRA_LIBS Makefile + EXTRA_LIBS = -ldl + ...)RP( + +)0 P(The Funtools library contains both the zlib library +\201http://www.gzip.org/zlib/\202 and Doug Mink's WCS library +\201http://tdc-www.harvard.edu/software/wcstools/\202. It is not necessary +to put these libraries on a Funtools link line. Include files +necessary for using these libraries are installed in the Funtools +include directory. + +)0 2 28 H(Funtools)WB 94 Sn()WB 20 Sn( Programming Tutorial)EA()EH( + +The +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( +function is used to open a FITS file, an array, or a raw event file: +) 4 79 PR( /* open the input FITS file for reading */ + ifun = FunOpen\201iname, "r", NULL\202; + /* open the output FITS file for writing, and connect it to the input file */ + ofun = FunOpen\201iname, "w", ifun\202;)RP( +A new output file can inherit header parameters automatically from +existing input file by passing the input Funtools handle as the last +argument to the new file's +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( +call as shown above. + +)0 P(For image data, you then can call +)0 26 1 A(FunImageGet\201\202)26 0 TN TL()Ec /AF f D( +to read an image into memory. +) 3 61 PR( float buf=NULL; + /* extract and bin the data section into an image buffer */ + buf = FunImageGet\201fun, NULL, "bitpix=-32"\202;)RP( +If the \201second\202 buf argument to this call is NULL, buffer space is allocated +automatically. The \201third\202 plist argument can be used to specify the +return data type of the array. If NULL is specified, the data type of +the input file is used. + +)0 P(To process an image buffer, you would generally make a call to +)0 35 1 A(FunInfoGet\201\202)35 0 TN TL()Ec /AF f D( to determine the +dimensions of the image \201which may have been changed from the original +file dimensions due to )0 49 1 A(Funtools image +sectioning)49 0 TN TL()Ec /AF f D( on the command line\202. In a FITS image, the index along +the dim1 axis varies most rapidly, followed by the dim2 axis, etc. +Thus, to access each pixel in an 2D image, use a double loop such as:)RP( + buf = FunImageGet\201fun, NULL, "bitpix=-32"\202; + FunInfoGet\201fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0\202; + for\201i=1; i<=dim2; i++\202{ + for\201j=1; j<=dim1; j++\202{ + ... process buf[\201\201i-1\202*dim1\202+\201j-1\202] ... + } + })RP( +or: +) 5 65 PR( buf = FunImageGet\201fun, NULL, "bitpix=-32"\202; + FunInfoGet\201fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0\202; + for\201i=0; i<\201dim1*dim2\202; i++\202{ + ... process buf[i] ... + })RP( +Finally, you can write the resulting image to disk using +)0 27 1 A(FunImagePut\201\202)27 0 TN TL()Ec /AF f D(: +) 1 48 PR( FunImagePut\201fun2, buf, dim1, dim2, -32, NULL\202;)RP( +Note that Funtools automatically takes care of book-keeping tasks such as +reading and writing FITS headers \201although you can, of course, write +your own header or add your own parameters to a header\202. + +)0 P(For binary tables and raw event files, a call to +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( +will be followed by a call to the +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( +routine to select columns to be read from the input file and/or +written to the output file: + +) 8 69 PR( typedef struct evstruct{ + double time; + int time2; + } *Ev, EvRec; + FunColumnSelect\201fun, sizeof\201EvRec\202, NULL, + "time", "D", "rw", FUN_OFFSET\201Ev, time\202, + "time2", "J", "w", FUN_OFFSET\201Ev, time2\202, + NULL\202;)RP( +Columns whose \201third\202 mode argument contains an "r" are "readable", +i.e., columns will be read from the input file and converted into the +data type specified in the call's second argument. These columns +values then are stored in the specified offset of the user record +structure. Columns whose mode argument contains a "w" are +"writable", i.e., these values will be written to the output file. +The +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( +routine also offers the option of automatically merging user +columns with the original input columns when writing the output +rows. + +)0 P(Once a set of columns has been specified, you can retrieve rows using +)0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D(, +and write the rows using +)0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D(: +) 17 70 PR( Ev ebuf, ev; + /* get rows -- let routine allocate the array */ + while\201 \201ebuf = \201Ev\202FunTableRowGet\201fun, NULL, MAXROW, NULL, &got\202\202 \202{ + /* process all rows */ + for\201i=0; i<got; i++\202{ + /* point to the i'th row */ + ev = ebuf+i; + /* time2 is generated here */ + ev->time2 = \201int\202\201ev->time+.5\202; + /* change the input time as well */ + ev->time = -\201ev->time/10.0\202; + } + /* write out this batch of rows with the new column */ + FunTableRowPut\201fun2, \201char *\202ebuf, got, 0, NULL\202; + /* free row data */ + if\201 ebuf \202 free\201ebuf\202; + })RP( +The input rows are retrieved into an array of user structs, which +can be accessed serially as shown above. Once again, Funtools +automatically takes care of book-keeping tasks such as reading and writing +FITS headers \201although you can, of course, write your own header or +add your own parameters to a header\202. + +)0 P(When all processing is done, you can call +)0 40 1 A(FunClose\201\202)40 0 TN TL()Ec /AF f D( +to close the file\201s\202: +) 2 17 PR( FunClose\201fun2\202; + FunClose\201fun\202;)RP( + +)0 P(These are the basics of processing FITS files \201and arrays or raw event +data\202 using Funtools. The routines in these examples are described in +more detail below, along with a few other routines that support +parameter access, data flushing, etc. + +)0 2 29 H(Compiling)WB 95 Sn()WB 22 Sn( and Linking)EA()EH( +)0 P(To create a Funtools application, a software developer will include +the funtools.h definitions file in Funtools code: +) 1 23 PR( #include <funtools.h>)RP( +The program is linked against the libfuntools.a library, along with the +math library \201and the dynamic load library, if the latter is available +on your system\202: +) 1 38 PR( gcc -o foo foo.c -lfuntools -ldl -lm)RP( +)0 P(If gcc is used, Funtools filtering can be performed using dynamically +loaded shared objects that are built at run-time. Otherwise, filtering +is performed using a slave process. +)0 P(Funtools has been built on the following systems: +)UL()-1 LI( Sun/Solaris 5.X +)-1 LI( Linux/RedHat Linux 5.X,6.X,7.X +)-1 LI( Dec Alpha/OSF1 V4.X +)-1 LI( WindowsNT/Cygwin 1.0 +)-1 LI( SGI/IRIX64 6.5)LU( + +)0 2 30 H(A)WB 96 Sn()WB 21 Sn( Short Digression on Subroutine Order)EA()EH( +)0 P(There is a natural order for all I/O access libraries. You would not +think of reading a file without first opening it, or writing a file +after closing it. A large part of the experiment in funtools is to use +the idea of "natural order" as a means of making programming +easier. We do this by maintaining the state of processing for a given +funtools file, so that we can do things like write headers and flush +extension padding at the right time, without you having to do it. + +)0 P(For example, if you open a new funtools file for writing using +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(, +then generate an array of image data and call +)0 27 1 A(FunImagePut\201\202)27 0 TN TL()Ec /AF f D(, +funtools knows to write the image header automatically. +There is no need to think about writing a standard header. +Of course, you can add parameters to the file first by +calling one of the +)0 38 1 A(FunParamPut\201\202)38 0 TN TL()Ec /AF f D( +routines, and these parameters will automatically be added +to the header when it is written out. There still is no +need to write the header explicitly. + +)0 P(Maintaining state in this way means that there are certain rules of +order which should be maintained in any funtools program. In particular, +we strongly recommend the following ordering rules be adhered to: + +)UL()-1 LI( When specifying that input extensions be copied to an output file +via a reference handle, open the output file )BD(before)ES( reading the +input file. \201Otherwise the initial copy will not occur\202. + +)-1 LI( Always write parameters to an output file using one of the +)0 38 1 A(FunParamPut\201\202)38 0 TN TL()Ec /AF f D( calls +)BD(before)ES( writing any data. \201This is a good idea for all FITS +libraries, to avoid having to recopy data is the FITS header needs +to be extended by adding a single parameter.\202 + +)-1 LI( If you retrieve an image, and need to know the data +type, use the FUN_SECT_BITPIX option of +)0 35 1 A(FunInfoGet\201\202)35 0 TN TL()Ec /AF f D(, +)BD(after)ES( calling +)0 26 1 A(FunImageGet\201\202)26 0 TN TL()Ec /AF f D(, since +it is possible to change the value of BITPIX from the latter. + +)-1 LI( When specifying that input extensions be copied to an output file +via a reference handle, close the output file )BD(before)ES( closing +input file, or else use +)0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( +explicitly on the output file +)BD(before)ES( closing the input file. \201Otherwise the final copy will +not occur\202.)LU( + +)0 P(We believe that these are the natural rules that are implied in most +FITS programming tasks. However, we recognize that making explicit use +of "natural order" to decide what automatic action to take on behalf +of the programmer is experimental. Therefore, if you find that your +needs are not compatible with our preferred order, please let us know +-- it will be most illuminating for us as we evaluate this experiment. + +)0 2 31 H(Funtools)WB 97 Sn()WB 41 Sn( Programming Examples)EA()EH( +)0 P(The following complete coding examples are provided to illustrate the +simplicity of Funtools applications. They can be found in the funtest +subdirectory of the Funtools distribution. In many cases, you should +be able to modify one of these programs to generate your own Funtools +program: +)UL()-1 LI()0 2 A(evread.c)EA(: read and write binary tables +)-1 LI()0 2 A(evcols.c)EA(: add column and rows to binary tables +)-1 LI()0 2 A(evmerge.c)EA(: merge new columns with existing columns +)-1 LI()0 2 A(evnext.c)EA(: manipulate raw data pointers +)-1 LI()0 2 A(imblank.c)EA(: blank out image values below a threshold +)-1 LI()0 2 A(asc2fits.c)EA(: convert a specific ASCII table to FITS binary table)LU( + +)0 2 32 H(The)WB 98 Sn()WB 24 Sn( Funtools Programming Reference Manual)EA()EH( +)0 P() 45 116 PR(#include <funtools.h> + +Fun )0 25 1 A(FunOpen\201char *name, char *mode, Fun ref\202)25 0 TN TL()Ec /AF f D( + +void *)0 26 1 A(FunImageGet\201Fun fun, void *buf, char *plist\202)26 0 TN TL()Ec /AF f D( + +int )0 27 1 A(FunImagePut\201Fun fun, void *buf, int dim1, int dim2, int bitpix, char *plist\202)27 0 TN TL()Ec /AF f D( + +void * )0 28 1 A(FunImageRowGet\201Fun fun, void *buf, int rstart, int rstop, char *plist\202)28 0 TN TL()Ec /AF f D( + +void * )0 29 1 A(FunImageRowPut\201Fun fun, void *buf, int rstart, int rstop, int dim1, int dim2, int bitpix, char *plist\202)29 0 TN TL()Ec /AF f D( + +int )0 32 1 A(FunColumnSelect\201Fun fun, int size, char *plist, ...\202)32 0 TN TL()Ec /AF f D( + +void )0 33 1 A(FunColumnActivate\201Fun fun, char *s, char *plist\202)33 0 TN TL()Ec /AF f D( + +int )0 34 1 A(FunColumnLookup\201Fun fun, char *s, int which, char **name, int *type, int *mode, int *offset, int *n, int *width\202)34 0 TN TL()Ec /AF f D( + +void *)0 30 1 A(FunTableRowGet\201Fun fun, void *rows, int maxrow, char *plist, int *nrow\202)30 0 TN TL()Ec /AF f D( + +int )0 31 1 A(FunTableRowPut\201Fun fun, void *rows, int nev, int idx, char *plist\202)31 0 TN TL()Ec /AF f D( + +int )0 37 1 A(FunParamGetb\201Fun fun, char *name, int n, int defval, int *got\202)37 0 TN TL()Ec /AF f D( + +int )0 37 1 A(FunParamGeti\201Fun fun, char *name, int n, int defval, int *got\202)37 0 TN TL()Ec /AF f D( + +double )0 37 1 A(FunParamGetd\201Fun fun, char *name, int n, double defval, int *got\202)37 0 TN TL()Ec /AF f D( + +char *)0 37 1 A(FunParamGets\201Fun fun, char *name, int n, char *defval, int *got\202)37 0 TN TL()Ec /AF f D( + +int )0 38 1 A(FunParamPutb\201Fun fun, char *name, int n, int value, char *comm, int append\202)38 0 TN TL()Ec /AF f D()WR( + +int )0 38 1 A(FunParamPuti\201Fun fun, char *name, int n, int value, char *comm, int append\202)38 0 TN TL()Ec /AF f D( + +int )0 38 1 A(FunParamPutd\201Fun fun, char *name, int n, double value, int prec, char *comm, int append\202)38 0 TN TL()Ec /AF f D( + +int )0 38 1 A(FunParamPuts\201Fun fun, char *name, int n, char *value, char *comm, int append\202)38 0 TN TL()Ec /AF f D( + +int )0 35 1 A(FunInfoGet\201Fun fun, int type, ...\202)35 0 TN TL()Ec /AF f D( + +int )0 36 1 A(FunInfoPut\201Fun fun, int type, ...\202)36 0 TN TL()Ec /AF f D( + +void )0 39 1 A(FunFlush\201Fun fun, char *plist\202)39 0 TN TL()Ec /AF f D( + +void )0 40 1 A(FunClose\201Fun fun\202)40 0 TN TL()Ec /AF f D()RP( + + + + +)0 2 33 H(FunOpen)WB 99 Sn()WB 25 Sn( - open a Funtools data file)EA()EH( + + +)BD() 3 47 PR( #include <funtools.h> + + Fun FunOpen\201char *name, char *mode, Fun ref\202;)RP()ES( + + +)0 P(The )BD(FunOpen\201\202)ES( routine opens a Funtools data file for reading or +appending, or creates a new FITS file for writing. The )BD(name)ES( +argument specifies the name of the Funtools data file to open. You can +use IRAF-style bracket notation to specify +)0 42 1 A(Funtools Files, Extensions, and Filters)42 0 TN TL()Ec /AF f D(. +A separate call should be made each time a different FITS extension is +accessed: +) 7 65 PR( Fun fun; + char *iname; + ... + if\201 !\201fun = FunOpen\201iname, "r", NULL\202\202 \202{ + fprintf\201stderr, "could not FunOpen input file: %s\200n", iname\202; + exit\2011\202; + })RP( +)0 P(If )BD(mode)ES( is "r", the file is opened for reading, and processing +is set up to begin at the specified extension. For reading, +)BD(name)ES( can be )BD(stdin)ES(, in which case the standard input is read. + +)0 P(If )BD(mode)ES( is "w", the file is created if it does not exist, or +opened and truncated for writing if it does exist. Processing starts +at the beginning of the file. The )BD(name)ES( can be )BD(stdout)ES(, +in which case the standard output is readied for processing. + +)0 P(If )BD(mode)ES( is "a", the file is created if it does not exist, or +opened if it does exist. Processing starts at the end of the file. +The )BD(name)ES( can be )BD(stdout)ES(, in which case the standard +output is readied for processing. + +)0 P(When a Funtools file is opened for writing or appending, a previously +opened )0 23 1 A(Funtools reference +handle)23 0 TN TL()Ec /AF f D( can be specified as the third argument. This handle +typically is associated with the input Funtools file that will be used +to generate the data for the output data. When a reference file is +specified in this way, the output file will inherit the \201extension\202 +header parameters from the input file: +) 8 67 PR( Fun fun, fun2; + ... + /* open input file */ + if\201 !\201fun = FunOpen\201argv[1], "r", NULL\202\202 \202 + gerror\201stderr, "could not FunOpen input file: %s\200n", argv[1]\202; + /* open the output FITS image, inheriting params from input */ + if\201 !\201fun2 = FunOpen\201argv[2], "w", fun\202\202 \202 + gerror\201stderr, "could not FunOpen output file: %s\200n", argv[2]\202;)RP( +Thus, in the above example, the output FITS binary table file will +inherit all of the parameters associated with the input binary table +extension. +)0 P(A file opened for writing with a +)0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( also +inherits the selected columns \201i.e. those columns chosen for +processing using the +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( routine\202 +from the reference file as its default columns. This makes it easy to +open an output file in such a way that the columns written to the +output file are the same as the columns read in the input file. Of +course, column selection can easily be tailored using the +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( routine. +In particular, it is easy to merge user-defined columns with the input +columns to generate a new file. See the +)0 2 A(evmerge)EA( for a complete example. + +)0 P(In addition, when a +)0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( +is supplied in a )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( call, +it is possible also to specify that all other extensions from the +reference file \201other than the input extension being processed\202 should +be copied from the reference file to the output file. This is useful, +for example, in a case where you are processing a FITS binary table +or image and you want to copy all of the other extensions to +the output file as well. Copy of other extensions is controlled by +adding a "C" or "c" to the mode string of the +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( call )BD(of the input +reference file)ES(. If "C" is specified, then other extensions are +)BD(always)ES( copied \201i.e., copy is forced by the application\202. If +"c" is used, then other extensions are copied if the user requests +copying by adding a plus sign "+" to the extension name in the bracket +specification. For example, the )BD(funtable)ES( program utilizes +"c" mode, giving users the option of copying all other extensions: +) 6 67 PR( /* open input file -- allow user copy of other extensions */ + if\201 !\201fun = FunOpen\201argv[1], "rc", NULL\202\202 \202 + gerror\201stderr, "could not FunOpen input file: %s\200n", argv[1]\202; + /* open the output FITS image, inheriting params from input */ + if\201 !\201fun2 = FunOpen\201argv[2], "w", fun\202\202 \202 + gerror\201stderr, "could not FunOpen output file: %s\200n", argv[2]\202;)RP( + +Thus, )BD(funtable)ES( supports either of these command lines: +) 4 60 PR( # copy only the EVENTS extension + csh> funtable "test.ev[EVENTS,circle\201512,512,10\202]" foo.ev + # copy ALL extensions + csh> funtable "test.ev[EVENTS+,circle\201512,512,10\202]" foo.ev)RP( + +)0 P(Use of a )0 23 1 A(Funtools reference +handle)23 0 TN TL()Ec /AF f D( implies that the input file is opened before the output +file. However, it is important to note that if copy mode \201"c" or "C"\202 +is specified for the input file, the actual input file open is delayed +until just after the output file is opened, since the copy of prior +extensions to the output file takes place while Funtools is seeking to +the specified input extension. This implies that the output file +should be opened before any I/O is done on the input file or else the +copy will fail. Note also that the copy of subsequent extension will +be handled automatically by +)0 40 1 A(FunClose\201\202)40 0 TN TL()Ec /AF f D( +if the output file is +closed before the input file. Alternatively, it can be done explicitly +by )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D(, but again, this +assumes that the input file still is open. + +)0 P(Upon success )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( returns a +Fun handle that is used in subsequent Funtools calls. On error, NULL +is returned. + + + + +)0 2 34 H(FunImageGet)WB 100 Sn()WB 26 Sn( - get an image or image section)EA()EH( + + +)BD() 3 52 PR( #include <funtools.h> + + void *FunImageGet\201Fun fun, void *buf, char *plist\202)RP()ES( + + +)0 P(The )BD(FunImageGet\201\202)ES( routine returns an binned image array of the +specified section of a Funtools data file. If the input data are +already of type image, the array is generated by extracting the +specified image section and then binning it according to the specified +bin factor. If the input data are contained in a binary table or raw +event file, the rows are binned on the columns specified by the +)BD(bincols=)ES( keyword \201using appropriate default columns as +necessary\202, after which the image section and bin factors are +applied. In both cases, the data is automatically converted from FITS +to native format, if necessary. +)0 P(The first argument is the Funtools handle returned by +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(. The second )BD(buf)ES( +argument is a pointer to a data buffer to fill. If NULL is specified, +FunImageGet will allocate a buffer of the appropriate size. Generally +speaking, you always want Funtools to allocate the buffer because +the image dimensions will be determined by +)0 49 1 A(Funtools image sectioning)49 0 TN TL()Ec /AF f D( +on the command line. +)0 P(The third )BD(plist)ES( \201i.e., parameter list\202 argument is a string +containing one or more comma-delimited )BD(keyword=value)ES( +parameters. It can be used to specify the return data type using the +)BD(bitpix=)ES( keyword. If no such keyword is specified in the plist +string, the data type of the returned image is the same as the data type +of the original input file, or is of type int for FITS binary tables. + +)0 P(If the )BD(bitpix=)ES( keyword is supplied in the plist string, the data +type of the returned image will be one of the supported FITS image +data types: +)UL()-1 LI( 8 unsigned char +)-1 LI( 16 short +)-1 LI( 32 int +)-1 LI( -32 float +)-1 LI( -64 double)LU( +For example: +) 4 57 PR( void *buf; + /* extract data section into an image buffer */ + if\201 !\201buf = FunImageGet\201fun, NULL, NULL\202\202 \202 + gerror\201stderr, "could not FunImageGet: %s\200n", iname\202;)RP( +will allocate buf and retrieve the image in the file data format. In +this case, you will have to determine the data type \201using the +FUN_SECT_BITPIX value in the +)0 35 1 A(FunInfoGet\201\202)35 0 TN TL()Ec /AF f D( +routine\202 +and then use a switch statement to process each data type: +) 17 65 PR( int bitpix; + void *buf; + unsigned char *cbuf; + short *sbuf; + int *ibuf; + ... + buf = FunImageGet\201fun, NULL, NULL\202; + FunInfoGet\201fun, FUN_SECT_BITPIX, &bitpix, 0\202; + /* set appropriate data type buffer to point to image buffer */ + switch\201bitpix\202{ + case 8: + cbuf = \201unsigned char *\202buf; break; + case 16: + sbuf = \201short *\202buf; break; + case 32: + ibuf = \201int *\202buf; break; + ...)RP( +See the +)0 2 A(imblank example code)EA( +for more details on how to process an image when the data type is not +specified beforehand. + +)0 P(It often is easier to specify the data type directly: +) 4 57 PR( double *buf; + /* extract data section into a double image buffer */ + if\201 !\201buf = FunImageGet\201fun, NULL, "bitpix=-64"\202\202 \202 + gerror\201stderr, "could not FunImageGet: %s\200n", iname\202;)RP( +will extract the image while converting to type double. + +)0 P(On success, a pointer to the image buffer is returned. \201This will be +the same as the second argument, if NULL is not passed to the latter.\202 +On error, NULL is returned. + +)0 P(In summary, to retrieve image or row data into a binned image, you simply +call FunOpen\201\202 followed by +)0 26 1 A(FunImageGet\201\202)26 0 TN TL()Ec /AF f D(. Generally, you +then will want to call +)0 35 1 A(FunInfoGet\201\202)35 0 TN TL()Ec /AF f D( +to retrieve the +axis dimensions \201and data type\202 of the section you are processing +\201so as to take account of sectioning and blocking of the original data\202: +) 20 73 PR( double *buf; + int i, j; + int dim1, dim2; + ... other declarations, etc. + + /* open the input FITS file */ + if\201 !\201fun = FunOpen\201argv[1], "rc", NULL\202\202 \202 + gerror\201stderr, "could not FunOpen input file: %s\200n", argv[1]\202; + + /* extract and bin the data section into a double float image buffer */ + if\201 !\201buf = FunImageGet\201fun, NULL, "bitpix=-64"\202\202 \202 + gerror\201stderr, "could not FunImageGet: %s\200n", argv[1]\202; + + /* get dimension information from funtools structure */ + FunInfoGet\201fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0\202; + + /* loop through pixels and reset values below limit to value */ + for\201i=0; i<dim1*dim2; i++\202{ + if\201 buf[i] <= blimit \202 buf[i] = bvalue; + })RP( + +)0 P(Another useful plist string value is "mask=all", which returns an +image populated with regions id values. Image pixels within a region +will contain the associated region id \201region values start at 1\202, and +otherwise will contain a 0 value. Thus, the returned image is a +region mask which can be used to process the image data \201which +presumably is retrieved by a separate call to FunImageGet\202 pixel by +pixel. + +)0 P(If a FITS binary table or a non-FITS raw event file is being binned +into an image, it is necessary to specify the two columns that will be +used in the 2D binning. This usually is done on the command line +using the )BD(bincols=\201x,y\202)ES( keyword: +) 1 46 PR( funcnts "foo.ev[EVENTS,bincols=\201detx,dety\202]")RP( + +)0 P(The full form of the )BD(bincols=)ES( specifier is: +) 1 77 PR( bincols=\201[xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]]]\202)RP( +where the tlmin, tlmax, and binsiz specifiers determine the image binning +dimensions: +) 2 56 PR( dim = \201tlmax - tlmin\202/binsiz \201floating point data\202 + dim = \201tlmax - tlmin\202/binsiz + 1 \201integer data\202)RP( +These tlmin, tlmax, and binsiz specifiers can be omitted if TLMIN, +TLMAX, and TDBIN header parameters \201respectively\202 are present in the +FITS binary table header for the column in question. Note that 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. + +)0 P(If )BD(bincols)ES( is not specified on the command line, Funtools tries +to use appropriate defaults: it looks for the environment variable +FITS_BINCOLS \201or FITS_BINKEY\202. Then it looks for the Chandra +parameters CPREF \201or PREFX\202 in the FITS binary table header. Failing +this, it looks for columns named "X" and "Y" and if these are not +found, it looks for columns containing the characters "X" and "Y". +)0 P(See )0 50 1 A(Binning FITS Binary Tables and +Non-FITS Event Files)50 0 TN TL()Ec /AF f D( for more information. + + + + +)0 2 35 H(FunImagePut)WB 101 Sn()WB 27 Sn( - put an image to a Funtools file)EA()EH( + +)BD() 4 69 PR( #include <funtools.h> + + int FunImagePut\201Fun fun, void *buf, int dim1, int dim2, int bitpix, + char *plist\202)RP()ES( + + +The )BD(FunImagePut\201\202)ES( routine outputs an image array to a FITS +file. The image is written either as a primary header/data unit or as +an image extension, depending on whether other data have already been +written to the file. That is, if the current file position is at the +beginning of the file, a primary HDU is written. Otherwise, an +image extension is written. + +)0 P(The first argument is the Funtools handle returned by +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(. The second )BD(buf)ES( +argument is a pointer to a data buffer to write. The )BD(dim1)ES(and +)BD(dim2)ES( arguments that follow specify the dimensions of the image, +where dim1 corresponds to naxis1 and dim2 corresponds to naxis2. The +)BD(bitpix)ES( argument specifies the data type of the image and can +have the following FITS-standard values: +)UL()-1 LI( 8 unsigned char +)-1 LI( 16 short +)-1 LI( 32 int +)-1 LI( -32 float +)-1 LI( -64 double)LU( + +)0 P(When )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D( is first +called for a given image, Funtools checks to see if the primary header +has already been written \201by having previously written an image or a +binary table.\202 If not, this image is written to the primary HDU. +Otherwise, it is written to an image extension. +)0 P(Thus, a simple program to generate a FITS image might look like this: +) 16 67 PR( int i; + int dim1=512, dim2=512; + double *dbuf; + Fun fun; + dbuf = malloc\201dim1*dim2*sizeof\201double\202\202; + /* open the output FITS image, preparing to copy input params */ + if\201 !\201fun = FunOpen\201argv[1], "w", NULL\202\202 \202 + gerror\201stderr, "could not FunOpen output file: %s\200n", argv[1]\202; + for\201i=0; i<\201dim1*dim2\202; i++\202{ + ... fill dbuf ... + } + /* put the image \201header will be generated automatically */ + if\201 !FunImagePut\201fun, buf, dim1, dim2, -64, NULL\202 \202 + gerror\201stderr, "could not FunImagePut: %s\200n", argv[1]\202; + FunClose\201fun\202; + free\201dbuf\202;)RP( + +)0 P(In addition, if a +)0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( +was specified when this table was opened, the +parameters from this +)0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( +are merged into the new image +header. Furthermore, if a reference image was specified during +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(, the values of +)BD(dim1)ES(, )BD(dim2)ES(, and )BD(bitpix)ES( in the calling sequence +can all be set to 0. In this case, default values are taken from the +reference image section. This is useful if you are reading an image +section in its native data format, processing it, and then writing +that section to a new FITS file. See the +)0 2 A(imblank example code)EA(. + +)0 P(The data are assumed to be in the native machine format and will +automatically be swapped to FITS big-endian format if necessary. This +behavior can be over-ridden with the )BD(convert=[true|false])ES( +keyword in the )BD(plist)ES( param list string. + +)0 P(When you are finished writing the image, you should call +)0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( to write out the FITS +image padding. However, this is not necessary if you subsequently call +FunClose\201\202 without doing any other I/O to the FITS file. + + + + +)0 2 36 H(FunImageRowGet)WB 102 Sn()WB 28 Sn( - get row\201s\202 of an image)EA()EH( + + +)BD() 4 65 PR( #include <funtools.h> + + void *FunImageRowGet\201Fun fun, void *buf, int rstart, int rstop, + char *plist\202)RP()ES( + + +)0 P(The )BD(FunImageRowGet\201\202)ES( routine returns one or more image rows +from the specified section of a Funtools data file. If the input data +are of type image, the array is generated by extracting the specified +image rows and then binning them according to the specified bin +factor. If the input data are contained in a binary table or raw +event file, the rows are binned on the columns specified by the +)BD(bincols=)ES( keyword \201using appropriate default columns as needed\202, +after which the image section and bin factors are applied. + +)0 P(The first argument is the Funtools handle returned by +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(. The second )BD(buf)ES( +argument is a pointer to a data buffer to fill. If NULL is specified, +FunImageGet\201\202 will allocate a buffer of the appropriate size. + +)0 P(The third and fourth arguments specify the first and last row to +retrieve. Rows are counted starting from 1, up to the value of +FUN_YMAX\201fun\202. The final )BD(plist)ES( \201i.e., parameter list\202 argument +is a string containing one or more comma-delimited +)BD(keyword=value)ES( parameters. It can be used to specify the return +data type using the )BD(bitpix=)ES( keyword. If no such keyword is +specified in the plist string, the data type of the image is the same +as the data type of the original input file, or is of type int for +FITS binary tables. + +)0 P(If the )BD(bitpix=)ES(value is supplied in the plist string, the data +type of the returned image will be one of the supported FITS image +data types: +)UL()-1 LI( 8 unsigned char +)-1 LI( 16 short +)-1 LI( 32 int +)-1 LI( -32 float +)-1 LI( -64 double)LU( + +)0 P(For example: +) 17 65 PR( double *drow; + Fun fun; + ... open files ... + /* get section dimensions */ + FunInfoGet\201fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0\202; + /* allocate one line's worth */ + drow = malloc\201dim1*sizeof\201double\202\202; + /* retrieve and process each input row \201starting at 1\202 */ + for\201i=1; i <= dim2; i++\202{ + if\201 !FunImageRowGet\201fun, drow, i, i, "bitpix=-64"\202 \202 + gerror\201stderr, "can't FunImageRowGet: %d %s\200n", i, iname\202; + /* reverse the line */ + for\201j=1; j<=dim1; j++\202{ + ... process drow[j-1] ... + } + } + ...)RP( + +)0 P(On success, a pointer to the image buffer is returned. \201This will be +the same as the second argument, if NULL is not passed to the latter.\202 +On error, NULL is returned. Note that the considerations described +above for specifying binning columns in +)0 26 1 A(FunImageGet\201\202)26 0 TN TL()Ec /AF f D( also apply to +)BD(FunImageRowGet\201\202)ES(. + + + + +)0 2 37 H(FunImageRowPut)WB 103 Sn()WB 29 Sn( - put row\201s\202 of an image)EA()EH( + + +)BD() 4 67 PR( #include <funtools.h> + + void *FunImageRowPut\201Fun fun, void *buf, int rstart, int rstop, + int dim1, int dim2, int bitpix, char *plist\202)RP()ES( + + +)0 P(The )BD(FunImageRowPut\201\202)ES( routine writes one or more image rows to +the specified FITS image file. The first argument is the Funtools +handle returned by )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(. +The second )BD(buf)ES( argument is a pointer to the row data buffer, +while the third and fourth arguments specify the starting and ending +rows to write. Valid rows values range from 1 to dim2, i.e., row is +one-valued. + +)0 P(The )BD(dim1)ES(and )BD(dim2)ES( arguments that follow specify the +dimensions, where dim1 corresponds to naxis1 and dim2 corresponds to +naxis2. The )BD(bitpix)ES( argument data type of the image and can +have the following FITS-standard values: +)UL()-1 LI( 8 unsigned char +)-1 LI( 16 short +)-1 LI( 32 int +)-1 LI( -32 float +)-1 LI( -64 double)LU( + +For example: +) 16 65 PR( double *drow; + Fun fun, fun2; + ... open files ... + /* get section dimensions */ + FunInfoGet\201fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0\202; + /* allocate one line's worth */ + drow = malloc\201dim1*sizeof\201double\202\202; + /* retrieve and process each input row \201starting at 1\202 */ + for\201i=1; i <= dim2; i++\202{ + if\201 !FunImageRowGet\201fun, drow, i, i, "bitpix=-64"\202 \202 + gerror\201stderr, "can't FunImageRowGet: %d %s\200n", i, iname\202; + ... process drow ... + if\201 !FunImageRowPut\201fun2, drow, i, i, 64, NULL\202 \202 + gerror\201stderr, "can't FunImageRowPut: %d %s\200n", i, oname\202; + } + ...)RP( + +)0 P(The data are assumed to be in the native machine format and will +automatically be swapped to big-endian FITS format if necessary. This +behavior can be over-ridden with the )BD(convert=[true|false])ES( +keyword in the )BD(plist)ES( param list string. + +)0 P(When you are finished writing the image, you should call +)0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( to write out the FITS +image padding. However, this is not necessary if you subsequently call +FunClose\201\202 without doing any other I/O to the FITS file. + + + + +)0 2 38 H(FunColumnSelect)WB 104 Sn()WB 32 Sn( - select Funtools columns)EA()EH( + +)BD() 11 73 PR( #include <funtools.h> + + int FunColumnSelect\201Fun fun, int size, char *plist, + char *name1, char *type1, char *mode1, int offset1, + char *name2, char *type2, char *mode2, int offset2, + ..., + NULL\202 + + int FunColumnSelectArr\201Fun fun, int size, char *plist, + char **names, char **types, char **modes, + int *offsets, int nargs\202;)RP()ES( + + +The )BD(FunColumnSelect\201\202)ES( routine is used to select the columns +from a Funtools binary table extension or raw event file for +processing. This routine allows you to specify how columns in a file +are to be read into a user record structure or written from a user +record structure to an output FITS file. + +)0 P(The first argument is the Fun handle associated with this set of +columns. The second argument specifies the size of the user record +structure into which columns will be read. Typically, the sizeof\201\202 +macro is used to specify the size of a record structure. The third +argument allows you to specify keyword directives for the selection +and is described in more detail below. + +)0 P(Following the first three required arguments is a variable length list of +column specifications. Each column specification will consist of four +arguments: +)UL()-1 LI( )BD(name)ES(: the name of the column + +)-1 LI( )BD(type)ES(: the data type of the column as it will be stored in +the user record struct \201not the data type of the input file\202. The +following basic data types are recognized: +)UL()-1 LI(A: ASCII characters +)-1 LI(B: unsigned 8-bit char +)-1 LI(I: signed 16-bit int +)-1 LI(U: unsigned 16-bit int \201not standard FITS\202 +)-1 LI(J: signed 32-bit int +)-1 LI(V: unsigned 32-bit int \201not standard FITS\202 +)-1 LI(E: 32-bit float +)-1 LI(D: 64-bit float)LU( +The syntax used is similar to that which defines the TFORM parameter +in FITS binary tables. That is, a numeric repeat value can precede +the type character, so that "10I" means a vector of 10 short ints, "E" +means a single precision float, etc. Note that the column value from +the input file will be converted to the specified data type as the +data is read by +)0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D(. + +)0 P([ A short digression regarding bit-fields: Special attention is +required when reading or writing the FITS bit-field type +\201"X"\202. Bit-fields almost always have a numeric repeat character +preceding the 'X' specification. Usually this value is a multiple of 8 +so that bit-fields fit into an integral number of bytes. For all +cases, the byte size of the bit-field B is \201N+7\202/8, where N is the +numeric repeat character. + +)0 P(A bit-field is most easily declared in the user struct as an array of +type char of size B as defined above. In this case, bytes are simply +moved from the file to the user space. If, instead, a short or int +scalar or array is used, then the algorithm for reading the bit-field +into the user space depends on the size of the data type used along +with the value of the repeat character. That is, if the user data +size is equal to the byte size of the bit-field, then the data is +simply moved \201possibly with endian-based byte-swapping\202 from one to +the other. If, on the other hand, the data storage is larger than the +bit-field size, then a data type cast conversion is performed to move +parts of the bit-field into elements of the array. Examples will help +make this clear: + +)UL()-1 LI( If the file contains a 16X bit-field and user space specifies a 2B +char array[2], then the bit-field is moved directly into the char array. + +)-1 LI( If the file contains a 16X bit-field and user space specifies a 1I +scalar short int, then the bit-field is moved directly into the short int. + +)-1 LI( If the file contains a 16X bit-field and user space specifies a 1J +scalar int, then the bit-field is type-cast to unsigned int before +being moved \201use of unsigned avoids possible sign extension\202. + +)-1 LI( If the file contains a 16X bit-field and user space specifies a 2J +int array[2], then the bit-field is handled as 2 chars, each of which +are type-cast to unsigned int before being moved \201use of unsigned +avoids possible sign extension\202. + +)-1 LI( If the file contains a 16X bit-field and user space specifies a 1B +char, then the bit-field is treated as a char, i.e., truncation will +occur. + +)-1 LI( If the file contains a 16X bit-field and user space specifies a 4J +int array[4], then the results are undetermined. +)LU( +For all user data types larger than char, the bit-field is byte-swapped +as necessary to convert to native format, so that bits in the +resulting data in user space can be tested, masked, etc. in the same +way regardless of platform.] + +)0 P(In addition to setting data type and size, the )BD(type)ES( +specification allows a few ancillary parameters to be set, using the +full syntax for )BD(type)ES(: +) 1 53 PR( [@][n]<type>[[['B']poff]][:[tlmin[:tlmax[:binsiz]]]])RP( + +)0 P(The special character "@" can be prepended to this specification to +indicated that the data element is a pointer in the user record, +rather than an array stored within the record. + +)0 P(The [n] value is an integer that specifies the +number of elements that are in this column \201default is 1\202. TLMIN, +TLMAX, and BINSIZ values also can be specified for this column after +the type, separated by colons. If only one such number is specified, +it is assumed to be TLMAX, and TLMIN and BINSIZ are set to 1. + +)0 P(The [poff] value can be used to specify the offset into an +array. By default, this offset value is set to zero and the data +specified starts at the beginning of the array. The offset usually +is specified in terms of the data type of the column. Thus an offset +specification of [5] means a 20-byte offset if the data type is a +32-bit integer, and a 40-byte offset for a double. If you want to +specify a byte offset instead of an offset tied to the column data type, +precede the offset value with 'B', e.g. [B6] means a 6-bye offset, +regardless of the column data type. + +The [poff] is especially useful in conjunction with the pointer @ +specification, since it allows the data element to anywhere stored +anywhere in the allocated array. For example, a specification such as +"@I[2]" specifies the third \201i.e., starting from 0\202 element in the +array pointed to by the pointer value. A value of "@2I[4]" specifies +the fifth and sixth values in the array. For example, consider the +following specification: ) 12 67 PR( typedef struct EvStruct{ + short x[4], *atp; + } *Event, EventRec; + /* set up the \201hardwired\202 columns */ + FunColumnSelect\201 fun, sizeof\201EventRec\202, NULL, + "2i", "2I ", "w", FUN_OFFSET\201Event, x\202, + "2i2", "2I[2]", "w", FUN_OFFSET\201Event, x\202, + "at2p", "@2I", "w", FUN_OFFSET\201Event, atp\202, + "at2p4", "@2I[4]", "w", FUN_OFFSET\201Event, atp\202, + "atp9", "@I[9]", "w", FUN_OFFSET\201Event, atp\202, + "atb20", "@I[B20]", "w", FUN_OFFSET\201Event, atb\202, + NULL\202;)RP( +Here we have specified the following columns: +)UL()-1 LI( 2i: two short ints in an array which is stored as part the +record +)-1 LI( 2i2: the 3rd and 4th elements of an array which is stored +as part of the record +)-1 LI( an array of at least 10 elements, not stored in the record but +allocated elsewhere, and used by three different columns: +)UL()-1 LI( at2p: 2 short ints which are the first 2 elements of the allocated array +)-1 LI( at2p4: 2 short ints which are the 5th and 6th elements of +the allocated array +)-1 LI( atp9: a short int which is the 10th element of the allocated array)LU( +)-1 LI( atb20: a short int which is at byte offset 20 of another allocated array)LU( +In this way, several columns can be specified, all of which are in a +single array. )BD(NB)ES(: it is the programmer's responsibility to +ensure that specification of a positive value for poff does not point +past the end of valid data. + +)-1 LI( )BD(read/write mode)ES(: "r" means that the column is read from an +input file into user space by +)0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D(, "w" means that +the column is written to an output file. Both can specified at the same +time. + +)-1 LI( )BD(offset)ES(: the offset into the user data to store +this column. Typically, the macro FUN_OFFSET\201recname, colname\202 is used +to define the offset into a record structure.)LU( + +)0 P(When all column arguments have been specified, a final NULL argument +must added to signal the column selection list. + +)0 P(As an alternative to the varargs +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( +routine, a non-varargs routine called +)0 32 1 A(FunColumnSelectArr\201\202)32 0 TN TL()Ec /AF f D( +also is available. The first three arguments \201fun, size, plist\202 of this +routine are the same as in +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D(. +Instead of a variable +argument list, however, +)0 32 1 A(FunColumnSelectArr\201\202)32 0 TN TL()Ec /AF f D( +takes 5 additional arguments. The first 4 arrays arguments contain the +names, types, modes, and offsets, respectively, of the columns being +selected. The final argument is the number of columns that are +contained in these arrays. It is the user's responsibility to free +string space allocated in these arrays. + +)0 P(Consider the following example: +) 12 54 PR( typedef struct evstruct{ + int status; + float pi, pha, *phas; + double energy; + } *Ev, EvRec; + + FunColumnSelect\201fun, sizeof\201EvRec\202, NULL, + "status", "J", "r", FUN_OFFSET\201Ev, status\202, + "pi", "E", "r", FUN_OFFSET\201Ev, pi\202, + "pha", "E", "r", FUN_OFFSET\201Ev, pha\202, + "phas", "@9E", "r", FUN_OFFSET\201Ev, phas\202, + NULL\202;)RP( +)0 P(Each time a row is read into the Ev struct, the "status" column is +converted to an int data type \201regardless of its data type in the +file\202 and stored in the status value of the struct. Similarly, "pi" +and "pha", and the phas vector are all stored as floats. Note that the +"@" sign indicates that the "phas" vector is a pointer to a 9 element +array, rather than an array allocated in the struct itself. The row +record can then be processed as required: +) 9 70 PR( /* get rows -- let routine allocate the row array */ + while\201 \201ebuf = \201Ev\202FunTableRowGet\201fun, NULL, MAXROW, NULL, &got\202\202 \202{ + /* process all rows */ + for\201i=0; i<got; i++\202{ + /* point to the i'th row */ + ev = ebuf+i; + ev->pi = \201ev->pi+.5\202; + ev->pha = \201ev->pi-.5\202; + })RP( + +)0 P()0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( +can also be called to define "writable" columns in order to generate a FITS +Binary Table, without reference to any input columns. For +example, the following will generate a 4-column FITS binary table when +)0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D( is used to +write Ev records: + +) 12 56 PR( typedef struct evstruct{ + int status; + float pi, pha + double energy; + } *Ev, EvRec; + + FunColumnSelect\201fun, sizeof\201EvRec\202, NULL, + "status", "J", "w", FUN_OFFSET\201Ev, status\202, + "pi", "E", "w", FUN_OFFSET\201Ev, pi\202, + "pha", "E", "w", FUN_OFFSET\201Ev, pha\202, + "energy", "D", "w", FUN_OFFSET\201Ev, energy\202, + NULL\202;)RP( +All columns are declared to be write-only, so presumably the column +data is being generated or read from some other source. + +)0 P(In addition, +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( +can be called to define )BD(both)ES( "readable" and "writable" columns. +In this case, the "read" columns +are associated with an input file, while the "write" columns are +associated with the output file. Of course, columns can be specified as both +"readable" and "writable", in which case they are read from input +and \201possibly modified data values are\202 written to the output. +The +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( +call itself is made by passing the input Funtools handle, and it is +assumed that the output file has been opened using this input handle +as its +)0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D(. + +)0 P(Consider the following example: +) 13 54 PR( typedef struct evstruct{ + int status; + float pi, pha, *phas; + double energy; + } *Ev, EvRec; + + FunColumnSelect\201fun, sizeof\201EvRec\202, NULL, + "status", "J", "r", FUN_OFFSET\201Ev, status\202, + "pi", "E", "rw", FUN_OFFSET\201Ev, pi\202, + "pha", "E", "rw", FUN_OFFSET\201Ev, pha\202, + "phas", "@9E", "rw", FUN_OFFSET\201Ev, phas\202, + "energy", "D", "w", FUN_OFFSET\201Ev, energy\202, + NULL\202;)RP( +As in the "read" example above, each time an row is read into the Ev +struct, the "status" column is converted to an int data type +\201regardless of its data type in the file\202 and stored in the status +value of the struct. Similarly, "pi" and "pha", and the phas vector +are all stored as floats. Since the "pi", "pha", and "phas" variables +are declared as "writable" as well as "readable", they also will be +written to the output file. Note, however, that the "status" variable +is declared as "readable" only, and hence it will not be written to +an output file. Finally, the "energy" column is declared as +"writable" only, meaning it will not be read from the input file. In +this case, it can be assumed that "energy" will be calculated in the +program before being output along with the other values. + +)0 P(In these simple cases, only the columns specified as "writable" will +be output using +)0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D(. However, +it often is the case that you want to merge the user columns back in +with the input columns, even in cases where not all of the input +column names are explicitly read or even known. For this important +case, the )BD(merge=[type])ES( keyword is provided in the plist string. + +)0 P(The )BD(merge=[type])ES( keyword tells Funtools to merge the columns from +the input file with user columns on output. It is normally used when +an input and output file are opened and the input file provides the +)0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( +for the output file. In this case, each time +)0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D( is called, the +raw input rows are saved in a special buffer. If +)0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D( then is called +\201before another call to +)0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D(\202, the contents +of the raw input rows are merged with the user rows according to the +value of )BD(type)ES( as follows: + +)UL()-1 LI( )BD(update)ES(: add new user columns, and update value of existing ones \201maintaining the input data type\202 + +)-1 LI( )BD(replace)ES(: add new user columns, and replace the data type +and value of existing ones. \201Note that if tlmin/tlmax values are not +specified in the replacing column, but are specified in the original +column being replaced, then the original tlmin/tlmax values are used +in the replacing column.\202 + +)-1 LI( )BD(append)ES(: only add new columns, do not "replace" or "update" existing ones)LU( + +)0 P(Consider the example above. If )BD(merge=update)ES( is specified in the +plist string, then "energy" will be added to the input columns, and +the values of "pi", "pha", and "phas" will be taken from the user +space \201i.e., the values will be updated from the original values, if +they were changed by the program\202. The data type for "pi", "pha", and +"phas" will be the same as in the original file. If +)BD(merge=replace)ES( is specified, both the data type and value of +these three input columns will be changed to the data type and value +in the user structure. If )BD(merge=append)ES( is specified, none of +these three columns will be updated, and only the "energy" column will +be added. Note that in all cases, "status" will be written from the +input data, not from the user record, since it was specified as read-only. + +)0 P(Standard applications will call +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( +to define user columns. However, if this routine is not called, the +default behavior is to transfer all input columns into user space. For +this purpose a default record structure is defined such that each data +element is properly aligned on a valid data type boundary. This +mechanism is used by programs such as fundisp and funtable to process +columns without needing to know the specific names of those columns. +It is not anticipated that users will need such capabilities \201contact +us if you do!\202 + +)0 P(By default, )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( +reads/writes rows to/from an "array of structs", where each struct contains +the column values for a single row of the table. This means that the +returned values for a given column are not contiguous. You can +set up the IO to return a "struct of arrays" so that each of the +returned columns are contiguous by specifying )BD(org=structofarrays)ES( +\201abbreviation: )BD(org=soa)ES(\202 in the plist. +\201The default case is )BD(org=arrayofstructs)ES( or )BD(org=aos)ES(.\202 + +)0 P(For example, the default setup to retrieve rows from a table would be +to define a record structure for a single event and then call + )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( +as follows: +) 14 73 PR( typedef struct evstruct{ + short region; + double x, y; + int pi, pha; + double time; + } *Ev, EvRec; + + got = FunColumnSelect\201fun, sizeof\201EvRec\202, NULL, + "x", "D:10:10", mode, FUN_OFFSET\201Ev, x\202, + "y", "D:10:10", mode, FUN_OFFSET\201Ev, y\202, + "pi", "J", mode, FUN_OFFSET\201Ev, pi\202, + "pha", "J", mode, FUN_OFFSET\201Ev, pha\202, + "time", "1D", mode, FUN_OFFSET\201Ev, time\202, + NULL\202;)RP( +Subsequently, each call to +FunTableRowGet\201\202)EA( +will return an array of structs, one for each returned row. If instead you +wanted to read columns into contiguous arrays, you specify )BD(org=soa)ES(: +) 14 72 PR( typedef struct aevstruct{ + short region[MAXROW]; + double x[MAXROW], y[MAXROW]; + int pi[MAXROW], pha[MAXROW]; + double time[MAXROW]; + } *AEv, AEvRec; + + got = FunColumnSelect\201fun, sizeof\201AEvRec\202, "org=soa", + "x", "D:10:10", mode, FUN_OFFSET\201AEv, x\202, + "y", "D:10:10", mode, FUN_OFFSET\201AEv, y\202, + "pi", "J", mode, FUN_OFFSET\201AEv, pi\202, + "pha", "J", mode, FUN_OFFSET\201AEv, pha\202, + "time", "1D", mode, FUN_OFFSET\201AEv, time\202, + NULL\202;)RP( +Note that the only modification to the call is in the plist string. + +)0 P(Of course, instead of using staticly allocated arrays, you also can specify +dynamically allocated pointers: +) 16 75 PR( /* pointers to arrays of columns \201used in struct of arrays\202 */ + typedef struct pevstruct{ + short *region; + double *x, *y; + int *pi, *pha; + double *time; + } *PEv, PEvRec; + + got = FunColumnSelect\201fun, sizeof\201PEvRec\202, "org=structofarrays", + "$region", "@I", mode, FUN_OFFSET\201PEv, region\202, + "x", "@D:10:10", mode, FUN_OFFSET\201PEv, x\202, + "y", "@D:10:10", mode, FUN_OFFSET\201PEv, y\202, + "pi", "@J", mode, FUN_OFFSET\201PEv, pi\202, + "pha", "@J", mode, FUN_OFFSET\201PEv, pha\202, + "time", "@1D", mode, FUN_OFFSET\201PEv, time\202, + NULL\202;)RP( +Here, the actual storage space is either allocated by the user or by the +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( call\202. + +)0 P(In all of the above cases, the same call is made to retrieve rows, e.g.: +) 1 64 PR( buf = \201void *\202FunTableRowGet\201fun, NULL, MAXROW, NULL, &got\202;)RP( +However, the individual data elements are accessed differently. +For the default case of an "array of structs", the +individual row records are accessed using: +) 5 69 PR( for\201i=0; i<got; i++\202{ + ev = \201Ev\202buf+i; + fprintf\201stdout, "%.2f\200t%.2f\200t%d\200t%d\200t%.4f\200t%.4f\200t%21.8f\200n", + ev->x, ev->y, ev->pi, ev->pha, ev->dx, ev->dy, ev->time\202; + })RP( +For a struct of arrays or a struct of array pointers, we have a single struct +through which we access individual columns and rows using: +) 6 63 PR( aev = \201AEv\202buf; + for\201i=0; i<got; i++\202{ + fprintf\201stdout, "%.2f\200t%.2f\200t%d\200t%d\200t%.4f\200t%.4f\200t%21.8f\200n", + aev->x[i], aev->y[i], aev->pi[i], aev->pha[i], + aev->dx[i], aev->dy[i], aev->time[i]\202; + })RP( +Support for struct of arrays in the +)0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D( +call is handled analogously. + +)0 P(See the )0 2 A(evread example code)EA( +and +)0 2 A(evmerge example code)EA( +for working examples of how +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( is used. + + + + +)0 2 39 H(FunColumnActivate)WB 105 Sn()WB 33 Sn( - activate Funtools columns)EA()EH( + + +)BD() 3 55 PR( #include <funtools.h> + + void FunColumnActivate\201Fun fun, char *s, char *plist\202)RP()ES( + + +)0 P(The )BD(FunColumnActivate\201\202)ES( routine determines which columns \201set up +by )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D(\202 +ultimately will be read and/or written. By default, all columns that +are selected using +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( +are activated. The +)0 33 1 A(FunColumnActivate\201\202)33 0 TN TL()Ec /AF f D( +routine can be used to turn off/off activation of specific columns. + +)0 P(The first argument is the Fun handle associated with this set of +columns. The second argument is a space-delimited list of columns to +activate or de-activate. Columns preceded by "+" are activated and +columns preceded by a "-" are de-activated. If a column is named +without "+" or "-", it is activated. The reserved strings "$region" +and '$n' are used to activate a special columns containing the filter +region value and row value, respectively, associated with +this row. For example, if a filter containing two circular regions is +specified as part of the Funtools file name, this column will contain +a value of 1 or 2, depending on which region that row was in. The +reserved strings "$x" and "$y" are used to activate the current +binning columns. Thus, if the columns DX and DY are specified as +binning columns: +) 1 42 PR( [sh $] fundisp foo.fits[bincols=\201DX,DY\202])RP( +then "$x" and "$y" will refer to these columns in a call to +)0 33 1 A(FunColumnActivate\201\202)33 0 TN TL()Ec /AF f D(. + +)0 P(In addition, if the activation string contains only columns to be +activated, then the routine will de-activate all other columns. +Similarly, if the activation string contains only +columns to de-activate, then the routine will activate all other columns +before activating the list. This makes it simple to change the +activation state of all columns without having to know all of the +column names. For example: +)UL()-1 LI( )BD("pi pha time")ES( # only these three columns will be active +)-1 LI( )BD("-pi -pha -time")ES( # all but these columns will be active +)-1 LI( )BD("pi -pha")ES( # only pi is active, pha is not, others are not +)-1 LI( )BD("+pi -pha")ES( # same as above +)-1 LI( )BD("pi -pha -time")ES( # only pi is active, all others are not +)-1 LI( )BD("pi pha")ES( # pha and pi are active, all others are not +)-1 LI( )BD("pi pha -x -y")ES( # pha and pi are active, all others are not)LU( + +)0 P(You can use the column activation list to reorder columns, since +columns are output in the order specified. For example: +) 19 77 PR( # default output order + fundisp snr.ev'[cir 512 512 .1]' + 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 + + # re-order the output by specifying explicit order + fundisp snr.ev'[cir 512 512 .1]' "time x y dy dx pi pha" + TIME X Y DY DX PI PHA + --------------------- -------- -------- -------- -------- -------- -------- + 79493997.45854475 512 512 574 578 7 6 + 79494575.58943175 512 512 573 579 9 8 + 79493631.03866175 512 512 575 578 6 5 + 79493290.86521725 512 512 575 578 5 5 + 79493432.00990875 512 512 573 579 9 8)RP( + +)0 P(A "+" sign by itself means to activate all columns, so that you can reorder +just a few columns without specifying all of them: +) 9 77 PR( # reorder 3 columns and then output the rest + fundisp snr.ev'[cir 512 512 .1]' "time pi pha +" + TIME PI PHA Y X DX DY + --------------------- -------- -------- -------- -------- -------- -------- + 79493997.45854475 7 6 512 512 578 574 + 79494575.58943175 9 8 512 512 579 573 + 79493631.03866175 6 5 512 512 578 575 + 79493290.86521725 5 5 512 512 578 575 + 79493432.00990875 9 8 512 512 579 573)RP( +The column activation/deactivation is performed in the order of the +specified column arguments. This means you can mix "+", "-" \201which +de-activates all columns\202 and specific column names to reorder and +select columns in one command. For example, consider the following: +) 9 59 PR( # reorder and de-activate + fundisp snr.ev'[cir 512 512 .1]' "time pi pha + -x -y" + TIME PI PHA DX DY + --------------------- -------- -------- -------- -------- + 79493997.45854475 7 6 578 574 + 79494575.58943175 9 8 579 573 + 79493631.03866175 6 5 578 575 + 79493290.86521725 5 5 578 575 + 79493432.00990875 9 8 579 573)RP( +We first activate "time", "pi", and "pha" so that they are output first. +We then activate all of the other columns, and then de-activate "x" and "y". +Note that this is different from: +) 9 77 PR( # probably not what you want ... + fundisp snr.ev'[cir 512 512 .1]' "time pi pha -x -y +" + TIME PI PHA Y X DX DY + --------------------- -------- -------- -------- -------- -------- -------- + 79493997.45854475 7 6 512 512 578 574 + 79494575.58943175 9 8 512 512 579 573 + 79493631.03866175 6 5 512 512 578 575 + 79493290.86521725 5 5 512 512 578 575 + 79493432.00990875 9 8 512 512 579 573)RP( +Here, "x" and "y" are de-activated, but then all columns including "x" and +"y" are again re-activated. + +)0 P(Typically, +)0 33 1 A(FunColumnActivate\201\202)33 0 TN TL()Ec /AF f D( uses a +list of columns that are passed into the program from the command line. For +example, the code for funtable contains the following: +) 9 66 PR( char *cols=NULL; + + /* open the input FITS file */ + if\201 !\201fun = FunOpen\201argv[1], "rc", NULL\202\202 \202 + gerror\201stderr, "could not FunOpen input file: %s\200n", argv[1]\202; + + /* set active flag for specified columns */ + if\201 argc >= 4 \202 cols = argv[3]; + FunColumnActivate\201fun, cols, NULL\202;)RP( + +The )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( call sets the +default columns to be all columns in the input file. The +)0 33 1 A(FunColumnActivate\201\202)33 0 TN TL()Ec /AF f D( call +then allows the user to control which columns ultimately will be +activated \201i.e., in this case, written to the new file\202. For example: +) 1 39 PR( funtable test.ev foo.ev "pi pha time")RP( +will process only the three columns mentioned, while: +) 1 33 PR( funtable test.ev foo.ev "-time")RP( +will process all columns except "time". + +)0 P(If )0 33 1 A(FunColumnActivate\201\202)33 0 TN TL()Ec /AF f D( +is called with a null string, then the environment variable +)BD(FUN_COLUMNS)ES( will be used to provide a global value, if present. +This is the reason why we call the routine even if no columns +are specified on the command line \201see example above\202, instead +of calling it this way: +) 4 45 PR( /* set active flag for specified columns */ + if\201 argc >= 4 \202{ + FunColumnActivate\201fun, argv[3], NULL\202; + })RP( + + + + +)0 2 40 H(FunColumnLookup)WB 106 Sn()WB 34 Sn( - lookup a Funtools column)EA()EH( + +)BD() 5 56 PR( #include <funtools.h> + + int FunColumnLookup\201Fun fun, char *s, int which, + char **name, int *type, int *mode, + int *offset, int *n, int *width\202)RP()ES( + + +)0 P(The )BD(FunColumnLookup\201\202)ES( routine returns information about a named +\201or indexed\202 column. The first argument is the Fun handle associated +with this set of columns. The second argument is the name of the +column to look up. If the name argument is NULL, the argument that +follows is the zero-based index into the column array of the column +for which information should be returned. The next argument is a +pointer to a char *, which will contain the name of the column. The +arguments that follow are the addresses of int values into which +the following information will be returned: +)UL()-1 LI( )BD(type)ES(: data type of column: +)UL()-1 LI(A: ASCII characters +)-1 LI(B: unsigned 8-bit char +)-1 LI(I: signed 16-bit int +)-1 LI(U: unsigned 16-bit int \201not standard FITS\202 +)-1 LI(J: signed 32-bit int +)-1 LI(V: unsigned 32-bit int \201not standard FITS\202 +)-1 LI(E: 32-bit float +)-1 LI(D: 64-bit float)LU( +)-1 LI( )BD(mode)ES(: bit flag status of column, including: +)UL()-1 LI( COL_ACTIVE 1 is column activated? +)-1 LI( COL_IBUF 2 is column in the raw input data? +)-1 LI( COL_PTR 4 is column a pointer to an array? +)-1 LI( COL_READ 010 is read mode selected? +)-1 LI( COL_WRITE 020 is write mode selected? +)-1 LI( COL_REPLACEME 040 is this column being replaced by user data?)LU( +)-1 LI( )BD(offset)ES(: byte offset in struct +)-1 LI( )BD(n)ES(: number of elements \201i.e. size of vector\202 in this column +)-1 LI( )BD(width)ES(: size in bytes of this column)LU( +If the named column exists, the routine returns a positive integer, +otherwise zero is returned. \201The positive integer is the index+1 into +the column array where this column was located.\202 + +If NULL is passed as the return address of one \201or more\202 of these +values, no data is passed back for that information. For +example: +) 2 76 PR( if\201 !FunColumnLookup\201fun, "phas", 0, NULL NULL, NULL, NULL, &npha, NULL\202 \202 + gerror\201stderr, "can't find phas column\200n"\202;)RP( +only returns information about the size of the phas vector. + + + + +)0 2 41 H(FunTableRowGet)WB 107 Sn()WB 30 Sn( - get Funtools rows)EA()EH( + + +)BD() 4 68 PR( #include <funtools.h> + + void *FunTableRowGet\201Fun fun, void *rows, int maxrow, char *plist, + int *nrow\202)RP()ES( + + +)0 P(The )BD(FunTableRowGet\201\202)ES( routine retrieves rows from a Funtools +binary table or raw event file, and places the values of columns +selected by )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( +into an array of user structs. Selected column values are +automatically converted to the specified user data type \201and to native +data format\202 as necessary. + +)0 P(The first argument is the Fun handle associated with this row data. +The second )BD(rows)ES( argument is the array of user structs into +which the selected columns will be stored. If NULL is passed, the +routine will automatically allocate space for this array. \201This +includes proper allocation of pointers within each struct, if the "@" +pointer type is used in the selection of columns. Note that if you +pass NULL in the second argument, you should free this space using the +standard free\201\202 system call when you are finished with the array of +rows.\202 The third )BD(maxrow)ES( argument specifies the maximum number +of rows to be returned. Thus, if )BD(rows)ES( is allocated by the +user, it should be at least of size maxrow*sizeof\201evstruct\202. + +)0 P(The fourth )BD(plist)ES( argument is a param list string. Currently, +the keyword/value pair "mask=transparent" is supported in the plist +argument. If this string is passed in the call's plist argument, then +all rows are passed back to the user \201instead of just rows passing +the filter\202. This is only useful when +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( also is +used to specify "$region" as a column to return for each row. In +such a case, rows found within a region have a returned region value +greater than 0 \201corresponding to the region id of the region in which +they are located\202, rows passing the filter but not in a region have +region value of -1, and rows not passing any filter have region +value of 0. Thus, using "mask=transparent" and the returned region +value, a program can process all rows and decide on an action based +on whether a given row passed the filter or not. + +)0 P(The final argument is a pointer to an int variable that will return +the actual number of rows returned. The routine returns a pointer to +the array of stored rows, or NULL if there was an error. \201This pointer +will be the same as the second argument, if the latter is non-NULL\202. +) 16 69 PR( /* get rows -- let routine allocate the row array */ + while\201 \201buf = \201Ev\202FunTableRowGet\201fun, NULL, MAXROW, NULL, &got\202\202 \202{ + /* process all rows */ + for\201i=0; i<got; i++\202{ + /* point to the i'th row */ + ev = buf+i; + /* rearrange some values. etc. */ + ev->energy = \201ev->pi+ev->pha\202/2.0; + ev->pha = -ev->pha; + ev->pi = -ev->pi; + } + /* write out this batch of rows */ + FunTableRowPut\201fun2, buf, got, 0, NULL\202; + /* free row data */ + if\201 buf \202 free\201buf\202; + })RP( +As shown above, successive calls to +)0 30 1 A(FunTableRowGet\201\202)30 0 TN TL()Ec /AF f D( will return the +next set of rows from the input file until all rows have been read, +i.e., the routine behaves like sequential Unix I/O calls such as +fread\201\202. See )0 2 A(evmerge example code)EA( for a +more complete example. + +)0 P(Note that FunTableRowGet\201\202 also can be called as FunEventsGet\201\202, for +backward compatibility. + + + + +)0 2 42 H(FunTableRowPut)WB 108 Sn()WB 31 Sn( - put Funtools rows)EA()EH( + + +) 1 70 PR()BD(int FunTableRowPut\201Fun fun, void *rows, int nev, int idx, char *plist\202)ES()RP( + + +The )BD(FunTableRowPut\201\202)ES( routine writes rows to a FITS binary +table, taking its input from an array of user structs that contain +column values selected by a previous call to +)0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D(. Selected +column values are automatically converted from native data format to +FITS data format as necessary. + +)0 P(The first argument is the Fun handle associated with this row data. +The second )BD(rows)ES( argument is the array of user structs to +output. The third )BD(nrow)ES( argument specifies the number number of +rows to write. The routine will write )BD(nrow)ES( records, starting +from the location specified by )BD(rows)ES(. + +)0 P(The fourth )BD(idx)ES( argument is the index of the first raw input +row to write, in the case where rows from the user buffer are +being merged with their raw input row counterparts \201see below\202. Note +that this )BD(idx)ES( value is has nothing to do with the +row buffer specified in argument 1. It merely matches the row +being written with its corresponding \201hidden\202 raw row. Thus, if you +read a number of rows, process them, and then write them out all at +once starting from the first user row, the value of )BD(idx)ES( +should be 0: +) 14 70 PR( Ev ebuf, ev; + /* get rows -- let routine allocate the row array */ + while\201 \201ebuf = \201Ev\202FunTableRowGet\201fun, NULL, MAXROW, NULL, &got\202\202 \202{ + /* process all rows */ + for\201i=0; i<got; i++\202{ + /* point to the i'th row */ + ev = ebuf+i; + ... + } + /* write out this batch of rows, starting with the first */ + FunTableRowPut\201fun2, \201char *\202ebuf, got, 0, NULL\202; + /* free row data */ + if\201 ebuf \202 free\201ebuf\202; + })RP( + +)0 P(On the other hand, if you write out the rows one at a time \201possibly +skipping rows\202, then, when writing the i'th row from the input +array of rows, set )BD(idx)ES( to the value of i: +) 14 70 PR( Ev ebuf, ev; + /* get rows -- let routine allocate the row array */ + while\201 \201ebuf = \201Ev\202FunTableRowGet\201fun, NULL, MAXROW, NULL, &got\202\202 \202{ + /* process all rows */ + for\201i=0; i<got; i++\202{ + /* point to the i'th row */ + ev = ebuf+i; + ... + /* write out the current \201i.e., i'th\202 row */ + FunTableRowPut\201fun2, \201char *\202ev, 1, i, NULL\202; + } + /* free row data */ + if\201 ebuf \202 free\201ebuf\202; + })RP( + +)0 P(The final argument is a param list string that is not currently used. +The routine returns the number of rows output. This should be equal +to the value passed in the third )BD(nrowFunParamGet)WB 37 Sn( - get a Funtools param value)EA()EH( + + +)BD() 9 74 PR( #include <funtools.h> + + int FunParamGetb\201Fun fun, char *name, int n, int defval, int *got\202 + + int FunParamGeti\201Fun fun, char *name, int n, int defval, int *got\202 + + double FunParamGetd\201Fun fun, char *name, int n, double defval, int *got\202 + + char *FunParamGets\201Fun fun, char *name, int n, char *defval, int *got\202)RP()ES( + + +)0 P(The four routines )BD(FunParamGetb\201\202)ES(, )BD(FunParamGeti\201\202)ES(, +)BD(FunParamGetd\201\202)ES(, and )BD(FunParamGets\201\202)ES(, return the value of +a FITS header parameter as a boolean, int, double, and string, +respectively. The string returned by )BD(FunParamGets\201\202)ES( is a malloc'ed +copy of the header value and should be freed when no longer needed. + +)0 P(The first argument is the Fun handle associated with the FITS header +being accessed. Normally, the header is associated with the FITS +extension that you opened with )BD(FunOpen\201\202)ES(. However, you can use +FunInfoPut\201\202 to specify access of the primary header. In particular, +if you set the FUN_PRIMARYHEADER parameter to 1, then the primary +header is used for all parameter access until the value is reset to +0. For example: +) 9 75 PR( int val; + FunParamGeti\201fun, "NAXIS", 1, 0, &got\202; # current header + val=1; + FunInfoPut\201fun, FUN_PRIMARYHEADER, &val, 0\202; # switch to ... + FunParamGeti\201fun, "NAXIS", 1, 0, &got\202; # ... primary header + FunParamGeti\201fun, "NAXIS", 2, 0, &got\202; # ... primary header + val=0; + FunInfoPut\201fun, FUN_PRIMARYHEADER, &val, 0\202; # switch back to ... + FunParamGeti\201fun, "NAXIS", 2, 0, &got\202; # current header)RP( + +)0 P(Alternatively, you can use the FUN_PRIMARY macro to access parameters +from the primary header on a per-parameter basis: +) 2 72 PR( FunParamGeti\201fun, "NAXIS1", 0, 0, &got\202; # current header + FunParamGeti\201FUN_PRIMARY\201fun\202, "NAXIS1", 0, 0, &got\202; # primary header)RP( +)BD(NB: FUN_PRIMARY is deprecated.)ES( +It makes use of a global parameter and therefore will not not +appropriate for threaded applications, when we make funtools +thread-safe. We recommend use of FunInfoPut\201\202 to switch between the +extension header and the primary header. + +)0 P(For output data, access to the primary header is only possible until +the header is written out, which usually takes place when the first +data are written. + +)0 P(The second argument is the name of the parameter to access. The third +)BD(n)ES( argument, if non-zero, is an integer that will be added as a +suffix to the parameter name. This makes it easy to use a simple loop +to process parameters having the same root name. For example, to +gather up all values of TLMIN and TLMAX for each column in a binary +table, you can use: +) 4 74 PR( for\201i=0, got=1; got; i++\202{ + fun->cols[i]->tlmin = \201int\202FunParamGeti\201fun, "TLMIN", i+1, 0.0, &got\202; + fun->cols[i]->tlmax = \201int\202FunParamGeti\201fun, "TLMAX", i+1, 0.0, &got\202; + })RP( + +)0 P(The fourth )BD(defval)ES( argument is the default value to return if +the parameter does not exist. Note that the data type of this +parameter is different for each specific FunParamGet\201\202 call. The final +)BD(got)ES( argument will be 0 if no param was found. Otherwise the +data type of the parameter is returned as follows: FUN_PAR_UNKNOWN +\201'u'\202, FUN_PAR_COMMENT \201'c'\202, FUN_PAR_LOGICAL \201'l'\202, FUN_PAR_INTEGER +\201'i'\202, FUN_PAR_STRING \201's'\202, FUN_PAR_REAL \201'r'\202, FUN_PAR_COMPLEX \201'x'\202. + +)0 P(These routines return the value of the header parameter, or the +specified default value if the header parameter does not exist. The +returned value is a malloc'ed string and should be freed when no +longer needed. + +)0 P(By default, )BD(FunParamGets\201\202)ES( returns the string value of the +named parameter. However, you can use FunInfoPut\201\202 to retrieve the +raw 80-character FITS card instead. In particular, if you set the +FUN_RAWPARAM parameter to 1, then card images will be returned by +FunParamGets\201\202 until the value is reset to 0. + +)0 P(Alternatively, if the FUN_RAW macro is applied to the name, then the +80-character raw FITS card is returned instead. +)BD(NB: FUN_RAW is deprecated.)ES( +It makes use of a global parameter and therefore will not not +appropriate for threaded applications, when we make funtools +thread-safe. We recommend use of FunInfoPut\201\202 to switch between the +extension header and the primary header. + +)0 P(Note that in addition to the behaviors described above, the +routine )BD(FunParamGets\201\202)ES( will return the 80 raw characters of the +)BD(nth)ES( FITS card \201including the comment\202 if )BD(name)ES( is specified as +NULL and )BD(n)ES( is positive. For example, to loop through all FITS +header cards in a given extension and print out the raw card, use: +) 9 55 PR( for\201i=1; ;i++\202{ + if\201 \201s = FunParamGets\201fun, NULL, i, NULL, &got\202\202 \202{ + fprintf\201stdout, "%.80s\200n", s\202; + free\201s\202; + } + else{ + break; + } + })RP( + + + + +)0 2 43 H(FunParamPut)WB 109 Sn()WB 38 Sn( - put a Funtools param value)EA()EH( + + +)BD() 13 71 PR( #include <funtools.h> + + int FunParamPutb\201Fun fun, char *name, int n, int value, char *comm, + int append\202 + + int FunParamPuti\201Fun fun, char *name, int n, int value, char *comm, + int append\202 + + int FunParamPutd\201Fun fun, char *name, int n, double value, int prec, + char *comm, int append\202 + + int FunParamPuts\201Fun fun, char *name, int n, char *value, char *comm, + int append\202)RP()ES( + + +)0 P(The four routines )BD(FunParamPutb\201\202)ES(, )BD(FunParamPuti\201\202)ES(, +)BD(FunParamPutd\201\202)ES(, and )BD(FunParamPuts\201\202)ES(, will set the value +of a FITS header parameter as a boolean, int, double, and string, +respectively. + +)0 P(The first argument is the Fun handle associated with the FITS header +being accessed. Normally, the header is associated with the FITS +extension that you opened with )BD(FunOpen\201\202)ES(. +However, you can use FunInfoPut\201\202 to specify that use of the primary +header. In particular, if you set the FUN_PRIMARYHEADER parameter to +1, then the primary header is used for all parameter access until the +value is reset to 0. For example: +) 5 69 PR( int val; + FunParamPuti\201fun, "NAXIS1", 0, 10, NULL, 1\202; # current header + val=1; + FunInfoPut\201fun, FUN_PRIMARYHEADER, &val, 0\202; # switch to ... + FunParamPuti\201fun, "NAXIS1", 0, 10, NULL, 1\202; # primary header)RP( +\201You also can use the deprecated FUN_PRIMARY macro, to access +parameters from the primary header.\202 + +)0 P(The second argument is the )BD(name)ES( of the parameter. \201 +In accordance with FITS standards, the special names )BD(COMMENT)ES( +and )BD(HISTORY)ES(, as well as blank names, are output without the "= " +value indicator in columns 9 and 10. + +)0 P(The third )BD(n)ES( argument, if non-zero, is an integer that will be +added as a suffix to the parameter name. This makes it easy to use a +simple loop to process parameters having the same root name. For +example, to set the values of TLMIN and TLMAX for each column in a +binary table, you can use: +) 4 70 PR( for\201i=0; i<got; i++\202{ + FunParamPutd\201fun, "TLMIN", i+1, tlmin[i], 7, "min column val", 1\202; + FunParamPutd\201fun, "TLMAX", i+1, tlmax[i], 7, "max column val", 1\202; + })RP( + +)0 P(The fourth )BD(defval)ES( argument is the value to set. Note that the +data type of this argument is different for each specific +FunParamPut\201\202 call. The )BD(comm)ES( argument is the comment +string to add to this header parameter. Its value can be NULL. The +final )BD(append)ES( argument determines whether the parameter is added +to the header if it does not exist. If set to a non-zero value, the +header parameter will be appended to the header if it does not exist. +If set to 0, the value will only be used to change an existing parameter. + +)0 P(Note that the double precision routine FunParamPutd\201\202 supports an +extra )BD(prec)ES( argument after the )BD(value)ES( argument, in order +to specify the precision when converting the double value to ASCII. In +general a 20.[prec] format is used \201since 20 characters are alloted to +a floating point number in FITS\202 as follows: if the double value being +put to the header is less than 0.1 or greater than or equal to +10**\20120-2-[prec]\202, then %20.[prec]e format is used \201i.e., scientific +notation\202; otherwise %20.[prec]f format is used \201i.e., numeric +notation\202. + +)0 P(As a rule, parameters should be set before writing the table or image. +It is, however, possible to update the value of an )BD(existing)ES( +parameter after writing an image or table \201but not to add a new +one\202. Such updating only works if the parameter already exists and if +the output file is seekable, i.e. if it is a disk file or is stdout +being redirected to a disk file. + +)0 P(It is possible to add a new parameter to a header after the data has +been written, but only if space has previously been reserved. To reserve +space, add a blank parameter whose value is the name of the parameter you +eventually will update. Then, when writing the new parameter, specify a +value of 2 for the append flag. The parameter writing routine will +first look to update an existing parameter, as usual. If an existing +parameter is not found, an appropriately-valued blank parameter will be +searched for and replaced. For example: +) 8 71 PR( /* add blank card to be used as a place holder for IPAR1 update */ + FunParamPuts\201fun, NULL, 0, "IPAR1", "INTEGER Param", 0\202; + ... + /* write header and data */ + FunTableRowPut\201fun, events, got, 0, NULL\202; + ... + /* update param in file after writing data -- note append = 2 here */ + FunParamPuti\201fun, "IPAR", 1, 400, "INTEGER Param", 2\202;)RP( + +)0 P(The parameter routines return a 1 if the routine was successful and a 0 on +failure. In general, the major reason for failure is that you did not +set the append argument to a non-zero value and the parameter did not +already exist in the file. + + + + +)0 2 44 H(FunInfoGet)WB 110 Sn()WB 35 Sn( - get information from Funtools struct)EA()EH( + + +)BD() 3 52 PR( #include <funtools.h> + + int FunInfoGet\201Fun fun, int type, char *addr, ...\202)RP()ES( + + +)0 P(The )BD(FunInfoGet\201\202)ES( routine returns information culled from the +Funtools structure. The first argument is the Fun handle from which +information is to be retrieved. This first required argument is followed +by a variable length list of pairs of arguments. Each pair consists +of an integer representing the type of information to retrieve and the +address where the information is to be stored. The list is terminated by a 0. +The routine returns the number of get actions performed. + +)0 P(The full list of available information is described below. Please note +that only a few of these will be useful to most application developers. +For imaging applications, the most important types are: +) 3 47 PR( FUN_SECT_DIM1 int /* dim1 for section */ + FUN_SECT_DIM2 int /* dim2 for section */ + FUN_SECT_BITPIX int /* bitpix for section */)RP( +These would be used to determine the dimensions and data type of image +data retrieved using the +)0 26 1 A(FunImageGet\201\202)26 0 TN TL()Ec /AF f D( routine. For +example: +) 17 68 PR( /* extract and bin the data section into an image buffer */ + buf = FunImageGet\201fun, NULL, NULL\202; + /* get required information from funtools structure. + this should come after the FunImageGet\201\202 call, in case the call + changed sect_bitpix */ + FunInfoGet\201fun, + FUN_SECT_BITPIX, &bitpix, + FUN_SECT_DIM1, &dim1, + FUN_SECT_DIM2, &dim2, + 0\202; + /* loop through pixels and reset values below limit to value */ + for\201i=0; i<dim1*dim2; i++\202{ + switch\201bitpix\202{ + case 8: + if\201 cbuf[i] <= blimit \202 cbuf[i] = bvalue; + ... + })RP( +It is important to bear in mind that the call to +)0 26 1 A(FunImageGet\201\202)26 0 TN TL()Ec /AF f D( +can change the value of FUN_SECT_BITPIX \201e.g. if "bitpix=n" is passed +in the param list\202. Therefore, a call to +)0 35 1 A(FunInfoGet\201\202)35 0 TN TL()Ec /AF f D( +should be made )BD(after)ES( the call to +)0 26 1 A(FunImageGet\201\202)26 0 TN TL()Ec /AF f D(, +in order to retrieve the updated bitpix value. +See the )0 2 A(imblank example code)EA( for more +details. + +)0 P(It also can be useful to retrieve the World Coordinate System +information from the Funtools structure. Funtools uses the the WCS +Library developed by Doug Mink at SAO, which is available +)R3 2 A(here)EA(. +\201More information about the WCSTools project in general can be found +)R4 2 A(here)EA(.\202 +The )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( routine initializes +two WCS structures that can be used with this WCS Library. +Applications can retrieve either of these two WCS structures using +)BD(FunInfoGet\201\202)ES(: +) 2 75 PR( FUN_WCS struct WorldCoor * /* wcs structure, for image coordinates*/ + FUN_WCS0 struct WorldCoor * /* wcs structure, for physical coordinates */)RP( +The structure retrieved by FUN_WCS is a WCS library handle containing +parameters suitable for use with image coordinates, regardless of whether the +data are images or tables. For this structure, the WCS reference point +\201CRPIX\202 has been converted to image coordinates if the underlying file +is a table \201and therefore in physical coordinates\202. You therefore must +ensure that the positions being passed to a routine like pix2wcs are in +image coordinates. The FUN_WCS0 structure has not had its WCS +reference point converted to image coordinates. It therefore is useful +when passing processing physical coordinates from a table. + +)0 P(Once a WCS structure has been retrieved, it can be used as the first +argument to the WCS library routines. \201If the structure is NULL, no +WCS information was contained in the file.\202 The two important WCS routines +that Funtools uses are: +) 5 66 PR( #include <wcs.h> + void pix2wcs \201wcs,xpix,ypix,xpos,ypos\202 + struct WorldCoor *wcs; /* World coordinate system structure */ + double xpix,ypix; /* x and y coordinates in pixels */ + double *xpos,*ypos; /* RA and Dec in degrees \201returned\202 */)RP( + +which converts pixel coordinates to sky coordinates, and: + +) 5 67 PR( void wcs2pix \201wcs, xpos, ypos, xpix, ypix, offscl\202 + struct WorldCoor *wcs; /* World coordinate system structure */ + double xpos,ypos; /* World coordinates in degrees */ + double *xpix,*ypix; /* coordinates in pixels */ + int *offscl; /* 0 if within bounds, else off scale */)RP( +which converts sky coordinates to pixel coordinates. Again, please note +that the wcs structure returned by FUN_WCS assumes that image coordinates +are passed to the pix2wcs routine, while FUN_WCS0 assumes that physical +coordinates are passed. + +)0 P(Note that funtools.h file automatically includes wcs.h. An example +program that utilizes these WCS structure to call WCS Library routines +is )0 2 A(twcs.c)EA(. + +)0 P(The following is the complete list of information that can be returned: +) 52 79 PR( name type comment + --------- -------- --------------------------------------------- + FUN_FNAME char * /* file name */ + FUN_GIO GIO /* gio handle */ + FUN_HEADER FITSHead /* fitsy header struct */ + FUN_TYPE int /* TY_TABLE,TY_IMAGE,TY_EVENTS,TY_ARRAY */ + FUN_BITPIX int /* bits/pixel in file */ + FUN_MIN1 int /* tlmin of axis1 -- tables */ + FUN_MAX1 int /* tlmax of axis1 -- tables */ + FUN_MIN2 int /* tlmin of axis2 -- tables */ + FUN_MAX2 int /* tlmax of axis2 -- tables */ + FUN_DIM1 int /* dimension of axis1 */ + FUN_DIM2 int /* dimension of axis2 */ + FUN_ENDIAN int /* 0=little, 1=big endian */ + FUN_FILTER char * /* supplied filter */ + FUN_IFUN FITSHead /* pointer to reference header */ + FUN_IFUN0 FITSHead /* same as above, but no reset performed */ + /* image information */ + FUN_DTYPE int /* data type for images */ + FUN_DLEN int /* length of image in bytes */ + FUN_DPAD int /* padding to end of extension */ + FUN_DOBLANK int /* was blank keyword defined? */ + FUN_BLANK int /* value for blank */ + FUN_SCALED int /* was bscale/bzero defined? */ + FUN_BSCALE double /* bscale value */ + FUN_BZERO double /* bzero value */ + /* table information */ + FUN_NROWS int /* number of rows in file \201naxis2\202 */ + FUN_ROWSIZE int /* size of user row struct */ + FUN_BINCOLS char * /* specified binning columns */ + FUN_OVERFLOW int /* overflow detected during binning? */)WR( + /* array information */ + FUN_SKIP int /* bytes to skip in array header */ + /* section information */ + FUN_SECT_X0 int /* low dim1 value of section */ + FUN_SECT_X1 int /* hi dim1 value of section */ + FUN_SECT_Y0 int /* low dim2 value of section */ + FUN_SECT_Y1 int /* hi dim2 value of section */ + FUN_SECT_BLOCK int /* section block factor */ + FUN_SECT_BTYPE int /* 's' \201sum\202, 'a' \201average\202 for binning */ + FUN_SECT_DIM1 int /* dim1 for section */ + FUN_SECT_DIM2 int /* dim2 for section */ + FUN_SECT_BITPIX int /* bitpix for section */ + FUN_SECT_DTYPE int /* data type for section */ + FUN_RAWBUF char * /* pointer to raw row buffer */ + FUN_RAWSIZE int /* byte size of raw row records */ + /* column information */ + FUN_NCOL int /* number of row columns defined */ + FUN_COLS FunCol /* array of row columns */ + /* WCS information */ + FUN_WCS struct WorldCoor * /* wcs structure, converted for images*/ + FUN_WCS0 struct WorldCoor * /* wcs structure, not converted */)RP( + +)0 P(Row applications would not normally need any of this information. +An example of how these values can be used in more complex programs is +the )0 2 A(evnext example code)EA(. In this program, the +time value for each row is changed to be the value of the succeeding +row. The program thus reads the time values for a batch of rows, +changes the time values to be the value for the succeeding row, and +then merges these changed time values back with the other columns to +the output file. It then reads the next batch, etc. + +)0 P(This does not work for the last row read in each batch, since there +is no succeeding row until the next batch is read. Therefore, the +program saves that last row until it has read the next batch, then +processes the former before starting on the new batch. In order to +merge the last row successfully, the code uses FUN_RAWBUF to save +and restore the raw input data associated with each batch of +rows. Clearly, this requires some information about how funtools +works internally. We are happy to help you write such programs as the +need arises. + + + + +)0 2 45 H(FunInfoPut)WB 111 Sn()WB 36 Sn( - put information into a Funtools struct)EA()EH( + + +)BD() 3 52 PR( #include <funtools.h> + + int FunInfoPut\201Fun fun, int type, char *addr, ...\202)RP()ES( + + +)0 P(The )BD(FunInfoPut\201\202)ES( routine puts information into a Funtools +structure. The first argument is the Fun handle from which +information is to be retrieved. After this first required argument +comes a variable length list of pairs of arguments. Each pair consists +of an integer representing the type of information to store and the +address of the new information to store in the struct. The variable +list is terminated by a 0. The routine returns the number of put +actions performed. + +)0 P(The full list of available information is described above with the +)0 36 1 A(FunInfoPut\201\202)36 0 TN TL()Ec /AF f D( routine. Although +use of this routine is expected to be uncommon, there is one +important situation in which it plays an essential part: writing +multiple extensions to a single output file. + +)0 P(For input, multiple extensions are handled by calling +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( for each extension to be +processed. When opening multiple inputs, it sometimes is the case that +you will want to process them and then write them \201including their +header parameters\202 to a single output file. To accomplish this, you +open successive input extensions using +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( and then call +)BD(FunInfoPut\201\202)ES( to set the +)0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( +of the output file to that of the newly opened input extension: +) 4 71 PR( /* open a new input extension */ + ifun=FunOpen\201tbuf, "r", NULL\202\202 \202 + /* make the new extension the reference handle for the output file */ + FunInfoPut\201ofun, FUN_IFUN, &ifun, 0\202;)RP( + +Resetting FUN_IFUN has same effect as when a funtools handle is passed +as the final argument to +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(. The state of the output +file is reset so that a new extension is ready to be written. +Thus, the next I/O call on the output extension will output the +header, as expected. + +)0 P(For example, in a binary table, after resetting FUN_IFUN you can then +call )0 32 1 A(FunColumnSelect\201\202)32 0 TN TL()Ec /AF f D( to +select the columns for output. When you then call +)0 27 1 A(FunImagePut\201\202)27 0 TN TL()Ec /AF f D( or )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D(, a new +extension will be written that contains the header parameters from the +reference extension. Remember to call +)0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( to complete output of a +given extension. + +)0 P(A complete example of this capability is given +in the )0 2 A(evcol example code)EA(. +The central algorithm is: +)UL()-1 LI( open the output file without a reference handle +)-1 LI( loop: open each input extension in turn +)UL()-1 LI( set the reference handle for output to the newly opened input extension +)-1 LI( read the input rows or image and perform processing +)-1 LI( write new rows or image to the output file +)-1 LI( flush the output +)-1 LI( close input extension)LU( +)-1 LI( close output file)LU( +Note that )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( is called +after processing each input extension in order to ensure that the +proper padding is written to the output file. A call to +)0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( also ensures that the +extension header is written to the output file in the case where there +are no rows to output. + +)0 P(If you wish to output a new extension without using a +)0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D(, you can +call FunInfoPut\201\202 to reset the FUN_OPS value directly. For a binary +table, you would then call FunColumnSelect\201\202 to set up the columns for +this new extension. +) 6 59 PR( /* reset the operations performed on this handle */ + int ops=0; + FunInfoPut\201ofun, FUN_OPS, &ops, 0\202; + FunColumnSelect\201fun, sizeof\201EvRec\202, NULL, + "MYCOL", "J", "w", FUN_OFFSET\201Ev, mycol\202, + NULL\202;)RP( +Once the FUN_OPS variable has been reset, the next I/O call on the +output extension will output the header, as expected. + + + + +)0 2 46 H(FunFlush)WB 112 Sn()WB 39 Sn( - flush data to output file)EA()EH( + + +)BD() 3 37 PR( #include <funtools.h> + + void FunFlush\201Fun fun, char *plist\202)RP()ES( + + +)0 P(The )BD(FunFlush)ES( routine will flush data to a FITS output file. In +particular, it can be called after all rows have been written \201using +the )0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D( routine\202 +in order to add the null padding that is required to complete a FITS +block. It also should be called after completely writing an image using +)0 27 1 A(FunImagePut\201\202)27 0 TN TL()Ec /AF f D( or after writing +the final row of an image using +)0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D(. + +)0 P(The )BD(plist)ES( \201i.e., parameter list\202 argument is a string +containing one or more comma-delimited )BD(keyword=value)ES( +parameters. If the plist string contains the parameter +"copy=remainder" and the file was opened with a reference file, which, +in turn, was opened for extension copying \201i.e. the input +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( mode also was "c" or "C"\202, +then FunFlush also will copy the remainder of the FITS extensions from +the input reference file to the output file. This normally would be +done only at the end of processing. + +)0 P(Note that )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( is called +with "copy=remainder" in the mode string by FunClose\201\202. This means +that if you close the output file before the reference input file, it +is not necessary to call +)0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( explicitly, unless you +are writing more than one extension. See the +)0 2 A(evmerge example code)EA(. However, it is safe to +call )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( more than once +without fear of re-writing either the padding or the copied +extensions. + +)0 P(In addition, if )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( is +called on an output file with the plist set to "copy=reference" and if +the file was opened with a reference file, the reference extension is +written to the output file. This mechanism provides a simple way to +copy input extensions to an output file without processing the former. +For example, in the code fragment below, an input extension is set to +be the reference file for a newly opened output extension. If that +reference extension is not a binary table, it is written to the output +file: +) 22 73 PR( /* process each input extension in turn */ + for\201ext=0; ;ext++\202{ + /* get new extension name */ + sprintf\201tbuf, "%s[%d]", argv[1], ext\202; + /* open input extension -- if we cannot open it, we are done */ + if\201 !\201ifun=FunOpen\201tbuf, "r", NULL\202\202 \202 + break; + /* make the new extension the reference handle for the output file */ + FunInfoPut\201ofun, FUN_IFUN, &ifun, 0\202; + /* if its not a binary table, just write it out */ + if\201 !\201s=FunParamGets\201ifun, "XTENSION", 0, NULL, &got\202\202 || + strcmp\201s, "BINTABLE"\202\202{ + if\201 s \202 free\201s\202; + FunFlush\201ofun, "copy=reference"\202; + FunClose\201ifun\202; + continue; + } + else{ + /* process binary table */ + .... + } + })RP( + + + + +)0 2 47 H(FunClose)WB 113 Sn()WB 40 Sn( - close a Funtools data file)EA()EH( + + +)BD() 3 24 PR( #include <funtools.h> + + void FunClose\201Fun fun\202)RP()ES( + + +)0 P(The )BD(FunClose\201\202)ES( routine closes a previously-opened Funtools data +file, freeing control structures. If a +)0 23 1 A(Funtools reference handle)23 0 TN TL()Ec /AF f D( +was passed to +the )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( call for this file, +and if copy mode also was specified for that file, then +)0 40 1 A(FunClose\201\202)40 0 TN TL()Ec /AF f D( also will copy the +remaining extensions from the input file to the output file \201if the +input file still is open\202. Thus, we recommend always closing the +output Funtools file )BD(before)ES( the input file. \201Alternatively, +you can call )0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( +explicitly\202. + + + + +)0 2 48 H(FunRef:)WB 114 Sn()WB 23 Sn( the Funtools Reference Handle)EA()EH( + + +)0 2 49 H(Summary)WB 115 Sn()EH( +A description of how to use a Funtools reference handle to connect a +Funtools input file to an output file. + + +)0 2 50 H(Description)WB 116 Sn()EH( +)0 P(The Funtools reference handle connects a Funtools input file to a +Funtools output file so that parameters \201or even whole extensions\202 can +be copied from the one to the other. To make the connection, the Funtools +handle of the input file is passed to the +final argument of the +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( call for the output file: +) 4 67 PR( if\201 !\201ifun = FunOpen\201argv[1], "r", NULL\202\202 \202 + gerror\201stderr, "could not FunOpen input file: %s\200n", argv[1]\202; + if\201 !\201ofun = FunOpen\201argv[2], "w", ifun\202\202 \202 + gerror\201stderr, "could not FunOpen output file: %s\200n", argv[2]\202;)RP( +It does not matter what type of input or output file \201or extension\202 is +opened, or whether they are the same type. When the output image or +binary table is written using +)0 27 1 A(FunImagePut\201\202)27 0 TN TL()Ec /AF f D( +or +)0 31 1 A(FunTableRowPut\201\202)31 0 TN TL()Ec /AF f D( +an appropriate header will be written first, with parameters copied +from the input extension. Of course, invalid parameters will be +removed first, e.g., if the input is a binary table and the output is +an image, then binary table parameters such as TFORM, TUNIT, +etc. parameters will not be copied to the output. + +)0 P(Use of a reference handle also allows default values to be passed +to +)0 27 1 A(FunImagePut\201\202)27 0 TN TL()Ec /AF f D( in order to +write out an output image with the same dimensions and data type +as the input image. To use the defaults from the input, a value +of 0 is entered for dim1, dim2, and bitpix. For example: +) 5 40 PR( fun = FunOpen\201argv[1], "r", NULL\202; + fun2 = FunOpen\201argv[2], "w", fun\202; + buf = FunImageGet\201fun, NULL, NULL\202; + ... process image data ... + FunImagePut\201fun2, buf, 0, 0, 0, NULL\202;)RP( +Of course, you often want to get information about the data type +and dimensions of the image for processing. The above code +is equivalent to the following: +) 7 61 PR( fun = FunOpen\201argv[1], "r", NULL\202; + fun2 = FunOpen\201argv[2], "w", fun\202; + buf = FunImageGet\201fun, NULL, NULL\202; + FunInfoGet\201fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, + FUN_SECT_BITPIX, &bitpix, 0\202; + ... process image data ... + FunImagePut\201fun2, buf, dim1, dim2, bitpix, NULL\202;)RP( + +)0 P(It is possible to change the reference handle for a given output Funtools +handle using the +)0 36 1 A(FunInfoPut\201\202)36 0 TN TL()Ec /AF f D( routine: +) 2 71 PR( /* make the new extension the reference handle for the output file */ + FunInfoPut\201fun2, FUN_IFUN, &fun, 0\202;)RP( +When this is done, Funtools specially resets the output file to start +a new output extension, which is connected to the new input reference +handle. You can use this mechanism to process multiple input extensions +into a single output file, by successively opening the former and +setting the reference handle for the latter. For example: +) 18 73 PR( /* open a new output FITS file */ + if\201 !\201fun2 = FunOpen\201argv[2], "w", NULL\202\202 \202 + gerror\201stderr, "could not FunOpen output file: %s\200n", argv[2]\202; + /* process each input extension in turn */ + for\201ext=0; ;ext++\202{ + /* get new extension name */ + sprintf\201tbuf, "%s[%d]", argv[1], ext\202; + /* open it -- if we cannot open it, we are done */ + if\201 !\201fun=FunOpen\201tbuf, "r", NULL\202\202 \202 + break; + /* make the new extension the reference handle for the output file */ + FunInfoPut\201fun2, FUN_IFUN, &fun, 0\202; + ... process ... + /* flush output extension \201write padding, etc.\202 */ + FunFlush\201fun2, NULL\202; + /* close the input extension */ + FunClose\201fun\202; + })RP( +In this example, the output file is opened first. Then each successive +input extension is opened, and the output reference handle is set to +the newly opened input handle. After data processing is performed, the +output extension is flushed and the input extension is closed, in +preparation for the next input extension. +)0 P(Finally, a reference handle can be used to copy other extensions from +the input file to the output file. Copy of other extensions is +controlled by adding a "C" or "c" to the mode string of the +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( +call )BD(of the input reference file)ES(. If "C" is specified, then +other extensions are )BD(always)ES( copied \201i.e., copy is forced by the +application\202. If "c" is used, then other extensions are copied if the +user requests copying by adding a plus sign "+" to the extension name +in the bracket specification. For example, the )BD(funtable)ES( +program utilizes user-specified "c" mode so that the second example +below will copy all extensions: +) 4 60 PR( # copy only the EVENTS extension + csh> funtable "test.ev[EVENTS,circle\201512,512,10\202]" foo.ev + # copy ALL extensions + csh> funtable "test.ev[EVENTS+,circle\201512,512,10\202]" foo.ev)RP( +When extension copy is specified in the input file, the call to +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( +on the input file delays the actual file open until the output file +also is opened \201or until I/O is performed on the input file, which +ever happens first\202. Then, when the output file is opened, the input +file is also opened and input extensions are copied to the output +file, up to the specific extension being opened. Processing of input +and output extensions then proceed. +)0 P(When extension processing is complete, the remaining extensions need to +be copied from input to output. This can be done explicitly, using the +)0 39 1 A(FunFlush\201\202)39 0 TN TL()Ec /AF f D( +call with the "copy=remaining" plist: +) 1 34 PR( FunFlush\201fun, "copy=remaining"\202;)RP( +Alternatively, this will happen automatically, if the output file +is closed )BD(before)ES( the input file: +) 5 77 PR( /* we could explicitly flush remaining extensions that need copying */ + /* FunFlush\201fun2, "copy=remaining"\202; */ + /* but if we close output before input, end flush is done automatically */ + FunClose\201fun2\202; + FunClose\201fun\202;)RP( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 51 H(Last)WB 117 Sn( updated: December 1, 2005)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (files.html) D +/Ti (Funtools Data Files) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 42 Sn( + + +)0 2 52 H(FunFiles:)WB 120 Sn()WB 118 Sn( Funtools Data Files)EA()EH( + + +)0 2 53 H(Summary)WB 121 Sn()EH( +This document describes the data file formats \201FITS, array, raw +events\202 as well as the file types \201gzip, socket, etc.\202 supported +by Funtools. + + +)0 2 54 H(Description)WB 122 Sn()EH( +)0 P(Funtools supports FITS images and binary tables, and binary files +containing array \201homogeneous\202 data or event \201heterogeneous\202 data. +IRAF-style brackets are appended to the filename to specify various +kinds of information needed to characterize these data: +) 3 49 PR( file[ext|ind|ARRAY\201\202|EVENTS\201\202,section][filters] + or + file[ext|ind|ARRAY\201\202|EVENTS\201\202,section,filters])RP( +where: +)UL()-1 LI( )BD(file)ES( is the Funtools file name +)-1 LI( )BD(ext)ES( is the FITS extension name +)-1 LI( )BD(ind)ES( is the FITS extension number +)-1 LI( )BD(ARRAY\201\202)ES( is an array specification +)-1 LI( )BD(EVENTS\201\202)ES( is an event specification +)-1 LI( )BD(section)ES( is the image section specification +)-1 LI( )BD(filters)ES( are spatial region and table \201row\202 filters)LU( + +)0 2 55 H(Supported)WB 123 Sn()WB 43 Sn( Data Formats)EA()EH( +)0 P(Funtools programs \201and the underlying libraries\202 support the +following data file formats: +)UL()-1 LI( FITS images \201and image extensions\202 +)-1 LI( FITS binary tables +)-1 LI( binary files containing an array of homogeneous data +)-1 LI( binary files containing events, i.e. records of heterogeneous data +)-1 LI( column-based text files, which are documented )0 47 1 A(here)47 0 TN TL()Ec /AF f D( +)-1 LI( non-disk files and lists of files)LU( +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: +) 5 69 PR( foo.fits # open FITS default extension + image.fits[3] # open FITS extension #3 + events.fits[EVENTS] # open EVENTS extension + array.file[ARRAY\201s1024\202] # open 1024x1024 short array + events.file[EVENTS\201x:1024,y:1024...\202] # open non-FITS event list)RP( +Note that in many Unix shells \201e.g., csh and tcsh\202, filenames must +be enclosed in quotes to protect the brackets from shell processing. + +)0 2 56 H(FITS)WB 124 Sn()WB 44 Sn( Images and Binary Tables)EA()EH( +)0 P(When )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( opens a FITS file +without a bracket specifier, the default behavior is to look for a +valid image in the primary HDU. In the absence of a primary image, +Funtools will try to open an extension named either )BD(EVENTS)ES( or +)BD(STDEVT)ES(, if one of these exists. This default behavior supports +both FITS image processing and standard X-ray event list processing +\201which, after all, is what we at SAO/HEAD do\202. + +)0 P(In order to open a FITS binary table or image extension explicitly, it +is necessary to specify either the extension name or the extension +number in brackets: +) 3 71 PR( 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)RP( +The ext argument specifies the name of the FITS extension \201i.e. the +value of the EXTENSION header parameter in a FITS extension\202, while +the index specifies the value of the FITS EXTVER header parameter. +Following FITS conventions, extension numbers start at 1. + +)0 P(When a FITS data file is opened for reading using +)0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D(, the specified extension +is automatically located and is used to initialize the Funtools internal +data structures. + +)0 2 57 H(Non-FITS)WB 125 Sn()WB 45 Sn( Raw Event Files)EA()EH( + +In addition to FITS tables, Funtools programs and libraries can operate +on non-FITS files containing heterogeneous event records. To specify +such an event file, use: + +)UL()-1 LI( file[EVENTS\201event-spec\202] +)-1 LI( file[EVENTS\201\202])LU( +where )BD(event-spec)ES( is a string that specified the names, data +types, and optional image dimensions for each element of the event +record: +)UL()-1 LI( [name]:[n][type]:[\201lodim:\202hidim])LU( + +)0 P(Data types follow standard conventions for FITS binary tables, but include +two extra unsigned types \201'U' and 'V'\202: +)UL()-1 LI( )BD(B)ES( -- unsigned 8-bit char +)-1 LI( )BD(I)ES( -- signed 16-bit int +)-1 LI( )BD(J)ES( -- signed 32-bit int +)-1 LI( )BD(K)ES( -- signed 64-bit int +)-1 LI( )BD(E)ES( -- 32-bit float +)-1 LI( )BD(D)ES( -- 64-bit float +)-1 LI( )BD(U)ES( -- unsigned 16-bit int +)-1 LI( )BD(V)ES( -- unsigned 32-bit int)LU( +An optional integer value )BD(n)ES( can be prefixed to the type to indicate +that the element is an array of n values. For example: +) 1 37 PR( foo.fits[EVENTS\201x:I,y:I,status:4J\202])RP( +defines x and y as 16-bit ints and status as an array of 4 32-bit ints. + +)0 P(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 FITS TLMIN/TLMAX keywords. If the low +image dimension is not specified, it defaults to 1. Thus: + +)UL()-1 LI( RAWX:J:1:100 +)-1 LI( RAWX:J:100)LU( +both specify that the dimension of this column runs from 1 to 100. + +)0 P(NB: 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. + +)0 P(For example, suppose a FITS binary table has the following set of column +definitions: +) 22 54 PR( 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)RP( + +An raw event file containing these same data would have the event +specification: +) 1 61 PR( EVENTS\201X:I:10,Y:I:2:11,PHA:I,PI:J,TIME:D,DX:E:10,DY:E:3:12\202)RP( + +)0 P(If no event specification string is included within the EVENTS\201\202 operator, +then the event specification is taken from the )BD(EVENTS)ES( environment +variable: +) 1 65 PR( setenv EVENTS "X:I:10,Y:I:10,PHA:I,PI:J,TIME:D,DX:E:10,DY:E:10")RP( + +)0 P(In addition to knowing the data structure, it is necessary to know the +)EM(endian)ES( ordering of the data, i.e., whether or not the data is +in )EM(bigendian)ES( format, so that we can convert to the native +format for this platform. This issue does not arise for FITS Binary +Tables because all FITS 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 PC needs to be byte-swapped, since PCs +use little-endian ordering. To specify an ordering, use the +)EM(bigendian=)ES( or )EM(endian=)ES( keywords on the command-line +or the EVENTS_BIGENDIAN or EVENTS_ENDIAN environment variables. The +value of the )EM(bigendian)ES( variables should be "true" or "false", +while the value of the )EM(endian)ES( variables should be "little" or +"big". + +)0 P(For example, a PC can access data produced by a Sun using: +) 7 35 PR( hrc.nepr[EVENTS\201\202,bigendian=true] +or + hrc.nepr[EVENTS\201\202,endian=big] +or + setenv EVENTS_BIGENDIAN true +or + setenv EVENTS_ENDIAN big)RP( +If none of these are specified, the data are assumed to follow the +format for that platform and no byte-swapping is performed. + +)0 2 58 H(Non-FITS)WB 126 Sn()WB 46 Sn( Array Files)EA()EH( + +In addition to FITS images, Funtools programs and libraries can operate +on non-FITS files containing arrays of homogeneous data. To specify +an array file, use: +)UL()-1 LI( file[ARRAY\201array-spec\202] +)-1 LI( file[ARRAY\201\202])LU( + +where array-spec is of the form: +)UL()-1 LI( [type][dim1][.dim2][:skip][endian])LU( + +and where [type] is: +)UL()-1 LI( b \2018-bit unsigned char\202 +)-1 LI( s \20116-bit short int\202 +)-1 LI( u \20116-bit unsigned short int\202 +)-1 LI( i \20132-bit int\202 +)-1 LI( r,f \20132-bit float\202 +)-1 LI( d \20164-bit float\202)LU( + +)0 P(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. + +)0 P(If no array specification is included within the ARRAY\201\202 operator, +then the array specification is taken from the )BD(ARRAY)ES( environment +variable. For example: + +) 7 76 PR( foo.arr[ARRAY\201r512\202] # bitpix=-32 dim1=512 dim2=512 + foo.arr[ARRAY\201r512.400\202] # bitpix=-32 dim1=512 dim2=400 + foo.arr[ARRAY\201r512.400]\202 # bitpix=-32 dim1=512 dim2=400 + foo.arr[ARRAY\201r512.400:2880\202] # bitpix=-32 dim1=512 dim2=400 skip=2880 + foo.arr[ARRAY\201r512l\202] # bitpix=-32 dim1=512 dim2=512 endian=little + setenv ARRAY "r512.400:2880" + foo.arr[ARRAY\201\202] # bitpix=-32 dim1=512 dim2=400 skip=2880)RP( + +)0 2 59 H(Specifying)WB 127 Sn()WB 49 Sn( Image Sections)EA()EH( + +Once a data file \201and possibly, a FITS extension\202 has been specified, +the next \201optional\202 part of a bracket specification can be used to +select image )BD(section)ES( 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. + +)0 P(The format of the image section specification is one of the following: +)UL()-1 LI( file[xy0:xy1,block] +)-1 LI( file[x0:x1,y0:y1,block] +)-1 LI( file[x0:x1,*,block] +)-1 LI( file[*,y0:y1,block] +)-1 LI( file[*,block])LU( +where the limit values can be ints or "*" for default. A single "*" +can be used instead of val:val, as shown. Note that blocking is +applied to the section after it is extracted. + +)0 P(In addition to image sections specified by the lo and hi x,y limits, image +sections using center positions can be specified: +)UL()-1 LI( file[dim1@xcen,dim2@ycen] +)-1 LI( file[xdim2@xcen@ycen] +)-1 LI( file[dim1@xcen,dim2@ycen,block] +)-1 LI( file[dim@xcen@ycen,block])LU( +Note that the \201float\202 values for dim, dim1, dim2, xcen, ycen must be +specified or else the expression does not make sense! + +)0 P(In all cases, block is optional and defaults to 1. An 's' or 'a' can +be appended to signify "sum" or "average" blocking \201default is "sum"\202. +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: +) 2 21 PR()UL()-1 LI( file[-8:-7,-8:-7p] +)-1 LI( file[-8:-7,-8:-7,2p])LU()RP( +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. + +)0 P(Do not be confused by: +) 2 15 PR( foo.fits[2] + foo.fits[*,2])RP( +The former specifies opening the second extension of the FITS file. +The latter specifies application of block 2 to the image section. + +)0 P(Note that the section specification must come after +any of FITS )BD(ext)ES( name or )BD(ind)ES( number, +but all sensible defaults are supported: +)UL()-1 LI( file[ext] +)-1 LI( file[ext,index] +)-1 LI( file[index] +)-1 LI( file[ext,section] +)-1 LI( file[ext,index,section] +)-1 LI( file[index,section] +)-1 LI( file[section])LU( + +)0 2 60 H(Binning)WB 128 Sn()WB 50 Sn( FITS Binary Tables and Non-FITS Event Files)EH( + +If a FITS binary table or a non-FITS raw event file is to be binned +into a 2D image \201e.g., using the +)0 10 1 A(funimage)10 0 TN TL()Ec /AF f D( +program\202, 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: +) 1 74 PR( bincols=\201[xnam[:tlmin[:tlmax:[binsiz]]]],[ynam[:tlmin[:tlmax[:binsiz]]]]\202)RP( +in bracket syntax, and uses the column names thus specified. The tlmin, tlmax, +and binsiz specifiers determine the image binning dimensions using: +) 2 56 PR( dim = \201tlmax - tlmin\202/binsiz \201floating point data\202 + dim = \201tlmax - tlmin\202/binsiz + 1 \201integer data\202)RP( +These tlmin, tlmax, and binsiz specifiers can be omitted if TLMIN, +TLMAX, and TDBIN header parameters are present in the FITS 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. + +For example, to bin an HRC event list columns "VPOS" and "UPOS", use: +) 1 31 PR( hrc.nepr[bincols=\201VPOS,UPOS\202])RP( +or +) 1 42 PR( hrc.nepr[bincols=\201VPOS:49152,UPOS:4096\202])RP( +Note that you can optionally specify the dimensions of these columns +to cover cases where neither TLMAX keywords are defined in +the header. If either dimension is specified, then both must be specified. + +)0 P(You can set the FITS_BINCOLS or EVENTS_BINCOLS environment variable as +an alternative to adding the "bincols=" specifier to each file name +for FITS 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 +CPREF \201or PREFX\202 are searched for in the FITS binary table header. +Failing this, columns named "X" and "Y" are sought. If these are not +found, the code looks for columns containing the characters "X" and +"Y". Thus, you can bin on "DETX" and "DETX" columns without +specifying them, if these are the only column names containing the "X" +and "Y" characters. + +)0 P(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 +\201x,y\202 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: +) 1 15 PR( vcol=[colname])RP( +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: +) 10 24 PR( 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)RP( +There are two events with x,y value of \2011,1\202 so ordinarily a 2D image will +have a value of 2 in the \2011,1\202 pixel. If the v column is specified as the +value column: +) 1 20 PR( foo.fits'[vcol=v]')RP( +then each pixel will contain the additive sum of the associated \201x,y\202 +column values from the v column. For example, image pixel \2011,1\202 will +contain 1. + 1. = 2, image pixel \2012,2\202 will contain \2012 + 2\202 = 4, etc. + +)0 P(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 / \201divide sign\202 thus: +) 1 21 PR( foo.fits'[vcol=/v]')RP( +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 \201not a number\202. +Thus, in the above example, image pixel \2011.1\202 will contain 1/1 + 1/1 = 2, +image pixel \2012,2\202 will contain \2011/2 + 1/2\202 = 1, etc. Image pixel \2014,4\202 +will contain \2011/0 + 1/4\202 = NaN. + +)0 P(You can set the FITS_VCOL or EVENTS_VCOL environment variable as +an alternative to adding the "vcol=" specifier to each file name +for FITS binary tables and raw event files, respectively. + +)0 P(Finally, when binning events, the data type of the resulting 2D image +must be specified. This can be done with the "bitpix=[n]" keyword in +the bracket specification. For example: +) 1 45 PR( events.fits[bincols=\201VPOS,UPOS\202,bitpix=-32])RP( +will create a floating point image binned on columns VPOS and UPOS. +If no bitpix keyword is specified, bitpix=32 is assumed. As with +bincols values, you also can use the FITS_BITPIX and EVENTS_BITPIX +environment variables to set this value for FITS binary tables and +raw event files, respectively. + +)0 P(The )BD(funimage)ES( program also allows you to create a 1D image projection +along any column of a table by using the )BD(bincols=[column])ES( +filter specification and specifying a single column. +For example, the following command projects a 1D image along +the chipx column of a table: +) 1 43 PR( funimage ev.fits'[bincols=chipx]' im.fits)RP( +See )0 10 1 A(funimage)10 0 TN TL()Ec /AF f D( for more +information about creating 1D and 2D images. + +)0 P(Finally, please note that Funtools supports most FITS 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. + +)0 2 61 H(Table)WB 129 Sn()WB 119 Sn( and Spatial Region Filters)EH( +)0 P(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: +)UL()-1 LI( file[ext|ind|ARRAY\201\202|EVENTS\201\202,section][filters] +)-1 LI( file[ext|ind|ARRAY\201\202|EVENTS\201\202,section,filters])LU( +where: +)UL()-1 LI( )BD(file)ES( is the Funtools file name +)-1 LI( )BD(ARRAY\201\202)ES( is an array specification +)-1 LI( )BD(EVENTS\201\202)ES( is an event list specification +)-1 LI( )BD(ext)ES( is the FITS extension name +)-1 LI( )BD(ind)ES( is the FITS extension number +)-1 LI( )BD(section)ES( is the image section to extract +)-1 LI( )BD(filters)ES( are spatial region and table \201row\202 filters to apply)LU( + +The topics of table and region filtering are covered in detail in: +)UL()-1 LI()0 52 1 A(Table Filtering)52 0 TN TL()Ec /AF f D( +)-1 LI()0 54 1 A(Spatial Region Filtering)54 0 TN TL()Ec /AF f D()LU( + +)0 2 62 H(Disk)WB 130 Sn()WB 51 Sn( Files and Other Supported File Types)EA()EH( +)0 P(The specified )BD(file)ES( 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. NB: if a FITS 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 FITS programs such as ds9. + +)0 P(The special keywords "stdin" and "stdout" designate Unix standard +input and standard output, respectively. The string "-" \201hyphen\202 will +be taken to mean "stdin" if the file is opened for reading and +"stdout" if the file is opened for writing. + +)0 P(A file also can be an INET socket on the same or another machine using +the syntax: +) 1 14 PR( machine:port)RP( +Thus, for example: +) 1 14 PR( karapet:1428)RP( +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: +) 1 7 PR( :1428)RP( +This means to open port 1428 on the current machine. Socket support +allows you to generate a distributed pipe: +) 2 48 PR( on karapet: funtask1 in.fits bynars:1428 + on bynars: funtask2 :1428 out.fits)RP( +The socket mechanism thus supports simple parallel processing using +)BD(process decomposition)ES(. Note that parallel processing using +)BD(data decomposition)ES( is supported via the )BD(section)ES( specifier \201see +below\202, and the )BD(row#)ES( specifier, which is part of +)0 52 1 A(Table Filtering)52 0 TN TL()Ec /AF f D(. + +)0 P(A file also can be a pointer to shared memory using the syntax: +) 1 22 PR( shm:[id|@key][:size])RP( +A shared memory segment is specified with a )BD(shm:)ES( prefix, +followed by either the shared memory id or the shared memory key +\201where the latter is prefixed by the '@' character\202. The size \201in +bytes\202 of the shared memory segment can then be appended \201preceded by +the ':' character\202. If the size specification is absent, the code will +attempt to determine the length automatically. + +If the open mode contains the string "w+", then the memory segment will be +created if it does not exist. \201It also will be released and deleted when the +file is closed.\202 In the case where a memory segment is being created, the +length of the segment is required. + +)0 P(A file also can be Unix piped command \201i.e. a program to run\202 using the syntax: +) 1 31 PR( "pipe: command arg1 ... argn")RP( +The output from the command must be a valid FITS file. It is important +to use quotes to protect spaces so that command arguments are passed +correctly. A silly example is: +) 1 60 PR( fundisp "pipe: funtable 'foo.fits[cir 512 512 .1]' stdout")RP( +This seemed like a good idea at the time ... + +)0 2 63 H(Lists)WB 131 Sn()WB 51 Sn( of Files)EA()EH( + +)0 P(Funtools also will process a list of files as a single file using the +syntax: +) 1 31 PR( "list: file1 file2 ... filen")RP( +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 \201using their own filters\202: +) 17 77 PR( fundisp "list: foo1.fits[cir\201512,512,10\202] foo2.fits[cir\201511,511,10\202]" + 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)RP( +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: +) 1 72 PR( fundisp "list: 'foo1.fits[cir 512 512 .1]' foo2.fits[cir\201511,511,.1\202]")RP( + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 64 H(Last)WB 132 Sn( updated: February 15, 2006)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (text.html) D +/Ti (Column-based Text Files) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 47 Sn( + + +)0 2 65 H(Funtext:)WB 134 Sn()WB 133 Sn( Support for Column-based Text Files)EA()EH( + + +)0 2 66 H(Summary)WB 135 Sn()EH( +)0 P(This document contains a summary of the options for processing column-based +text files. + + +)0 2 67 H(Description)WB 136 Sn()EH( + +)0 P(Funtools will automatically sense and process "standard" +column-based text files as if they were FITS binary tables without any +change in Funtools syntax. In particular, you can filter text files +using the same syntax as FITS binary tables: +) 3 54 PR( 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)RP( + +)0 P(The first example displays a filtered selection of a text file. The +second example converts a text file to an RDB file. The third example +converts a filtered selection of a text file to a FITS binary table. + +)0 P(Text files can also be used in Funtools image programs. In this case, +you must provide binning parameters \201as with raw event files\202, using +the bincols keyword specifier: + +) 1 75 PR( bincols=\201[xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]])RP( + +For example: +) 1 64 PR( funcnts foo'[bincols=\201x:1024,y:1024\202]' "ann 512 512 0 10 n=10")RP( + +)0 2 68 H(Standard)WB 137 Sn( Text Files)EH( + +)0 P(Standard text files have the following characteristics: + +)UL()-1 LI( Optional comment lines start with # +)-1 LI( Optional blank lines are considered comments +)-1 LI( An optional table header consists of the following \201in order\202: +)UL( )-1 LI( a single line of alpha-numeric column names + )-1 LI( an optional line of unit strings containing the same number of cols + )-1 LI( an optional line of dashes containing the same number of cols)LU( +)-1 LI( Data lines follow the optional header and \201for the present\202 consist of + the same number of columns as the header. +)-1 LI( Standard delimiters such as space, tab, comma, semi-colon, and bar.)LU( + +)0 P(Examples: + +) 26 46 PR( # rdb file + foo1 foo2 foo3 foos + ---- ---- ---- ---- + 1 2.2 3 xxxx + 10 20.2 30 yyyy + + # multiple consecutive whitespace and dashes + foo1 foo2 foo3 foos + --- ---- ---- ---- + 1 2.2 3 xxxx + 10 20.2 30 yyyy + + # comma delims and blank lines + foo1,foo2,foo3,foos + + 1,2.2,3,xxxx + 10,20.2,30,yyyy + + # bar delims with null values + foo1|foo2|foo3|foos + 1||3|xxxx + 10|20.2||yyyy + + # header-less data + 1 2.2 3 xxxx + 10 20.2 30 yyyy)RP( + +)0 P(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 \201no null values between +consecutive delimiters\202. 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 \201e.g. RDB file\202. 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. \201Theoretically, there are +pathological cases, which will be taken care of as needed\202. Bad parsers +are discarded on the fly. + +)0 P(If the header does not exist, then names "col1", "col2", 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: +) 4 58 PR( fundisp foo'[foo1>5]' + FOO1 FOO2 FOO3 FOOS + ---------- --------------------- ---------- ------------ + 10 20.20000000 30 yyyy)RP( + +)0 2 69 H(Comments)WB 138 Sn( Convert to Header Params)EH( + +)0 P(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: + +)0 P(1. FITS-style comments have an equal sign "=" between the keyword and +value and an optional slash "/" to signify a comment. The strict FITS +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: + +) 5 55 PR( # 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)RP( + +Note that the fits3c comment is not quoted and therefore its value is the +single token "/usr/local/bin" and the comment is "opt/local/bin /usr/bin". +This is different from the quoted comment in fits4c. + +)0 P(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 "/" after the string will signify a comment. +For example: + +) 9 54 PR( # 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 + + # 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)RP( + +)0 P(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. + +)0 P(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 "hcolfmt=" specification. See below for a detailed +description. + +)0 2 70 H(Multiple)WB 139 Sn( Tables in a Single File)EH( + +)0 P( +Multiple tables are supported in a single file. If an RDB-style file +is sensed, then a ^L \201vertical tab\202 will signify end of +table. Otherwise, an end of table is sensed when a new header \201i.e., +all alphanumeric columns\202 is found. \201Note that this heuristic does not +work for single column tables where the column type is ASCII and the +table that follows also has only one column.\202 You also can specify +characters that signal an end of table condition using the )BD(eot=)ES( +keyword. See below for details. + +)0 P(You can access the nth table \201starting from 1\202 in a multi-table file +by enclosing the table number in brackets, as with a FITS extension: + +) 1 18 PR( fundisp foo'[2]')RP( +The above example will display the second table in the file. +\201Index values start at 1 in oder to maintain logical compatibility +with FITS files, where extension numbers also start at 1\202. + + +)0 2 71 H(TEXT\201\202)WB 140 Sn( Specifier)EH( + +)0 P(As with ARRAY\201\202 and EVENTS\201\202 specifiers for raw image arrays and raw +event lists respectively, you can use TEXT\201\202 on text files to pass +key=value options to the parsers. An empty set of keywords is +equivalent to not having TEXT\201\202 at all, that is: + +) 2 23 PR( fundisp foo + fundisp foo'[TEXT\201\202]')RP( + +are equivalent. A multi-table index number is placed before the TEXT\201\202 +specifier as the first token, when indexing into a multi-table: + + fundisp foo'[2,TEXT\201...\202]' + +)0 P(The filter specification is placed after the TEXT\201\202 specifier, separated +by a comma, or in an entirely separate bracket: + +) 2 47 PR( fundisp foo'[TEXT\201...\202,circle 512 512 .1]' + fundisp foo'[2,TEXT\201...\202][circle 512 512 .1]')RP( + +)0 2 72 H(Text\201\202)WB 141 Sn( Keyword Options)EH( + +)0 P( +The following is a list of keywords that can be used within the TEXT\201\202 +specifier \201the first three are the most important\202: + +)0 DL( +)0 P()0 DT( delims="[delims]" +)DD(Specify token delimiters for this file. Only a single parser having these +delimiters will be used to process the file. +) 2 40 PR( fundisp foo.fits'[TEXT\201delims="!"\202]' + fundisp foo.fits'[TEXT\201delims="\200t%"\202]')RP( + +)0 P()0 DT( comchars="[comchars]" +)DD( Specify comment characters. You must include "\200n" to allow blank lines. +These comment characters will be used for all standard parsers \201unless delims +are also specified\202. +) 1 42 PR( fundisp foo.fits'[TEXT\201comchars="!\200n"\202]')RP( + +)0 P()0 DT( cols="[name1:type1 ...]" +)DD( 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. +) 1 70 PR( fundisp foo.fits'[TEXT\201cols="x:I,y:I,pha:I,pi:I,time:D,dx:E,dy:e"\202]')RP( +)0 P(If the column specifier is the only keyword, then the cols= is not +required \201in analogy with EVENTS\201\202\202: +) 1 63 PR( fundisp foo.fits'[TEXT\201x:I,y:I,pha:I,pi:I,time:D,dx:E,dy:e\202]')RP( +Of course, an index is allowed in this case: +) 1 65 PR( fundisp foo.fits'[2,TEXT\201x:I,y:I,pha:I,pi:I,time:D,dx:E,dy:e\202]')RP( + +)0 P()0 DT( eot="[eot delim]" +)DD( Specify end of table string specifier for multi-table files. RDB +files support ^L. The end of table specifier is a string and the whole +string must be found alone on a line to signify EOT. For example: +) 1 37 PR( fundisp foo.fits'[TEXT\201eot="END"\202]')RP( +will end the table when a line contains "END" is found. Multiple lines +are supported, so that: +) 1 43 PR( fundisp foo.fits'[TEXT\201eot="END\200nGAME"\202]')RP( +will end the table when a line contains "END" followed by a line +containing "GAME". +)0 P(In the absence of an EOT delimiter, a new table will be sensed when a new +header \201all alphanumeric columns\202 is found. + +)0 P()0 DT( null1="[datatype]" +)DD( 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="type" to +specify its data type. + +)0 P()0 DT( alen=[n] +)DD(Specify size in bytes for ASCII type columns. +FITS binary tables only support fixed length ASCII columns, so a +size value must be specified. The default is 16 bytes. + +)0 P()0 DT( nullvalues=["true"|"false"] +)DD(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. + +)0 P()0 DT( whitespace=["true"|"false"] +)DD( Specify whether surrounding white space should be kept as part of +string tokens. By default surrounding white space is removed from +tokens. + +)0 P()0 DT( header=["true"|"false"] +)DD(Specify whether to require a header. This is needed by tables +containing all string columns \201and with no row containing dashes\202, 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. + +)0 P()0 DT( units=["true"|"false"] +)DD(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. + +)0 P()0 DT( i2f=["true"|"false"] +)DD(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= \201or by changing the value of +the column in row 1\202. + +)0 P()0 DT( comeot=["true"|"false"|0|1|2] +)DD(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 \201the +default for standard parsers\202, then non-blank lines \201e.g. lines +beginning with '#'\202 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. + +)0 P()0 DT( lazyeot=["true"|"false"] +)DD(Specify whether "lazy" end of table should be permitted \201default is +true for standard formats, except rdb format where explicit ^L is required +between tables\202. A lazy EOT can occur when a new table starts directly +after an old one, with no special EOT delimiter. A check for this EOT +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: +) 9 20 PR( ival1 sval3 + ----- ----- + 1 two + 3 four + + jval1 jval2 tval3 + ----- ----- ------ + 10 20 thirty + 40 50 sixty)RP( +Here the line "jval1 ..." contains all string tokens. In addition, +the number of tokens in this line \2013\202 differs from the number of +tokens in the previous line \2012\202. Therefore a new table is assumed +to have started. Similarly: +) 9 20 PR( ival1 ival2 sval3 + ----- ----- ----- + 1 2 three + 4 5 six + + jval1 jval2 tval3 + ----- ----- ------ + 10 20 thirty + 40 50 sixty)RP( +Again, the line "jval1 ..." contains all string tokens. The number of +string tokens in the previous row \2011\202 differs from the number of +tokens in the current row\2013\202. We therefore assume a new table as been +started. This lazy EOT test is not performed if lazyeot is explicitly +set to false. + +)0 P()0 DT( hcolfmt=[header column format] +)DD( 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: +) 3 95 PR( #Column e_Kmag \201F6.3\202 ?\201k_msigcom\202 K total magnitude uncertainty \2014\202 [ucd=ERROR] + #Column Rflg \201A3\202 \201rd_flg\202 Source of JHK default mag \2016\202 [ucd=REFER_CODE] + #Column Xflg \201I1\202 [0,2] \201gal_contam\202 Extended source contamination \20110\202 [ucd=CODE_MISC])RP( + +while Sextractor files have headers containing column names alone: + +) 4 79 PR( # 1 X_IMAGE Object position along x [pixel] + # 2 Y_IMAGE Object position along y [pixel] + # 3 ALPHA_J2000 Right ascension of barycenter \201J2000\202 [deg] + # 4 DELTA_J2000 Declination of barycenter \201J2000\202 [deg])RP( +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 "$col" \201or "$name"\202 to +specify placement of the column name, "$fmt" to specify placement of the +data format, and "$skip" to specify tokens to ignore. You also can +specify tokens explicitly \201or, for those users familiar with how +sscanf works, you can specify scanf skip specifiers using "%*"\202. +For example, the VizieR hcolfmt above might be specified in several ways: +) 3 67 PR( Column $col \201$fmt\202 # explicit specification of "Column" string + $skip $col \201$fmt\202 # skip one token + %*s $col \201$fmt\202 # skip one string \201using scanf format\202)RP( +while the Sextractor format might be specified using: +) 2 59 PR( $skip $col # skip one token + %*d $col # skip one int \201using scanf format\202)RP( +You must ensure that the hcolfmt statement only senses actual column +definitions, with no false positives or negatives. For example, the +first Sextractor specification, "$skip $col", will consider any header +line containing two tokens to be a column name specifier, while the +second one, "%*d $col", requires an integer to be the first token. In +general, it is preferable to specify formats as explicitly as +possible. + +)0 P(Note that the VizieR-style header info is sensed automatically by the +funtools standard VizieR-like parser, using the hcolfmt "Column $col +\201$fmt\202". There is no need for explicit use of hcolfmt in this case. + +)0 P()0 DT( debug=["true"|"false"] +)DD(Display debugging information during parsing. +)LD( + +)0 2 73 H(Environment)WB 142 Sn( Variables)EH( + +)0 P( +Environment variables are defined to allow many of these TEXT\201\202 values to be +set without having to include them in TEXT\201\202 every time a file is processed: + +) 10 36 PR( 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)RP( + +)0 2 74 H(Restrictions)WB 143 Sn( and Problems)EH( + +)0 P( +As with raw event files, the '+' \201copy extensions\202 specifier is not +supported for programs such as funtable. + +)0 P(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: +) 4 20 PR( xxx yyy zzz + ---- ---- ---- + 111 aaa bbb + ccc 222 ddd)RP( +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: +) 5 38 PR( fundisp foo.tab + XXX YYY ZZZ + ---------- ------------ ------------ + 111 'aaa' 'bbb' + 1667457792 '222' 'ddd')RP( +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: +) 10 40 PR( xxx yyy zzz + ---- ---- ---- + "111" aaa bbb + ccc 222 ddd + + [sh] fundisp foo.tab + XXX YYY ZZZ + ------------ ------------ ------------ + '111' 'aaa' 'bbb' + 'ccc' '222' 'ddd')RP( +You can edit the file and explicitly set the data type of the first column: +) 10 40 PR( xxx:3A yyy zzz + ------ ---- ---- + 111 aaa bbb + ccc 222 ddd + + [sh] fundisp foo.tab + XXX YYY ZZZ + ------------ ------------ ------------ + '111' 'aaa' 'bbb' + 'ccc' '222' 'ddd')RP( +You also can explicitly set the column names and data types of all columns, +without editing the file: +) 5 52 PR( [sh] fundisp foo.tab'[TEXT\201xxx:3A,yyy:3A,zzz:3a\202]' + XXX YYY ZZZ + ------------ ------------ ------------ + '111' 'aaa' 'bbb' + 'ccc' '222' 'ddd')RP( +The issue of data type transitions \201which to allow and which to disallow\202 +is still under discussion. + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 75 H(Last)WB 144 Sn( updated: August 3, 2007)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (view.html) D +/Ti (Database View Support for Tables) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 48 Sn( + + +)0 2 76 H(Funview:)WB 146 Sn()WB 145 Sn( Database View Support for Tables)EA()EH( + + +)0 2 77 H(Summary)WB 147 Sn()EH( +)0 P(This document contains a summary of the options for utilizing +database-inspired Views of tables. + + +)0 2 78 H(Description)WB 148 Sn()EH( + +)0 2 79 H(Database)WB 149 Sn( Views)EH( +)0 P(In database parlance, a )BD(View)ES( defines a "virtual table", i.e., +a description of row and/or column selection filters \201but with no +permanent storage space allocated\202. 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: +) 1 72 PR(http://www.cs.unibo.it/~ciaccia/COURSES/RESOURCES/SQLTutorial/sqlch5.htm)RP( +for a good discussion of SQL Views.] + +)0 P(Funtools supports an expanded notion of Views for all tabular data +\201FITS tables, raw binary tables, and ASCII column files\202. Funtools +Views allow you to pre-set values for the filter specification, the +columns to activate, and display format \201though the latter is for +fundisp only\202. 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. + +)0 2 80 H(Funtools)WB 150 Sn( View Attributes)EH( +)0 P(A Funtools View is a text file containing one or more of the following +columns: +) 7 46 PR( column description + ------ ----------------------------- + view name of view + file data file name or template + filter filter specification + columns columns to activate + format fundisp format specification)RP( +All of the attribute columns are optional, including +the )BD(view)ES( 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 \201obviously if neither the view or the file column is specified, +the input View specification will never be used\202. You can specify any +combination of filter, column, and format parameters. \201It also is +possible to apply file-specific View to other files; see the discussion +on )BD(View Lists)ES( below\202. Each column has a size limit of 1024 characters. + +)0 P(For example, consider the following View file: +) 13 70 PR( 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)RP( +This database example is in rdb format, i.e. using tab delimiters and +permitting null values. Any valid ASCII 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. + +)0 P(The first five entries \201x3, x2, x1, x1a, x0\202 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. + +)0 P(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 \201see )BD(View Lists)ES( below\202 so that the associated +parameter\201s\202 were applied to that file. + +)0 P(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. + +)0 2 81 H(Invoking)WB 151 Sn( a Funtools View \201in Place of an Input File\202)EH( +)0 P(To use a Funtools View, you simply pre-pend the "v:" prefix to a View name or +a file name where an input file name usually is specified. For example: +) 1 14 PR( fundisp v:x3)RP( +specifies that the View named x3 \201with its file name and associated +parameters\202 is processed as the input file to fundisp. Using the +example database, above, this is equivalent to: +) 1 73 PR( fundisp -f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha")RP( +That is, the format is used with fundisp's -f \201format\202 switch, while the +filename and extension are composed of the x3 View's filename and +region filter. + +)0 P(Similarly, executing a command such as: +) 1 19 PR( fundisp v:foo.fit)RP( +will match the unnamed View associated with the template "*.fit". +This is equivalent to executing: +) 1 46 PR( fundisp foo.fit'[cir 400 400 3]' "x y dx dy")RP( +Of course, if you omit the "v:" prefix, then no View processing takes place: +) 2 66 PR( fundisp foo.fit # process foo.fit without any View parameters + fundisp x3 # error \201assuming there is no file named x3\202)RP( + +)0 2 82 H(Basic)WB 152 Sn( View Matching Rules)EH( + +)0 P(When a "v:" prefix is recognized, Funtools searches for a View database +file in the following order: +) 5 59 PR( location description + ------------ ------------------------------------ + FUN_VIEWFILE environment variable \201any file name\202 + ./.funtools.vu hidden file, default name + $HOME/.funtools.vu hidden file, default name)RP( +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: + +)0 P(1. An attempt is made to match the input name \201i.e., the part of the +input View after the "v:" prefix\202 against the )BD(view)ES( column value +\201if present\202 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., )BD(the order of the +database rows matters)ES(. + +)0 P(2. If no )BD(view)ES( match is made, an attempt is made to match the input +name against the )BD(file)ES( column value \201if present\202. Matching is +performed on the full pathname of both the input name and the +database file name, and on the non-directory \201root\202 part of these +files. This means that the root specification: +) 1 18 PR( fundisp v:snr.ev)RP( +will match a row in the database that has a full pathname in the file, +allowing you to use a )BD(file)ES(-matched View without having to +specify the full pathname. In this example, the "v:snr.ev" View +specification will match the first row \201v:x3\202 in the database: +) 1 67 PR( x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1)RP( +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. + +)0 P(3. If neither a )BD(view)ES( or a )BD(view)ES( match has been found, +then a simple template match is attempted against the )BD(view)ES( +values. Template matching supports a simplified version of file +globbing \201not a regular expression\202, with support for a single "*" +\201all characters\202, "?" \201single character\202, or "[...]" \201range\202 specification. + +)0 P(4. If no template match was found on the )BD(view)ES( column, then a +simple template match is attempted against the )BD(file)ES( columns. + +)0 P(5. If no match is found, then the filename \201minus the "v:" prefix\202 is +returned. + +)0 2 83 H(More)WB 153 Sn( on View Matching Rules: Single vs. Multiple Matches )EH( + +The matching rules described above stop after the first match, +regardless of whether that match provides values for all three +parameters \201filter, columns, and format\202. In cases where a )BD(view)ES( +or )BD(file)ES( 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 "global" values to several Views. + +)0 P(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 FUN_VIEWMATCH environment variable. If +the FUN_VIEWMATCH environment variable exists and if its value begins +with "s", 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 "m" \201or does not exist\202, +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. + +)0 P(Thus, in the example above, the View specification: +) 1 14 PR( fundisp v:x1)RP( +will take the file name and filter value from the x1 View: +) 1 70 PR( x1 ${HOME}/data/snr.ev cir 512 512 .1)RP( +The column value then will be taken from the "*.ev" file template match +against the x1 file name: +) 1 52 PR( *.ev x y pi pha)RP( +Note once again that order is important: missing values are taken in the +order in which the template matches are processed. + +)0 2 84 H(View)WB 154 Sn( Lists: Applying a View to Any File)EH( + +)0 P(It is possible to apply a named View, or even several Views, to any +data file by appending a )BD(viewlist)ES( immediately after the standard "v:" +prefix. A viewlist takes the form: +) 1 15 PR( :v1,v2,...vn:)RP( +where v1, v2, etc. are named Views. The two ":" colon characters surrounding +the list are required. Thus, the syntax for applying a viewlist to a file is: +) 1 34 PR( v::view1,view2,...viewn:filename)RP( +Note that the name after the last ":" is assumed to be a file; it is +not permissible \201or sensible\202 to use a View name. + +)0 P(For example, the View specification: +) 1 19 PR( fundisp v::x2:foo)RP( +applies the x2 View to the file foo \201even if there is a View named foo\202 +and \201in using our example database\202 is equivalent to: +) 1 45 PR( ./fundisp foo'[cir 512 512 .1] "x y pi pha")RP( +The same command can be effected using a list of Views: +) 1 23 PR( fundisp v::x1,x1a:foo)RP( + +)0 P(What happens if a viewlist is used and the file also matches a +template? Consider, for example, this View specification: +) 1 23 PR( fundisp v::x2:foo.fit)RP( +Here, the x2 View will supply filter and column values, while the +template *.fit can also supply \201different\202 filter and column +values. In this case, the explicitly specified Views of the viewlist +trump the matched view values. + +)0 P(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: +) 1 24 PR( fundisp v::x2:foo.fits)RP( +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 ":" with a "-" in a viewlist +specification: +) 1 24 PR( fundisp v:-x2:foo.fits)RP( +The use of ":+" 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. + +)0 2 85 H(Overriding)WB 155 Sn( Values Associated with a View)EH( + +)0 P(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: +) 1 14 PR( fundisp v:x3)RP( +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: +) 1 73 PR( fundisp -f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha")RP( +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: +) 1 31 PR( fundisp v:x3'[cir 400 400 3]')RP( +will use the columns and format of the x3 View but not the x3 filter. Further +examples are: +) 2 67 PR( fundisp v:x3 "x y dx dy" # activate a different set of columns + fundisp -f "I=%3d" v:x3 # use a different format statement)RP( + +)0 P(Note that extension names, extension index values, and other +non-filter specifications )BD(do not)ES( override the View +filter. Thus: +) 1 22 PR( fundisp v:foo.fit[3])RP( +will still use the filter associated with the .fit template \201see above\202, since +the "3" is an extension index, not a filter. + +)0 2 86 H(Environment)WB 156 Sn( Variables)EH( + +The following environment variables are used by Funtools Views: +)0 DL()0 DT()BD(FUN_VIEWNAME)ES( +)DD( The )BD(FUN_VIEWNAME)ES( environment variable specifies the +name and location of the View database file. If not present, the +files ./.funtools.vu and $HOME/.funtools.vu are searched for, in +that order. + +)0 DT()BD(FUN_VIEWMATCH)ES( +)DD( The )BD(FUN_VIEWMATCH)ES( 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 "s", +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 "m", then multiple matches are used to try to fill in missing +parameters. The default is to use multiple matches.)LD( + +)0 2 87 H(Restrictions)WB 157 Sn( and Problems)EH( + +Support for overriding a filter \201while not overriding extension names, +extension indexes, etc.\202 requires that we can sense the presence of a +filter in a bracket specification. It is unclear yet whether our +algorithm is perfect. + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 88 H(Last)WB 158 Sn( updated: August 3, 2007)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (filters.html) D +/Ti (Table Filtering) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 52 Sn( + + +)0 2 89 H(Funfilters:)WB 165 Sn()WB 159 Sn( Filtering Rows in a Table)EA()EH( + + +)0 2 90 H(Summary)WB 166 Sn()EH( +)0 P(This document contains a summary of the user interface for +filtering rows in binary tables. + + +)0 2 91 H(Description)WB 167 Sn()EH( +)0 P(Table filtering allows a program to select rows from an table \201e.g., +X-ray event list\202 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. + +)0 P(A filter expression is specified using bracket notation appended to +the filename of the data being processed: +) 1 23 PR( foo.fits[pha==1&)SY(\160)ES(==2])RP( +It is also possible to put region specification inside a file and +then pass the filename in bracket notation: +) 1 19 PR( foo.fits[@my.reg])RP( +Filters must be placed after the extension and image section +information, when such information is present. The correct order is: +)UL()-1 LI( file[fileinfo,sectioninfo][filters] +)-1 LI( file[fileinfo,sectioninfo,filters])LU( +where: +)UL()-1 LI( )BD(file)ES( is the Funtools file name +)-1 LI( )BD(fileinfo)ES( is an ARRAY, EVENT, FITS extension, or FITS index +)-1 LI( )BD(sectioninfo)ES( is the image section to extract +)-1 LI( )BD(filters)ES( are spatial region and table \201row\202 filters to apply)LU( +See )0 42 1 A(Funtools Files)42 0 TN TL()Ec /AF f D( for more information +on file and image section specifications. + +)0 2 92 H(Filter)WB 168 Sn( Expressions)EH( + +)0 P(Table filtering can be performed on columns of data in a FITS +binary table or a raw event file. Table filtering is accomplished by +means of )BD(table filter specifications)ES(. An table filter +specification consists of one or more )BD(filter expressions)ES( Filter +specifications also can contain comments and local/global processing +directives. + +)0 P(More specifically, a filter specification consist of one or more lines +containing: +) 13 75 PR( # 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])RP( + +)0 P(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: +) 15 55 PR( Operator Associativity + -------- ------------- + \201\202 left to right + !! \201logical not\202 right to left + ! \201bitwise not\202 - \201unary minus\202 right to left + * / left to right + + - left to right + < <= > >= left to right + == != left to right + & \201bitwise and\202 left to right + ^ \201bitwise exclusive or\202 left to right + | \201bitwise inclusive or\202 left to right + && \201logical and\202 left to right + || \201logical or\202 left to right + = right to left)RP( +For example, if energy and pha are columns in a table, +then the following are valid expressions: +) 4 24 PR( pha>1 + energy == pha + \201pha>1\202 && \201energy<=2\202 + max\201pha,energy\202>=2.5)RP( + +)0 P(Comparison values can be integers or floats. Integer comparison values can be +specified in decimal, octal \201using '0' as prefix\202, hex \201using '0x' as prefix\202 +or binary \201using '0b' as prefix\202. Thus, the following all specify the same +comparison test of a status mask: +) 4 40 PR( \201status & 15\202 == 8 # decimal + \201status & 017\202 == 010 # octal + \201status & 0xf\202 == 0x8 # hex + \201status & 0b1111\202 == 0b1000 # binary)RP( +)0 P(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 +"*" character can be utilized as the high limit value to denote +processing of the remaining rows. Thus: +) 1 14 PR( row#=100:109)RP( +processes 10 rows, starting with row 100 \201counting from 1\202, +while: +) 1 12 PR( row#=100:*)RP( +specifies that all but the first 99 rows are to be processed. + +)0 P(Spatial region filtering allows a program to select regions of an +image or rows of a table \201e.g., X-ray events\202 using simple geometric +shapes and boolean combinations of shapes. For a complete description +of regions, see )0 54 1 A(Spatial Region Filtering)54 0 TN TL()Ec /AF f D(. + +)0 2 93 H(Separators)WB 169 Sn()WB 160 Sn( Also Are Operators)EA()EH( +)0 P(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 AND operator +is automatically generated in its place. Thus and expression such as: +) 1 15 PR( pha==1,pi=2:4)RP( +is equivalent to: +) 1 26 PR( \201pha==1\202 && \201pi>=2&)SY(\160)ES(<=4\202)RP( +)0 P([Note that the behavior of separators is different for filter expressions +and spatial region expressions. The former uses AND as the operator, while +the latter user OR. See +)0 60 1 A(Combining Region and Table Filters)60 0 TN TL()Ec /AF f D( +for more information about these conventions and how they are treated +when combined.] + +)0 2 94 H(Range)WB 170 Sn()WB 161 Sn( Lists)EA()EH()0 P( +)0 P(Aside from the standard C syntax, filter expressions can make use of +IRAF-style )BD(range lists)ES( 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: +) 4 52 PR( 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)RP( +The vv's above must be numeric constants; the right hand side of a +range list cannot contain a column name or header value. +)0 P(Note that, unlike an ordinary comma separator, the comma separator used +between two or more range expressions denotes OR. 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: +) 1 18 PR( col = :3,6:8,10:)RP( +is equivalent to: +) 1 47 PR( \201col<=3\202 || \201col>=6 && col <=8\202 || \201col >=10\202)RP( +Note also that the single-valued rangelist: +) 1 11 PR( col = val)RP( +is equivalent to the C-based filter expression: +) 1 12 PR( col == val)RP( +assuming, of course, that val is a numeric constant. + +)0 2 95 H(Math)WB 171 Sn()WB 162 Sn( Operations and Functions)EA()EH()0 P( +)0 P(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: +)UL()-1 LI(\201pi+pha\202>\2012+log\201pi\202-pha\202 +)-1 LI( min\201pi,pha\202*14>x +)-1 LI( max\201pi,pha\202==\201pi+1\202 +)-1 LI( feq\201pi,pha\202 +)-1 LI( div\201pi,pha\202>0)LU( +The function feq\201a,b\202 returns true \2011\202 if the difference between a and b +\201taken as double precision values\202 is less than approximately 10E-15. +The function div\201a,b\202 divides a by b, but returns NaN \201not a number\202 +if b is 0. It is a safe way to avoid floating point errors when +dividing one column by another. + +)0 2 96 H(Include)WB 172 Sn()WB 163 Sn( Files)EA()EH()0 P( +)0 P(The special )BD(@filename)ES( directive specifies an include file +containing filter expressions. This file is processed as part of +the overall filter descriptor: +) 1 23 PR( foo.fits[pha==1,@foo])RP( + +)0 2 97 H(Header)WB 173 Sn()WB 164 Sn( Parameters)EA()EH()0 P( +)0 P(The filter syntax supports comparison between a column value and a +header parameter value of a FITS binary tables \201raw event files have no +such header\202. The header parameters can be taken from the binary +table header or the primary header. For example, assuming there is a +header value MEAN_PHA in one of these headers, you can select photons +having exactly this value using: + +)UL()-1 LI( pha==MEAN_PHA)LU( + +)0 2 98 H(Examples)WB 174 Sn()EH( +)0 P(Table filtering is more easily described by means of examples. +Consider data containing the following table structure: +)UL()-1 LI( double TIME +)-1 LI( int X +)-1 LI( int Y +)-1 LI( short PI +)-1 LI( short PHA +)-1 LI( int DX +)-1 LI( int DY)LU( + +)0 P(Tables can be filtered on these columns using IRAF/QPOE range syntax or +any valid C syntax. The following examples illustrate the possibilities: +)0 DL( +)0 P()0 DT( pha=10 +)0 DT( pha==10 +)DD( select rows whose pha value is exactly 10 + +)0 P()0 DT( pha=10:50 +)DD( select rows whose pha value is in the range of 10 to 50 + +)0 P()0 DT( pha=10:50,100 +)DD( select rows whose pha value is in the range of 10 to 50 or is +equal to 100 + +)0 P()0 DT( pha>=10 && pha<=50 +)DD( select rows whose pha value is in the range of 10 to 50 + +)0 P()0 DT( pi=1,2&&pha>3 +)DD( select rows whose pha value is 1 or 2 and whose pi value is 3 + +)0 P()0 DT( pi=1,2 || pha>3 +)DD( select rows whose pha value is 1 or 2 or whose pi value is 3 + +)0 P()0 DT( pha==pi+1 +)DD( select rows whose pha value is 1 less than the pi value + +)0 P()0 DT( \201pha==pi+1\202 && \201time>50000.0\202 +)DD( select rows whose pha value is 1 less than the pi value +and whose time value is greater than 50000 + +)0 P()0 DT(\201pi+pha\202>20 +)DD( select rows in which the sum of the pi and pha values is greater +than 20 + +)0 P()0 DT( pi%2==1 +)DD( select rows in which the pi value is odd)LD( + +)0 P(Currently, integer range list limits cannot be specified in binary +notation \201use decimal, hex, or octal instead\202. Please contact us if +this is a problem. + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 99 H(Last)WB 175 Sn( updated: November 17, 2005)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (idx.html) D +/Ti (Table Filtering with Indexes) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 53 Sn( + + +)0 2 100 H(Funidx:)WB 177 Sn()WB 176 Sn( Using Indexes to Filter Rows in a Table)EA()EH( + + +)0 2 101 H(Summary)WB 178 Sn()EH( +)0 P(This document contains a summary of the user interface for +filtering rows in binary tables with indexes. + + +)0 2 102 H(Description)WB 179 Sn()EH( +)0 P(Funtools )0 52 1 A(Table Filtering)52 0 TN TL()Ec /AF f D( 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 \201hundreds of Mb or larger\202, +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. + +)0 P(The )0 11 1 A(funindex)11 0 TN TL()Ec /AF f D( 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: +) 1 23 PR( funindex huge.fits pi)RP( +This will create an index named huge_pi.idx. + +)0 P(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 +)0 54 1 A(Spatial Region Filtering)54 0 TN TL()Ec /AF f D( is part of the +expression, the columns associated with the region are checked for index +files. + +)0 P(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 AND expression. In this case, only the rows that pass the +other part of the AND expression need to be checked. Thus, in some cases, +filtering speed can increase significantly even if all columns are not +indexed. + +)0 P(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 AND +expression, then a significant improvement in speed still is possible +if the other part of the AND expression is indexed. + +)0 P(For example, note below the dramatic speedup in searching a 1 Gb +file using an AND filter, even when one of the columns \201pha\202 has no +index: + +) 49 69 PR( time fundisp \200 + huge.fits'[idx_activate=0,idx_debug=1,pha=2348&&cir 4000 4000 1]' \200 + "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% + + time fundisp \200 + huge.fits'[idx_activate=1,idx_debug=1,pha=2348&&cir 4000 4000 1]' \200 + "x y pha" + x y pha + ---------- ----------- ---------- + idxeq: [INDEF] + idxand sort: x[ROW 8037025:8070128] y[ROW 5757665:5792352] + idxand\2011\202: INDEF [IDX_OR_SORT] )WR( + idxall\2011\202: [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%)RP( + +When all columns are indexed, the increase in speed can be even more dramatic: +) 50 67 PR( time fundisp \200 + huge.fits'[idx_activate=0,idx_debug=1,pi=770&&cir 4000 4000 1]' \200 + "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% + + time fundisp \200 + huge.fits'[idx_activate=1,idx_debug=1,pi=770&&cir 4000 4000 1]' \200 + "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] )WR( + idxmerge\2015\202: [IDX_OR_SORT] pi[ROW] + idxall\2011\202: [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%)RP( + +)0 P(The miracle of indexed filtering \201and indeed, of any indexing\202 is the +speed of the binary search on the index, which is of order log2\201n\202 +instead of n. \201The funtools binary search method is taken from +http://www.tbray.org/ongoing/When/200x/2003/03/22/Binary, to whom +grateful acknowledgement is made.\202 This means that the larger the +file, the better the performance. Conversely, it also means that for +small files, using an index \201and the overhead involved\202 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 \201disk access speed, amount of available +memory, process load, etc.\202 + +)0 P(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 \201in a filter +expression\202 or the FILTER_IDX_ACTIVATE environment variable to 0 \201in the global +environment\202. Debugging output showing how the indexes are being processed can +be displayed to stderr by setting the idx_debug variable to 1 \201in a filter +expression\202 or the FILTER_IDX_DEBUG environment variable to 1 \201in the global +environment\202. + +)0 P(Currently, indexed filtering only works with FITS binary tables and raw +event files. It does not work with text files. This restriction might be +removed in a future release. + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 103 H(Last)WB 180 Sn( updated: August 3, 2007)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (regions.html) D +/Ti (Spatial Region Filtering) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 54 Sn( + + +)0 2 104 H(Regions:)WB 182 Sn()WB 181 Sn( Spatial Region Filtering)EA()EH( + + +)0 2 105 H(Summary)WB 183 Sn()EH( +)0 P(This document contains a summary of the user interface for spatial +region filtering images and tables. + + +)0 2 106 H(Description)WB 184 Sn()EH( +)0 P(Spatial region filtering allows a program to select regions of an +image or rows of a table \201e.g., X-ray events\202 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. + +)0 P(Spatial region filtering for images and tables is accomplished by +means of )BD(region specifications)ES(. A region specification +consists of one or more )BD(region expressions)ES(, which are geometric +shapes,combined according to the rules of boolean algebra. Region +specifications also can contain comments and local/global processing +directives. + +)0 P(Typically, region specifications are specified using bracket notation +appended to the filename of the data being processed: +) 1 31 PR( foo.fits[circle\201512,512,100\202])RP( +It is also possible to put region specification inside a file and +then pass the filename in bracket notation: +) 1 19 PR( foo.fits[@my.reg])RP( + +)0 P(When region filters are passed in bracket notation in this manner, the +filtering is set up automatically when the file is opened and all +processing occurs through the filter. Programs also can use the filter +library API to open filters explicitly. + +)0 2 107 H(Region)WB 185 Sn( Expressions)EH( + +More specifically, region specifications consist of one or more lines +containing: +) 9 68 PR( # comment until end of line + global keyword=value keyword=value ... # set global value\201s\202 + # include the following file in the region descriptor + @file + # use the FITS image as a mask \201cannot be used with other regions\202 + @fitsimage + # each region expression contains shapes separated by operators + [region_expression1], [region_expression2], ... + [region_expression], [region_expression], ...)RP( + +)0 P(A single region expression consists of: +) 8 72 PR( # parens and commas are optional, as is the + sign + [+-]shape\201num , num , ...\202 OP1 shape num num num OP2 shape ... + +e.g.: + + \201[+-]shape\201num , num , ...\202 && shape num num || shape\201num, num\202 + # a comment can come after a region -- reserved for local properties + [+-]shape\201num , num , ...\202 # local properties go here, e.g. color=red)RP( + +)0 P(Thus, a region descriptor consists of one or more )BD(region +expressions)ES( or )BD(regions)ES(, separated by comas, new-lines, or +semi-colons. Each )BD(region)ES( consists of one or more )BD(geometric +shapes)ES( combined using standard boolean operation. Several types +of shapes are supported, including: + +) 11 57 PR( shape: arguments: + ----- ---------------------------------------- + ANNULUS xcenter ycenter inner_radius outer_radius + BOX xcenter ycenter xwidth yheight \201angle\202 + CIRCLE xcenter ycenter radius + ELLIPSE xcenter ycenter xwidth yheight \201angle\202 + FIELD none + LINE x1 y1 x2 y2 + PIE xcenter ycenter angle1 angle2 + POINT x1 y1 + POLYGON x1 y1 x2 y2 ... xn yn)RP( + +)0 P(In addition, the following regions accept )BD(accelerator)ES( syntax: + +) 13 73 PR( 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 \201angle\202 + BOX xcenter ycenter xwlo yhlo xwhi yhhi n=[number] \201angle\202 + 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 \201angle\202 + ELLIPSE xcenter ycenter xwlo yhlo xwhi yhhi n=[number] \201angle\202 + PIE xcenter ycenter angle1 angle2 \201angle3\202 \201angle4\202 \201angle5\202 ... + PIE xcenter ycenter angle1 angle2 \201n=[number]\202 + POINT x1 y1 x2 y2 ... xn yn)RP( +Note that the circle accelerators are simply aliases for the annulus +accelerators. See )0 55 1 A(region geometry)55 0 TN TL()Ec /AF f D( +for more information about accelerators. + +)0 P(Finally, the following are combinations of pie with different shapes +\201called "panda" for "Pie AND Annulus"\202 allow for easy specification of +radial sections: + +) 6 75 PR( 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 \201ang\202 # box + EPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad \201ang\202 # ellipse)RP( + +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 )0 55 1 A(region geometry)55 0 TN TL()Ec /AF f D( +for more information about pandas. + +)0 P(The following "shapes" are ignored by funtools \201generated by ds9\202: +) 8 62 PR( 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)RP( + +)0 P(All arguments to regions are real values; integer values are +automatically converted to real where necessary. All angles are in +degrees and run from the positive image x-axis to the positive image +y-axis. If a rotation angle is part of the associated WCS header, that +angle is added implicitly as well. + +)0 P(Note that 3-letter abbreviations are supported for all shapes, so that +you can specify "circle" or "cir". + +)0 P()0 2 108 H(Columns)WB 186 Sn( Used in Region Filtering)EH( +)0 P(By default, the x,y values in a region expression refer to the two +"image binning" columns, i.e. the columns that would be used to +bin the data into an image. For images, these are just the 2 dimensions +of the image. For tables, these usually default to x and y but +can be changed as required. For example, in Funtools, new binning +columns are specified using a bincols=\201col1,col2\202 statement within +the bracket string on the command line. +)0 P(Alternate columns for region filtering can be specified by the syntax: +) 1 25 PR( \201col1,col2\202=region\201...\202)RP( +e.g.: +) 3 34 PR( \201X,Y\202=annulus\201x,y,ri,ro\202 + \201PHA,PI\202=circle\201x,y,r\202 + \201DX,DY\202=ellipse\201x,y,a,b[,angle]\202)RP( + +)0 P()0 2 109 H(Region)WB 187 Sn( Algebra)EH( + +\201See also )0 56 1 A(Region Algebra)56 0 TN TL()Ec /AF f D( for more complete +information.\202 + +)0 P(Region shapes can be combined together using Boolean operators: +) 6 72 PR( 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)RP( +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, +) 1 21 PR( !circle\201512,512,10\202)RP( +is not a legal region because there is no valid region id to work with. +To get the full field without a circle, combine the above with field\201\202, +as in: +) 1 32 PR( field\201\202 && !circle\201512,512,10\202)RP( + +)0 2 110 H()WB 188 Sn( Region Separators Also Are Operators)EH( + +)0 P(As mentioned previously, multiple region expressions can be specified +in a region descriptor, separated by commas, new-lines, or +semi-colons. When such a separator is used, the boolean OR operator +is automatically generated in its place but, unlike explicit use of +the OR operator, the region ID is incremented \201starting from 1\202. + +)0 P(For example, the two shapes specified in this example are given the +same region value: +) 1 50 PR( foo.fits[circle\201512,512,10\202||circle\201400,400,20\202])RP( +On the other hand, the two shapes defined in the following example are +given different region values: +) 1 49 PR( foo.fits[circle\201512,512,10\202,circle\201400,400,20\202])RP( + +)0 P(Of course these two examples will both mask the same table rows or +pixels. However, in programs that distinguish region id's \201such as +)0 5 1 A(funcnts)5 0 TN TL()Ec /AF f D( \202, they will act +differently. The explicit OR operator will result in one region +expression consisting of two shapes having the same region id and +funcnts will report a single region. The comma operator will cause +funcnts to report two region expressions, each with one shape, in +its output. + +)0 P(In general, commas are used to separate region expressions entered +in bracket notation on the command line: +) 2 57 PR( # regions are added to the filename in bracket notation + foo.fits[circle\201512,512,100\202,circle\201400,400,20\202])RP( +New-lines are used to separate region +expressions in a file: +) 4 58 PR( # regions usually are separated by new-lines in a file + # use @filename to include this file on the command line + circle\201512,512,100\202 + circle\201400,400,20\202)RP( +Semi-colons are provided for backward compatibility with the original +IRAF/PROS implementation and can be used in either case. + +)0 P(If a pixel is covered by two different regions expressions, it is +given the mask value of the )BD(first)ES( region that contains that +pixel. That is, successive regions )BD(do not)ES( overwrite previous +regions in the mask, as was the case with the original PROS regions. +In this way, an individual pixel is covered by one and only one +region. This means that one must sometimes be careful about the order +in which regions are defined. If region N is fully contained within +region M, then N should be defined )BD(before)ES( M, or else it will be +"covered up" by the latter. + +)0 2 111 H(Region)WB 189 Sn( Exclusion)EH( +)0 P(Shapes also can be globally excluded from all the region specifiers in +a region descriptor by using a minus sign before a region: + +) 4 73 PR( operator arguments: + -------- ----------- + - Globally exclude the region expression following '-' sign + from ALL regions specified in this file)RP( +The global exclude region can be used by itself; in such a case, field\201\202 is +implied. + +)0 P(A global exclude differs from the local exclude \201i.e. a shape prefixed +by the logical not "!" symbol\202 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. + +)0 2 112 H(Include)WB 190 Sn( Files)EH( + +)0 P(The )BD(@filename)ES( directive specifies an include file +containing region expressions. This file is processed as part of +the overall region descriptor: +) 1 35 PR( foo.fits[circle\201512,512,10\202,@foo])RP( +A filter include file simply includes text without changing the state +of the filter. It therefore can be used in expression. That is, if the +file foo1 contains "pi==1" and foo2 contains "pha==2" then +the following expressions are equivalent: +) 3 57 PR( "[@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]")RP( +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: +) 2 19 PR( circle 512 512 10 + circle 520 520 10)RP( +If you want to include only events \201or pixels\202 that are in these regions +and have a pi value of 4, then the correct syntax is: +) 1 17 PR( pi==4&&\201@foo\202)RP( +since this is equivalent to: +) 1 53 PR( pi==4 && \201circle 512 512 10 || circle 520 520 10\202)RP( +If you leave out the parenthesis, you are filtering this statement: +) 1 52 PR( pi==4 && circle 512 512 10 || circle 520 520 10\202)RP( +which is equivalent to: +) 1 54 PR( \201pi==4 && circle 512 512 10\202 || circle 520 520 10\202)RP( +The latter syntax only applies the pi test to the first region. + +)0 P(For image-style filtering, the )BD(@filename)ES( can specify an 8-bit +or 16-bit FITS image. In this case, the pixel values in the mask image +are used as the region mask. The valid pixels in the mask must have +positive values. Zero values are excluded from the mask and negative +values are not allowed. Moreover, the region id value is taken as +the image pixel value and the total number of regions is taken to be +the highest pixel value. The dimensions of the image mask must be less +than or equal to the image dimensions of the data. The mask will be +replicated as needed to match the size of the image. \201Thus, best +results are obtained when the data dimensions are an even multiple of +the mask dimensions.\202 + +)0 P(An image mask can be used in any image filtering operation, regardless +of whether the data is of type image or table. For example, the +)0 5 1 A(funcnts)5 0 TN TL()Ec /AF f D( \202 +program performs image filtering on images or tables, and so +FITS image masks are valid input for either type of data in this +program.. An image mask cannot be used in a program such as +)0 7 1 A(fundisp)7 0 TN TL()Ec /AF f D( \202 +when the input data is a table, because fundisp displays +rows of a table and processes these rows using event-style filtering. + +)0 2 113 H(Global)WB 191 Sn( and Local Properties of Regions)EH( + +)0 P(The ds9 image display program describes a host of properties such as +color, font, fix/free state, etc. Such properties can be specified +globally \201for all regions\202 or locally \201for an individual region\202. +The )BD(global)ES( keyword specifies properties and qualifiers for all +regions, while local properties are specified in comments on the same +line as the region: +) 4 30 PR( global color=red + circle\20110,10,2\202 + circle\20120,20,3\202 # color=blue + circle\20130,30,4\202)RP( +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. + +)0 2 114 H()WB 192 Sn( Coordinate Systems)EH( + +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: + +) 12 68 PR( 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)RP( + +)0 P()0 2 115 H(Specifying)WB 193 Sn( Positions, Sizes, and Angles)EH( + +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: + +) 21 57 PR( position arguments description + ------------------ ------------------------------ + [num] context-dependent \201see below\202 + [num]d degrees + [num]r radians + [num]p physical pixels + [num]i image pixels + [num]:[num]:[num] hms for 'odd' position arguments + [num]:[num]:[num] dms for 'even' position arguments + [num]h[num]m[num]s explicit hms + [num]d[num]m[num]s explicit dms + + size arguments description + -------------- ----------- + [num] context-dependent \201see below\202 + [num]" arc seconds + [num]' arc minutes + [num]d degrees + [num]r radians + [num]p physical pixels + [num]i image pixels)RP( + + +When a "pure number" \201i.e. one without a format directive such as 'd' +for 'degrees'\202 is specified, its interpretation depends on the context +defined by the 'coordsys' keyword. In general, the rule is: + +)0 P()BD(All pure numbers have implied units corresponding to the current +coordinate system.)ES( + +)0 P(If no such system is explicitly specified, the default system is +implicitly assumed to be PHYSICAL. + +)0 P(In practice this means that for IMAGE and PHYSICAL systems, pure +numbers are pixels. Otherwise, for all systems other than linear, +pure numbers are degrees. For LINEAR systems, pure numbers are in the +units of the linear system. This rule covers both positions and +sizes. + +)0 P(The input values to each shape can be specified in several coordinate +systems including: + +) 12 68 PR( 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)RP( + +)0 P(If no coordinate system is specified, PHYSICAL is assumed. PHYSICAL or +a World Coordinate System such as J2000 is preferred and most general. +The coordinate system specifier should appear at the beginning of the +region description, on a separate line \201in a file\202, or followed by a +new-line or semicolon; e.g., + +) 2 26 PR( global coordsys physical + circle 6500 9320 200)RP( + +The use of celestial input units automatically implies WORLD +coordinates of the reference image. Thus, if the world coordinate +system of the reference image is J2000, then + +) 1 27 PR( circle 10:10:0 20:22:0 3')RP( + +is equivalent to: + +) 1 35 PR( circle 10:10:0 20:22:0 3' # j2000)RP()RP( +Note that by using units as described above, you may mix coordinate +systems within a region specifier; e.g., + +) 1 32 PR( circle 6500 9320 3' # physical)RP( + +)0 P(Note that, for regions which accept a rotation angle: + +) 2 29 PR(ellipse \201x, y, r1, r2, angle\202 +box\201x, y, w, h, angle\202)RP( + +the angle is relative to the specified coordinate system. In +particular, if the region is specified in WCS coordinates, the angle +is related to the WCS system, not x/y image coordinate axis. For WCS +systems with no rotation, this obviously is not an issue. However, +some images do define an implicit rotation \201e.g., by using a non-zero +CROTA value in the WCS parameters\202 and for these images, the angle +will be relative to the WCS axes. In such case, a region specification +such as: + +) 1 54 PR(fk4;ellipse\20122:59:43.985, +58:45:26.92,320", 160", 30\202)RP( + +will not, in general, be the same region specified as: + +) 1 38 PR(physical;ellipse\201465, 578, 40, 20, 30\202)RP( + +even when positions and sizes match. The angle is relative to WCS axes +in the first case, and relative to physical x,y axes in the second. + + +)0 P(More detailed descriptions are available for: +)0 55 1 A(Region Geometry)55 0 TN TL()Ec /AF f D(, +)0 56 1 A(Region Algebra)56 0 TN TL()Ec /AF f D(, +)0 57 1 A(Region Coordinates)57 0 TN TL()Ec /AF f D(, and +)0 58 1 A(Region Boundaries)58 0 TN TL()Ec /AF f D(. + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 116 H(Last)WB 194 Sn( updated: November 17, 2005)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (reggeometry.html) D +/Ti (Region Geometry) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 55 Sn( + + +)0 2 117 H(RegGeometry:)WB 196 Sn()WB 195 Sn( Geometric Shapes in Spatial Region Filtering)EA()EH( + + +)0 2 118 H(Summary)WB 197 Sn()EH( +)0 P(This document describes the geometry of regions available for spatial +filtering in IRAF/PROS analysis. + + +)0 2 119 H(Geometric)WB 198 Sn( shapes)EH( +)0 P(Several geometric shapes are used to describe regions. The valid +shapes are: + +) 11 57 PR( shape: arguments: + ----- ---------------------------------------- + ANNULUS xcenter ycenter inner_radius outer_radius + BOX xcenter ycenter xwidth yheight \201angle\202 + CIRCLE xcenter ycenter radius + ELLIPSE xcenter ycenter xwidth yheight \201angle\202 + FIELD none + LINE x1 y1 x2 y2 + PIE xcenter ycenter angle1 angle2 + POINT x1 y1 + POLYGON x1 y1 x2 y2 ... xn yn)RP( + + +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. + +)0 P(Shapes can be specified using "command" syntax: +) 1 23 PR( [shape] arg1 arg2 ...)RP( +or using "routine" syntax: +) 1 26 PR( [shape]\201arg1, arg2, ...\202)RP( +or by any combination of the these. \201Of course, the parentheses must +balance and there cannot be more commas than necessary.\202 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: + +) 1 64 PR( "foo.fits[CIRCLE 512 512 50;CIR\201128 128, 10\202;cir\201650,650,20\202]")RP( + +\201Quotes generally are required to protect the region descriptor +from being processed by the Unix shell.\202 + +)2 1 1 HR( +)0 P(The )BD(annulus)ES( shape specifies annuli, centered at xcenter, +ycenter, with inner and outer radii \201r1, r2\202. For example, +) 1 20 PR( ANNULUS 25 25 5 10)RP( +specifies an annulus centered at 25.0 25.0 with an inner radius of 5.0 and +an outer radius of 10. Assuming \201as will be done for all examples in this +document, unless otherwise noted\202 this shape is used in a mask of size 40x40, +it will look like this: +) 42 51 PR( 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:........................................)WR( + 11:........................................ + 10:........................................ + 9:........................................ + 8:........................................ + 7:........................................ + 6:........................................ + 5:........................................ + 4:........................................ + 3:........................................ + 2:........................................ + 1:........................................)RP( + +)2 1 1 HR( +)0 P(The )BD(box)ES( 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 \201in degrees\202, the box is rotated by +an angle that runs counter-clockwise from the positive y-axis. + +)0 P(The )BD(box)ES( 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. + +)2 1 1 HR( +)0 P(The )BD(circle)ES( shape specifies a circle, centered at xcenter, +ycenter, of radius r. It requires three arguments. + +)2 1 1 HR( +)0 P(The )BD(ellipse)ES( shape specifies an ellipse, centered at +xcenter, ycenter, with y-axis width a and the y-axis length b defined such +that: +) 1 27 PR( x**2/a**2 + y**2/b**2 = 1)RP( +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: +) 1 23 PR( ELLIPSE 20 20 5 10 45)RP( +will look like this: +) 42 49 PR( 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:........................................)WR( + 11:........................................ + 10:........................................ + 9:........................................ + 8:........................................ + 7:........................................ + 6:........................................ + 5:........................................ + 4:........................................ + 3:........................................ + 2:........................................ + 1:........................................)RP( + + +)2 1 1 HR( +)0 P(The )BD(field)ES( 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 "none" is input. +)BD(Field)ES( takes no arguments. + +)2 1 1 HR( +)0 P(The )BD(pie)ES( 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, +) 1 18 PR( PIE 20 20 90 180)RP( +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: + +) 42 51 PR( 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:........................................)WR( + 11:........................................ + 10:........................................ + 9:........................................ + 8:........................................ + 7:........................................ + 6:........................................ + 5:........................................ + 4:........................................ + 3:........................................ + 2:........................................ + 1:........................................)RP( +The pie slice specified is always a counter-clockwise sweep between +the angles, starting at the first angle and ending at the second. Thus: +) 1 17 PR( PIE 10 15 30 60)RP( +describes a 30 degree sweep from 2 o'clock to 1 o'clock, while: +) 1 17 PR( PIE 10 15 60 30)RP( +describes a 330 degree counter-clockwise sweep from 1 o'clock to 2 o'clock +passing through 12 o'clock \2010 degrees\202. Note in both of these examples that +the center of the slice can be anywhere on the plane. The second mask looks +like this: + +) 42 51 PR( 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)WR( + 11:1111111111111111111111111111111111111111 + 10:1111111111111111111111111111111111111111 + 9:1111111111111111111111111111111111111111 + 8:1111111111111111111111111111111111111111 + 7:1111111111111111111111111111111111111111 + 6:1111111111111111111111111111111111111111 + 5:1111111111111111111111111111111111111111 + 4:1111111111111111111111111111111111111111 + 3:1111111111111111111111111111111111111111 + 2:1111111111111111111111111111111111111111 + 1:1111111111111111111111111111111111111111)RP( +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. \201See below and in "help regalgebra"\202. + +)0 P(Pie Performance Notes: +)0 P(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 \201unlike other regions, where the y limits can be +calculated beforehand\202. Thus, pie can run very slowly on large images. +In particular, it will run MUCH more slowly than the panda shape in +image-based region operations \201such as funcnts\202. We recommend use of +panda over pie where ever possible. + +)0 P(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 ACIS file when a pie and circle are combined in +two different orders: + +) 5 74 PR( time ./funcnts nacis.fits "circle 4096 4096 100 && pie 4096 4096 10 78" +2.87u 0.38s 0:35.08 9.2% + + time ./funcnts nacis.fits "pie 4096 4096 10 78 && circle 4096 4096 100 " +89.73u 0.36s 1:03.50 141.8%)RP( + +)0 P(Black-magic performance note: + +)0 P(Panda region processing uses a )BD(quick test)ES( pie region instead of +the normal pie region when combining its annulus and pie shapes. This +)BD(qtpie)ES( 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. + +)0 P(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: + +) 2 75 PR( time ./funcnts nacis.fits "circle 4096 4096 100 && qtpie 4096 4096 10 78" +4.66u 0.33s 0:05.87 85.0%)RP( + +)0 P(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. + +)2 1 1 HR( +)0 P(The )BD(line)ES( shape allows single pixels in a line between \201x1,y1\202 and +\201x2,y2\202 to be included or excluded. For example: +) 44 49 PR( LINE \2015,6, 24,25\202 +) 43 49 PR(displays as: +) 42 49 PR( 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...........................)WR( + 13:...........1............................)WR( + 12:..........1.............................)WR( + 11:.........1.............................. + 10:........1............................... + 9:.......1................................ + 8:......1................................. + 7:.....1.................................. + 6:....1................................... + 5:........................................ + 4:........................................ + 3:........................................ + 2:........................................ + 1:........................................)RP( + +)2 1 1 HR( +)0 P(The )BD(point)ES( shape allows single pixels to be included or +excluded. Although the \201x,y\202 values are real numbers, they are truncated +to integer and the corresponding pixel is included or excluded, as specified. + +)0 P(Several points can be put in one region declaration; unlike the +original IRAF 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, +) 1 37 PR( POINT \2015,6, 10,11, 20,20, 35,30\202)RP( +will give the different region mask values to all four points, as shown below: + +) 42 49 PR( 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:........................................)WR( + 11:.........2.............................. + 10:........................................ + 9:........................................ + 8:........................................ + 7:........................................ + 6:....1................................... + 5:........................................ + 4:........................................ + 3:........................................ + 2:........................................ + 1:........................................)RP( + +)2 1 1 HR( +)0 P(The )BD(polygon)ES( shape specifies a polygon with vertices +\201x1, y1\202 ... \201xn, yn\202. 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: +) 1 33 PR( POLYGON \20110,10, 10,30, 30,30\202)RP( + +looks like this: + +) 42 49 PR( 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............................)WR( + 11:..........1............................. + 10:........................................ + 9:........................................ + 8:........................................ + 7:........................................ + 6:........................................ + 5:........................................ + 4:........................................ + 3:........................................ + 2:........................................ + 1:........................................)RP( +Note that polygons can get twisted upon themselves if edge lines +cross. Thus: +) 1 37 PR( POL \20110,10, 20,20, 20,10, 10,20\202)RP( +will produce an area which is two triangles, like butterfly wings, as shown +below: + +) 42 49 PR( 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....................)WR( + 11:..........1........1.................... + 10:........................................ + 9:........................................ + 8:........................................ + 7:........................................ + 6:........................................ + 5:........................................ + 4:........................................ + 3:........................................ + 2:........................................ + 1:........................................)RP( + +)2 1 1 HR( +)0 P(The following are combinations of pie with different shapes +\201called "panda" for "Pie AND Annulus"\202 allow for easy specification of +radial sections: +) 6 76 PR( 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 \201ang\202 # box + EPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad \201ang\202 # ellipse)RP( + +The )BD(panda)ES( \201)BD(P)ES(ies )BD(AND)ES( )BD(A)ES(nnuli\202 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 AND 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. + +)0 P(Consider the example shown below: +) 1 31 PR( PANDA\20120,20, 0,360,3, 0,15,4\202)RP( +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 \201displayed in +base 16 to save characters\202: +) 42 51 PR( 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........)WR( + 11:........888887bbbbbbbbbbbbccccc......... + 10:........888888bbbbbbbbbbbcccccc......... + 9:.........8888ccccbbbbbcccccccc.......... + 8:...........88ccccccccccccccc............ + 7:............ccccccccccccccc............. + 6:..............ccccccccccc............... + 5:........................................ + 4:........................................ + 3:........................................ + 2:........................................ + 1:........................................)RP( + +)2 1 1 HR( +)0 P(Several regions with different mask values can be combined in the +same mask. This supports comparing data from the different regions. +\201For information on how to combine different shapes into a single +region, see "help regalgebra".\202 For example, consider the following +set of regions: +) 3 24 PR( ANNULUS 25 25 5 10 + ELLIPSE 20 20 5 10 315 + BOX 15 15 5 10)RP( +The resulting mask will look as follows: + +) 42 49 PR( 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.......................)WR( + 11:............33333....................... + 10:........................................ + 9:........................................ + 8:........................................ + 7:........................................ + 6:........................................ + 5:........................................ + 4:........................................ + 3:........................................ + 2:........................................ + 1:........................................)RP( +Note that when a pixel is in 2 or more regions, it is arbitrarily +assigned to a one of the regions in question \201often based on how a +give C compiler optimizes boolean expressions\202. + +)0 P()0 2 120 H(Region)WB 199 Sn( accelerators)EH( + +)0 P(Two types of \200fBaccelerators)ES(, 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 +)BD(n=)ES(, valid for annulus, box, circle, ellipse, and pie \201not +point\202. 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. + +)0 P(The following regions accept )BD(accelerator)ES( syntax: +) 13 73 PR( 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 \201angle\202 + BOX xcenter ycenter xwlo yhlo xwhi yhhi n=[number] \201angle\202 + 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 \201angle\202 + ELLIPSE xcenter ycenter xwlo yhlo xwhi yhhi n=[number] \201angle\202 + PIE xcenter ycenter angle1 angle2 \201angle3\202 \201angle4\202 \201angle5\202 ... + PIE xcenter ycenter angle1 angle2 \201n=[number]\202 + POINT x1 y1 x2 y2 ... xn yn)RP( +Note that the circle accelerators are simply aliases for the annulus +accelerators. + +)0 P(For example, several annuli at the same center can be specified in one +region expression by specifying more than two radii. If )BD(N)ES( +radii are specified, then )BD(N)ES(-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, +) 1 30 PR( ANNULUS 20 20 0 2 5 10 15 20)RP( +specifies five different annuli centered at 20 20, and is equivalent to: +) 5 25 PR( 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)RP( +The mask is shown below: + +) 42 49 PR( 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..)WR( + 11:..55555544444443333333334444444555555... + 10:..55555544444444444444444444444555555... + 9:...555555444444444444444444444555555.... + 8:....5555555444444444444444445555555..... + 7:....5555555544444444444444455555555..... + 6:.....55555555544444444444555555555...... + 5:......555555555555555555555555555....... + 4:........55555555555555555555555......... + 3:.........555555555555555555555.......... + 2:...........55555555555555555............ + 1:.............5555555555555..............)RP( + +)0 P(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: +) 1 38 PR( ellipse 20 20 3 5 6 10 9 15 12 20 45)RP( +specifies an 3 ellipses at a 45 degree angle: +) 42 51 PR( 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....)WR( + 11:............333322222222222222233333.... + 10:.............33333222222222222233333.... + 9:..............3333332222222222333333.... + 8:...............33333333222223333333..... + 7:.................333333333333333333..... + 6:..................3333333333333333...... + 5:.....................333333333333....... + 4:.......................33333333......... + 3:........................................ + 2:........................................ + 1:........................................)RP( +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.: +) 2 26 PR( circle 20 20 5 10 15 20 + annulus 20 20 5 10 15 20)RP( +both give the following region mask: +) 42 51 PR( 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..)WR( + 11:..33333322222221111111112222222333333... + 10:..33333322222222222222222222222333333... + 9:...333333222222222222222222222333333.... + 8:....3333333222222222222222223333333..... + 7:....3333333322222222222222233333333..... + 6:.....33333333322222222222333333333...... + 5:......333333333333333333333333333....... + 4:........33333333333333333333333......... + 3:.........333333333333333333333.......... + 2:...........33333333333333333............ + 1:.............3333333333333..............)RP( + +)0 P(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 )BD(N)ES( angles are +specified, then )BD(N)ES(-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, +) 1 26 PR( PIE 12 12 315 45 115 270)RP( +specifies three regions as shown below: +) 42 51 PR( 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)WR( + 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)RP( + +)0 P(The annulus, box, circle, ellipse, and pie shapes also accept an +)BD(n=[int])ES( syntax for specifying multiple regions. The +)BD(n=[int])ES(syntax interprets the previous \201shape-dependent\202 +arguments as lower and upper limits for the region and creates n +shapes with evenly spaced boundaries. For example, if )BD(n=[int])ES( +is specified in an annulus, the two immediately preceding radii +\201)BD(rn)ES( and )BD(rm)ES(\202 are divided into )BD(int)ES( annuli, such +that the inner radius of the first is )BD(rn)ES( and the outer radius +of the last is )BD(rm)ES(. For example, +) 1 24 PR( ANNULUS 20 20 5 20 n=3)RP( +is equivalent to: +) 1 26 PR( ANNULUS 20 20 5 10 15 20)RP( +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 )BD(n=[int])ES( syntax allows any single alphabetic character +before the "=", i.e, i=3, z=3, etc. are all equivalent. + +)0 P(Also note that for boxes and ellipses, the optional angle argument is +always specified after the )BD(n=[int])ES( syntax. For example: +) 45 57 PR( ellipse 20 20 4 6 16 24 n=3 45 +) 44 57 PR(specifies 3 elliptical regions at an angle of 45 degrees: + +) 42 45 PR( 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)WR( + 14:....333332222211111111111111122222233333)WR( + 13:.....33333222221111111111111122222233333 + 12:.....33333322222211111111111222222233333)WR( + 11:......3333332222222111111112222222333333 + 10:.......333333222222221111222222222333333 + 9:........33333322222222222222222222333333 + 8:.........333333222222222222222222333333. + 7:..........33333332222222222222223333333. + 6:...........3333333322222222222233333333. + 5:.............3333333333222223333333333.. + 4:..............33333333333333333333333... + 3:................33333333333333333333.... + 2:..................33333333333333333..... + 1:....................33333333333333......)RP( + +)0 P(Both the variable argument syntax and the )BD(n=[int])ES( syntax must +occur alone in a region descriptor \201aside from the optional angle for +boxes and ellipses\202. They cannot be combined. Thus, it is not valid +to precede or follow an )BD(n=[int])ES( accelerator with more angles or +radii, as in this example: +) 3 49 PR( # 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)RP( +Instead, use three separate specifications, such as: +) 3 21 PR( PIE 12 12 10 25 + PIE 12 12 25 50 a=5 + PIE 12 12 85 135)RP( +The original \201IRAF\202 implementation of region filtering permitted this +looser syntax, but we found it caused more confusion than it was worth +and therefore removed it. + +)0 P(NB: Accelerators may be combined with other shapes in a boolean +expression in any order. \201This is a change starting with funtools +v1.1.1. Prior to this release, the accelerator shape had to be +specified last\202. 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. + +)0 P([All region masks displayed in this document were generated using the +)BD(fundisp)ES( routine and the undocumented "mask=all" argument \201with +spaced removed using sed \202: +) 2 72 PR( fundisp "funtools/funtest/test40.fits[ANNULUS 25 25 5 10]" mask=all |\200 + sed 's/ //g')RP( +Note that you must supply an image of the appropriate size -- in this case, +a FITS image of dimension 40x40 is used.] + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 121 H(Last)WB 200 Sn( updated: March 12, 2007)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (regalgebra.html) D +/Ti (Region Algebra) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 56 Sn( + + +)0 2 122 H(RegAlgebra:)WB 202 Sn()WB 201 Sn( Boolean Algebra on Spatial Regions)EA()EH( + + +)0 2 123 H(Summary)WB 203 Sn()EH( +)0 P(This document describes the boolean arithmetic defined for +region expressions. + + +)0 2 124 H(Description)WB 204 Sn()EH( +)0 P(When defining a region, several shapes can be combined using boolean +operations. The boolean operators are \201in order of precedence\202: +) 6 53 PR( Symbol Operator Associativity + ------ -------- ------------- + ! not right to left + & and left to right + ^ exclusive or left to right + | inclusive or left to right)RP( +For example, to create a mask consisting of a large circle with a +smaller box removed, one can use the )BD(and)ES( and )BD(not)ES( +operators: +) 1 36 PR( CIRCLE\20111,11,15\202 & !BOX\20111,11,3,6\202)RP( + +and the resulting mask is: +) 42 49 PR( 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:........................................)WR( + 30:........................................ + 31:........................................ + 32:........................................ + 33:........................................ + 34:........................................ + 35:........................................ + 36:........................................ + 37:........................................ + 38:........................................ + 39:........................................ + 40:........................................)RP( +A three-quarter circle can be defined as: +) 1 40 PR( CIRCLE\20120,20,10\202 & !PIE\20120,20,270,360\202)RP( + +and looks as follows: +) 42 49 PR( 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....................)WR( + 30:........................................ + 31:........................................ + 32:........................................ + 33:........................................ + 34:........................................ + 35:........................................ + 36:........................................ + 37:........................................ + 38:........................................ + 39:........................................ + 40:........................................)RP( +Two non-intersecting ellipses can be made into the same region: +) 1 40 PR( ELL\20120,20,10,20,90\202 | ELL\2011,1,20,10,0\202)RP( + +and looks as follows: +) 42 49 PR( 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............)WR( + 30:........................................ + 31:........................................ + 32:........................................ + 33:........................................ + 34:........................................ + 35:........................................ + 36:........................................ + 37:........................................ + 38:........................................ + 39:........................................ + 40:........................................)RP( +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. + +)0 P(NB: Using a panda shape is always much more efficient than explicitly +specifying "pie & annulus", 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. + +)0 P(As described in "help regreometry", the )BD(PIE)ES( slice goes to the +edge of the field. To limit its scope, )BD(PIE)ES( 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 )BD(-PIE)ES( and )BD(&!PIE)ES(. The former is a +global exclude of all pixels in the )BD(PIE)ES( slice, while the latter +is a local excludes of pixels affecting only the region\201s\202 with which +the )BD(PIE)ES( is combined. For example, the following region uses +)BD(&!PIE)ES( as a local exclude of a single circle. Two other circles +are also defined and are unaffected by the local exclude: +) 21 56 PR( CIRCLE\2011,8,1\202 + CIRCLE\2018,8,7\202&!PIE\2018,8,60,120\202&!PIE\2018,8,240,300\202 + CIRCLE\20115,8,2\202 + + 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: . . . . . . . . . . . . . . .)RP( +Note that the two other regions are not affected by the )BD(&!PIE)ES(, +which only affects the circle with which it is combined. + +)0 P(On the other hand, a )BD(-PIE)ES( is an global exclude that does +affect other regions with which it overlaps: +) 23 39 PR( CIRCLE\2011,8,1\202 + CIRCLE\2018,8,7\202 + -PIE\2018,8,60,120\202 + -PIE\2018,8,240,300\202 + CIRCLE\20115,8,2\202 + + 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: . . . . . . . . . . . . . . .)RP( +The two smaller circles are entirely contained within the two exclude +)BD(PIE)ES( slices and therefore are excluded from the region. + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 125 H(Last)WB 205 Sn( updated: November 17, 2005)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (regcoords.html) D +/Ti (Spatial Region Coordinates) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 57 Sn( + + +)0 2 126 H(RegCoords:)WB 207 Sn()WB 206 Sn( Spatial Region Coordinates)EA()EH( + + +)0 2 127 H(Summary)WB 208 Sn()EH( +)0 P(This document describes the specification of coordinate systems, and the +interpretation of coordinate values, for spatial region filtering. + + +)0 2 128 H(Pixel)WB 209 Sn( coordinate systems)EH( +)0 P(The default coordinate system for regions is PHYSICAL, which means +that region position and size values are taken from the original +data. \201Note that this is a change from the original IRAF/PROS +implementation, in which the IMAGE coordinate system was the default.\202 +PHYSICAL coordinates always refer to pixel positions on the original +image \201using IRAF LTM and LTV keywords\202. With PHYSICAL coordinates, +if a set of coordinates specifies the position of an object in an +original FITS file, the same coordinates will specify the same object +in any FITS derived from the original. Physical coordinates are +invariant with blocking of FITS files or taking sections of images, +even when a blocked section is written to a new file. + +)0 P(Thus, although a value in pixels refers, by default, to the PHYSICAL +coordinate system, you may specify that position values refer to the +image coordinate system using the )BD(global)ES( or )BD(local)ES( +properties commands: + +) 2 23 PR( global coordsys image + circle 512 512 100)RP( + +The )BD(global)ES( command changes the coordinate system for all +regions that follow, while the )BD(local)ES( command changes the +coordinate system only for the region immediately following: +) 3 22 PR( local coordsys image + circle 512 512 100 + circle 1024 1024 200)RP( +This changes the coordinate system only for the region that follows. +In the above example, the second region uses the global coordinate +system \201PHYSICAL by default\202. + +)0 P()0 2 129 H(World)WB 210 Sn( Coordinate Systems)EH( + +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: + +) 10 67 PR( 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)RP( + +In addition, two mosaic coordinate systems have been defined that +utilize the \201evolving\202 IRAF mosaic keywords: + +) 4 68 PR( name description + ---- ----------- + AMPLIFIER mosaic coords of original file using ATM/ATV + DETECTOR mosaic coords of original file using DTM/DTV)RP( +Again, to use one of these coordinate systems, the )BD(global)ES( or +)BD(local)ES( properties commands are used: + +) 1 26 PR( global coordsys galactic)RP( + +)0 2 130 H(WCS)WB 211 Sn( Positions and Sizes)EH( + +In addition to pixels, positional values in a WCS-enabled region can +be specified using sexagesimal or degrees format: + +) 11 57 PR( position arguments description + ------------------ ----------- + [num] context-dependent \201see below\202 + [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)RP( + +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 \201except for galactic coordinates, which always use degrees\202: + +) 7 78 PR( 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)RP( + +Similarly, the units of size values are defined by the formating +character\201s\202 attached to a number: + +) 9 53 PR( size arguments description + -------------- ----------- + [num] context-dependent \201see below\202 + [num]" arc seconds + [num]' arc minutes + [num]d degrees + [num]r radians + [num]p physical pixels + [num]i image pixels)RP( + +For example: +) 8 34 PR( 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)RP( + +)0 P(An example of using sky coordinate systems follows: + +) 4 65 PR( 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)RP( + +At the FK4 1950 coordinates 175.54d RA, 20.01156d DEC exclude a 10 +minute by 10 minute box. Then at the FK5 2000 coordinates 179.57d RA +22.4d DEC draw a radial profile regions pattern with 4 quadrants and 5 +annuli ranging from 3 minutes to 24 minutes in diameter. In this +example, the default coordinate system is overridden by the commands +in the regions spec. + +)0 2 131 H(NB:)WB 212 Sn( The Meaning of Pure Numbers Are Context Sensitive)EH( + +)0 P(When a "pure number" \201i.e. one without a format directive such as 'd' +for 'degrees'\202 is specified as a position or size, its interpretation +depends on the context defined by the 'coordsys' keyword. In general, +the rule is: + +)0 P()BD(All pure numbers have implied units corresponding to the current +coordinate system.)ES( + +)0 P(If no coordinate system is explicitly specified, the default system is +implicitly assumed to be PHYSICAL. In practice this means that for +IMAGE and PHYSICAL systems, pure numbers are pixels. Otherwise, +for all systems other than LINEAR, pure numbers are degrees. For +LINEAR systems, pure numbers are in the units of the linear system. +This rule covers both positions and sizes. + +)0 P(As a corollary, when a sky-formatted number is used with the IMAGE +or PHYSICAL coordinate system \201which includes the default case of no +coordsys being specified\202, the formatted number is assumed to be in +the units of the WCS contained in the current file. If no sky WCS is +specified, an error results. + +)0 P(Examples: + +) 2 43 PR( circle\201512,512,10\202 + ellipse 202.44382d 47.181656d 0.01d 0.02d)RP( + +)0 P(In the absence of a specified coordinate system, the circle uses the +default PHYSICAL units of pixels, while the ellipse explicitly uses degrees, +presumably to go with the WCS in the current file. + +) 5 43 PR( global coordsys=fk5 + global color=green font="system 10 normal" + circle 202.44382 47.181656 0.01 + circle 202.44382 47.181656 10p + ellipse\201512p,512p,10p,15p,20\202)RP( + + +)0 P(Here, the circles use the FK5 units of degrees \201except for the +explicit use of pixels in the second radius\202, while the ellipse +explicitly specifies pixels. The ellipse angle is in degrees. + +)0 P(Note that Chandra data format appears to use "coordsys=physical" +implicitly. Therefore, for most Chandra applications, valid regions +can be generated safely by asking ds9 to save/display regions in +pixels using the PHYSICAL coordsys. + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 132 H(Last)WB 213 Sn( updated: November 17, 2005)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (regbounds.html) D +/Ti (Spatial Region Boundaries) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 58 Sn( + + +)0 2 133 H(RegBounds:)WB 215 Sn()WB 214 Sn( Region Boundaries)EA()EH( + + +)0 2 134 H(Summary)WB 216 Sn()EH( +Describes how spatial region boundaries are handled. + + +)0 2 135 H(Description)WB 217 Sn()EH( +)0 P(The golden rule for spatial region filtering was first enunciated by +Leon VanSpeybroeck in 1986: + +)0 P()BD(Each photon will be counted once, and no photon will be counted +more than once)ES(. + +)0 P(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. + +With this in mind, the rules for determining whether a boundary image +pixel or table row are assigned to a region are defined below. + +)0 2 136 H(Image)WB 218 Sn( boundaries : radially-symmetric shapes \201circle, annuli, ellipse\202)EH( + +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: + +)UL()-1 LI( the outer boundary of a symmetric shape does not include such pixels +)-1 LI( the inner boundary of a symmetric shape \201annulus\202 includes such pixels)LU( + +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. + +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. + +)0 2 137 H(Image)WB 219 Sn( Boundaries: non-radially symmetric shapes \201polygons, boxes\202)EH( + +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. + +)0 2 138 H(Row)WB 220 Sn( Boundaries are Analytic)EH( + +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, \201since table rows, especially X-ray events rows, often have +discrete, floating point positions\202 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. + +)0 P(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 \201which utilize analytic +row filtering\202 perform differently from funcnts \201which performs image +filtering, even on tables\202. + +)0 2 139 H(Image)WB 221 Sn( Boundaries vs. Row Boundaries: Practical Considerations)EH( + +)0 P(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: +) 2 49 PR( fundisp test1.fits"[box\2014219,3887,6,6,0\202]" | wc + 8893 320148 3752846)RP( +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: +) 1 58 PR( ./funtable test1.fits"[box\2014219,3887,6,6,0\202]" test2.fits)RP( +Now run funcnts using the original filter on the derived file: +) 12 61 PR( ./funcnts test2.fits "physical; box\2014219,3887,6,6,0\202" + + [... lot of processed output ...] + + # the following source and background components were used: + source region\201s\202 + ---------------- + physical; box\2014219,3887,6,6,0\202 + + reg counts pixels + ---- ------------ --------- + 1 7847.000 36)RP( +There are 1044 rows \201events\202 that pass the row filter in fundisp \201or +funtable\202 but fail to make it through funcnts. Why? + +)0 P(The reason can be traced to how analytic row filtering \201fundisp, funtable\202 +differs from integerized pixel filtering\201funcnts, funimage\202. Consider the +region: +) 1 22 PR( box\2014219,3887,6,6,0\202)RP( +Analytically \201i.e., using row filtering\202, positions will pass this +filter successfully if: +) 2 19 PR( 4216 <= x <= 4222 + 3884 <= y <= 3890)RP( +For example, photons with position values of x=4216.4 or y=3884.08 will pass. + +)0 P(Integerized image filtering is different in that the pixels that will +pass this filter have centers at: +) 2 40 PR( x = 4217, 4218, 4219, 4220, 4221, 4222 + y = 3885, 3886, 3887, 3888, 3889, 3890)RP( +Note that there are 6 pixels in each direction, as specified by the region. +That means that positions will pass the filter successfully if: +) 2 24 PR( 4217 <= \201int\202x <= 4222 + 3885 <= \201int\202y <= 3890)RP( +Photons with position values of x=4216.4 or y=3884.08 will NOT pass. + +)0 P(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. + +)0 P([It could be argued that the correct photon limits for floating point +row data really should be: +) 2 23 PR( 4216.5 <= x <= 4222.5 + 3884.5 <= y <= 3890.5)RP( +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.] + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 140 H(Last)WB 222 Sn( updated: November 16, 2005)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (regdiff.html) D +/Ti (Differences Between Funtools and IRAF Regions) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 59 Sn( + + +)0 2 141 H(RegDiff:Differences)WB 224 Sn()WB 223 Sn( Between Funtools and IRAF Regions)EA()EH( + + +)0 2 142 H(Summary)WB 225 Sn()EH( +Describes the differences between Funtools/ds9 regions and the old IRAF/PROS +regions. + + +)0 2 143 H(Description)WB 226 Sn()EH( +)0 P(We have tried to make Funtools regions compatible with their +predecessor, IRAF/PROS 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: + +)UL( +)0 P()-1 LI(If a pixel is covered by two different regions expressions, +Funtools assigns the mask value of the )BD(first)ES( region that +contains that pixel. That is, successive regions )BD(do not)ES( +overwrite previous regions in the mask, as was the case with the +original PROS regions. This means that one must define overlapping +regions in the reverse order in which they were defined in PROS. If +region N is fully contained within region M, then N should be defined +)BD(before)ES( M, or else it will be "covered up" 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. + +)0 P()-1 LI( The )BD(PANDA)ES( region has replaced the old PROS syntax in which +a )BD(PIE)ES( accelerator was combined with an )BD(ANNULUS)ES( accelerator +using )BD(AND)ES(. That is, +) 1 48 PR( ANNULUS\20120,20,0,15,n=4\202 & PIE\20120,20,0,360,n=3\202)RP( +has been replaced by: +) 1 29 PR( PANDA\20120,20,0,360,3,0,15,4\202)RP( +The PROS syntax was inconsistent with the meaning of the )BD(AND)ES( operator. + +)0 P()-1 LI( The meaning of pure numbers \201i.e., without format specifiers\202 in +regions has been clarified, as has the syntax for specifying coordinate +systems. See the general discussion on +)0 54 1 A(Spatial Region Filtering)54 0 TN TL()Ec /AF f D( +for more information. +)LU( + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 144 H(Last)WB 227 Sn( updated: November 16, 2005)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (combo.html) D +/Ti (Combining Region and Table Filters) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 60 Sn( + + +)0 2 145 H(FunCombine:)WB 230 Sn()WB 228 Sn( Combining Region and Table Filters)EA()EH( + + +)0 2 146 H(Summary)WB 231 Sn()EH( +)0 P(This document discusses the conventions for combining region and table +filters, especially with regards to the comma operator. + + + +)0 2 147 H(Comma)WB 232 Sn()WB 229 Sn( Conventions)EA()EH( +)0 P(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. + +)0 P(According to long-standing usage in IRAF, when a comma separates two +table filters, it takes on the meaning of a boolean )BD(and)ES(. Thus: +) 1 24 PR( foo.fits[pha==1,pi==2])RP( +is equivalent to: +) 1 27 PR( foo.fits[pha==1 && pi==2])RP( + +When a comma separates two spatial region filters, however, it has +traditionally taken on the meaning of a boolean )BD(or)ES(. Thus: +) 1 46 PR( foo.fits[circle\20110,10,3\202,ellipse\20120,20,8,5\202])RP( +is equivalent to: +) 1 49 PR( foo.fits[circle\20110,10,3\202 || ellipse\20120,20,8,5\202])RP( +\201except that in the former case, each region is given a unique id +in programs such as funcnts\202. + +)0 P(Region and table filters can be combined: +) 1 34 PR( foo.fits[circle\20110,10,3\202,pi=1:5])RP( +or even: +) 1 61 PR( foo.fits[pha==1&&circle\20110,10,3\202,pi==2&&ellipse\20120,20,8,5\202])RP( +In these cases, it is not obvious whether the command should utilize an +)BD(or)ES( or )BD(and)ES( operator. We therefore arbitrarily chose to +implement the following rule: +)UL()-1 LI( if both expressions contain a region, the operator used is )BD(or)ES(. +)-1 LI( if one \201or both\202 expression\201s\202 does not contain a region, the operator +used is )BD(and)ES(.)LU( +This rule handles the cases of pure regions and pure column filters properly. +It unambiguously assigns the boolean )BD(and)ES( to all mixed cases. Thus: +) 1 34 PR( foo.fits[circle\20110,10,3\202,pi=1:5])RP( +and +) 1 34 PR( foo.fits[pi=1:5,circle\20110,10,3\202])RP( +both are equivalent to: +) 1 37 PR( foo.fits[circle\20110,10,3\202 && pi=1:5])RP( + +)0 P([NB: This arbitrary rule )BD(replaces the previous arbitrary rule)ES( +\201pre-funtools 1.2.3\202 which stated: +)UL()-1 LI( if the 2nd expression contains a region, the operator used is )BD(or)ES(. +)-1 LI( if the 2nd expression does not contain a region, the operator +used is )BD(and)ES(.)LU( +In that scenario, the )BD(or)ES( operator was implied by: +) 1 21 PR( pha==4,circle 5 5 1)RP( +while the )BD(and)ES( operator was implied by +) 1 21 PR( circle 5 5 1,pha==4)RP( +Experience showed that this non-commutative treatment of the comma +operator was confusing and led to unexpected results.] + +)0 P(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. + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 148 H(Last)WB 233 Sn( updated: November 16, 2005)EH( + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (env.html) D +/Ti (Funtools Environment Variables) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 61 Sn( + + +)0 2 149 H(FunEnv:)WB 235 Sn()WB 234 Sn( Funtools Environment Variables)EA()EH( + + +)0 2 150 H(Summary)WB 236 Sn()EH( +Describes the environment variables which can be used to tailor the overall +Funtools environment. + + +)0 2 151 H(Description)WB 237 Sn()EH( +)0 P(The following environment variables are supported by Funtools: +)0 DL()0 P()0 DT()BD(FITS_EXTNAME)ES( +)DD( The )BD(FITS_EXTNAME)ES( environment variable specifies the +default FITS extension name when )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( is called on a file lacking +a primary image. Thus, +) 1 29 PR( setenv FITS_EXTNAME "NEWEV")RP( +will allow you to call )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( on files without specifying NEWEV in +the +)0 42 1 A(Funtools bracket specification)42 0 TN TL()Ec /AF f D(. +If no FITS_EXTNAME 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 "EVENTS" or +"STDEVT" \201we are, after all, and X-ray astronomy group at heart!\202. + +)0 P()0 DT()BD(FITS_EXTNUM)ES( +)DD( The )BD(FITS_EXTNUM)ES( environment variable specifies the +default FITS extension number when )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( is called on a file lacking +a primary image. Thus, +) 1 22 PR( setenv FITS_EXTNUM 7)RP( +will allow you to call )0 25 1 A(FunOpen\201\202)25 0 TN TL()Ec /AF f D( on files to open the seventh +extension without specifying the number in the +)0 42 1 A(Funtools bracket specification)42 0 TN TL()Ec /AF f D(. + +)0 P()0 DT()BD(FITS_BINCOLS)ES( and )BD(EVENTS_BINCOLS)ES( +)DD( These environment variable specifies the default binning key for +FITS binary tables and raw event files, respectively. They can be +over-ridden using the )BD(bincols=[naxis1,naxis2])ES( keyword in a +)0 42 1 A(Funtools bracket specification)42 0 TN TL()Ec /AF f D(. +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: +) 1 35 PR( setenv FITS_BINCOLS "\201detx,dety\202")RP( +in preference to adding a bincols specification to each filename: +) 1 31 PR( foo.fits[bincols=\201detx,dety\202])RP( + +)0 P()0 DT()BD(FITS_BITPIX)ES( and )BD(EVENTS_BITPIX)ES( +)DD( These environment variable specifies the default bitpix value for +binning FITS binary tables and raw event files, respectively. They can +be over-ridden using the )BD(bitpix=[value])ES( keyword in a +)0 42 1 A(Funtools bracket specification)42 0 TN TL()Ec /AF f D(. The value +of each environment variable is one of the standard FITS bitpix values +\2018,16,32,-32,-64\202. For example, if you want binning routines to +create a floating array, then use: +) 1 24 PR( setenv FITS_BITPIX -32)RP( +in preference to adding a bitpix specification to each filename: +) 1 22 PR( foo.fits[bitpix=-32])RP( + +)0 P()0 DT()BD(ARRAY)ES( +)DD( The )BD(ARRAY)ES( environment variable specifies the default +definition of an array file for Funtools. +It is used if there is no array specification passed in the +)BD(ARRAY\201\202)ES( directive in a +)0 46 1 A(Non-FITS Array specification)46 0 TN TL()Ec /AF f D(. +The value of the environment variable is a valid array specification such as: +) 2 25 PR( setenv ARRAY "s100.150" + foo.arr[ARRAY\201\202])RP( +This can be defined in preference to adding the specification to each filename: +) 1 26 PR( foo.arr[ARRAY\201s100.150\202])RP( + +)0 P()0 DT()BD(EVENTS)ES( +)DD( The )BD(EVENTS)ES( environment variable specifies the default +definition of an raw event file for Funtools. +It is used if there is no EVENTS specification passed in the +)BD(EVENTS\201\202)ES( directive in a +)0 45 1 A(Non-FITS EVENTS specification)45 0 TN TL()Ec /AF f D(. +The value of the environment variable is a valid EVENTS specification such as: +) 2 73 PR( setenv EVENTS "x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024" + foo.ev[EVENTS\201\202])RP( +This can be defined in preference to adding the specification to each filename: +) 1 73 PR( foo.ev[EVENTS\201x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024\202])RP()LD( + +The following filter-related environment variables are supported by Funtools: +)0 DL( +)0 P()0 DT()BD(FILTER_PTYPE)ES( +)DD( The )BD(FILTER_PTYPE)ES( environment variable specifies how to +build a filter. There are three possible methods: +)0 DL()0 DT(process or p +)DD(The filter is compiled and linked against the funtools library \201which +must therefore be accessible in the original install directory\202 to produce +a slave program. This program is fed events or image data and returns +filter results. + +)0 DT(dynamic or d \201gcc only\202 +)DD(The filter is compiled and linked against the funtools library \201which +must therefore be accessible in the original install directory\202 to produce +a dynamic shared object, which is loaded into the funtools program and +executed as a subroutine. \201Extensive testing has shown that, contrary to +expectations, this method is no faster than using a slave process.\202 + +)0 DT(contained or c +)DD(The filter and all supporting region code is compiled and linked +without reference to the funtools library to produce a slave program +\201which is fed events or image data and returns filter results\202. 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.)LD( + +By default, )BD(dynamic)ES( is generally used for gcc compilers and +)BD(process)ES( for other compilers. However the filter building algorithm +will check for required external files and will use )BD(contained)ES( is +these are missing. + +)0 P()0 DT()BD(FUN_MAXROW)ES( +)DD( The )BD(FUN_MAXROW)ES( environment variable is used by core +row-processing Funtools programs \201funtable, fundisp, funcnts, funhist, +funmerge, and funcalc\202 to set the maximum number of rows read at once +\201i.e. it sets the third argument to the FunTableRowGet\201\202 call\202. 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 FunTableRowGet\201\202 specifies its own maximum +number of rows to read. NB: if you make this value very large, you +probably will need to increase )BD(FUN_MAXBUFSIZE)ES( \201see below\202 as well. + +)0 P()0 DT()BD(FUN_MAXBUFSIZE)ES( +)DD( The )BD(FUN_MAXBUFSIZE)ES( 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 \201see above\202. Since the +row size is unlimited \201and we have examples of it being larger than 5 +Mb\202, 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. \201If the row size is greater than this max buffer +size, then maxrow is set to 1.\202 This environment variable will change +the max buffer size allowed. + +)0 P()0 DT()BD(FILTER_CC)ES( +)DD( The )BD(FILTER_CC)ES( environment variable specifies the compiler to +use for compiling a filter specification. You also can use the )BD(CC)ES( +environment variable. If neither has been set, then gcc will be used +if available. Otherwise cc is used if available. + +)0 P()0 DT()BD(FILTER_EXTRA)ES( +)DD( The )BD(FILTER_EXTRA)ES( 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. + +)0 P()0 DT()BD(FILTER_TMPDIR)ES( +)DD( The )BD(FILTER_TMPDIR)ES( environment variable specifies the temporary +directory for filter compilation intermediate files. You also can use +the )BD(TMPDIR)ES( and )BD(TMP)ES( variables. By default, /tmp is used +as the temporary directory. + +)0 P()0 DT()BD(FILTER_KEEP)ES( +)DD( The )BD(FILTER_KEEP)ES( environment variable specifies whether the +intermediate filter files \201i.e. C source file and compile log file\202 +should be saved after a filter is built. The default is "false", 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. +)LD( + + + + + +)0 P()0 0 1 A(Go to Funtools Help Index)0 0 TN TL()Ec /AF f D( + +)0 5 152 H(Last)WB 238 Sn( updated: November 16, 2005)EH( + + +)WB NL +/Cb Db D /Ct [16#00 16#00 16#00] D /Cl [16#00 16#00 16#00] D /CL -1 D Ct Sc +DS +/Ba f D /BO 0 D Bs +/UR (changelog.html) D +/Ti (Funtools ChangeLog) D +/Au () D +/Df f D +/ME [()] D + +0 BO R +()1 Sl()WB 62 Sn( +)0 2 153 H(Funtools)WB 239 Sn( ChangeLog)EH( + +)0 P(This ChangeLog covers both the Funtools library and the suite of +applications. It will be updated as we continue to develop and improve +Funtools. The up-to-date version can be found +)R5 2 A(here)EA(. +[The changelog for the initial development of Funtools, covering the +beta releases, can be found +)R6 2 A(here)EA(.] + +)0 2 154 H()WB 240 Sn( Patch Release 1.4.5 \201internal ds9 release\202)EH( +)UL()0 P()-1 LI( Removed permission checking from Find\201\202 on cygwin systems. This was broken +by Windows 7. +)0 P()-1 LI( Removed addition of -no-cpp-precomp flag from gcc 4.2 and beyond.)LU( + +)0 2 155 H()WB 241 Sn( Patch Release 1.4.4 \201internal ds9 release\202)EH( +)UL()0 P()-1 LI( Fixed -J funcone, which was not properly outputting all rows. +)0 P()-1 LI( Filter: when an image is flipped, the rotation angle must be reversed. +)0 P()-1 LI( Filter: add support for windows-based ipc communication when using tcc +compiler.)LU( + +)0 2 156 H()WB 242 Sn( Patch Release 1.4.3 \201internal ds9 release\202)EH( +)UL()0 P()-1 LI( Filter: improve checks for existence of compiler, even if CC is set. +)0 P()-1 LI( Change launch.h to xlaunch.h to avoid conflict with OS X. +)0 P()-1 LI( handle flipped images in filtering)LU( + +)0 2 157 H()WB 243 Sn( Patch Release 1.4.2 \201internal ds9 release\202)EH( +)UL()0 P( +)-1 LI( Port to gcc 4.2. +)0 P()-1 LI( Fix 1-byte filters on intel machines \201missing SW1 no-op\202. +)0 P()-1 LI( Remove ambiguity from filt.l \201and calc.l\202 using [A-z] in a +case-insensitive lexer. +)0 P()-1 LI( In funsky, the default unit for RA was changed from hours to degrees. +)0 P()-1 LI( Fixed bug in funtable in which TCRVL header values were output as strings. +)0 P()-1 LI( Added support for running funtools filters in Rosetta \201i.e. running PPC +executables on an Intel Mac\202 by sensing and handling data swap requirements. +Only works with FILTER_PTYPE set to 'c' \201can't link against wrong architecture +libraries\202. +)0 P()-1 LI( Fixed bug in FITS library to allow "-" in extension names. +)0 P()-1 LI( Code and documentation now agree that the copy extension specifier \201'+'\202 +comes after the extension name.)LU( + +)0 2 158 H()WB 244 Sn( Patch Release 1.4.1 \201internal ds9 release\202)EH( +)UL()0 P()-1 LI( Modified internal Launch\201\202 routine to use posix_spawn\201\202, if necessary. +This is required for OS X 10.5 \201leopard\202, which frowns upon use of fork\201\202 +and exec\201\202. Also modified zprocess routines to use Launch\201\202.)LU( + +)0 2 159 H()WB 245 Sn( Public Release 1.4.0 \20115 August 2007\202)EH( + +)UL()-1 LI( Public release of production-quality code, incorporating changes +and improvements from previous beta releases, including: +)UL()-1 LI( Support for access to ASCII text column files. +)-1 LI( Support for fast indexed access of binary tables. +)-1 LI( Support for database views of tables, i.e. pre-set values for the filter + specification, the columns to activate, and display format. +)-1 LI( New programs include funcone \201cone search\202, funindex \201create index files\202, + and funcen \201calculate centroids within regions\202.)LU( +)LU( + +)0 2 160 H()WB 246 Sn( Release 1.3.0b[n] \201mainly internal SAO beta releases\202)EH( +)UL( +)0 P()-1 LI( Added -F[c] switch to change the column delimiter to the +specified character. + +)0 P()-1 LI( Extended fundisp's format switch \201-f\202 so that it can now handle complex +formats such as 'x=sometext%3d- y=othertest%3d.ext'. + +)0 P()-1 LI( Added support for creating and processing 1D FITS images. + +)0 P()-1 LI( Added vcol=colname and vcol=/colname to filter specifications to +support use of a third value column when binning 2D images. + +)0 P()-1 LI( Added switches to funcone to write out data rows are not within +any cone \201-J, -X\202 and centers which have no close data rows \201-L\202. + +)0 P()-1 LI( In funjoin, added ability to specify a numeric tolerance for when joining +two files. + +)0 P()-1 LI( shared memory support in gio now can create a shared segment if w+ is +specified as the open mode. + +)0 P()-1 LI( Changed reggeometry man page so that examples correctly show angles +going counter-clockwise from the x-axis instead of from the y-axis. + +)0 P()-1 LI( Added checks to funmerge to ensure that all files have the same columns. + +)0 P()-1 LI( Fixed bug in text support that prevented header-less files from being +processed properly. + +)0 P()-1 LI( Added support for 64-bit images \201bitpix=64\202 and table columns \201TFORM=K\202. + +)0 P()-1 LI( Filter code was not applying bscale/bzero to columns. + +)0 P( +)-1 LI( Fixed funimage bug that caused a .5/block error in WCS CRPIX values +generated from binary tables. + +)0 P()-1 LI( Added feq\201a,b\202 and div\201a,b\202 macros to funcalc. + +)0 P()-1 LI( Added support for single-line #define to funcalc. + +)0 P()-1 LI( Updated wcs library to 3.6.6 + +)0 P()-1 LI( Fix bug in funcen in which ra,dec was not being calculated correctly +if physical and image coords did not match up. + +)0 P()-1 LI( The filter syntax "col1 = col2" now explicitly generates an error +\201you really want to do "col1 == col2"\202. + +)0 P()-1 LI( Added -o switch to include offset from the nominal target position. + +)0 P()-1 LI( Fundisp now displays multi-dimensional vector columns properly. + +)0 P()-1 LI( Documented support for lists of files processed as a single file +using "list: file1 ... filen" syntax. + +)0 P()-1 LI( Fixed bugs in support for pipe file type \201i.e. ability to pass +commands as a filename using "pipe: cmd arg1 ... argn" syntax\202. + +)0 P()-1 LI( Fixed bug in funhist processing of image-based pixel histograms +\201i.e using "xy" for columns\202 where a region was specified. All pixels +outside the region were erroneously being added to the bin containing +the 0 value. + +)0 P()-1 LI( Disabled multi-file processing in funds9, which was breaking support +for pathnames containing spaces and is not used by ds9 anyway. + +)0 P()-1 LI( Added support for Views of tables, i.e. pre-set values for the +filter specification, the columns to activate, and display format +\201though the latter is for fundisp only\202. + +)0 P()-1 LI( Added -l switch to funimage to read x, y, val columns from a list. + +)0 P()-1 LI( Removed useless and meaningless section syntax foo'[*]' because it +breaks pointer de-referencing on string columns \201i.e. foo'[*xxx=='a']'\202. +Use foo'[*,*]' instead, as documented. + +)0 P()-1 LI( String variables were not always being terminated properly in the +filter code because FITS 'A' data is not necessarily null-terminated. + +)0 P()-1 LI( Added funtools version number to all usage\201\202 displays. + +)0 P()-1 LI( Added explanation of switch arguments to many usage\201\202 displays. + +)0 P()-1 LI( The filter keyword row# now supports single row selection as well +as range selection, i.e., "row#=100" along with previous "row#=100:200". + +)0 P()-1 LI( fundisp now outputs "0x" before hex values. + +)0 P()-1 LI( Fixed bug in filter parser which processed rangelists incorrectly +if spaces were put into the rangelist \201i.e. "pha= 1 : 3" instead of +pha=1:3\202. + +)0 P()-1 LI( Fixed a bug in funindex which created a wrongly named index file +if more than one "." was in the input file name. + +)0 P()-1 LI( Added support to funcone to take ra, dec, radius from a list +\201i.e. columns in a FITS file or a text file\202. + +)0 P()-1 LI( Fixed a bug in FunColumnActivate so that if some columns are +explicitly activated while others are de-activated, only the +explicitly activated columns are activated \201code was activating all +columns in this case\202. + +)0 P()-1 LI( Fixed a bug in funindex which prevented indexing tables containing +a column named N. + +)0 P()-1 LI( fundisp now encloses ASCII column values in single quotes \201unless +-T is specified to output RDB format\202. + +)0 P()-1 LI( If a filter specification only involves indexed columns, then the +compiled filter is not used. + +)0 P()-1 LI( Funmerge can now be given a list of files to merge using @list syntax. +Also removed the restriction on how many files can be merged \201was limited to +the max number of open files\202. + +)0 P()-1 LI( Added ability to edit \201add, delete, modify\202 header parameters in funhead +by specifying an output file \201editing acts as a filter\202 and an edit command +file \201which can be stdin\202. + +)0 P()-1 LI( Funtools now contains preliminary code to support \201fast\202 indexed access +of binary tables. See idx.html or "man funidx" for more details. + +)0 P()-1 LI( Funtools now contains preliminary code supporting access to ASCII +column files. See text.html or "man funtext" for more details. + +)0 P()-1 LI( Fixed bug in funcalc in which columns used in an expression were +always being replaced by new columns, with all associated parameters +\201e.g. WCS\202 were being deleted. Now this only happens if the column +explicitly changes its data type. + +)0 P()-1 LI( Fixed bug in funcalc in which the raw data and user data became out +of sync for one row after every 8192 \201FUN_MAXROW\202 rows. + +)0 P()-1 LI( Fixed bug in gio in which gseek returned 0 instead of the current byte +offset for disk files. + +)0 P()-1 LI( Added funcone program to perform cone search on RA, Dec columns in +a FITS binary table. + +)0 P()-1 LI( Fixed bug in polygon, pie and rotated box region filtering for +tables \201nearby rows exactly in line between two non-vertical or +non-horizontal vertices were being accepted incorrectly\202. + +)0 P()-1 LI( Fixed pie and panda regions so that the angles now start from +positive x axis == 0 degrees and run counter-clockwise, as +documented. They were going from positive y. NB: a similar change +was made to ds9 release 4.0b3. You must be using ds9 4.0b3 or later +in order to have the correct behavior when generating regions in ds9 +and using them in funtools. + +)0 P()-1 LI( Added -p [prog] switch to funcalc to save the generated program. +instead of executing \201and deleting\202 it. + +)0 P()-1 LI( Upgraded zlib to 1.2.3. +)LU( + +)0 2 161 H()WB 247 Sn( Patch Release 1.2.4 \201internal SAO and beta release only\202)EH( +)UL( +)0 P()-1 LI( In funcalc, added support for user-specified arguments via the +-a [argstr] switch. These arguments are accessed in the compiled program +using the supplied ARGC and ARGV\201n\202 macros. + +)0 P()-1 LI( Added -n \201no header display\202 to fundisp to skip outputting header. + +)0 P()-1 LI( Added checks for various types of blank filters. + +)0 P( +)-1 LI( Added macros NROW \201current row number\202 and WRITE_ROW \201write current +row to disk\202 to funcalc. + +)0 P()-1 LI( funcalc no longer requires that at least one data column be +specified in the compiled expression. + +)0 P()-1 LI( Added FUN_NROWS to FunInfoGet\201\202 to return the total number of rows in +an input table \201i.e. value of NAXIS2\202. + +)0 P( +)-1 LI( The compiled funcalc program now includes stdlib.h and unistd.h. + +)0 P()-1 LI( The util/NaN.h header file is now modified at configure time to +contain endian status for the target architecture. References to +specific platforms have been removed. + +)0 P()-1 LI( Added -m switch to funtable to output multiple files, one for +each input region \201and a separate file for events that pass the +filters but are not in any region\202. + +)0 P()-1 LI( Added ability to add new parameters \201FunParamPutx\202 after writing +data if space is previously reserved in the form of a blank parameter +whose value is the name of the param to be updated. \201Also requires the +append argument of FunParamPutx be set to 2\202. + +)0 P( +)-1 LI( Added ability to build shared libraries. With --enable-shared=yes, +shared library is built but not used. With --enable-shared=link, +shared library is linked against \201requires proper installation and/or +use of LD_LIBRARY_PATH\202. + +)0 P()-1 LI( Added -v [column] support to funcnts so that counts in a table +can be accumulated using values from a specified column \201instead of +the default case where an integral count is accumulated for each event +in a region\202. + +)0 P()-1 LI( Added funcen program to calculate centroids within regions +\201binary tables only\202. Also added support for a funcen-based centroid +tool to funtools.ds9. + +)0 P()-1 LI( Fixed bug which prevented successful filtering of columns containing +arrays. + +)0 P()-1 LI( Added filter check to ensure that a column is not incorrectly used +as an array. + +)0 P()-1 LI( Fundisp now displays column arrays indexed from 0, not 1. + +)0 P()-1 LI( Added -i [interval] support to funcnts so that multiple intervals +can be processed in a single pass through the data. For example, +specifying -i "pha=1:5;pha=6:10;pha=11:15" will generate results in +each of 3 pha bands. + +)0 P()-1 LI( Fixed calculation of LTV quantities when binning floating point +column data \201value was off by 0.5\202. + +)0 P()-1 LI( Added support for 'D' in floating point header values. + +)0 P()-1 LI( Added -a switch to funimage and funtable to append output image or +table to an existing FITS file \201as an IMAGE or BINTABLE extension\202. + +)0 P()-1 LI( Added support for column scaling \201TSCAL and TZERO\202 on input columns. +Note that the default column type is changed to accommodate scaling \201e.g. +a column of type 'I' is changed to 'J', 'J' is changed to 'D'\202 so that +the scaled values can be handled properly by programs such as fundisp +\201which utilize default types\202. + +)0 P( +)-1 LI( Added support to FunColumnSelect\201\202 for handling structs of arrays +\201i.e. where returned columns are contiguous\202 instead of the default array +of structs \201returned row are contiguous\202. This is done by specifying +"org=structofarrays" in the plist and passing a single struct containing +the arrays. + +)0 P()-1 LI( When writing an rdb/starbase file, fundisp now outputs the full +column name, regardless of the width of the column \201which ordinarily +is truncated to match\202. + +)0 P()-1 LI( Fixed support for large files by changing all file positions variables +from "long" declarations to "off_t. + +)0 P()-1 LI( Fixed bug in funcalc incorrectly processed multiple array +references \201e.g. cur->foo[0]=cur->x;cur->foo[1]=cur->y;\202 within a single +line of code. + +)0 P()-1 LI( Added FILTER_CFLAGS environment variable for all filtering. Also added +--with-filter-cc and --with-filter-cflags options on configure to allow +specification of a default C compiler and associated CFLAGS for filtering. +All of this is necessary in order to support 64-bit libraries under Solaris. + +)0 P()-1 LI( Added the funtbl script to extract a table from Funtools ASCII output. + +)0 P()-1 LI( Added code to funimage to update IRAF DATASEC keyword. + +)0 P()-1 LI( Added checks to ensure that image dimensions are positive. + +)0 P()-1 LI( Fixed a bug in funimage where int data was being scaled using BSCALE and +BZERO but these keywords also were being retained in the output image header. +Now the data are not scaled unless the output data type is float \201in which +case the scaling parameters are removed\202. + +)0 P()-1 LI( Fixed a bug in funmerge which prevented merging of files unless one of +the -f, -w, or -x switches were used. + +)0 P()-1 LI( Fixed a bug in funtable and fundisp which caused the special '$n' column +to be output incorrectly. + +)0 P()-1 LI( Fixed sort option in funtable, which previously worked only if the +record size was an even divisor of 8192 \201and returned garbage otherwise\202. + +)0 P()-1 LI( Fixed bug in filters involving FITS data type 'X' \201bitfield\202. + +)0 P()-1 LI( Fixed bug in funcnts in which the output angles and radii were +being displayed incorrectly when multiple panda shapes were specified. + +)0 P()-1 LI( Fixed bug in pandas and pies using n= syntax when first angle +specified was greater than second. The resulting mask was of +the correct shape but contained only a single region. + +)0 P()-1 LI( Table row access routines will now decrease maxrows if memory cannot be +allocated for maxrows*sizeof\201row\202, i.e. if the size of a row is so large that +space for maxrows cannot be allocated. + +)0 P()-1 LI( The FUN_MAXBUFSIZE environment variable was added to limit the +max buffer size that will be allocated to hold table row data. The +default is 5Mb. + +)0 P()-1 LI( Generated PostScript and PDF versions of the help pages. + +)0 P()-1 LI( Moved OPTIONS section before \201often-lengthy\202 DESCRIPTION section in +man pages. + +)0 P()-1 LI( All memory allocation now does error checking on the result +\201except wcs library, which is external code\202. + +)0 P()-1 LI( Removed some compiler warnings that surfaced when using gcc -O2. + +)0 P()-1 LI( Updated wcs library to 3.5.5. + +)0 P()-1 LI( Upgraded zlib to 1.2.1. +)LU( + +)0 2 162 H()WB 248 Sn( Patch Release 1.2.3 \20112 January 2004\202)EH( +)UL( +)0 P()-1 LI( Generated man pages from the html pages. These are installed +automatically at build time. + +)0 P()-1 LI( Changed instances of sprintf\201\202 to snprintf\201\202 to protect +against buffer overflow. + +)0 P()-1 LI( Fixed a number of compiler warnings in non-ANSI compilers. + +)0 P()-1 LI( Increased SZ_LINE parameter value from 1024 to 4096. +)LU( + +)0 2 163 H()WB 249 Sn( Patch Release 1.2.3b1 \20119 August 2003\202)EH( +)UL( +)0 P()-1 LI( The rule for using comma to separate a table filter expression +and a region expression has been changed. The rule now states: +)UL()-1 LI( if both expressions contain a region, the operator used is )BD(or)ES(. +)-1 LI( if one \201or both\202 expression\201s\202 does not contain a region, the operator +used is )BD(and)ES(.)LU( +This rule handles the cases of pure regions and pure column filters properly. +It unambiguously assigns the boolean )BD(and)ES( to all mixed cases. Thus: +) 1 34 PR( foo.fits[circle\20110,10,3\202,pi=1:5])RP( +and +) 1 34 PR( foo.fits[pi=1:5,circle\20110,10,3\202])RP( +both are equivalent to: +) 1 37 PR( foo.fits[circle\20110,10,3\202 && pi=1:5])RP( + +)0 P()-1 LI( When include files are used in filters, they now have implied +parentheses surrounding them. Thus, if a region file foo.reg contains two +regions \201e.g. circle 1 2 3 and circle 4 5 6\202, the syntax: +) 1 21 PR( pha=4:5&&@foo.reg)RP( +is equivalent to: +) 1 42 PR( pha=4:5 && \201circle 1 2 3 || cir 4 5 6\202)RP( +instead of: +) 1 40 PR( pha=4:5 && circle 1 2 3 || cir 4 5 6)RP( +and the pha filter is applied to both regions. + +)0 P()-1 LI( Filters and comments now can be terminated with the string +literal "\200n" as well as ";" and the new-line character. This means +that a region can have comments embedded in it: +) 1 72 PR( funcnts foo.fits "circle 512 512 10 # color=red\200n circle 512 512 20")RP( + +)0 P()-1 LI( Added capability to update the value of an existing parameter +after writing the table or image \201assuming the output image is a +disk file or is being redirected into a file\202. + +)0 P()-1 LI( Improved handling of parentheses in filter expressions. + +)0 P( +)-1 LI( Fixed a bug in image \201not event\202 regions in which circles and +annuli with radius of 1 pixel were not being processed. No counts and +no area would be found in such regions. + +)0 P()-1 LI( Fixed a bug in funcnts in which the radii column values for out of sync +if multiple annuli were specified \201instead of a single varargs or accel +annulus\202. + +)0 P()-1 LI( By default, fundisp will display integer image data as floats +if the BSCALE and BZERO header parameters are present. + +)0 P()-1 LI( Added -L switch to funhead to output starbase list format. + +)0 P()-1 LI( Changed the name of the routine _FunColumnSelect to +FunColumnSelectArr, in order to emphasize that it is not +a private routine. + +)0 P()-1 LI( Funcalc now checks to ensure that a column was specified as part of +the expression. + +)0 P()-1 LI( Funcalc local variables in the compiled program now use a "__" prefix +to avoid conflicts with user-defined variables. + +)0 P()-1 LI( Unofficial unsigned short \201bitpix=-16\202 image data now is scaled +correctly using BSCALE and BZERO header parameters. + +)0 P()-1 LI( Ported to Intel icc and gcc 3.3 compilers. + +)0 P()-1 LI( Updated wcs library to 3.5.1. + +)0 P()-1 LI( Changed license from public domain to GNU GPL. +)LU( + +)0 2 164 H()WB 250 Sn( Patch Release 1.2.2 \20118 May 2003\202)EH( +)UL( +)0 P( +)-1 LI( Fixed funcalc so that it now actually compiles an expression and +runs it, instead of getting a "filter compilation error". Oops! + +)0 P()-1 LI( Fixed bug in FunOpen in which the bracket specification was being +removed from the filename if a disk file was opened for "w" or "a". + +)0 P()-1 LI( Fixed bug in FunFlush which prevented two successive calls to +FunImagePut from writing the second extension header properly. + +)0 P()-1 LI( All filter routines now use gerror\201stderr, ...\202 call instead of +fprintf\201stderr, ...\202 so that output to stderr can be turned off \201via +setgerror\201level\202 or GERROR environment variable\202. + +)0 P()-1 LI( All standard Funtools programs check for GERROR environment +variable before setting gerror flag. + +)0 P()-1 LI( Some error messages about invalid region arguments were not being +printed. + +)0 P()-1 LI( FITS parameters/headers now conform more closely to FITS standard: +)UL()-1 LI( Blank keywords are treated in the same way as COMMENTS and HISTORY cards +)-1 LI( XTENSION keywords are now exactly 8 characters long +)-1 LI( 'E' is output instead of 'e' in floating point param values +)-1 LI( PCOUNT and GCOUNT are output correctly for image extensions +)-1 LI( EXTEND=T is output in primary header +)-1 LI( COMMENTS and HISTORY start in column 9)LU( +)LU( + +)0 2 165 H()WB 251 Sn( Patch Release 1.2.1 \20124 April 2003\202)EH( +)UL( +)0 P()-1 LI( Varargs ellipse and box annular regions were being +processed incorrectly when the following conditions all were met: +)UL()-1 LI( the region was specified in physical or wcs coordinates +)-1 LI( the data file contained LTM/LTV keywords, i.e., it +was blocked with respect to the original data file +)-1 LI( the program being run was an image program \201e.g. funcnts, funimage\202)LU( +Varargs ellipse and boxes are regions of the form: +) 2 43 PR( ellipse x y a1 b1 a2 b2 ... an bn [angle] + box x y l1 w1 l2 w2 ... ln wn [angle])RP( +where at least 2 sets of axis \201length\202 values were specified to form +an annulus \201i.e. simple ellipses and boxes worked properly\202. With all +of the above conditions met, a region in physical coordinates saw its +second length argument converted incorrectly from physical coordinates +to image coordinates. In simple terms, this means that funcnts did not +process elliptical or box regions in physical coords on blocked images +properly. Note that blocking on the command line \201e.g. foo.fits[*,*,2]\202 +did work when no LTM/LTV keywords existed in the file. + +)0 P()-1 LI( The fundisp -f switch now supports specification of +column-specific display formats as well as a more convenient way to +specify datatype-specific display formats. Both use keyword=value +specifiers. For columns, use: +) 1 58 PR( fundisp -f "colname1=format1 colname2=format2 ..." ...)RP( +e.g. +) 1 40 PR( fundisp -f "time=%13.2f pha=%3d" ...)RP( +You also can specify display formats for individual datatypes using the FITS +binary table TFORM variables as the keywords: +) 1 65 PR( fundisp -f "D=double_format E=float_format J=int_format etc.")RP( +e.g. +) 1 35 PR( fundisp -f "D=%13.2f I=%3d" ...)RP( +The old position-dependent syntax is deprecated. + +)0 P()-1 LI( Fundisp will now print out a single 16-bit \201or 32-bit\202 unsigned +int for a column whose data format is 16X \201or 32X\202, instead of +printing 2 \201or 4\202 unsigned chars. + +)0 P()-1 LI( Fixed bug in which fundisp was not able to display bitfield data for +raw event lists. + +)0 P()-1 LI( Previously, when binning columns used implicitly in a region +and explicitly in a filter could suffer from a case sensitivity problem. +This has been fixed. + +)0 P()-1 LI( Fixed internal mask=all switch on fundisp. + +)0 P()-1 LI( Filter include files now simply include text without changing the state +of the filter. They therefore can be used in expression. That is, if foo1 +contains "pi==1" and foo2 contains "pha==2" then the following expressions +are equivalent: +) 3 57 PR( "[@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]")RP( + +)0 P()-1 LI( Fixed bug in filter specification which caused a SEGV if a varargs-style +region was enclosed in parens. + +)0 P()-1 LI( Updated wcs library to 3.3.2. +)LU( + +)0 2 166 H()WB 252 Sn( Public Release 1.2.0 \20124 March 2003\202)EH( +)UL( +)0 P()-1 LI( BSCALE and BZERO are now always applied to int pixel data, instead of +only being applied if the desired output is floating point. +)LU( + +)0 2 167 H()WB 253 Sn( Beta Release 1.2.b3 \2014 February 2003\202)EH( +)UL( +)0 P()-1 LI( In FunColumnSelect, added the ability to specify an offset into +an array in the type specification, using the extended syntax: +) 1 48 PR( [@][n]<type>[[poff]][:[tlmin[:tlmax[:binsiz]]]])RP( +The [poff] string specifies the offset. For example, a type specification +such as "@I[2]" specifies the third \201i.e., starting from 0\202 element in +the array pointed to by the pointer value. A value of "@2I[4]" specifies +the fifth and sixth values in the array. + +)0 P()-1 LI( Added a non-varargs version of FunColumnSelect called _FunColumnSelect: +) 3 76 PR(int _FunColumnSelect\201Fun fun, int size, char *plist, + char **names, char **types, char **modes, int *offsets, + int nargs\202;)RP( + +)0 P()-1 LI( Added support for sorting binary tables by column name using: +funtable -s "col1 col2 ... coln" ... + +)0 P()-1 LI( Added the FUN_RAW macro which, when applied to the "name" parameter +of FunParamGets\201\202, returns the 80-character raw FITS card instead of +only the value. + +)0 P()-1 LI( Added support for comparing column values with binary masks of the +form 0b[01]+, e.g.: +) 1 23 PR( \201status&0b111\202==0b001)RP( +Previously, such masks had to be specified in decimal, octal, or hex. + +)0 P()-1 LI( Completed support for type 'L' \201logical\202 in fundisp and in filtering of +binary tables. + +)0 P()-1 LI( Fixed bug in funhist that was improperly setting the number of bins +when the data was of type float. + +)0 P()-1 LI( Fixed bug in filter/Makefile where the filter OBJPATH #define was +being passed to the wrong module. +)LU( + +)0 2 168 H()WB 254 Sn( Beta Release 1.2.b2 \2017 October 2002\202)EH( +)UL( +)0 P()-1 LI( Updated wcs library to 3.1.3. + +)0 P()-1 LI( Added support for reading gzip'ed files via stdin. +)LU( + +)0 2 169 H()WB 255 Sn( Beta Release 1.2.b1 \20124 September 2002\202)EH( +)UL( +)0 P()-1 LI( Added the following accelerators to region filtering: +) 8 73 PR( shape: arguments: + ----- --------- + BOX xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn \201angle\202 + BOX xcenter ycenter xwlo yhin xwout yhhi n=[number] \201angle\202 + 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 \201angle\202 + ELLIPSE xcenter ycenter xwlo yhin xwout yhhi n=[number] \201angle\202)RP( + +)0 P()-1 LI( Added the following new pandas \201Pie AND Annulus\202 to region filtering: +) 5 77 PR( shape: arguments: + ----- --------- + CPANDA xcen ycen ang1 ang2 nang irad orad nrad # same as panda + BPANDA xcen ycen ang1 ang2 nang ixlo iylo ixhi iyhi nrad \201ang\202 # box + EPANDA xcen ycen ang1 ang2 nang ixlo iylo ixhi iyhi nrad \201ang\202 # ellipse)RP( + +)0 P()-1 LI( Added support for filtering images using simple FITS image masks, +i.e. 8-bit or 16-bit FITS images where the value of a pixel is the +region id number for that pixel \201and therefore must be greater than +0\202. The image section being filtered must either be the same size as the +mask dimensions or else be an even multiple of the mask. This works with +image-style filtering, i.e., funcnts can utilize a mask on both +images and binary tables. + +)0 P()-1 LI( Added '$n' to fundisp column specification to allow display of +ordinal value of each row passing the filter. + +)0 P()-1 LI( Added code to support region filtering on image sections. + +)0 P()-1 LI( Fixed bugs which prevented filtering more than one ASCII region file. + +)0 P()-1 LI( Fixed bug occasionally causing filter slave processes to become zombies. + +)0 P()-1 LI( Fixed bugs in event filtering: annulus with inner radius of 0 +\201i.e., a circle\202 was rejecting events with coordinates xcen, ycen. +Also, pie with angles of 0 and 360 was rejecting some events. +Image filtering \201e.g. funcnts\202 did not have these problems. + +)0 P()-1 LI( Filters now accept global exclude regions without an include region. +In such a case, the field region is implied. That is, "-circle\201x,y,r\202" +is equivalent to "field; -circle\201x,y,r\202", etc. + +)0 P()-1 LI( Fixed panda so that it can be used as a global exclude. + +)0 P()-1 LI( Allow empty ds9 region file \201comments and globals only\202 to be +a valid filter. Totally ignore zero length region or include file. + +)0 P( +)-1 LI( Fixed funcnts bug that was displaying 0 value as inner radius of +a circle, instead of just one radius value. +)LU( + +)0 2 170 H()WB 256 Sn( Public Release 1.1.0 \20122 April 2002\202)EH( + +)0 P(New features include: +)UL()0 P()-1 LI( Funtools programs now accept gzip'ed files as valid input. + +)0 P()-1 LI( Improved security via replacement of system\201\202 function. + +)0 P()-1 LI( fundisp, funcnts, funhist can output starbase/rdb format \201tabs between columns, form-feeds between tables\202. + +)0 P()-1 LI( Improved support for Windows platform, as well as new support for Mac OSX.)LU( + +)0 2 171 H()WB 257 Sn( Pre-Release 1.1.0e \20110 April 2002\202)EH( +)UL( + +)0 P()-1 LI( Added enough support to skip over variable length arrays in BINTABLES. +We will add full support if this non-standard construct becomes more widely +used. + +)0 P()-1 LI( Fixed bug in underlying fitsy _gread\201\202 routine that was returning +an arbitrary bytes-read value if the input fd was invalid. +)LU( + +)0 2 172 H()WB 258 Sn( Pre-Release 1.1.0e \20119 March 2002\202)EH( +)UL( + +)0 P()-1 LI( Added additional check for Windows/PC to filter/Nan.h. + +)0 P()-1 LI( Upgraded zlib library to 1.1.4 \201fix double free security hole\202. +)LU( + + +)0 2 173 H()WB 259 Sn( Pre-Release 1.1.0e \20127 February 2002\202)EH( +)UL( + +)0 P()-1 LI( Changed filter/process.[ch] to filter/zprocess.[ch] to avoid name +collision with Cygwin include file. + +)0 P()-1 LI( Added -a switch to funhead to display all headers in a FITS file. +)LU( + +)0 2 174 H()WB 260 Sn( Pre-Release 1.1.0e \20111 February 2002\202)EH( +)UL( + +)0 P()-1 LI( Fixed filter parser so that it ignores ds9 "ruler" and "text" markers +only up to the first \200n or ; \201was ignoring to last \200n\202. + +)0 P()-1 LI( The NBLOCK parameter in fitsy/headdata.c was too large for Mac OS X +\201max size of a declared char buf seems to be about .5 Mb\202. +)LU( + +)0 2 175 H()WB 261 Sn( Beta Release 1.0.1b5 \20131 January 2002\202)EH( +)UL( + +)0 P()-1 LI( Fixed bug introduced in calculated IRAF LTM values in 1.0.1b3. + +)0 P()-1 LI( Fixed bug in filter parser giving wrong answers when two range +lists were combined with and explicit boolean operator: +) 1 34 PR( $ fundisp $S"[x=512&&y=511,512]")RP( +incorrectly acted like: +) 1 39 PR( fundisp $S"[\201x=512&&y=511\202||\201y=512\202]")RP( +instead of: +) 1 37 PR( fundisp $S"[x=512&&\201y=511||y=512\202]")RP( +In general, we recommend use of explicit parentheses. + +)0 P()-1 LI( Fixed filter/NaN.h to recognize Compaq Alpha again \201broken by their last change to cc\202. + +)0 P()-1 LI( Removed redundant varargs definitions that conflicted with Alpha compiler definitions. + +)0 P()-1 LI( Added blank line to inc.sed to work around Apple Mac OS X bug in which the +"i" \201insert\202 command was treating final \200\200 as continuation \200 in the text. + +)0 P( +)-1 LI( Added include of mkrtemp.h to mkrtemp.c to get conditional compilation +for Mac OSX. + +)0 P()-1 LI( Added support for --with-zlib to fitsy so that ds9 could use its own +copy of zlib \201and not build the copy in fitsy\202. + +)0 P()-1 LI( Removed config.cache and Makefile files from distribution tar file. +)LU( + +)0 2 176 H()WB 262 Sn( Beta Release 1.0.1b4 \20126 January 2002\202)EH( +)UL( + +)0 P()-1 LI( Make explicit that column filters are not permitted in an image +expression \201such as the funcnts region arguments\202. + +)0 P()-1 LI( Fix bug in region parser in which a region \201without parens\202, +followed immediately by an operator: +) 1 24 PR( circle 512 512 .5&)SY(\160)ES(==1)RP( +was not processing the final argument of the region correctly. + +)0 P()-1 LI( Ignore new "tile" directive in filters \201used by ds9\202. +)LU( + +)0 2 177 H()WB 263 Sn( Beta Release 1.0.1b3 \2014 January 2002\202)EH( +)UL( + +)0 P()-1 LI( Made modifications to Makefile.in to make releases easier. + +)0 P()-1 LI( Added instructions Makefile.in so that funtools.h will always +have correct #defines for FUN_VERSION, FUN_MAJOR_VERSION, +FUN_MINOR_VERSION, and FUN_PATCH_LEVEL. + +)0 P()-1 LI( Allow #include statements in funcalc program files. + +)0 P()-1 LI( funimage now updates all 4 CDX_Y values by the block factor. + +)0 P()-1 LI( Minor changes to make funtools work under darwin \201Mac OS X\202. +)LU( + +)0 2 178 H()WB 264 Sn( Beta Release 1.0.1b2 \20114 November 2001\202)EH( +)UL( + +)0 P()-1 LI( Fixed FunOpen\201\202 bug \201introduced in b1\202 in which filenames without +extensions SEGV'ed on open. Yikes! + +)0 P()-1 LI( Funmerge now extends the tlmin/tlmax values of the output +binning columns so that merged events from widely separated files are +valid in the output table. + +)0 P()-1 LI( In funhist, added -w switch to specify bin width \201lo:hi:width\202 +instead of number of bins \201lo:hi:num\202. Added support for this new +width option in funtools.ds9. + +)0 P()-1 LI( If a tdbin value was set using bincols=\201name:tlmin:tlmax:tdbin, ...\202, +the WCS parameters were not being updated properly. + +)0 P()-1 LI( Cleaned up build support for zlib. +)LU( + +)0 2 179 H()WB 265 Sn( Beta Release 1.0.1b1 \2016 November 2001\202)EH( +)UL( + +)0 P()-1 LI( Added support for gzip'ed files to the underlying fitsy/gio +library. This means that all funtools programs now accept gzip'ed +files as valid input: +) 1 41 PR( funcnts foo.fits.gz "circle 504 512 10")RP( +It is no longer necessary to run gunzip and pipe the results to +stdin of a funtools program. + +)0 P()-1 LI( Funtools tasks are now placed in a sub-menu in the DS9 Analysis +menu, instead of at the top level. + +)0 P()-1 LI( Fixed a bug in funcnts in which the bottom-most pixel of a small +circle or annulus region could be missed when the region is only one +pixel wide for that value of y. + +)0 P()-1 LI( Added -n switch to funhist so that table histograms could be +normalized by the width of the bin \201val/\201hi_edge-lo_edge\202\202. + +)0 P()-1 LI( Added -T switch to fundisp, funcnts, funhist to output in +starbase/rdb format \201uses tabs instead of spaces between columns, +form-feeds between tables, etc.\202 + +)0 P()-1 LI( Fixed a bug in which the field\201\202 region was not being properly +processed in combination with an image section. This could affect +funcnts processing of image data where an image section was specified +\201though it usually resulted in a funcnts error\202. + +)0 P()-1 LI( Fixed bug in display of binary table header for vector columns. + +)0 P()-1 LI( Filters now recognize hex constants \201starting with 0x\202 and long +constants \201ending with L\202. + +)0 P()-1 LI(Filenames containing a ':' are now only treated as sockets if they +actually are in the form of a valid ip:port. + +)0 P()-1 LI(Replaced funtools.ds9 with a new version that calls a new funds9 +script, instead of calling funcnts or funhist directly. The new script +supports gzip'ed files and bracket specifications on filenames at the +same time, which the direct call could not. Also the new script has +better error reporting. + +)0 P()-1 LI( Replaced system\201\202 call used to compile filter and funcalc +expression with a special launch\201\202 call, which performs execvp\201\202 +directly without going through sh. \201launch\201\202 works under DOS and has +fewer security problems.\202 + +)0 P()-1 LI( Fixed image filter code in which the field\201\202 region was being ignored +if it was combined with one or more exclude regions \201and no other include +regions\202, resulting in no valid pixels. + +)0 P()-1 LI( Changed use of getdtable\201\202 to FD_SETSIZE in calls to select\201\202. + +)0 P()-1 LI( Added code to guard against FITS binary tables without proper TFORMx +parameters. + +)0 P()-1 LI( Added support to FunParamGets so that it returns the raw FITS card +if the specified input name is NULL and the input n value is positive. + +)0 P()-1 LI( Fixed bug in underlying fitsy code that set the comment in a +header parameter. +)LU( + + +)0 2 180 H()WB 266 Sn( Public Release 1.0.0 \20131 July 2001\202)EH( +)UL( +)0 P()-1 LI( "a new day with no mistakes ... yet")LU( + +)2 1 1 HR()0 0 1 A(Index to the Funtools Help Pages)0 0 TN TL()Ec /AF f D( +)0 5 181 H(Last)WB 267 Sn( updated: 22 April 2002)EH( +)WB NL +/TE t D NP TU PM 0 eq and{/Pn () D showpage}if end restore |