diff options
Diffstat (limited to 'funtools/man')
47 files changed, 0 insertions, 17807 deletions
diff --git a/funtools/man/man1/funcalc.1 b/funtools/man/man1/funcalc.1 deleted file mode 100644 index b864865..0000000 --- a/funtools/man/man1/funcalc.1 +++ /dev/null @@ -1,622 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funcalc 1" -.TH funcalc 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funcalc \- Funtools calculator (for binary tables) -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfuncalc\fR [\-n] [\-a argstr] [\-e expr] [\-f file] [\-l link] [\-p prog] <iname> [oname [columns]] -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 7 -\& \-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 (don't auto-declare) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBfuncalc\fR is a calculator program that allows arbitrary -expressions to be constructed, compiled, and executed on columns in a -Funtools table (\s-1FITS\s0 binary table or raw event file). It works by -integrating user-supplied expression(s) into a template C program, -then compiling and executing the program. \fBfuncalc\fR expressions -are C statements, although some important simplifications (such -as automatic declaration of variables) are supported. -.PP -\&\fBfuncalc\fR expressions can be specified in three ways: on the -command line using the \fB\-e [expression]\fR switch, in a file using -the \fB\-f [file]\fR switch, or from stdin (if neither \fB\-e\fR nor -\&\fB\-f\fR is specified). Of course a file containing \fBfuncalc\fR -expressions can be read from stdin. -.PP -Each invocation of \fBfuncalc\fR 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 \s-1FITS\s0 file is being created (i.e., in cases where the -\&\fBfuncalc\fR expression only prints values, no output file is -needed). If input and output file are both specified, a third optional -argument can specify the list of columns to activate (using -\&\fIFunColumnActivate()\fR). Note -that \fBfuncalc\fR determines whether or not to generate code for -writing an output file based on the presence or absence of an -output file argument. -.PP -A \fBfuncalc\fR expression executes on each row of a table and -consists of one or more C statements that operate on the columns of -that row (possibly using temporary variables). Within an expression, -reference is made to a column of the \fBcurrent\fR row using the C -struct syntax \fBcur\-\fR[colname]>, 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 \fBfuncalc\fR (to be of type double). Thus, for example, a swap of -columns x and y in a table can be performed using either of the -following equivalent \fBfuncalc\fR expressions: -.PP -.Vb 4 -\& double temp; -\& temp = cur->x; -\& cur->x = cur->y; -\& cur->y = temp; -.Ve -.PP -or: -.PP -.Vb 3 -\& temp = cur->x; -\& cur->x = cur->y; -\& cur->y = temp; -.Ve -.PP -When this expression is executed using a command such as: -.PP -.Vb 1 -\& funcalc \-f swap.expr itest.ev otest.ev -.Ve -.PP -the resulting file will have values of the x and y columns swapped. -.PP -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 \*(L":[dtype]\*(R" 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: -.PP -.Vb 3 -\& temp = cur->x:D; -\& cur->x = cur->y:D; -\& cur->y = temp; -.Ve -.PP -Data type specifiers follow standard \s-1FITS\s0 table syntax for defining -columns using \s-1TFORM:\s0 -.IP "\(bu" 4 -A: \s-1ASCII\s0 characters -.IP "\(bu" 4 -B: unsigned 8-bit char -.IP "\(bu" 4 -I: signed 16-bit int -.IP "\(bu" 4 -U: unsigned 16-bit int (not standard \s-1FITS\s0) -.IP "\(bu" 4 -J: signed 32-bit int -.IP "\(bu" 4 -V: unsigned 32-bit int (not standard \s-1FITS\s0) -.IP "\(bu" 4 -E: 32-bit float -.IP "\(bu" 4 -D: 64-bit float -.IP "\(bu" 4 -X: bits (treated as an array of chars) -.PP -Note that only the first reference to a column should contain the -explicit data type specifier. -.PP -Of course, it is important to handle the data type of the columns -correctly. One of the most frequent cause of error in \fBfuncalc\fR -programming is the implicit use of the wrong data type for a column in -expression. For example, the calculation: -.PP -.Vb 1 -\& dx = (cur->x - cur->y)/(cur->x + cur->y); -.Ve -.PP -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: -.PP -.Vb 1 -\& dx = (cur->x:D - cur->y:D)/(cur->x + cur->y); -.Ve -.PP -Alternatively, it can be done using C type-casting in the expression: -.PP -.Vb 1 -\& dx = ((double)cur->x - (double)cur->y)/((double)cur->x + (double)cur->y); -.Ve -.PP -In addition to accessing columns in the current row, reference also -can be made to the \fBprevious\fR row using \fBprev\-\fR[colname]>, -and to the \fBnext\fR row using \fBnext\-\fR[colname]>. Note that if -\&\fBprev\-\fR[colname]> is specified in the \fBfuncalc\fR -expression, the very first row is not processed. If -\&\fBnext\-\fR[colname]> is specified in the \fBfuncalc\fR -expression, the very last row is not processed. In this way, -\&\fBprev\fR and \fBnext\fR 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 -\&\fBfuncalc\fR expression: -.PP -.Vb 1 -\& fprintf(stdout, "%d %d\en", cur->x, prev->y); -.Ve -.PP -New columns can be specified using the same \fBcur\-\fR[colname]> -syntax by appending the column type (and optional tlmin/tlmax/binsiz -specifiers), 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. -.PP -For example, to create and output a new column that is the average value of the -x and y columns, a new \*(L"avg\*(R" column can be defined: -.PP -.Vb 1 -\& cur->avg:D = (cur->x + cur->y)/2.0 -.Ve -.PP -Note that the final ';' is not required for single-line expressions. -.PP -As with \s-1FITS\s0 \s-1TFORM\s0 data type specification, the column data type -specifier can be preceded by a numeric count to define an array, e.g., -\&\*(L"10I\*(R" means a vector of 10 short ints, \*(L"2E\*(R" means two single precision -floats, etc. A new column only needs to be defined once in a -\&\fBfuncalc\fR expression, after which it can be used without -re-specifying the type. This includes reference to elements of a -column array: -.PP -.Vb 2 -\& cur->avg[0]:2D = (cur->x + cur->y)/2.0; -\& cur->avg[1] = (cur->x - cur->y)/2.0; -.Ve -.PP -The 'X' (bits) data type is treated as a char array of dimension -(numeric_count/8), i.e., 16X is processed as a 2\-byte char array. Each -8-bit array element is accessed separately: -.PP -.Vb 2 -\& cur->stat[0]:16X = 1; -\& cur->stat[1] = 2; -.Ve -.PP -Here, a 16-bit column is created with the \s-1MSB\s0 is set to 1 and the \s-1LSB\s0 set to 2. -.PP -By default, all processed rows are written to the specified output -file. If you want to skip writing certain rows, simply execute the C -\&\*(L"continue\*(R" statement at the end of the \fBfuncalc\fR 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: -.PP -.Vb 4 -\& cur->avg[0]:2D = (cur->x + cur->y)/2.0; -\& cur->avg[1] = (cur->x - cur->y)/2.0; -\& if( cur->avg[0] == cur->x ) -\& continue; -.Ve -.PP -If no output file argument is specified on the \fBfuncalc\fR 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: -.PP -.Vb 5 -\& fpv = (cur->av3:D-cur->av1:D)/(cur->av1+cur->av2:D+cur->av3); -\& fbv = cur->av2/(cur->av1+cur->av2+cur->av3); -\& fpu = ((double)cur->au3-cur->au1)/((double)cur->au1+cur->au2+cur->au3); -\& fbu = cur->au2/(double)(cur->au1+cur->au2+cur->au3); -\& fprintf(stdout, "%f\et%f\et%f\et%f\en", fpv, fbv, fpu, fbu); -.Ve -.PP -In the above example, we use both explicit type specification -(for \*(L"av\*(R" columns) and type casting (for \*(L"au\*(R" columns) to ensure that -all operations are performed in double precision. -.PP -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 \*(L"stdout\*(R" 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. -.PP -In a \s-1FITS\s0 binary table, it sometimes is desirable to copy all of the -other \s-1FITS\s0 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 \fBfuntable\fR for a related example. -.PP -\&\fBfuncalc\fR works by integrating the user-specified expression -into a template C program called tabcalc.c. -The completed program then is compiled and executed. Variable -declarations that begin the \fBfuncalc\fR 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 -\&\fIFunColumnSelect()\fR and used -in \fIFunTableRowGet()\fR. 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. -.PP -Normally, \fBfuncalc\fR expression code is added to -\&\fBfuncalc\fR 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: -.PP -.Vb 3 -\& [directive name] -\& ... code goes here ... -\& end -.Ve -.PP -The directives are: -.IP "\(bu" 4 -\&\fBglobal\fR add code and declarations in global space, before the main routine. -.IP "\(bu" 4 -\&\fBlocal\fR add declarations (and code) just after the local declarations in -main -.IP "\(bu" 4 -\&\fBbefore\fR add code just before entering the main row processing loop -.IP "\(bu" 4 -\&\fBafter\fR add code just after exiting the main row processing loop -.PP -Thus, the following \fBfuncalc\fR expression will declare global -variables and make subroutine calls just before and just after the -main processing loop: -.PP -.Vb 16 -\& global -\& double v1, v2; -\& double init(void); -\& double finish(double v); -\& end -\& before -\& v1 = init(); -\& end -\& ... process rows, with calculations using v1 ... -\& after -\& v2 = finish(v1); -\& if( v2 < 0.0 ){ -\& fprintf(stderr, "processing failed %g -> %g\en", v1, v2); -\& exit(1); -\& } -\& end -.Ve -.PP -Routines such as \fIinit()\fR and \fIfinish()\fR above are passed to the generated -program for linking using the \fB\-l [link directives ...]\fR -switch. The string specified by this switch will be added to the link -line used to build the program (before the funtools library). For -example, assuming that \fIinit()\fR and \fIfinish()\fR are in the library -libmysubs.a in the /opt/special/lib directory, use: -.PP -.Vb 1 -\& funcalc \-l "\-L/opt/special/lib \-lmysubs" ... -.Ve -.PP -User arguments can be passed to a compiled funcalc program using a string -argument to the \*(L"\-a\*(R" switch. The string should contain all of the -user arguments. For example, to pass the integers 1 and 2, use: -.PP -.Vb 1 -\& funcalc \-a "1 2" ... -.Ve -.PP -The arguments are stored in an internal array and are accessed as -strings via the \s-1ARGV\s0(n) macro. For example, consider the following -expression: -.PP -.Vb 3 -\& local -\& int pmin, pmax; -\& end -.Ve -.PP -.Vb 4 -\& before -\& pmin=atoi(ARGV(0)); -\& pmax=atoi(ARGV(1)); -\& end -.Ve -.PP -.Vb 2 -\& if( (cur->pha >= pmin) && (cur->pha <= pmax) ) -\& fprintf(stderr, "%d %d %d\en", cur->x, cur->y, cur->pha); -.Ve -.PP -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: -.PP -.Vb 6 -\& 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 -.Ve -.PP -.Vb 4 -\& funcalc \-a '5 6' \-f foo snr.ev'[cir 512 512 .1]' -\& 512 512 6 -\& 512 512 5 -\& 512 512 5 -.Ve -.PP -Note that it is the user's responsibility to ensure that the correct -number of arguments are passed. The \s-1ARGV\s0(n) macro returns a \s-1NULL\s0 if a -requested argument is outside the limits of the actual number of args, -usually resulting in a \s-1SEGV\s0 if processed blindly. To check the -argument count, use the \s-1ARGC\s0 macro: -.PP -.Vb 4 -\& local -\& long int seed=1; -\& double limit=0.8; -\& end -.Ve -.PP -.Vb 5 -\& before -\& if( ARGC >= 1 ) seed = atol(ARGV(0)); -\& if( ARGC >= 2 ) limit = atof(ARGV(1)); -\& srand48(seed); -\& end -.Ve -.PP -.Vb 1 -\& if ( drand48() > limit ) continue; -.Ve -.PP -The macro \s-1WRITE_ROW\s0 expands to the \fIFunTableRowPut()\fR call that writes -the current row. It can be used to write the row more than once. In -addition, the macro \s-1NROW\s0 expands to the row number currently being -processed. Use of these two macros is shown in the following example: -.PP -.Vb 7 -\& if( cur->pha:I == cur->pi:I ) continue; -\& a = cur->pha; -\& cur->pha = cur->pi; -\& cur->pi = a; -\& cur->AVG:E = (cur->pha+cur->pi)/2.0; -\& cur->NR:I = NROW; -\& if( NROW < 10 ) WRITE_ROW; -.Ve -.PP -If the \fB\-p [prog]\fR switch is specified, the expression is not -executed. Rather, the generated executable is saved with the specified -program name for later use. -.PP -If the \fB\-n\fR 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. (The command can change from -platform to platform because of the use of different libraries, -compiler switches, etc.) -.PP -As mentioned previously, \fBfuncalc\fR will declare a scalar -variable automatically (as a double) if that variable has been used -but not declared. This facility is implemented using a sed script -named funcalc.sed, 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 \s-1SGI\s0 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. -.PP -In order to keep the lexical analysis of \fBfuncalc\fR expressions -(reasonably) 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 (i.e., not in a -\&\fBlocal...end\fR block) will usually end up in the inner loop, not -with the local declarations: -.PP -.Vb 8 -\& /* this comment will end up in the wrong place (i.e, inner loop) */ -\& double a; /* also in wrong place */ -\& /* this will be in the the right place (inner loop) */ -\& if( cur->x:D == cur->y:D ) continue; /* also in right place */ -\& a = cur->x; -\& cur->x = cur->y; -\& cur->y = a; -\& cur->avg:E = (cur->x+cur->y)/2.0; -.Ve -.PP -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. -.PP -Because \fBfuncalc\fR must analyze the user expression using the data -file(s) passed on the command line, the input file(s) 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: \fBfuncalc\fR cannot be used as a filter. We will -consider removing this restriction at a later time. -.PP -Along with C comments, \fBfuncalc\fR expressions can have one-line -internal comments that are not passed on to the generated C -program. These internal comment start with the \fB#\fR character and -continue up to the new\-line: -.PP -.Vb 7 -\& 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 = (cur->x+cur->y)/2.0; -.Ve -.PP -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 (and therefore not -implicitly specified as a column to be read). To ensure that such a -column is read by the event loop, use the \fBexplicit\fR 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: -.PP -.Vb 1 -\& explicit pi pha -.Ve -.PP -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 \fBexplicit\fR -statement can be placed anywhere. -.PP -Finally, note that \fBfuncalc\fR currently works on expressions -involving \s-1FITS\s0 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. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/funcen.1 b/funtools/man/man1/funcen.1 deleted file mode 100644 index d8c1b28..0000000 --- a/funtools/man/man1/funcen.1 +++ /dev/null @@ -1,250 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funcen 1" -.TH funcen 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funcen \- find centroid (for binary tables) -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfuncen\fR [\-i] [\-n iter] [\-t tol] [\-v lev] <iname> <region> -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 4 -\& \-i # use image filtering (default: event filtering) -\& \-n iter # max number of iterations (default: 0) -\& \-t tol # pixel tolerance distance (default: 1.0) -\& \-v [0,1,2,3] # output verbosity level (default: 0) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBfuncen\fR iteratively calculates the centroid position within one -or more regions of a Funtools table (\s-1FITS\s0 binary table or raw event -file). 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 (and, where -available, \s-1WCS\s0 position). -.PP -The first argument to the program specifies the Funtools table file to -process. Since the file must be read repeatedly, a value of \*(L"stdin\*(R" -is not permitted when the number of iterations is non\-zero. Use -Funtools Bracket Notation to specify \s-1FITS\s0 -extensions and filters. -.PP -The second required argument is the initial region descriptor. Multiple -regions are permitted. However, compound regions (accelerators, -variable argument regions and regions connected via boolean algebra) -are not permitted. Points and polygons also are illegal. These -restrictions might be lifted in a future version, if warranted. -.PP -The \fB\-n\fR (iteration number) 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(s). -Note that when iterations is 0, the data can be input via stdin. -.PP -The \fB\-t\fR (tolerance) 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. -.PP -The \fB\-v\fR (verbosity) 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: -.PP -.Vb 1 -\& counts x y [ra dec coordsys] -.Ve -.PP -The last 3 \s-1WCS\s0 values are output if \s-1WCS\s0 information is available in the -data file header. Thus, for example: -.PP -.Vb 2 -\& [sh] funcen \-n 0 snr.ev "cir 505 508 5" -\& 915 505.00 508.00 345.284038 58.870920 j2000 -.Ve -.PP -.Vb 2 -\& [sh] funcen \-n 3 snr.ev "cir 505 508 5" -\& 1120 504.43 509.65 345.286480 58.874587 j2000 -.Ve -.PP -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 \*(L"best\*(R" position. -.PP -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: -.PP -.Vb 5 -\& [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 -.Ve -.PP -.Vb 4 -\& events: 1120 -\& x,y(physical): 504.43 509.65 -\& ra,dec(j2000): 345.286480 58.874587 -\& final_region1: cir 504.43 509.65 5 -.Ve -.PP -Level 2 outputs results from intermediate calculations as well. -.PP -Ordinarily, region filtering is performed using analytic (event) -filtering, i.e. that same style of filtering as is performed by -\&\fBfundisp\fR and \fBfuntable\fR. Use the \fB\-i\fR switch to specify image -filtering, i.e. the same style filtering as is performed by \fBfuncnts\fR. -Thus, you can perform a quick calculation of counts in regions, using -either the analytic or image filtering method, by specifying the - \fB\-n 0\fR and optional \fB\-i\fR switches. These two method often -give different results because of how boundary events are processed: -.PP -.Vb 2 -\& [sh] funcen snr.ev "cir 505 508 5" -\& 915 505.00 508.00 345.284038 58.870920 j2000 -.Ve -.PP -.Vb 2 -\& [sh] funcen \-i snr.ev "cir 505 508 5" -\& 798 505.00 508.00 345.284038 58.870920 j2000 -.Ve -.PP -See Region Boundaries for more information -about how boundaries are calculated using these two methods. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/funcnts.1 b/funtools/man/man1/funcnts.1 deleted file mode 100644 index 0af4b73..0000000 --- a/funtools/man/man1/funcnts.1 +++ /dev/null @@ -1,806 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funcnts 1" -.TH funcnts 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funcnts \- count photons in specified regions, with bkgd subtraction -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfuncnts\fR [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_value] -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 16 -\& \-e "source_exposure[;bkgd_exposure]" -\& # source (bkgd) FITS exposure image using matching files -\& \-w "source_exposure[;bkgd_exposure]" -\& # source (bkgd) FITS exposure image using WCS transform -\& \-t "source_timecorr[;bkgd_timecorr]" -\& # source (bkgd) time correction value or header parameter name -\& \-g # output using nice g format -\& \-G # output using %.14g format (maximum precision) -\& \-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 (and angles) for annuli (and pandas) -\& \-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 -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBfuncnts\fR counts photons in the specified source regions and -reports the results for each region. Regions are specified using the -Spatial Region Filtering mechanism. -Photons are also counted in the specified bkgd regions applied to the -same data file or a different data file. (Alternatively, a constant -background value in counts/pixel**2 can be specified.) 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 (cnts/area**2) calculated for -each region. -.PP -The first argument to the program specifies the \s-1FITS\s0 input image, array, or -raw event file to process. If \*(L"stdin\*(R" is specified, data are read from -the standard input. Use Funtools Bracket -Notation to specify \s-1FITS\s0 extensions, image sections, and filters. -.PP -The optional second argument is the source region descriptor. If no -region is specified, the entire field is used. -.PP -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 -(i.e., no background). -.PP -In summary, the following command arguments are valid: -.PP -.Vb 5 -\& [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 -.Ve -.PP -\&\s-1NB:\s0 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 (i.e. use it simply as a -filter) 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 \fIfield()\fR is the -default source region. This rarely is the desired behavior. On the -other hand, with \s-1FITS\s0 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. -.PP -For example, to extract the counts within a radius of 22 pixels from the -center of the \s-1FITS\s0 binary table snr.ev and subtract the background determined -from the same image within an annulus of radii 50\-100 pixels: -.PP -.Vb 10 -\& [sh] funcnts snr.ev "circle(502,512,22)" "annulus(502,512,50,100)" -\& # 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 -.Ve -.PP -.Vb 4 -\& # 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 -.Ve -.PP -.Vb 4 -\& # the following source and background components were used: -\& source region(s) -\& ---------------- -\& circle(502,512,22) -.Ve -.PP -.Vb 3 -\& reg counts pixels -\& ---- ------------ --------- -\& 1 4382.000 1513 -.Ve -.PP -.Vb 3 -\& background region(s) -\& -------------------- -\& annulus(502,512,50,100) -.Ve -.PP -.Vb 3 -\& reg counts pixels -\& ---- ------------ --------- -\& all 8656.000 23572 -.Ve -.PP -The area units for the output columns labeled \*(L"area\*(R", \*(L"surf_bri\*(R" -(surface brightness) and \*(L"surf_err\*(R" will be given either in -arc-seconds (if appropriate \s-1WCS\s0 information is in the data file -header(s)) or in pixels. If the data file has \s-1WCS\s0 info, but you do not -want arc-second units, use the \fB\-p\fR switch to force output in -pixels. Also, regions having zero area are not normally included in -the primary (background\-subtracted) 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 \fB\-z\fR switch. -.PP -Note that a simple sed command will extract the background-subtracted results -for further analysis: -.PP -.Vb 3 -\& [sh] cat funcnts.sed -\& 1,/---- .*/d -\& /^$/,$d -.Ve -.PP -.Vb 2 -\& [sh] sed \-f funcnts.sed funcnts.out -\& 1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001 -.Ve -.PP -If separate source and background files are specified, \fBfuncnts\fR 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 \s-1WCS\s0 information is contained in -both files (e.g. degrees/pixel values in \s-1CDELT\s0). 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. -.PP -Normally, if more than one background region is specified, \fBfuncnts\fR -will combine them all into a single region and use this background -region to produce the background-subtracted results for each source -region. The \fB\-m\fR (match multiple backgrounds) switch tells -\&\fBfuncnts\fR 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: -.PP -.Vb 10 -\& [sh] funcnts snr.ev "annulus(502,512,0,22,n=2)" "annulus(502,512,50,100,n=2)" -\& # 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 -.Ve -.PP -.Vb 5 -\& # 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 -.Ve -.PP -.Vb 4 -\& # the following source and background components were used: -\& source region(s) -\& ---------------- -\& annulus(502,512,0,22,n=2) -.Ve -.PP -.Vb 4 -\& reg counts pixels -\& ---- ------------ --------- -\& 1 3238.000 373 -\& 2 1144.000 1140 -.Ve -.PP -.Vb 3 -\& background region(s) -\& -------------------- -\& annulus(502,512,50,100,n=2) -.Ve -.PP -.Vb 3 -\& reg counts pixels -\& ---- ------------ --------- -\& all 8656.000 23572 -.Ve -.PP -Note that the basic region filter rule \*(L"each photon is counted once -and no photon is counted more than once\*(R" still applies when using The -\&\fB\-m\fR 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. -.PP -Using the \fB\-m\fR switch causes \fBfuncnts\fR to use each of the two -background regions independently with each of the two source regions: -.PP -.Vb 10 -\& [sh] funcnts \-m snr.ev "annulus(502,512,0,22,n=2)" "ann(502,512,50,100,n=2)" -\& # 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 -.Ve -.PP -.Vb 5 -\& # 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 -.Ve -.PP -.Vb 4 -\& # the following source and background components were used: -\& source region(s) -\& ---------------- -\& annulus(502,512,0,22,n=2) -.Ve -.PP -.Vb 4 -\& reg counts pixels -\& ---- ------------ --------- -\& 1 3238.000 373 -\& 2 1144.000 1140 -.Ve -.PP -.Vb 3 -\& background region(s) -\& -------------------- -\& ann(502,512,50,100,n=2) -.Ve -.PP -.Vb 4 -\& reg counts pixels -\& ---- ------------ --------- -\& 1 3975.000 9820 -\& 2 4681.000 13752 -.Ve -.PP -Note that most floating point quantities are displayed using \*(L"f\*(R" -format. You can change this to \*(L"g\*(R" format using the \fB\-g\fR -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 \fB\-G\fR, which outputs -all floating values as %.14g. -.PP -When counting photons using the annulus and panda (pie and annuli) -shapes, it often is useful to have access to the radii (and panda -angles) for each separate region. The \fB\-r\fR switch will add radii -and angle columns to the output table: -.PP -.Vb 12 -\& [sh] funcnts \-r snr.ev "annulus(502,512,0,22,n=2)" "ann(502,512,50,100,n=2)" -\& # 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 -.Ve -.PP -.Vb 5 -\& # 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 -.Ve -.PP -.Vb 4 -\& # the following source and background components were used: -\& source region(s) -\& ---------------- -\& annulus(502,512,0,22,n=2) -.Ve -.PP -.Vb 4 -\& reg counts pixels -\& ---- ------------ --------- -\& 1 3238.000 373 -\& 2 1144.000 1140 -.Ve -.PP -.Vb 3 -\& background region(s) -\& -------------------- -\& ann(502,512,50,100,n=2) -.Ve -.PP -.Vb 3 -\& reg counts pixels -\& ---- ------------ --------- -\& all 8656.000 23572 -.Ve -.PP -Radii are given in units of pixels or arc-seconds (depending on the -presence of \s-1WCS\s0 info), while the angle values (when present) are in -degrees. These columns can be used to plot radial profiles. For -example, the script \fBfuncnts.plot\fR in the funtools -distribution) will plot a radial profile using gnuplot (version 3.7 or -above). A simplified version of this script is shown below: -.PP -.Vb 1 -\& #!/bin/sh -.Ve -.PP -.Vb 37 -\& 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( $1 == "#" && $2 == "data" && $3 == "file:" ){ -\& if( FILES != "" ) FILES = FILES "," -\& FILES = FILES $4 -\& } -\& else if( $1 == "#" && $2 == "radii:" ){ -\& XLABEL = $3 -\& } -\& else if( $1 == "#" && $2 == "surf_bri:" ){ -\& YLABEL = $3 -\& } -\& else if( $1 == "----" ){ -\& printf "set nokey; set title \e"funcnts(%s)\e"\en", FILES -\& printf "set xlabel \e" radius(%s)\e"\en", XLABEL -\& printf "set ylabel \e"surf_bri(%s)\e"\en", YLABEL -\& print "plot \e"-\e" using 3:4:6:7:8 with boxerrorbars" -\& HEADER = 0 -\& DATA = 1 -\& next -\& } -\& } -\& DATA==1{ -\& if( NF == 12 ){ -\& print $9, $10, ($9+$10)/2, $7, $8, $7-$8, $7+$8, $10-$9 -\& } -\& else{ -\& exit -\& } -\& } -\& ' | gnuplot \-persist - 1>/dev/null 2>&1 -.Ve -.PP -.Vb 34 -\& elif [ x"$1" = xds9 ]; then -\& awk ' -\& BEGIN{HEADER=1; DATA=0; XLABEL="unknown"; YLABEL="unknown"} -\& HEADER==1{ -\& if( $1 == "#" && $2 == "data" && $3 == "file:" ){ -\& if( FILES != "" ) FILES = FILES "," -\& FILES = FILES $4 -\& } -\& else if( $1 == "#" && $2 == "radii:" ){ -\& XLABEL = $3 -\& } -\& else if( $1 == "#" && $2 == "surf_bri:" ){ -\& YLABEL = $3 -\& } -\& else if( $1 == "----" ){ -\& printf "funcnts(%s) radius(%s) surf_bri(%s) 3\en", FILES, XLABEL, YLABEL -\& HEADER = 0 -\& DATA = 1 -\& next -\& } -\& } -\& DATA==1{ -\& if( NF == 12 ){ -\& print $9, $7, $8 -\& } -\& else{ -\& exit -\& } -\& } -\& ' -\& else -\& echo "funcnts \-r ... | funcnts.plot [ds9|gnuplot]" -\& exit 1 -\& fi -.Ve -.PP -Thus, to run \fBfuncnts\fR and plot the results using gnuplot (version 3.7 -or above), use: -.PP -.Vb 1 -\& funcnts \-r snr.ev "annulus(502,512,0,50,n=5)" ... | funcnts.plot gnuplot -.Ve -.PP -The \fB\-s\fR (sum) switch causes \fBfuncnts\fR to produce an -additional table of summed (integrated) background subtracted values, -along with the default table of individual values: -.PP -.Vb 10 -\& [sh] funcnts \-s snr.ev "annulus(502,512,0,50,n=5)" "annulus(502,512,50,100)" -\& # 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 -.Ve -.PP -.Vb 8 -\& # 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 -.Ve -.PP -.Vb 8 -\& # 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 -.Ve -.PP -.Vb 4 -\& # the following source and background components were used: -\& source region(s) -\& ---------------- -\& annulus(502,512,0,50,n=5) -.Ve -.PP -.Vb 7 -\& 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 -.Ve -.PP -.Vb 3 -\& background region(s) -\& -------------------- -\& annulus(502,512,50,100) -.Ve -.PP -.Vb 3 -\& reg counts pixels -\& ---- ------------ --------- -\& all 8656.000 23572 -.Ve -.PP -The \fB\-t\fR and \fB\-e\fR 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: -.PP -.Vb 4 -\& 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 -.Ve -.PP -.Vb 4 -\& B= Raw Counts in Background Region -\& Ab= Area of Background Region -\& Tb= (Exposure) time for Background Data -\& Eb= Average exposure in Background Region, from exposure map -.Ve -.PP -Then, Net Counts in Source region is -.PP -.Vb 1 -\& Net= C - B * (Ac*Tc*Ec)/(Ab*Tb*Eb) -.Ve -.PP -with the standard propagation of errors for the Error on Net. -The net rate would then be -.PP -.Vb 1 -\& Net Rate = Net/(Ac*Tc*Ec) -.Ve -.PP -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 (e.g., block 4 means that each -exposure pixel contains 4x4 pixels at full resolution) and -\&\fBfuncnts\fR will deal with the blocking automatically. Using the -\&\fB\-e\fR switch, you can supply both source and background exposure -files (separated by \*(L";\*(R"), 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, \fBfuncnts\fR 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. -.PP -\&\s-1NB:\s0 The \fB\-e\fR switch assumes that the exposure map overlays the -image file \fBexactly\fR, 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, \fBdo not use\fR the \fB\-e\fR exposure -correction. In this case, it still is possible to perform exposure -correction \fBif\fR both the image and the exposure map have valid -\&\s-1WCS\s0 information: use the \fB\-w\fR switch so that the transformation -from image pixel to exposure pixel uses the \s-1WCS\s0 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 \fB\-w\fR can increase the time -required to process the exposure correction considerably. -.PP -A time correction can be applied to both source and -background data using the \fB\-t\fR switch. The value for the correction can -either be a numeric constant or the name of a header parameter in -the source (or background) file: -.PP -.Vb 2 -\& [sh] funcnts \-t 23.4 ... # number for source -\& [sh] funcnts \-t "LIVETIME;23.4" ... # param for source, numeric for bkgd -.Ve -.PP -When a time correction is specified, it is applied to the net counts -as well (see algorithm above), so that the units of surface brightness -become cnts/area**2/sec. -.PP -The \fB\-i\fR (interval) switch is used to run \fBfuncnts\fR on multiple -column-based intervals with only a single pass through the data. It is -equivalent to running \fBfuncnts\fR several times with a different column -filter added to the source and background data each time. For each -interval, the full \fBfuncnts\fR output is generated, with a linefeed -character (^L) 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. -.PP -Two formats are supported for interval specification. The most general -format is semi-colon-delimited list of filters to be used as intervals: -.PP -.Vb 1 -\& funcnts \-i "pha=1:5;pha=6:10;pha=11:15" snr.ev "circle(502,512,22)" ... -.Ve -.PP -Conceptually, this will be equivalent to running \fBfuncnts\fR three times: -.PP -.Vb 3 -\& funcnts snr.ev'[pha=1:5]' "circle(502,512,22)" -\& funcnts snr.ev'[pha=6:10]' "circle(502,512,22)" -\& funcnts snr.ev'[pha=11:15]' "circle(502,512,22)" -.Ve -.PP -However, using the \fB\-i\fR switch will require only one pass through -the data. -.PP -Note that complex filters can be used to specify intervals: -.PP -.Vb 1 -\& funcnts \-i "pha=1:5&&pi=4;pha=6:10&&pi=5;pha=11:15&&pi=6" snr.ev ... -.Ve -.PP -The program simply runs the data through each filter in turn and generates -three \fBfuncnts\fR outputs, separated by the line-feed character. -.PP -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 -\&\*(L"interval\*(R" filter have to be related to another. For example: -.PP -.Vb 1 -\& funcnts \-i "pha=1:5;pi=6:10;energy=11:15" snr.ev "circle(502,512,22)" ... -.Ve -.PP -is equivalent to running \fBfuncnts\fR three times with unrelated filter -specifications. -.PP -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: -.PP -.Vb 1 -\& funcnts \-i "pha;1:5;6:10;11:15" snr.ev "circle(502,512,22)" ... -.Ve -.PP -This is equivalent to the first example, but requires less typing. The -\&\fBfuncnts\fR program will simply prepend \*(L"pha=\*(R" before each of the specified -intervals. (Note that this format does not contain the \*(L"=\*(R" character in -the column argument.) -.PP -Ordinarily, when \fBfuncnts\fR is run on a \s-1FITS\s0 binary table (or a -raw event table), one integral count is accumulated for each row -(event) contained within a given region. The \fB\-v \*(L"scol[;bcol]\*(R"\fR -(value column) 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. -.PP -If the \fB\-T\fR (rdb table) 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. -.PP -Finally, note that \fBfuncnts\fR is an image program, even though it -can be run directly on \s-1FITS\s0 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 \fBfuncnts\fR can differ from the number of events found -using row-filter programs such as \fBfundisp\fR or \fBfuntable\fR -For more information about these difference, see the discussion of -Region Boundaries. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/funcone.1 b/funtools/man/man1/funcone.1 deleted file mode 100644 index d22356c..0000000 --- a/funtools/man/man1/funcone.1 +++ /dev/null @@ -1,285 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'\-1'\(ga -. ds D- D\h'\-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funcone 1" -.TH funcone 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funcone \- cone search of a binary table containing RA, Dec columns -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfuncone\fR <switches> <iname> <oname> <ra[hdr]> <dec[hdr]> <radius[dr'"]> [columns] -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 9 -\& \-d deccol:[hdr] # Dec column name, units (def: DEC:d) -\& \-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 (def: RA:h) -\& \-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 -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Funcone performs a cone search on the \s-1RA\s0 and Dec columns of a \s-1FITS\s0 -binary table. The distance from the center \s-1RA\s0, Dec position to the \s-1RA\s0, -Dec in each row in the table is calculated. Rows whose distance is -less than the specified radius are output. -.PP -The first argument to the program specifies the \s-1FITS\s0 file, raw event -file, or raw array file. If \*(L"stdin\*(R" is specified, data are read from -the standard input. Use Funtools Bracket -Notation to specify \s-1FITS\s0 extensions, and filters. The second -argument is the output \s-1FITS\s0 file. If \*(L"stdout\*(R" is specified, the \s-1FITS\s0 -binary table is written to the standard output. -.PP -The third and fourth required arguments are the \s-1RA\s0 and Dec center -position. By default, \s-1RA\s0 is specified in hours while Dec is specified -in degrees. You can change the units of either of these by appending -the character \*(L"d\*(R" (degrees), \*(L"h\*(R" (hours) or \*(L"r\*(R" (radians). Sexagesimal -notation is supported, with colons or spaces separating hms and dms. -(When using spaces, please ensure that the entire string is quoted.) -.PP -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 \*(L"d\*(R" (degrees), \*(L"r\*(R" (radians), \*(L"'\*(R" (arc minutes) or -\&'"' (arc seconds). -.PP -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: -.PP -.Vb 1 -\& "column1 column1 ... columnN" -.Ve -.PP -A seventh argument allows you to output selected columns from the list -file when \fB\-j\fR switch is used. Note that the \s-1RA\s0 and Dec columns -used in the cone calculation must not be de\-selected. -.PP -Also by default, the \s-1RA\s0 and Dec column names are named \*(L"\s-1RA\s0\*(R" and \*(L"Dec\*(R", -and are given in units of hours and degrees respectively. You can -change both the name and the units using the \-r [\s-1RA\s0] and/or \-d [Dec] -switches. Once again, one of \*(L"h\*(R", \*(L"d\*(R", or \*(L"r\*(R" is appended to the -column name to specify units but in this case, there must be a colon \*(L":\*(R" -between the name and the unit specification. -.PP -If the \fB\-l [listfile]\fR switch is used, then one or more of the -center \s-1RA\s0, center Dec, and radius can be taken from a list file (which -can be a \s-1FITS\s0 table or an \s-1ASCII\s0 column text file). In this case, the -third (center \s-1RA\s0), fourth (center Dec), and fifth (radius) command -line arguments can either be a column name in the list file (if that -parameter varies) or else a numeric value (if that parameter is -static). When a column name is specified for the \s-1RA\s0, Dec, or radius, -you can append a colon followed by \*(L"h\*(R", \*(L"d\*(R", or \*(L"r\*(R" to specify units -(also ' and " for radius). The cone search algorithm is run once for -each row in the list, taking \s-1RA\s0, Dec, and radius values from the -specified columns or from static numeric values specified on the -command line. -.PP -When using a list, all valid rows from each iteration are written to a -single output file. Use the \fB\-x\fR switch to help delineate which -line of the list file was used to produce the given output row(s). -This switch causes the values for the center \s-1RA\s0, Dec, radius, and row -number to be appended to the output file, in columns called \s-1RA_CEN\s0, -\&\s-1DEC_CEN\s0, \s-1RAD_CEN\s0 and \s-1CONE_KEY\s0, respectively. Alternatively, the -\&\fB\-j\fR (join) switch will append all columns from the list row to -the output row (essentially a join of the list row and input row), -along with the \s-1CONE_KEY\s0 row number. These two switches are mutually -exclusive. -.PP -The \fB\-X\fR and \fB\-J\fR 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 \s-1CONE_KEY\s0 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. -.PP -The \fB\-L\fR switch acts similarly to the \fB\-l\fR 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 \s-1CONE_KEY\s0 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. -.PP -If any of \*(L"all row\*(R" switches (\fB\-X\fR, \fB\-J\fR, or \fB\-L\fR) are -specified, then a new column named \s-1JSTAT\s0 is added to the output table. -The positive values in this column indicate the center position row number -(starting from 1) 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. -.PP -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 \fB\-n\fR -switch to see if this speeds up the processing (especially useful when -processing a large list of positions). -.PP -For example, the default cone search uses columns \*(L"\s-1RA\s0\*(R" and \*(L"Dec\*(R" in hours -and degrees (respectively) and \s-1RA\s0 position in hours, Dec and radius in degrees: -.PP -.Vb 1 -\& funone in.fits out.fits 23.45 34.56 0.01 -.Ve -.PP -To specify the \s-1RA\s0 position in degrees: -.PP -.Vb 1 -\& funcone in.fits out.fits 23.45d 34.56 0.01 -.Ve -.PP -To get \s-1RA\s0 and Dec from a list but use a static value for radius (and -also write identifying info for each row in the list): -.PP -.Vb 1 -\& funcone \-x \-l list.txt in.fits out.fits MYRA MYDec 0.01 -.Ve -.PP -User specified columns in degrees, \s-1RA\s0 position in hours (sexagesimal -notation), Dec position in degrees (sexagesimal notation) and radius -in arc minutes: -.PP -.Vb 1 -\& funcone \-r myRa:d \-d myDec in.fits out.fits 12:30:15.5 30:12 15' -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/fundisp.1 b/funtools/man/man1/fundisp.1 deleted file mode 100644 index 21d1e87..0000000 --- a/funtools/man/man1/fundisp.1 +++ /dev/null @@ -1,589 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "fundisp 1" -.TH fundisp 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -fundisp \- display data in a Funtools data file -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfundisp\fR [\-f format] [\-l] [\-n] [\-T] <iname> [columns|bitpix=n] -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 5 -\& \-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 (def: space) -\& \-T # output in rdb/starbase format (tab separators) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBfundisp\fR displays the data in the specified -\&\s-1FITS\s0 Extension -and/or -Image Section -of a \s-1FITS\s0 file, or in a -Section -of a non-FITS array or raw event file. -.PP -The first argument to the program specifies the \s-1FITS\s0 input image, array, or -raw event file to display. If \*(L"stdin\*(R" is specified, data are read from -the standard input. Use Funtools Bracket -Notation to specify \s-1FITS\s0 extensions, image sections, and filters. -.PP -If the data being displayed are columns (either in a \s-1FITS\s0 binary table -or a raw event file), the individual rows are listed. Filters can be -added using bracket notation. Thus: -.PP -.Vb 13 -\& [sh] fundisp "test.ev[time-(int)time>.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 -.Ve -.PP -[\s-1NB:\s0 The \s-1FITS\s0 binary table test file test.ev, as well as the \s-1FITS\s0 -image test.fits, are contained in the funtools funtest directory.] -.PP -When a table is being displayed using \fBfundisp\fR, a second optional -argument can be used to specify the columns to display. For example: -.PP -.Vb 12 -\& [sh] fundisp "test.ev[time-(int)time>=.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 -.Ve -.PP -The special column \fB$REGION\fR can be specified to display the -region id of each row: -.PP -.Vb 12 -\& [sh $] fundisp "test.ev[time-(int)time>=.99&&annulus(0 0 0 10 n=3)]" '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 -.Ve -.PP -Here only rows with the proper fractional time and whose position also is -within one of the three annuli are displayed. -.PP -Columns can be excluded from display using a minus sign before the -column: -.PP -.Vb 12 -\& [sh $] fundisp "test.ev[time-(int)time>=.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 -.Ve -.PP -All columns except the time column are displayed. -.PP -The special column \fB$N\fR can be specified to display the -ordinal value of each row. Thus, continuing the previous example: -.PP -.Vb 12 -\& fundisp "test.ev[time-(int)time>=.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 -.Ve -.PP -Note that the column specification is enclosed in single quotes to protect -\&'$n' from begin expanded by the shell. -.PP -In general, the rules for activating and de-activating columns are: -.IP "\(bu" 4 -If only exclude columns are specified, then all columns but -the exclude columns will be activated. -.IP "\(bu" 4 -If only include columns are specified, then only the specified columns -are activated. -.IP "\(bu" 4 -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. -.PP -In addition to specifying columns names explicitly, the special -symbols \fB+\fR and \fB\-\fR can be used to activate and -de-activate \fBall\fR columns. This is useful if you want to -activate the \f(CW$REGION\fR column along with all other columns. According -to the rules, the syntax \*(L"$REGION\*(R" only activates the region column -and de-activates the rest. Use \*(L"+ \f(CW$REGION\fR\*(R" to activate all -columns as well as the region column. -.PP -If the data being displayed are image data (either in a \s-1FITS\s0 primary -image, a \s-1FITS\s0 image extension, or an array file), 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 \s-1BSCALE\s0 and \s-1BZERO\s0 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: -.PP -.Vb 1 -\& bitpix=n -.Ve -.PP -where n is 8,16,32,\-32,\-64, for unsigned char, short, int, float and double, -respectively. -.PP -Of course, running \fBfundisp\fR on anything but the smallest image -usually results in a display whose size makes it unreadable. -Therefore, one can uses bracket notation (see below) -to apply section and/or blocking to the image before generating a -display. For example: -.PP -.Vb 9 -\& [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 -.Ve -.PP -Note that is is possible to display a \s-1FITS\s0 binary table as an image -simply by passing the table through \fBfunimage\fR first: -.PP -.Vb 9 -\& [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 -.Ve -.PP -If the \fB\-l\fR (list) switch is used, then an image is displayed as a -list containing the columns: X, Y, \s-1VAL\s0. For example: -.PP -.Vb 33 -\& 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 -\& 5 7 1.00 -\& 6 7 1.00 -.Ve -.PP -If the \fB\-n\fR (nohead) switch is used, then no header is output for -tables. This is useful, for example, when fundisp output is being -directed into gnuplot. -.PP -The \fBfundisp\fR program uses a default set of display formats: -.PP -.Vb 10 -\& 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" -.Ve -.PP -Thus, the default display of 1 double and 2 shorts gives: -.PP -.Vb 1 -\& [sh] fundisp snr.ev "time x y" -.Ve -.PP -.Vb 5 -\& TIME X Y -\& --------------------- -------- -------- -\& 79494546.56818075 546 201 -\& 79488769.94469175 548 201 -\& ... -.Ve -.PP -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 (in which case -the associated format pertains only to that column) or \s-1FITS\s0 table -\&\s-1TFORM\s0 specifiers (in which case the format pertains to all columns -having that data type). For example, you can change the double and -short formats for all columns like this: -.PP -.Vb 1 -\& [sh] fundisp \-f "D=%22.11f I=%3d" snr.ev "time x y" -.Ve -.PP -.Vb 5 -\& TIME X Y -\& ---------------------- --- --- -\& 79494546.56818075478 546 201 -\& 79488769.94469174743 548 201 -\& ... -.Ve -.PP -Alternatively, you can change the format of the time and x columns like this: -.PP -.Vb 1 -\& [sh] fundisp \-f "time=%22.11f x=%3d" snr.ev "time x y" -.Ve -.PP -.Vb 5 -\& TIME X Y -\& ---------------------- --- -------- -\& 79494546.56818075478 546 201 -\& 79488769.94469174743 548 201 -\& ... -.Ve -.PP -Note that there is a potential conflict if a column has the same name -as one of the \s-1TFORM\s0 specifiers. In the examples above, the the \*(L"X\*(R" -column in the table has the same name as the X (bit) datatype. To -resolve this conflict, the format string is processed such that -\&\s-1TFORM\s0 datatype specifiers are checked for first, using a -case-sensitive comparison. If the specified format value is not an -upper case \s-1TFORM\s0 value, then a case-insensitive check is made on the -column name. This means that, in the examples above, \*(L"X=%3d\*(R" will refer -to the X (bit) datatype, while \*(L"x=%3d\*(R" will refer to the X column: -.PP -.Vb 1 -\& [sh] fundisp \-f "X=%3d" snr.ev "x y" -.Ve -.PP -.Vb 5 -\& X Y -\& -------- -------- -\& 546 201 -\& 548 201 -\& ... -.Ve -.PP -.Vb 1 -\& [sh] fundisp \-f "x=%3d" snr.ev "x y" -.Ve -.PP -.Vb 5 -\& X Y -\& --- -------- -\& 546 201 -\& 548 201 -\& ... -.Ve -.PP -As a rule, therefore, it is best always to specify the column name in -lower case and \s-1TFORM\s0 data types in upper case. -.PP -The \fB\-f [format]\fR will change the format for a single execution -of fundisp. You also can use the \fB\s-1FUN_FORMAT\s0\fR 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 \fB\-f\fR switch. This global value can be overridden in -individual cases by use of the \fB\-f [format]\fR switch. -.PP -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 (on the left) if the -format width is less than the length of the name. However, truncation -is not performed if the output is in \s-1RDB\s0 format (using the \-T switch). -.PP -[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: -.PP -.Vb 1 -\& double float int short byte string bit. -.Ve -.PP -This order of the list is based on the assumption that people generally -will want to change the float formats. -.PP -If \*(L"\-\*(R" 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., \*(L"%6d\*(R" and -\&\*(L"%\-6d\*(R" are legal, \*(L"%d\*(R" is not legal. -.PP -By using \-f [format], you can change the double and short formats like this: -.PP -.Vb 1 -\& [sh] fundisp \-f "22.11f - - 3d" snr.ev "time x y" -.Ve -.PP -.Vb 5 -\& TIME X Y -\& ---------------------- --- --- -\& 79494546.56818075478 546 201 -\& 79488769.94469174743 548 201 -\& ... -.Ve -.PP -\&\s-1NB:\s0 This format is deprecated and will be removed in a future release.] -.PP -The \fB\-F[c]\fR switch can be used to specify a (single\-character) -column separator (where the default is a space). 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: -.PP -fundisp \-F',' snr.ev'[cir 512 512 .1]' - X, Y, \s-1PHA\s0, \s-1PI\s0, \s-1TIME\s0, \s-1DX\s0, \s-1DY\s0 - 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 -.PP -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 -.PP -fundisp \-f \*(L"x=%3d y=%3d pi=%1d pha=%1d time=%20.11f dx=%3d dy=%3d\*(R" \-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 -.PP -If the \fB\-T\fR (rdb table) 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 (except in conjunction with the \fB\-l\fR -switch). -.PP -Finally, note that \fBfundisp\fR can be used to create column filters from -the auxiliary tables in a \s-1FITS\s0 file. For example, the following shell code -will generate a good-time interval (\s-1GTI\s0) filter for X\-ray data files that -contain a standard \s-1GTI\s0 extension: -.PP -.Vb 3 -\& #!/bin/sh -\& sed '1,/---- .*/d -\& /^$/,$d' | awk 'tot>0{printf "||"};{printf "time="$1":"$2; tot++}' -.Ve -.PP -If this script is placed in a file called \*(L"mkgti\*(R", it can be used in a -command such as: -.PP -.Vb 1 -\& fundisp foo.fits"[GTI]" | mkgti > gti.filter -.Ve -.PP -The resulting filter file can then be used in various funtools programs: -.PP -.Vb 1 -\& funcnts foo.fits"[@gti.filter]" ... -.Ve -.PP -to process only the events in the good-time intervals. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/funhead.1 b/funtools/man/man1/funhead.1 deleted file mode 100644 index ed74333..0000000 --- a/funtools/man/man1/funhead.1 +++ /dev/null @@ -1,287 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funhead 1" -.TH funhead 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funhead \- display a header in a Funtools file -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfunhead\fR [\-a] [\-s] [\-t] [\-L] <iname> [oname ename] -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 4 -\& \-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 -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBfunhead\fR displays the \s-1FITS\s0 header parameters in the specified -\&\s-1FITS\s0 Extension. -.PP -The first argument to the program specifies the Funtools input file -to display. If \*(L"stdin\*(R" is specified, data are read from -the standard input. Funtools Bracket -Notation is used to specify particular \s-1FITS\s0 extension to process. -Normally, the full 80 characters of each header card is output, -followed by a new\-line. -.PP -If the \fB\-a\fR switch is specified, the header from each \s-1FITS\s0 -extensions in the file is displayed. Note, however, that the \fB\-a\fR -switch does not work with \s-1FITS\s0 files input via stdin. We hope to -remove this restriction in a future release. -.PP -If the \fB\-s\fR switch is specified, only 79 characters are output -before the new\-line. This helps the display on 80 character terminals. -.PP -If the \fB\-t\fR 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: \s-1FUN_PAR_UNKNOWN\s0 -('u'), \s-1FUN_PAR_COMMENT\s0 ('c'), \s-1FUN_PAR_LOGICAL\s0 ('l'), \s-1FUN_PAR_INTEGER\s0 -('i'), \s-1FUN_PAR_STRING\s0 ('s'), \s-1FUN_PAR_REAL\s0 ('r'), \s-1FUN_PAR_COMPLEX\s0 ('x'). -.PP -If the \fB\-L\fR (rdb table) switch is used, the output will conform -to starbase/rdb data base list format. -.PP -For example to display the \s-1EVENTS\s0 extension (binary table): -.PP -.Vb 17 -\& [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 -.Ve -.PP -To display the third header: -.PP -.Vb 14 -\& [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 -.Ve -.PP -To display the primary header (i.e., extension 0): -.PP -.Vb 8 -\& 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 -.Ve -.PP -The funhead program also can edit (i.e. add, delete, or modify) 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 \s-1FITS\s0 file, including other -extensions. The edit command file can be \*(L"stdin\*(R", in which case edit -command are read from the standard input. -.PP -The edit command file contains parameter comments (having '#' in the -first column) and delete and assignment(modify or add) operations. A -delete operation is specified by preceding the parameter name with a -minus sign \*(L"\-\*(R". A display operation (very useful in interactive -sessions, i.e., where the edit commands are taken from stdin) is -specified by preceding the parameter name with a question mark \*(L"?\*(R". 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 (but without the comment character that -precedes header params), i.e.: -.IP "\(bu" 4 -FITS-style comments have an equal sign \*(L"=\*(R" between the keyword and -value and an optional slash \*(L"/\*(R" to signify a comment. The strict \s-1FITS\s0 -rules on column positions are not enforced. -.IP "\(bu" 4 -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. -.PP -For example, the following interactive session checks for the -existence of parameters, adds new parameters, modifies them, and -modifies and deletes existing parameters: -.PP -.Vb 20 -\& 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 -.Ve -.PP -See Column-based Text Files -for more information about header parameter format. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/funhist.1 b/funtools/man/man1/funhist.1 deleted file mode 100644 index 38708ee..0000000 --- a/funtools/man/man1/funhist.1 +++ /dev/null @@ -1,370 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funhist 1" -.TH funhist 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funhist \- create a 1D histogram of a column (from a FITS binary table or raw event file) or an image -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfunhist\fR [\-n|\-w|\-T] <iname> [column] [[lo:hi:]bins] -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 3 -\& \-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 (tab separators) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBfunhist\fR creates a one-dimensional histogram from the specified -columns of a \s-1FITS\s0 Extension -binary table of a \s-1FITS\s0 file (or from a non-FITS raw event file), or -from a \s-1FITS\s0 image or array, and writes that histogram as an \s-1ASCII\s0 -table. Alternatively, the program can perform a 1D projection of one -of the image axes. -.PP -The first argument to the program is required, and specifies the -Funtools file: \s-1FITS\s0 table or image, raw event file, or array. If -\&\*(L"stdin\*(R" is specified, data are read from the standard input. Use -Funtools Bracket Notation to specify \s-1FITS\s0 -extensions, and filters. -.PP -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 (or array), the column is optional: if \*(L"x\*(R" (or \*(L"X\*(R"), \*(L"y\*(R" -(or \*(L"Y\*(R") is specified, then a projection is performed over the x -(dim1) or y (dim2) axes, respectively. (That is, this projection will -give the same results as a histogram performed on a table containing -the equivalent x,y event rows.) If no column name is specified or -\&\*(L"xy\*(R" (or \*(L"\s-1XY\s0\*(R") is specified for the image, then a histogram is -performed on the values contained in the image pixels. -.PP -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 \s-1TLMIN/TLMAX\s0 headers values (if these exist -in the table \s-1FITS\s0 header for the specified column) 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 \s-1DATAMIN/DATAMAX\s0 header -values, or by going through the data to calculate min and max value. -(Note that this latter calculation might fail if the image cannot be -fit in memory.) If the data are floating point (table or image) and -the number of bins is not specified, an arbitrary default of 128 is -used. -.PP -For binary table processing, the \fB\-w\fR (bin width) switch can be used -to specify the width of each bin rather than the number of bins. Thus: -.PP -.Vb 1 -\& funhist test.ev pha 1:100:5 -.Ve -.PP -means that 5 bins of width 20 are used in the histogram, while: -.PP -.Vb 1 -\& funhist \-w test.ev pha 1:100:5 -.Ve -.PP -means that 20 bins of width 5 are used in the histogram. -.PP -The data are divvied up into the specified number of bins and the -resulting 1D histogram (or projection) is output in \s-1ASCII\s0 table -format. For a table, the output displays the low_edge (inclusive) and -hi_edge (exclusive) values for the data. For example, a 15\-row table -containing a \*(L"pha\*(R" column whose values range from \-7.5 to 7.5 -can be processed thus: -.PP -.Vb 4 -\& [sh] funhist test.ev pha -\& # data file: /home/eric/data/test.ev -\& # column: pha -\& # min,max,bins: \-7.5 7.5 15 -.Ve -.PP -.Vb 17 -\& 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 -.Ve -.PP -.Vb 4 -\& [sh] funhist test.ev pha 1:6 -\& # data file: /home/eric/data/test.ev -\& # column: pha -\& # min,max,bins: 0.5 6.5 6 -.Ve -.PP -.Vb 8 -\& bin value lo_edge hi_edge -\& ------ --------- --------------------- --------------------- -\& 1 16 0.50000000 1.50000000 -\& 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 -.Ve -.PP -.Vb 4 -\& [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 -.Ve -.PP -.Vb 5 -\& bin value lo_edge hi_edge -\& ------ --------- --------------------- --------------------- -\& 1 33 0.50000000 2.50000000 -\& 2 37 2.50000000 4.50000000 -\& 3 41 4.50000000 6.50000000 -.Ve -.PP -For a table histogram, the \fB\-n\fR(normalize) switch can be used to -normalize the bin value by the width of the bin (i.e., hi_edge\-lo_edge): -.PP -.Vb 5 -\& [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 (val/(hi_edge-lo_edge)) is applied -.Ve -.PP -.Vb 5 -\& 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 -.Ve -.PP -This could used, for example, to produce a light curve with values -having units of counts/second instead of counts. -.PP -For an image histogram, the output displays the low and high image -values (both inclusive) 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: -.PP -.Vb 3 -\& [sh] funhist test.fits -\& # data file: /home/eric/data/test.fits -\& # min,max,bins: 1 7 7 -.Ve -.PP -.Vb 9 -\& 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 -.Ve -.PP -For the axis projection of an image, the output displays the low and -high image bins (both inclusive) used to generate the projection. For -example, in the following example, 21 counts had their X bin value of -2, etc.: -.PP -.Vb 4 -\& [sh] funhist test.fits x 2:7 -\& # data file: /home/eric/data/test.fits -\& # column: X -\& # min,max,bins: 2 7 6 -.Ve -.PP -.Vb 8 -\& 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 -.Ve -.PP -.Vb 4 -\& [sh] funhist test.fits x 2:7:2 -\& # data file: /home/eric/data/test.fits -\& # column: X -\& # min,max,bins: 2 7 2 -.Ve -.PP -.Vb 4 -\& bin value lo_bin hi_bin -\& ------ --------------------- --------------------- --------------------- -\& 1 60.00000000 2.00000000 4.00000000 -\& 2 51.00000000 5.00000000 7.00000000 -.Ve -.PP -You can use gnuplot or other plotting programs to graph the -results, using a script such as: -.PP -.Vb 7 -\& #!/bin/sh -\& sed \-e '1,/---- .*/d -\& /^$/,$d' | \e -\& awk '\e -\& BEGIN{print "set nokey; set title \e"funhist\e"; set xlabel \e"bin\e"; set ylabel \e"counts\e"; plot \e"-\e" with boxes"} \e -\& {print $3, $2, $4-$3}' | \e -\& gnuplot \-persist - 1>/dev/null 2>&1 -.Ve -.PP -Similar plot commands are supplied in the script \fBfunhist.plot\fR: -.PP -.Vb 1 -\& funhist test.ev pha ... | funhist.plot gnuplot -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/funimage.1 b/funtools/man/man1/funimage.1 deleted file mode 100644 index ea9db5a..0000000 --- a/funtools/man/man1/funimage.1 +++ /dev/null @@ -1,428 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funimage 1" -.TH funimage 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funimage \- create a FITS image from a Funtools data file -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfunimage\fR [\-a] <iname> <oname> [bitpix=n] -\&\fBfunimage\fR [\-l] <iname> <oname> <xcol:xdims> <ycol:ydims> <vcol> [bitpix=n] -\&\fBfunimage\fR [\-p x|y] <iname> <oname> [bitpix=n] -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 3 -\& \-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 -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBfunimage\fR creates a primary \s-1FITS\s0 image from the specified -\&\s-1FITS\s0 Extension -and/or -Image Section -of a \s-1FITS\s0 file, or from an -Image Section -of a non-FITS array, or from a raw event file. -.PP -The first argument to the program specifies the \s-1FITS\s0 input image, -array, or raw event file to process. If \*(L"stdin\*(R" is specified, data are -read from the standard input. Use Funtools -Bracket Notation to specify \s-1FITS\s0 extensions, image sections, and -filters. The second argument is the output \s-1FITS\s0 file. If \*(L"stdout\*(R" is -specified, the \s-1FITS\s0 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 (or type \*(L"int\*(R" when binning a table), but this can be -overridden using an optional third argument of the form: -.PP -.Vb 1 -\& bitpix=n -.Ve -.PP -where n is 8,16,32,\-32,\-64, for unsigned char, short, int, float and double, -respectively. -.PP -If the input data are of type image, the appropriate section is -extracted and blocked (based on how the -Image Section is specified), and -the result is written to the \s-1FITS\s0 primary image. When an integer -image containing the \s-1BSCALE\s0 and \s-1BZERO\s0 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 -(possibly of a different size), the pixels are not scaled and the -scaling keywords are retained. -.PP -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 \s-1FITS\s0 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 \fBbincols=(x,y)\fR keyword: -.PP -.Vb 1 -\& funcnts "foo.ev[EVENTS,bincols=(detx,dety)]" -.Ve -.PP -The full form of the \fBbincols=\fR specifier is: -.PP -.Vb 1 -\& bincols=([xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]]]) -.Ve -.PP -where the tlmin, tlmax, and binsiz specifiers determine the image binning -dimensions: -.PP -.Vb 2 -\& dim = (tlmax - tlmin)/binsiz (floating point data) -\& dim = (tlmax - tlmin)/binsiz + 1 (integer data) -.Ve -.PP -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 \s-1TLMIN\s0, \s-1TLMAX\s0, and \s-1TDBIN\s0 header parameters -(respectively) are present in the \s-1FITS\s0 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 Binning \s-1FITS\s0 Binary Tables and Non-FITS -Event Files for more information about binning parameters. -.PP -By default, a new 2D \s-1FITS\s0 image file is created and the image is written -to the primary \s-1HDU\s0. If the \fB\-a\fR (append) switch is specified, -the image is appended to an existing \s-1FITS\s0 file as an \s-1IMAGE\s0 extension. -(If the output file does not exist, the switch is effectively ignored -and the image is written to the primary \s-1HDU\s0.) This can be useful in a -shell programming environment when processing multiple \s-1FITS\s0 images -that you want to combine into a single final \s-1FITS\s0 file. -.PP -\&\fBfunimage\fR also can take input from a table containing columns of -x, y, and value (e.g., the output from \fBfundisp \-l\fR which -displays each image x and y and the number of counts at that -position.) When the \fB\-l\fR (list) switch is used, the input file is -taken to be a \s-1FITS\s0 or \s-1ASCII\s0 table containing (at least) three columns -that specify the x and y image coordinates and the value of that -image pixel. In this case, \fBfunimage\fR requires four extra -arguments: xcolumn:xdims, ycolumn:ydims, vcolumn and bitpix=n. The x -and y col:dim information takes the form: -.PP -.Vb 3 -\& 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 -.Ve -.PP -In particular, the min value should be used whenever the -minimum coordinate value is something other than one. For example: -.PP -.Vb 1 -\& funimage \-l foo.lst foo.fits xcol:0:512 ycol:0:512 value bitpix=-32 -.Ve -.PP -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: -.PP -.Vb 5 -\& funimage \-l stdin foo.fits "":0:512 "":0:512 "" bitpix=-32 -\& 240 250 1 -\& 255 256 2 -\& ... -\& ^D -.Ve -.PP -The list feature provides a simple way to generate a blank image. -If you pass a Column-based Text File -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 (called foo.txt): -.PP -.Vb 3 -\& x:I:1:10 y:I:1:10 -\& ------ ------ -\& 0 0 -.Ve -.PP -This text file defines two columns, x and y, each of data type 32-bit int and -image dimension 10. The command: -.PP -.Vb 1 -\& funimage foo.txt foo.fits bitpix=8 -.Ve -.PP -will create an empty \s-1FITS\s0 image called foo.fits containing a 10x10 -image of unsigned char: -.PP -.Vb 13 -\& 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 -.Ve -.PP -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. (You can, of course, -use real x,y values to seed the image with data.) -.PP -Furthermore, you can use the \s-1TEXT\s0 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: -.PP -.Vb 3 -\& funimage stdin'[TEXT(x:I:10,y:I:10)]' foo.fits bitpix=8 < /dev/null -\&or -\& funimage /dev/null'[TEXT(x:I:10,y:I:10)]' foo.fits bitpix=8 -.Ve -.PP -You also can use either of these methods to generate a region mask simply -by appending a region inside the filter brackets and specfying \fBmask=all\fR -along with the bitpix. For example, the following command will generate a -10x10 char mask using 3 regions: -.PP -.Vb 2 -\& funimage stdin'[TEXT(x:I:10,y:I:10),cir(5,5,4),point(10,1),-cir(5,5,2)]' \e -\& foo.fits bitpix=8,mask=all < /dev/null -.Ve -.PP -The resulting mask looks like this: -.PP -.Vb 13 -\& 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 -.Ve -.PP -You can use \fBfunimage\fR to create 1D image projections along the x -or y axis using the \fB\-p [x|y]\fR switch. This capability works for -both images and tables. For example consider a \s-1FITS\s0 table named ev.fits -containing the following rows: -.PP -.Vb 17 -\& 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 -.Ve -.PP -A corresponding 5x5 image, called dim2.fits, would therefore contain: -.PP -.Vb 7 -\& 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 -.Ve -.PP -A projection along the y axis can be performed on either the table or -the image: -.PP -.Vb 4 -\& funimage \-p y ev.fits stdout | fundisp stdin -\& 1 2 3 4 5 -\& ---------- ---------- ---------- ---------- ---------- -\& 1: 1 2 3 4 5 -.Ve -.PP -.Vb 4 -\& funimage \-p y dim2.fits stdout | fundisp stdin -\& 1 2 3 4 5 -\& ---------- ---------- ---------- ---------- ---------- -\& 1: 1 2 3 4 5 -.Ve -.PP -Furthermore, you can create a 1D image projection along any column of -a table by using the \fBbincols=[column]\fR filter specification and -specifying a single column. For example, the following command -projects the same 1D image along the y axis of a table as use of -the \fB\-p y\fR switch: -.PP -.Vb 4 -\& funimage ev.fits'[bincols=y]' stdout | fundisp stdin -\& 1 2 3 4 5 -\& ---------- ---------- ---------- ---------- ---------- -\& 1: 1 2 3 4 5 -.Ve -.PP -Examples: -.PP -Create a \s-1FITS\s0 image from a \s-1FITS\s0 binary table: -.PP -.Vb 1 -\& [sh] funimage test.ev test.fits -.Ve -.PP -Display the \s-1FITS\s0 image generated from a blocked section of \s-1FITS\s0 binary table: -.PP -.Vb 5 -\& [sh] funimage "test.ev[2:8,3:7,2]" stdout | fundisp stdin -\& 1 2 3 -\& --------- --------- --------- -\& 1: 20 28 36 -\& 2: 28 36 44 -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/funindex.1 b/funtools/man/man1/funindex.1 deleted file mode 100644 index 8c5b794..0000000 --- a/funtools/man/man1/funindex.1 +++ /dev/null @@ -1,179 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funindex 1" -.TH funindex 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funindex \- create an index for a column of a FITS binary table -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfunindex\fR <switches> <iname> <key> [oname] -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 7 -\& NB: these options are not compatible with Funtools processing. Please -\& use the defaults instead. -\& \-c # compress output using gzip" -\& \-a # ASCII output, ignore \-c (default: FITS table)" -\& \-f # FITS table output (default: FITS table)" -\& \-l # long output, i.e. with key value(s) (default: long)" -\& \-s # short output, i.e. no key value(s) (default: long)" -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The funindex script creates an index for the specified column (key) by -running funtable \-s (sort) 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. -.PP -The first required argument is the name of the \s-1FITS\s0 binary table -to index. Please note that text files cannot be indexed at this time. -The second required argument is the column (key) 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. -.PP -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 (output file name) should not be used for funtools -processing. -.PP -For example, to create an index on column Y for a given \s-1FITS\s0 file, use: -.PP -.Vb 1 -\& funindex foo.fits Y -.Ve -.PP -This will generate an index named foo_y.idx, which will be used by funtools -for filters involving the Y column. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/funjoin.1 b/funtools/man/man1/funjoin.1 deleted file mode 100644 index 6e7dd31..0000000 --- a/funtools/man/man1/funjoin.1 +++ /dev/null @@ -1,326 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funjoin 1" -.TH funjoin 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funjoin \- join two or more FITS binary tables on specified columns -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfunjoin\fR [switches] <ifile1> <ifile2> ... <ifilen> <ofile> -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 11 -\& \-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] -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBfunjoin\fR joins rows from two or more (up to 32) -\&\s-1FITS\s0 Binary Table files, based on the values -of specified join columns in each file. \s-1NB:\s0 the join columns must have -an index file associated with it. These files are generated using the -\&\fBfunindex\fR program. -.PP -The first argument to the program specifies the first input \s-1FITS\s0 table -or raw event file. If \*(L"stdin\*(R" 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 \s-1FITS\s0 file. -.PP -\&\s-1NB:\s0 Do \fBnot\fR use Funtools Bracket -Notation to specify \s-1FITS\s0 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. -.PP -The join columns are specified using the \fB\-j col\fR switch (which -specifies a column name to use for all files) or with \fB\-j1 col1\fR, -\&\fB\-j2 col2\fR, ... \fB\-jn coln\fR switches (which specify a column -name to use for each file). A join column must be specified for each file. -If both \fB\-j col\fR and \fB\-jn coln\fR 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: -.PP -.Vb 1 -\& funjoin \-j key in1.fits in2.fits in3.fits out.fits -.Ve -.PP -A different key can be specified for the third file in this way: -.PP -.Vb 1 -\& funjoin \-j key \-j3 otherkey in1.fits in2.fits in3.fits out.fits -.Ve -.PP -The \fB\-a \*(L"cols\*(R"\fR switch (and \fB\-a1 \*(L"col1\*(R"\fR, -\&\fB\-a2 \*(L"cols2\*(R"\fR counterparts) can be used to specify columns to -activate (i.e. write to the output file) for each input file. By -default, all columns are output. -.PP -If two or more columns from separate files have the same name, the -second (and subsequent) columns are renamed to have an underscore -and a numeric value appended. -.PP -The \fB\-m min\fR and \fB\-M max\fR switches specify the minimum -and maximum number of joins required to write out a row. The default -minimum is 0 joins (i.e. all rows are written out) and the default maximum -is 63 (the maximum number of possible joins with a limit of 32 input files). -For example, to write out only those rows in which exactly two files -have columns that match (i.e. one join): -.PP -.Vb 1 -\& funjoin \-j key \-m 1 \-M 1 in1.fits in2.fits in3.fits ... out.fits -.Ve -.PP -A given row can have the requisite number of joins without all of the -files being joined (e.g. three files are being joined but only two -have a given join key value). In this case, all of the columns of the -non-joined file are written out, by default, using blanks (zeros or NULLs). -The \fB\-b c1:bv1,c2:bv2\fR and -\-b1 'c1:bv1,c2:bv2' \-b2 'c1:bv1,c2 - bv2' ... -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 (single or double), a case-insensitive string -value of \*(L"nan\*(R" means that the \s-1IEEE\s0 NaN (not\-a\-number) should be -used. Thus, for example: -.PP -.Vb 1 -\& funjoin \-b "AKEY:???" \-b1 "A:-1" \-b3 "G:NaN,E:-1,F:-100" ... -.Ve -.PP -means that a non-joined \s-1AKEY\s0 column in any file will contain the -string \*(L"???\*(R", the non-joined A column of file 1 will contain a value -of \-1, the non-joined G column of file 3 will contain \s-1IEEE\s0 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. -.PP -To distinguish which files are non-blank components of a given row, -the \fB\-s\fR (status) switch can be used to add a bitmask column named -\&\*(L"\s-1JFILES\s0\*(R" 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 \s-1FITS\s0 header as parameters named \s-1JFILE1\s0, -\&\s-1JFILE2\s0, etc. The \fB\-S col\fR switch allows you to change the name -of the status column from the default \*(L"\s-1JFILES\s0\*(R". -.PP -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. -.PP -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. -.PP -The \fB\-t tol\fR switch specifies a tolerance value for numeric -columns. At present, a tolerance value can join only two files at a -time. (A completely different algorithm is required to join more than -two files using a tolerance, somethng we might consider implementing -in the future.) -.PP -The following example shows many of the features of funjoin. The input files -t1.fits, t2.fits, and t3.fits contain the following columns: -.PP -.Vb 11 -\& [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 -.Ve -.PP -fundisp t2.fits - \s-1AKEY\s0 \s-1KEY\s0 C D - \-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- - iii 8 24 25 - ggg 6 18 19 - eee 4 12 13 - ccc 2 6 7 - aaa 0 0 1 -.PP -fundisp t3.fits - \s-1AKEY\s0 \s-1KEY\s0 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 -.PP -Given these input files, the following funjoin command: -.PP -.Vb 3 -\& funjoin \-s \-a1 "\-B" \-a2 "\-D" \-a3 "\-E" \-b \e -\& "AKEY:???" \-b1 "AKEY:XXX,A:255" \-b3 "G:NaN,E:-1,F:-100" \e -\& \-j key t1.fits t2.fits t3.fits foo.fits -.Ve -.PP -will join the files on the \s-1KEY\s0 column, outputting all columns except B -(in t1.fits), D (in t2.fits) and E (in t3.fits), and setting blank -values for \s-1AKEY\s0 (globally, but overridden for t1.fits) and A (in file -1) and G, E, and F (in file 3). A \s-1JFILES\s0 column will be output to -flag which files were used in each row: -.PP -.Vb 12 -\& 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 -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/funmerge.1 b/funtools/man/man1/funmerge.1 deleted file mode 100644 index 068ba2f..0000000 --- a/funtools/man/man1/funmerge.1 +++ /dev/null @@ -1,215 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funmerge 1" -.TH funmerge 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funmerge \- merge one or more Funtools table files -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfunmerge\fR [\-w|\-x] \-f [colname] <iname1> <iname2> ... <oname> -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 3 -\& \-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 -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBfunmerge\fR merges \s-1FITS\s0 data from one or more -\&\s-1FITS\s0 Binary Table files -or raw event files. -.PP -The first argument to the program specifies the first input \s-1FITS\s0 table -or raw event file. If \*(L"stdin\*(R" is specified, data are read from the -standard input. Use Funtools Bracket -Notation to specify \s-1FITS\s0 extensions and row filters. Subsequent -arguments specify additional event files and tables to merge. (\s-1NB:\s0 Stdin -cannot not be used for any of these additional input file arguments.) -The last argument is the output \s-1FITS\s0 file. The columns in each input table -must be identical. -.PP -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 (as -well as blank lines and/or comment lines starting with the '#' sign). -If standard input is specified as an include file ('@stdin'), then -file names are read from the standard input until \s-1EOF\s0 (^D). Event -files and include files can be mixed on a command line. -.PP -Rows from each table are written sequentially to the output -file. If the switch \fB\-f [colname]\fR 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 (starting from one). In -this case, the corresponding file names are stored in the header -parameters having the prefix \fB\s-1FUNFIL\s0\fR, i.e., \s-1FUNFIL01\s0, -\&\s-1FUNFIL02\s0, etc. -.PP -Using the \fB\-w\fR switch (or \fB\-x\fR switch as described -below), \fBfunmerge\fR also can adjust the position column values -using the \s-1WCS\s0 information in each file. (By position columns, we mean -the columns that the table is binned on, i.e., those columns defined -by the \fBbincols=\fR switch, or (X,Y) by default.) To perform \s-1WCS\s0 -alignment, the \s-1WCS\s0 of the first file is taken as the base \s-1WCS\s0. Each -position in subsequent files is adjusted by first converting it to the -sky coordinate in its own \s-1WCS\s0 coordinate system, then by converting -this sky position to the sky position of the base \s-1WCS\s0, and finally -converting back to a pixel position in the base system. Note that in -order to perform \s-1WCS\s0 alignment, the appropriate \s-1WCS\s0 and \s-1TLMIN/TLMAX\s0 -keywords must already exist in each \s-1FITS\s0 file. -.PP -When performing \s-1WCS\s0 alignment, you can save the original positions in -the output file by using the \fB\-x\fR (for \*(L"xtra\*(R") switch instead -of the \fB\-w\fR switch (i.e., using this switch also implies using -\&\fB\-w\fR) The old positions are saved in columns having the same -name as the original positional columns, with the added prefix \*(L"\s-1OLD_\s0\*(R". -.PP -Examples: -.PP -Merge two tables, and preserve the originating file number for -each row in the column called \*(L"\s-1FILE\s0\*(R" (along with the corresponding -file name in the header): -.PP -.Vb 1 -\& [sh] funmerge \-f "FILE" test.ev test2.ev merge.ev -.Ve -.PP -Merge two tables with \s-1WCS\s0 alignment, saving the old position values in -2 additional columns: -.PP -.Vb 1 -\& [sh] funmerge \-x test.ev test2.ev merge.ev -.Ve -.PP -This program only works on raw event files and binary tables. We have -not yet implemented image and array merging. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/funsky.1 b/funtools/man/man1/funsky.1 deleted file mode 100644 index 45a2cac..0000000 --- a/funtools/man/man1/funsky.1 +++ /dev/null @@ -1,385 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funsky 1" -.TH funsky 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funsky \- convert between image and sky coordinates -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 4 -\&\fBfunsky\fR iname[ext] # RA,Dec (deg) or image pix from stdin -\&\fBfunsky\fR iname[ext] [lname] # RA, Dec (deg) or image pix from list -\&\fBfunsky\fR iname[ext] [col1] [col2] # named cols:units from stdin -\&\fBfunsky\fR iname[ext] [lname] [col1] [col2] # named cols:units from list -.Ve -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 5 -\& \-d # always use integer tlmin conversion (as ds9 does) -\& \-r # convert x,y to RA,Dec (default: convert RA,Dec to x,y) -\& \-o # include offset from the nominal target position (in arcsec) -\& \-v # display input values also (default: display output only) -\& \-T # output display in rdb format (w/header,tab delimiters) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Funsky converts input sky coordinates (\s-1RA\s0, Dec) to image coordinates (or vice -versa) using the \s-1WCS\s0 information contained in the specified \s-1FITS\s0 file. Several -calling sequences are supported in order to make it easy to specify -coordinate positions in different ways. -.PP -The first required argument is always the input \s-1FITS\s0 file (or -extension) containing the \s-1WCS\s0 information in an extension header. Note -that the data from this file is not used. By default, the program -converts input \s-1RA\s0 and Dec values to X and Y using this \s-1WCS\s0 -information. If the \s-1WCS\s0 is associated with a \s-1FITS\s0 image, then the X,Y -values are image values. If the \s-1WCS\s0 is associated with a binary table, -then the X, Y values are physical values. To convert X,Y to \s-1RA\s0 and -Dec, use the \fB\-r\fR (reverse) switch. -.PP -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 \s-1RA\s0 in degrees (or X in -pixels) followed by a Dec in degrees (or Y in pixels). The usual -delimiters are supported (spaces, commas, tabs). For example: -.PP -.Vb 9 -\& # read from stdin, default column names and units -\& [sh] funsky snr.ev -\& 22.982695 58.606523 # input RA (hrs), Dec(deg) -\& 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 -.Ve -.PP -If a second argument is supplied, this argument is assumed to be -a file containing \s-1RA\s0 (X) and Dec (Y) positions. The file can either be -an \s-1ASCII\s0 table or a \s-1FITS\s0 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 \*(L"\s-1RA\s0\*(R", \*(L"\s-1DEC\s0\*(R", or \*(L"X\*(R", \*(L"Y\*(R" for sky -to image and image to sky conversions, respectively. If the table has -no header, then once again, \s-1RA\s0 (X) is assumed to first, followed -by \s-1DEC\s0 (Y). -For example: -.PP -.Vb 7 -\& # 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 -.Ve -.PP -.Vb 4 -\& [sh] funsky snr.ev hd.in -\& 510.00 510.00 -\& 512.00 510.50 -\& 513.50 513.50 -.Ve -.PP -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 \s-1RA\s0 (or X in pixels) followed by a -Dec (or Y in pixels), 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: -.PP -.Vb 1 -\& [colname]:[h|d|r] -.Ve -.PP -If the colname is omitted, the names default to \*(L"\s-1RA\s0\*(R", \*(L"\s-1DEC\s0\*(R", \*(L"X\*(R", \*(L"Y\*(R", -\&\*(L"\s-1COL1\s0\*(R", or \*(L"\s-1COL2\s0\*(R" as above. If the units are omitted, the default is degrees -for both \s-1RA\s0 and Dec. When the \-r switch is used (convert from image -to sky) the units are applied to the output instead of the input. The following -examples will serve to illustrate the options: -.PP -.Vb 7 -\& # read from stdin, specifying column names (def. units: degrees) -\& [sh] cat hd.in -\& MYRA MYDEC -\& --------- --------- -\& 22.982695 58.606523 -\& 22.982127 58.607634 -\& 22.981700 58.614301 -.Ve -.PP -.Vb 4 -\& [sh] funsky snr.ev MYRA MYDEC < hd.in -\& 510.00 510.00 -\& 512.00 510.50 -\& 513.50 513.50 -.Ve -.PP -.Vb 7 -\& # 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 -.Ve -.PP -.Vb 4 -\& [sh] funsky snr.ev MYRA:d MYDEC:d < dd.in -\& 510.00 510.00 -\& 512.00 510.50 -\& 513.50 513.50 -.Ve -.PP -.Vb 5 -\& # 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 -.Ve -.PP -.Vb 4 -\& [sh] cat im.in | funsky \-r snr.ev :d :d -\& 344.740432 58.606523 -\& 344.731900 58.607634 -\& 344.725500 58.614301 -.Ve -.PP -Finally, four command arguments specify both and input file and column names -and/or units: -.PP -.Vb 6 -\& [sh] cat dd.in -\& MYRA MYDEC -\& --------- --------- -\& 344.740432 58.606523 -\& 344.731900 58.607634 -\& 344.725500 58.614301 -.Ve -.PP -.Vb 4 -\& [sh] funsky snr.ev dd.in MYRA:d MYDEC:d -\& 510.00 510.00 -\& 512.00 510.50 -\& 513.50 513.50 -.Ve -.PP -.Vb 5 -\& # 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 -.Ve -.PP -.Vb 4 -\& [sh] funsky \-r snr.ev im.in :d :d -\& 344.740432 58.606523 -\& 344.731900 58.607634 -\& 344.725500 58.614301 -.Ve -.PP -By default, the output of funsky consists only of the converted coordinate -position(s), one per output line. This makes parsing in shell scripts easy. -Use the \fB\-v\fR (verbose) switch to specify that the input -coordinates should be pre-pended to each line. For example: -.PP -.Vb 6 -\& [sh] cat dd.in -\& MYRA MYDEC -\& --------- --------- -\& 344.740432 58.606523 -\& 344.731900 58.607634 -\& 344.725500 58.614301 -.Ve -.PP -.Vb 4 -\& [sh] funsky snr.ev dd.in MYRA:d MYDEC:d -\& 510.00 510.00 -\& 512.00 510.50 -\& 513.50 513.50 -.Ve -.PP -.Vb 4 -\& [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 -.Ve -.PP -In addition, a full starbase table can be output using the \fB\-T\fR -(table) 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 (mainly to remind you of the -sky units): -.PP -.Vb 7 -\& # 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 -.Ve -.PP -.Vb 9 -\& # 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 -.Ve -.PP -.Vb 5 -\& 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 -.Ve -.PP -Finally, the \fB\-d\fR (ds9) switch mimicks ds9's use of integer \s-1TLMIN\s0 -and \s-1TLMAX\s0 values for all coordinate transformations. \s-1FITS\s0 conventions -seem to call for use of floating point \s-1TLMIN\s0 and \s-1TLMAX\s0 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. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/funtable.1 b/funtools/man/man1/funtable.1 deleted file mode 100644 index fe3b7ac..0000000 --- a/funtools/man/man1/funtable.1 +++ /dev/null @@ -1,356 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funtable 1" -.TH funtable 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funtable \- copy selected rows from a Funtools file to a FITS binary table -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfuntable\fR [\-a] [\-i|\-z] [\-m] [\-s cols] <iname> <oname> [columns] -.SH "OPTIONS" -.IX Header "OPTIONS" -.Vb 5 -\& \-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 -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBfuntable\fR selects rows from the specified -\&\s-1FITS\s0 Extension -(binary table only) of a \s-1FITS\s0 file, or from a non-FITS raw event -file, and writes those rows to a \s-1FITS\s0 binary table file. It also -will create a \s-1FITS\s0 binary table from an image or a raw array file. -.PP -The first argument to the program specifies the \s-1FITS\s0 file, raw event -file, or raw array file. If \*(L"stdin\*(R" is specified, data are read from -the standard input. Use Funtools Bracket -Notation to specify \s-1FITS\s0 extensions, and filters. The second -argument is the output \s-1FITS\s0 file. If \*(L"stdout\*(R" is specified, the \s-1FITS\s0 -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: -.PP -.Vb 1 -\& "column1 column1 ... columnN" -.Ve -.PP -The \fBfuntable\fR program generally is used to select rows from a -\&\s-1FITS\s0 binary table using -Table Filters -and/or -Spatial Region Filters. -For example, you can copy only selected rows (and output only selected -columns) by executing in a command such as: -.PP -.Vb 13 -\& [sh] funtable "test.ev[pha==1&&pi==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 -.Ve -.PP -The special column \fB$REGION\fR can be specified to write the -region id of each row: -.PP -.Vb 12 -\& [sh $] funtable "test.ev[time-(int)time>=.99&&annulus(0 0 0 10 n=3)]" 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 -.Ve -.PP -Here only rows with the proper fractional time and whose position also is -within one of the three annuli are written. -.PP -Columns can be excluded from display using a minus sign before the -column: -.PP -.Vb 12 -\& [sh $] funtable "test.ev[time-(int)time>=.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 -.Ve -.PP -All columns except the time column are written. -.PP -In general, the rules for activating and de-activating columns are: -.IP "\(bu" 4 -If only exclude columns are specified, then all columns but -the exclude columns will be activated. -.IP "\(bu" 4 -If only include columns are specified, then only the specified columns -are activated. -.IP "\(bu" 4 -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. -.PP -In addition to specifying columns names explicitly, the special -symbols \fI+\fR and \fI\-\fR can be used to activate and -de-activate \fIall\fR columns. This is useful if you want to -activate the \f(CW$REGION\fR column along with all other columns. According -to the rules, the syntax \*(L"$REGION\*(R" only activates the region column -and de-activates the rest. Use \*(L"+ \f(CW$REGION\fR\*(R" to activate all -columns as well as the region column. -.PP -Ordinarily, only the selected table is copied to the output file. In -a \s-1FITS\s0 binary table, it sometimes is desirable to copy all of the -other \s-1FITS\s0 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 \s-1EVENT\s0 table, -while the second command copies other extensions as well: -.PP -.Vb 2 -\& [sh] funtable "/proj/rd/data/snr.ev[EVENTS]" events.ev -\& [sh] funtable "/proj/rd/data/snr.ev[EVENTS+]" eventsandmore.ev -.Ve -.PP -If the input file is an image or a raw array file, then -\&\fBfuntable\fR will generate a \s-1FITS\s0 binary table from the pixel -values in the image. Note that it is not possible to specify the -columns to output (using command-line argument 3). 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 \*(L"X\*(R", \*(L"Y\*(R", and -\&\*(L"\s-1VALUE\s0\*(R". For each pixel in the image, a single row (event) is -generated with the \*(L"X\*(R" and \*(L"Y\*(R" columns assigned the dim1 and dim2 -values of the image pixel, respectively and the \*(L"\s-1VALUE\s0\*(R" column -assigned the value of the pixel. With sort of table, running -\&\fBfunhist\fR on the \*(L"\s-1VALUE\s0\*(R" column will give the same results as -running \fBfunhist\fR on the original image. -.PP -If the \fB\-i\fR (\*(L"individual\*(R" rows) switch is specified, then only -the \*(L"X\*(R" and \*(L"Y\*(R" columns are generated. In this case, each positive -pixel value in the image generates n rows (events), where n is equal -to the integerized value of that pixel (plus 0.5, for floating point -data). In effect, \fB\-i\fR approximately recreates the rows of a -table that would have been binned into the input image. (Of course, -this is only approximately correct, since the resulting x,y positions -are integerized.) -.PP -If the \fB\-s [col1 col2 ... coln]\fR (\*(L"sort\*(R") 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 (i.e. you cannot sort on a -column but not include it in the output). This facility uses the -\&\fB_sort\fR program (included with funtools), which must be accessible -via your path. -.PP -For binary tables, the \fB\-m\fR (\*(L"multiple files\*(R") 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. -.PP -The separate output file names generated by the \fB\-m\fR switch are -produced automatically from the root output file to contain the region id of -the associated region. (Note 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.) Output file names are generated as follows: -.IP "\(bu" 4 -A \f(CW$n\fR specification can be used anywhere in the root file name (suitably -quoted to protect it from the shell) and will be expanded to be the id -number of the associated region. For example: -.Sp -.Vb 1 -\& funtable \-m input.fits'[cir(512,512,1);cir(520,520,1)...]' 'foo.goo_$n.fits' -.Ve -.Sp -will generate files named foo.goo_0.fits (for rows not in any region but -still passing the filter), foo.goo_1.fits (rows in region id #1, the first -region), foo.goo_2.fits (rows in region id #2), etc. Note that single quotes -in the output root are required to protect the '$' from the shell. -.IP "\(bu" 4 -If \f(CW$n\fR is not specified, then the region id will be placed before -the first dot (.) in the filename. Thus: -.Sp -.Vb 1 -\& funtable \-m input.fits'[cir(512,512,1);cir(520,520,1)...]' foo.evt.fits -.Ve -.Sp -will generate files named foo0.evt.fits (for rows not in any region but -still passing the filter), foo1.evt.fits (rows in region id #1), -foo2.evt.fits (rows in region id #2), etc. -.IP "\(bu" 4 -If no dot is specified in the root output file name, then -the region id will be appended to the filename. Thus: -.Sp -.Vb 1 -\& funtable \-m input.fits'[cir(512,512,1);cir(520,520,1)...]' 'foo_evt' -.Ve -.Sp -will generate files named foo_evt0 (for rows not in any region but -still passing the filter), foo_evt1 (rows in region id #1), -foo_evt2 (rows in region id #2), etc. -.PP -The multiple file mechanism provide a simple way to generate -individual source data files with a single pass through the data. -.PP -By default, a new \s-1FITS\s0 file is created and the binary table is written -to the first extension. If the \fB\-a\fR (append) switch is specified, -the table is appended to an existing \s-1FITS\s0 file as a \s-1BINTABLE\s0 extension. -Note that the output \s-1FITS\s0 file must already exist. -.PP -If the \fB\-z\fR (\*(L"zero\*(R" pixel values) switch is specified and -\&\fB\-i\fR is not specified, then pixels having a zero value will -be output with their \*(L"\s-1VALUE\s0\*(R" column set to zero. Obviously, this -switch does not make sense when individual events are output. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man1/funtbl.1 b/funtools/man/man1/funtbl.1 deleted file mode 100644 index fbfc03e..0000000 --- a/funtools/man/man1/funtbl.1 +++ /dev/null @@ -1,249 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funtbl 1" -.TH funtbl 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -funtbl \- extract a table from Funtools ASCII output -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -\&\fBfuntable\fR [\-c cols] [\-h] [\-n table] [\-p prog] [\-s sep] <iname> -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -[\s-1NB:\s0 This program has been deprecated in favor of the \s-1ASCII\s0 text processing -support in funtools. You can now perform fundisp on funtools \s-1ASCII\s0 output -files (specifying the table using bracket notation) to extract tables -and columns.] -.PP -The \fBfuntbl\fR script extracts a specified table (without the -header and comments) from a funtools \s-1ASCII\s0 output file and writes the -result to the standard output. The first non-switch argument is the -\&\s-1ASCII\s0 input file name (i.e. the saved output from funcnts, fundisp, -funhist, etc.). If no filename is specified, stdin is read. The -\&\-n switch specifies which table (starting from 1) 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 \*(L"1 3 5\*(R" -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 (which is host-specific and is determined at -build time). The \-T switch will output the data in rdb format (i.e., -with a 2\-row header of column names and dashes, and with data columns -separated by tabs). The \-help switch will print out a message -describing program usage. -.PP -For example, consider the output from the following funcnts command: -.PP -.Vb 10 -\& [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 -.Ve -.PP -.Vb 6 -\& # 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 -.Ve -.PP -.Vb 6 -\& # 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 -.Ve -.PP -.Vb 4 -\& # the following source and background components were used: -\& source_region(s) -\& ---------------- -\& ann 512 512 0 9 n=3 -.Ve -.PP -.Vb 5 -\& 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 -.Ve -.PP -There are four tables in this output. To extract the last one, you -can execute: -.PP -.Vb 4 -\& [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 -.Ve -.PP -Note that the output has been re-formatted so that only a single space -separates each column, with no extraneous header or comment information. -.PP -To extract only columns 1,2, and 4 from the last example (but with a header -prepended and tabs between columns), you can execute: -.PP -.Vb 5 -\& [sh] funcnts \-s snr.ev "ann 512 512 0 9 n=3" | funtbl \-c "1 2 4" \-h \-n 4 \-s "\et" -\& #reg counts sumcnts -\& 1 147.000 147.000 -\& 2 478.000 625.000 -\& 3 817.000 1442.000 -.Ve -.PP -Of course, if the output has previously been saved in a file named -foo.out, the same result can be obtained by executing: -.PP -.Vb 5 -\& [sh] funtbl \-c "1 2 4" \-h \-n 4 \-s "\et" foo.out -\& #reg counts sumcnts -\& 1 147.000 147.000 -\& 2 478.000 625.000 -\& 3 817.000 1442.000 -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funclose.3 b/funtools/man/man3/funclose.3 deleted file mode 100644 index dc8dbd2..0000000 --- a/funtools/man/man3/funclose.3 +++ /dev/null @@ -1,160 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funclose 3" -.TH funclose 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunClose \- close a Funtools data file -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 1 -\& void FunClose(Fun fun) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunClose()\fB\fR routine closes a previously-opened Funtools data -file, freeing control structures. If a -Funtools reference handle -was passed to -the \fIFunOpen()\fR call for this file, -and if copy mode also was specified for that file, then -\&\fIFunClose()\fR also will copy the -remaining extensions from the input file to the output file (if the -input file still is open). Thus, we recommend always closing the -output Funtools file \fBbefore\fR the input file. (Alternatively, -you can call \fIFunFlush()\fR -explicitly). -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funcolumnactivate.3 b/funtools/man/man3/funcolumnactivate.3 deleted file mode 100644 index 2eda34b..0000000 --- a/funtools/man/man3/funcolumnactivate.3 +++ /dev/null @@ -1,330 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funcolumnactivate 3" -.TH funcolumnactivate 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunColumnActivate \- activate Funtools columns -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 1 -\& void FunColumnActivate(Fun fun, char *s, char *plist) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunColumnActivate()\fB\fR routine determines which columns (set up -by \fIFunColumnSelect()\fR) -ultimately will be read and/or written. By default, all columns that -are selected using -\&\fIFunColumnSelect()\fR -are activated. The -\&\fIFunColumnActivate()\fR -routine can be used to turn off/off activation of specific columns. -.PP -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 \*(L"+\*(R" are activated and -columns preceded by a \*(L"\-\*(R" are de\-activated. If a column is named -without \*(L"+\*(R" or \*(L"\-\*(R", it is activated. The reserved strings \*(L"$region\*(R" -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 \*(L"$x\*(R" and \*(L"$y\*(R" are used to activate the current -binning columns. Thus, if the columns \s-1DX\s0 and \s-1DY\s0 are specified as -binning columns: -.PP -.Vb 1 -\& [sh $] fundisp foo.fits[bincols=(DX,DY)] -.Ve -.PP -then \*(L"$x\*(R" and \*(L"$y\*(R" will refer to these columns in a call to -\&\fIFunColumnActivate()\fR. -.PP -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: -.IP "\(bu" 4 -\&\fB\*(L"pi pha time\*(R"\fR # only these three columns will be active -.IP "\(bu" 4 -\&\fB\*(L"\-pi \-pha \-time\*(R"\fR # all but these columns will be active -.IP "\(bu" 4 -\&\fB\*(L"pi \-pha\*(R"\fR # only pi is active, pha is not, others are not -.IP "\(bu" 4 -\&\fB\*(L"+pi \-pha\*(R"\fR # same as above -.IP "\(bu" 4 -\&\fB\*(L"pi \-pha \-time\*(R"\fR # only pi is active, all others are not -.IP "\(bu" 4 -\&\fB\*(L"pi pha\*(R"\fR # pha and pi are active, all others are not -.IP "\(bu" 4 -\&\fB\*(L"pi pha \-x \-y\*(R"\fR # pha and pi are active, all others are not -.PP -You can use the column activation list to reorder columns, since -columns are output in the order specified. For example: -.PP -.Vb 9 -\& # 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 -.Ve -.PP -.Vb 9 -\& # 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 -.Ve -.PP -A \*(L"+\*(R" sign by itself means to activate all columns, so that you can reorder -just a few columns without specifying all of them: -.PP -.Vb 9 -\& # 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 -.Ve -.PP -The column activation/deactivation is performed in the order of the -specified column arguments. This means you can mix \*(L"+\*(R", \*(L"\-\*(R" (which -de-activates all columns) and specific column names to reorder and -select columns in one command. For example, consider the following: -.PP -.Vb 9 -\& # 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 -.Ve -.PP -We first activate \*(L"time\*(R", \*(L"pi\*(R", and \*(L"pha\*(R" so that they are output first. -We then activate all of the other columns, and then de-activate \*(L"x\*(R" and \*(L"y\*(R". -Note that this is different from: -.PP -.Vb 9 -\& # 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 -.Ve -.PP -Here, \*(L"x\*(R" and \*(L"y\*(R" are de\-activated, but then all columns including \*(L"x\*(R" and -\&\*(L"y\*(R" are again re\-activated. -.PP -Typically, -\&\fIFunColumnActivate()\fR uses a -list of columns that are passed into the program from the command line. For -example, the code for funtable contains the following: -.PP -.Vb 1 -\& char *cols=NULL; -.Ve -.PP -.Vb 3 -\& /* open the input FITS file */ -\& if( !(fun = FunOpen(argv[1], "rc", NULL)) ) -\& gerror(stderr, "could not FunOpen input file: %s\en", argv[1]); -.Ve -.PP -.Vb 3 -\& /* set active flag for specified columns */ -\& if( argc >= 4 ) cols = argv[3]; -\& FunColumnActivate(fun, cols, NULL); -.Ve -.PP -The \fIFunOpen()\fR call sets the -default columns to be all columns in the input file. The -\&\fIFunColumnActivate()\fR call -then allows the user to control which columns ultimately will be -activated (i.e., in this case, written to the new file). For example: -.PP -.Vb 1 -\& funtable test.ev foo.ev "pi pha time" -.Ve -.PP -will process only the three columns mentioned, while: -.PP -.Vb 1 -\& funtable test.ev foo.ev "\-time" -.Ve -.PP -will process all columns except \*(L"time\*(R". -.PP -If \fIFunColumnActivate()\fR -is called with a null string, then the environment variable -\&\fB\s-1FUN_COLUMNS\s0\fR 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 (see example above), instead -of calling it this way: -.PP -.Vb 4 -\& /* set active flag for specified columns */ -\& if( argc >= 4 ){ -\& FunColumnActivate(fun, argv[3], NULL); -\& } -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funcolumnlookup.3 b/funtools/man/man3/funcolumnlookup.3 deleted file mode 100644 index 15c9c36..0000000 --- a/funtools/man/man3/funcolumnlookup.3 +++ /dev/null @@ -1,220 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funcolumnlookup 3" -.TH funcolumnlookup 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunColumnLookup \- lookup a Funtools column -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 3 -\& int FunColumnLookup(Fun fun, char *s, int which, -\& char **name, int *type, int *mode, -\& int *offset, int *n, int *width) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunColumnLookup()\fB\fR routine returns information about a named -(or indexed) 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 \s-1NULL\s0, 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: -.IP "\(bu" 4 -\&\fBtype\fR: data type of column: -.RS 4 -.IP "\(bu" 4 -A: \s-1ASCII\s0 characters -.IP "\(bu" 4 -B: unsigned 8-bit char -.IP "\(bu" 4 -I: signed 16-bit int -.IP "\(bu" 4 -U: unsigned 16-bit int (not standard \s-1FITS\s0) -.IP "\(bu" 4 -J: signed 32-bit int -.IP "\(bu" 4 -V: unsigned 32-bit int (not standard \s-1FITS\s0) -.IP "\(bu" 4 -E: 32-bit float -.IP "\(bu" 4 -D: 64-bit float -.RE -.RS 4 -.RE -.IP "\(bu" 4 -\&\fBmode\fR: bit flag status of column, including: -.RS 4 -.IP "\(bu" 4 -\&\s-1COL_ACTIVE\s0 1 is column activated? -.IP "\(bu" 4 -\&\s-1COL_IBUF\s0 2 is column in the raw input data? -.IP "\(bu" 4 -\&\s-1COL_PTR\s0 4 is column a pointer to an array? -.IP "\(bu" 4 -\&\s-1COL_READ\s0 010 is read mode selected? -.IP "\(bu" 4 -\&\s-1COL_WRITE\s0 020 is write mode selected? -.IP "\(bu" 4 -\&\s-1COL_REPLACEME\s0 040 is this column being replaced by user data? -.RE -.RS 4 -.RE -.IP "\(bu" 4 -\&\fBoffset\fR: byte offset in struct -.IP "\(bu" 4 -\&\fBn\fR: number of elements (i.e. size of vector) in this column -.IP "\(bu" 4 -\&\fBwidth\fR: size in bytes of this column -.PP -If the named column exists, the routine returns a positive integer, -otherwise zero is returned. (The positive integer is the index+1 into -the column array where this column was located.) -.PP -If \s-1NULL\s0 is passed as the return address of one (or more) of these -values, no data is passed back for that information. For -example: -.PP -.Vb 2 -\& if( !FunColumnLookup(fun, "phas", 0, NULL NULL, NULL, NULL, &npha, NULL) ) -\& gerror(stderr, "can't find phas column\en"); -.Ve -.PP -only returns information about the size of the phas vector. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funcolumnselect.3 b/funtools/man/man3/funcolumnselect.3 deleted file mode 100644 index 88158c0..0000000 --- a/funtools/man/man3/funcolumnselect.3 +++ /dev/null @@ -1,664 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funcolumnselect 3" -.TH funcolumnselect 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunColumnSelect \- select Funtools columns -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 5 -\& int FunColumnSelect(Fun fun, int size, char *plist, -\& char *name1, char *type1, char *mode1, int offset1, -\& char *name2, char *type2, char *mode2, int offset2, -\& ..., -\& NULL) -.Ve -.PP -.Vb 3 -\& int FunColumnSelectArr(Fun fun, int size, char *plist, -\& char **names, char **types, char **modes, -\& int *offsets, int nargs); -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunColumnSelect()\fB\fR 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 \s-1FITS\s0 file. -.PP -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 \fIsizeof()\fR -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. -.PP -Following the first three required arguments is a variable length list of -column specifications. Each column specification will consist of four -arguments: -.IP "\(bu" 4 -\&\fBname\fR: the name of the column -.IP "\(bu" 4 -\&\fBtype\fR: the data type of the column as it will be stored in -the user record struct (not the data type of the input file). The -following basic data types are recognized: -.RS 4 -.IP "\(bu" 4 -A: \s-1ASCII\s0 characters -.IP "\(bu" 4 -B: unsigned 8-bit char -.IP "\(bu" 4 -I: signed 16-bit int -.IP "\(bu" 4 -U: unsigned 16-bit int (not standard \s-1FITS\s0) -.IP "\(bu" 4 -J: signed 32-bit int -.IP "\(bu" 4 -V: unsigned 32-bit int (not standard \s-1FITS\s0) -.IP "\(bu" 4 -E: 32-bit float -.IP "\(bu" 4 -D: 64-bit float -.RE -.RS 4 -.Sp -The syntax used is similar to that which defines the \s-1TFORM\s0 parameter -in \s-1FITS\s0 binary tables. That is, a numeric repeat value can precede -the type character, so that \*(L"10I\*(R" means a vector of 10 short ints, \*(L"E\*(R" -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 -\&\fIFunTableRowGet()\fR. -.Sp -[ A short digression regarding bit\-fields: Special attention is -required when reading or writing the \s-1FITS\s0 bit-field type -(\*(L"X\*(R"). 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 (N+7)/8, where N is the -numeric repeat character. -.Sp -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 (possibly with endian-based byte\-swapping) 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: -.IP "\(bu" 4 -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. -.IP "\(bu" 4 -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. -.IP "\(bu" 4 -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 (use of unsigned avoids possible sign extension). -.IP "\(bu" 4 -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 (use of unsigned -avoids possible sign extension). -.IP "\(bu" 4 -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. -.IP "\(bu" 4 -If the file contains a 16X bit-field and user space specifies a 4J -int array[4], then the results are undetermined. -.RE -.RS 4 -.Sp -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.] -.Sp -In addition to setting data type and size, the \fBtype\fR -specification allows a few ancillary parameters to be set, using the -full syntax for \fBtype\fR: -.Sp -.Vb 1 -\& [@][n]<type>[[['B']poff]][:[tlmin[:tlmax[:binsiz]]]] -.Ve -.Sp -The special character \*(L"@\*(R" 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. -.Sp -The [n] value is an integer that specifies the -number of elements that are in this column (default is 1). \s-1TLMIN\s0, -\&\s-1TLMAX\s0, and \s-1BINSIZ\s0 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 \s-1TLMAX\s0, and \s-1TLMIN\s0 and \s-1BINSIZ\s0 are set to 1. -.Sp -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. -.Sp -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 -\&\*(L"@I[2]\*(R" specifies the third (i.e., starting from 0) element in the -array pointed to by the pointer value. A value of \*(L"@2I[4]\*(R" specifies -the fifth and sixth values in the array. For example, consider the -following specification: -.Sp -.Vb 12 -\& typedef struct EvStruct{ -\& short x[4], *atp; -\& } *Event, EventRec; -\& /* set up the (hardwired) columns */ -\& FunColumnSelect( fun, sizeof(EventRec), NULL, -\& "2i", "2I ", "w", FUN_OFFSET(Event, x), -\& "2i2", "2I[2]", "w", FUN_OFFSET(Event, x), -\& "at2p", "@2I", "w", FUN_OFFSET(Event, atp), -\& "at2p4", "@2I[4]", "w", FUN_OFFSET(Event, atp), -\& "atp9", "@I[9]", "w", FUN_OFFSET(Event, atp), -\& "atb20", "@I[B20]", "w", FUN_OFFSET(Event, atb), -\& NULL); -.Ve -.Sp -Here we have specified the following columns: -.IP "\(bu" 4 -2i: two short ints in an array which is stored as part the -record -.IP "\(bu" 4 -2i2: the 3rd and 4th elements of an array which is stored -as part of the record -.IP "\(bu" 4 -an array of at least 10 elements, not stored in the record but -allocated elsewhere, and used by three different columns: -.RS 4 -.IP "\(bu" 4 -at2p: 2 short ints which are the first 2 elements of the allocated array -.IP "\(bu" 4 -at2p4: 2 short ints which are the 5th and 6th elements of -the allocated array -.IP "\(bu" 4 -atp9: a short int which is the 10th element of the allocated array -.RE -.RS 4 -.RE -.IP "\(bu" 4 -atb20: a short int which is at byte offset 20 of another allocated array -.RE -.RS 4 -.Sp -In this way, several columns can be specified, all of which are in a -single array. \fB\s-1NB\s0\fR: 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. -.RE -.IP "\(bu" 4 -\&\fBread/write mode\fR: \*(L"r\*(R" means that the column is read from an -input file into user space by -\&\fIFunTableRowGet()\fR, \*(L"w\*(R" means that -the column is written to an output file. Both can specified at the same -time. -.IP "\(bu" 4 -\&\fBoffset\fR: the offset into the user data to store -this column. Typically, the macro \s-1FUN_OFFSET\s0(recname, colname) is used -to define the offset into a record structure. -.PP -When all column arguments have been specified, a final \s-1NULL\s0 argument -must added to signal the column selection list. -.PP -As an alternative to the varargs -\&\fIFunColumnSelect()\fR -routine, a non-varargs routine called -\&\fIFunColumnSelectArr()\fR -also is available. The first three arguments (fun, size, plist) of this -routine are the same as in -\&\fIFunColumnSelect()\fR. -Instead of a variable -argument list, however, -\&\fIFunColumnSelectArr()\fR -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. -.PP -Consider the following example: -.PP -.Vb 5 -\& typedef struct evstruct{ -\& int status; -\& float pi, pha, *phas; -\& double energy; -\& } *Ev, EvRec; -.Ve -.PP -.Vb 6 -\& FunColumnSelect(fun, sizeof(EvRec), NULL, -\& "status", "J", "r", FUN_OFFSET(Ev, status), -\& "pi", "E", "r", FUN_OFFSET(Ev, pi), -\& "pha", "E", "r", FUN_OFFSET(Ev, pha), -\& "phas", "@9E", "r", FUN_OFFSET(Ev, phas), -\& NULL); -.Ve -.PP -Each time a row is read into the Ev struct, the \*(L"status\*(R" column is -converted to an int data type (regardless of its data type in the -file) and stored in the status value of the struct. Similarly, \*(L"pi\*(R" -and \*(L"pha\*(R", and the phas vector are all stored as floats. Note that the -\&\*(L"@\*(R" sign indicates that the \*(L"phas\*(R" 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: -.PP -.Vb 9 -\& /* get rows -- let routine allocate the row array */ -\& while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ -\& /* process all rows */ -\& for(i=0; i<got; i++){ -\& /* point to the i'th row */ -\& ev = ebuf+i; -\& ev->pi = (ev->pi+.5); -\& ev->pha = (ev->pi-.5); -\& } -.Ve -.PP -\&\fIFunColumnSelect()\fR -can also be called to define \*(L"writable\*(R" columns in order to generate a \s-1FITS\s0 -Binary Table, without reference to any input columns. For -example, the following will generate a 4\-column \s-1FITS\s0 binary table when -\&\fIFunTableRowPut()\fR is used to -write Ev records: -.PP -.Vb 5 -\& typedef struct evstruct{ -\& int status; -\& float pi, pha -\& double energy; -\& } *Ev, EvRec; -.Ve -.PP -.Vb 6 -\& FunColumnSelect(fun, sizeof(EvRec), NULL, -\& "status", "J", "w", FUN_OFFSET(Ev, status), -\& "pi", "E", "w", FUN_OFFSET(Ev, pi), -\& "pha", "E", "w", FUN_OFFSET(Ev, pha), -\& "energy", "D", "w", FUN_OFFSET(Ev, energy), -\& NULL); -.Ve -.PP -All columns are declared to be write\-only, so presumably the column -data is being generated or read from some other source. -.PP -In addition, -\&\fIFunColumnSelect()\fR -can be called to define \fBboth\fR \*(L"readable\*(R" and \*(L"writable\*(R" columns. -In this case, the \*(L"read\*(R" columns -are associated with an input file, while the \*(L"write\*(R" columns are -associated with the output file. Of course, columns can be specified as both -\&\*(L"readable\*(R" and \*(L"writable\*(R", in which case they are read from input -and (possibly modified data values are) written to the output. -The -\&\fIFunColumnSelect()\fR -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 -Funtools reference handle. -.PP -Consider the following example: -.PP -.Vb 5 -\& typedef struct evstruct{ -\& int status; -\& float pi, pha, *phas; -\& double energy; -\& } *Ev, EvRec; -.Ve -.PP -.Vb 7 -\& FunColumnSelect(fun, sizeof(EvRec), NULL, -\& "status", "J", "r", FUN_OFFSET(Ev, status), -\& "pi", "E", "rw", FUN_OFFSET(Ev, pi), -\& "pha", "E", "rw", FUN_OFFSET(Ev, pha), -\& "phas", "@9E", "rw", FUN_OFFSET(Ev, phas), -\& "energy", "D", "w", FUN_OFFSET(Ev, energy), -\& NULL); -.Ve -.PP -As in the \*(L"read\*(R" example above, each time an row is read into the Ev -struct, the \*(L"status\*(R" column is converted to an int data type -(regardless of its data type in the file) and stored in the status -value of the struct. Similarly, \*(L"pi\*(R" and \*(L"pha\*(R", and the phas vector -are all stored as floats. Since the \*(L"pi\*(R", \*(L"pha\*(R", and \*(L"phas\*(R" variables -are declared as \*(L"writable\*(R" as well as \*(L"readable\*(R", they also will be -written to the output file. Note, however, that the \*(L"status\*(R" variable -is declared as \*(L"readable\*(R" only, and hence it will not be written to -an output file. Finally, the \*(L"energy\*(R" column is declared as -\&\*(L"writable\*(R" only, meaning it will not be read from the input file. In -this case, it can be assumed that \*(L"energy\*(R" will be calculated in the -program before being output along with the other values. -.PP -In these simple cases, only the columns specified as \*(L"writable\*(R" will -be output using -\&\fIFunTableRowPut()\fR. 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 \fBmerge=[type]\fR keyword is provided in the plist string. -.PP -The \fBmerge=[type]\fR 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 -Funtools reference handle -for the output file. In this case, each time -\&\fIFunTableRowGet()\fR is called, the -raw input rows are saved in a special buffer. If -\&\fIFunTableRowPut()\fR then is called -(before another call to -\&\fIFunTableRowGet()\fR), the contents -of the raw input rows are merged with the user rows according to the -value of \fBtype\fR as follows: -.IP "\(bu" 4 -\&\fBupdate\fR: add new user columns, and update value of existing ones (maintaining the input data type) -.IP "\(bu" 4 -\&\fBreplace\fR: add new user columns, and replace the data type -and value of existing ones. (Note 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.) -.IP "\(bu" 4 -\&\fBappend\fR: only add new columns, do not \*(L"replace\*(R" or \*(L"update\*(R" existing ones -.PP -Consider the example above. If \fBmerge=update\fR is specified in the -plist string, then \*(L"energy\*(R" will be added to the input columns, and -the values of \*(L"pi\*(R", \*(L"pha\*(R", and \*(L"phas\*(R" will be taken from the user -space (i.e., the values will be updated from the original values, if -they were changed by the program). The data type for \*(L"pi\*(R", \*(L"pha\*(R", and -\&\*(L"phas\*(R" will be the same as in the original file. If -\&\fBmerge=replace\fR 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 \fBmerge=append\fR is specified, none of -these three columns will be updated, and only the \*(L"energy\*(R" column will -be added. Note that in all cases, \*(L"status\*(R" will be written from the -input data, not from the user record, since it was specified as read\-only. -.PP -Standard applications will call -\&\fIFunColumnSelect()\fR -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 (contact -us if you do!) -.PP -By default, \fIFunColumnSelect()\fR -reads/writes rows to/from an \*(L"array of structs\*(R", 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 \s-1IO\s0 to return a \*(L"struct of arrays\*(R" so that each of the -returned columns are contiguous by specifying \fBorg=structofarrays\fR -(abbreviation: \fBorg=soa\fR) in the plist. -(The default case is \fBorg=arrayofstructs\fR or \fBorg=aos\fR.) -.PP -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 - \fIFunColumnSelect()\fR -as follows: -.PP -.Vb 6 -\& typedef struct evstruct{ -\& short region; -\& double x, y; -\& int pi, pha; -\& double time; -\& } *Ev, EvRec; -.Ve -.PP -.Vb 7 -\& got = FunColumnSelect(fun, sizeof(EvRec), NULL, -\& "x", "D:10:10", mode, FUN_OFFSET(Ev, x), -\& "y", "D:10:10", mode, FUN_OFFSET(Ev, y), -\& "pi", "J", mode, FUN_OFFSET(Ev, pi), -\& "pha", "J", mode, FUN_OFFSET(Ev, pha), -\& "time", "1D", mode, FUN_OFFSET(Ev, time), -\& NULL); -.Ve -.PP -Subsequently, each call to -\&\fIFunTableRowGet()\fR -will return an array of structs, one for each returned row. If instead you -wanted to read columns into contiguous arrays, you specify \fBorg=soa\fR: -.PP -.Vb 6 -\& typedef struct aevstruct{ -\& short region[MAXROW]; -\& double x[MAXROW], y[MAXROW]; -\& int pi[MAXROW], pha[MAXROW]; -\& double time[MAXROW]; -\& } *AEv, AEvRec; -.Ve -.PP -.Vb 7 -\& got = FunColumnSelect(fun, sizeof(AEvRec), "org=soa", -\& "x", "D:10:10", mode, FUN_OFFSET(AEv, x), -\& "y", "D:10:10", mode, FUN_OFFSET(AEv, y), -\& "pi", "J", mode, FUN_OFFSET(AEv, pi), -\& "pha", "J", mode, FUN_OFFSET(AEv, pha), -\& "time", "1D", mode, FUN_OFFSET(AEv, time), -\& NULL); -.Ve -.PP -Note that the only modification to the call is in the plist string. -.PP -Of course, instead of using statically allocated arrays, you also can specify -dynamically allocated pointers: -.PP -.Vb 7 -\& /* pointers to arrays of columns (used in struct of arrays) */ -\& typedef struct pevstruct{ -\& short *region; -\& double *x, *y; -\& int *pi, *pha; -\& double *time; -\& } *PEv, PEvRec; -.Ve -.PP -.Vb 8 -\& got = FunColumnSelect(fun, sizeof(PEvRec), "org=structofarrays", -\& "$region", "@I", mode, FUN_OFFSET(PEv, region), -\& "x", "@D:10:10", mode, FUN_OFFSET(PEv, x), -\& "y", "@D:10:10", mode, FUN_OFFSET(PEv, y), -\& "pi", "@J", mode, FUN_OFFSET(PEv, pi), -\& "pha", "@J", mode, FUN_OFFSET(PEv, pha), -\& "time", "@1D", mode, FUN_OFFSET(PEv, time), -\& NULL); -.Ve -.PP -Here, the actual storage space is either allocated by the user or by the -\&\fIFunColumnSelect()\fR call). -.PP -In all of the above cases, the same call is made to retrieve rows, e.g.: -.PP -.Vb 1 -\& buf = (void *)FunTableRowGet(fun, NULL, MAXROW, NULL, &got); -.Ve -.PP -However, the individual data elements are accessed differently. -For the default case of an \*(L"array of structs\*(R", the -individual row records are accessed using: -.PP -.Vb 5 -\& for(i=0; i<got; i++){ -\& ev = (Ev)buf+i; -\& fprintf(stdout, "%.2f\et%.2f\et%d\et%d\et%.4f\et%.4f\et%21.8f\en", -\& ev->x, ev->y, ev->pi, ev->pha, ev->dx, ev->dy, ev->time); -\& } -.Ve -.PP -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: -.PP -.Vb 6 -\& aev = (AEv)buf; -\& for(i=0; i<got; i++){ -\& fprintf(stdout, "%.2f\et%.2f\et%d\et%d\et%.4f\et%.4f\et%21.8f\en", -\& aev->x[i], aev->y[i], aev->pi[i], aev->pha[i], -\& aev->dx[i], aev->dy[i], aev->time[i]); -\& } -.Ve -.PP -Support for struct of arrays in the -\&\fIFunTableRowPut()\fR -call is handled analogously. -.PP -See the evread example code -and -evmerge example code -for working examples of how -\&\fIFunColumnSelect()\fR is used. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funflush.3 b/funtools/man/man3/funflush.3 deleted file mode 100644 index 611dfc3..0000000 --- a/funtools/man/man3/funflush.3 +++ /dev/null @@ -1,212 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funflush 3" -.TH funflush 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunFlush \- flush data to output file -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 1 -\& void FunFlush(Fun fun, char *plist) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fBFunFlush\fR routine will flush data to a \s-1FITS\s0 output file. In -particular, it can be called after all rows have been written (using -the \fIFunTableRowPut()\fR routine) -in order to add the null padding that is required to complete a \s-1FITS\s0 -block. It also should be called after completely writing an image using -\&\fIFunImagePut()\fR or after writing -the final row of an image using -\&\fIFunTableRowPut()\fR. -.PP -The \fBplist\fR (i.e., parameter list) argument is a string -containing one or more comma-delimited \fBkeyword=value\fR -parameters. If the plist string contains the parameter -\&\*(L"copy=remainder\*(R" and the file was opened with a reference file, which, -in turn, was opened for extension copying (i.e. the input -\&\fIFunOpen()\fR mode also was \*(L"c\*(R" or \*(L"C\*(R"), -then FunFlush also will copy the remainder of the \s-1FITS\s0 extensions from -the input reference file to the output file. This normally would be -done only at the end of processing. -.PP -Note that \fIFunFlush()\fR is called -with \*(L"copy=remainder\*(R" in the mode string by \fIFunClose()\fR. This means -that if you close the output file before the reference input file, it -is not necessary to call -\&\fIFunFlush()\fR explicitly, unless you -are writing more than one extension. See the -evmerge example code. However, it is safe to -call \fIFunFlush()\fR more than once -without fear of re-writing either the padding or the copied -extensions. -.PP -In addition, if \fIFunFlush()\fR is -called on an output file with the plist set to \*(L"copy=reference\*(R" 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: -.PP -.Vb 22 -\& /* process each input extension in turn */ -\& for(ext=0; ;ext++){ -\& /* get new extension name */ -\& sprintf(tbuf, "%s[%d]", argv[1], ext); -\& /* open input extension -- if we cannot open it, we are done */ -\& if( !(ifun=FunOpen(tbuf, "r", NULL)) ) -\& break; -\& /* make the new extension the reference handle for the output file */ -\& FunInfoPut(ofun, FUN_IFUN, &ifun, 0); -\& /* if its not a binary table, just write it out */ -\& if( !(s=FunParamGets(ifun, "XTENSION", 0, NULL, &got)) || -\& strcmp(s, "BINTABLE")){ -\& if( s ) free(s); -\& FunFlush(ofun, "copy=reference"); -\& FunClose(ifun); -\& continue; -\& } -\& else{ -\& /* process binary table */ -\& .... -\& } -\& } -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funimageget.3 b/funtools/man/man3/funimageget.3 deleted file mode 100644 index 091765d..0000000 --- a/funtools/man/man3/funimageget.3 +++ /dev/null @@ -1,332 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funimageget 3" -.TH funimageget 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunImageGet \- get an image or image section -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 1 -\& void *FunImageGet(Fun fun, void *buf, char *plist) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunImageGet()\fB\fR 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 -\&\fBbincols=\fR keyword (using appropriate default columns as -necessary), after which the image section and bin factors are -applied. In both cases, the data is automatically converted from \s-1FITS\s0 -to native format, if necessary. -.PP -The first argument is the Funtools handle returned by -\&\fIFunOpen()\fR. The second \fBbuf\fR -argument is a pointer to a data buffer to fill. If \s-1NULL\s0 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 -Funtools image sectioning -on the command line. -.PP -The third \fBplist\fR (i.e., parameter list) argument is a string -containing one or more comma-delimited \fBkeyword=value\fR -parameters. It can be used to specify the return data type using the -\&\fBbitpix=\fR 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 \s-1FITS\s0 binary tables. -.PP -If the \fBbitpix=\fR keyword is supplied in the plist string, the data -type of the returned image will be one of the supported \s-1FITS\s0 image -data types: -.IP "\(bu" 4 -8 unsigned char -.IP "\(bu" 4 -16 short -.IP "\(bu" 4 -32 int -.IP "\(bu" 4 -\&\-32 float -.IP "\(bu" 4 -\&\-64 double -.PP -For example: -.PP -.Vb 4 -\& void *buf; -\& /* extract data section into an image buffer */ -\& if( !(buf = FunImageGet(fun, NULL, NULL)) ) -\& gerror(stderr, "could not FunImageGet: %s\en", iname); -.Ve -.PP -will allocate buf and retrieve the image in the file data format. In -this case, you will have to determine the data type (using the -\&\s-1FUN_SECT_BITPIX\s0 value in the -\&\fIFunInfoGet()\fR -routine) -and then use a switch statement to process each data type: -.PP -.Vb 17 -\& int bitpix; -\& void *buf; -\& unsigned char *cbuf; -\& short *sbuf; -\& int *ibuf; -\& ... -\& buf = FunImageGet(fun, NULL, NULL); -\& FunInfoGet(fun, FUN_SECT_BITPIX, &bitpix, 0); -\& /* set appropriate data type buffer to point to image buffer */ -\& switch(bitpix){ -\& case 8: -\& cbuf = (unsigned char *)buf; break; -\& case 16: -\& sbuf = (short *)buf; break; -\& case 32: -\& ibuf = (int *)buf; break; -\& ... -.Ve -.PP -See the -imblank example code -for more details on how to process an image when the data type is not -specified beforehand. -.PP -It often is easier to specify the data type directly: -.PP -.Vb 4 -\& double *buf; -\& /* extract data section into a double image buffer */ -\& if( !(buf = FunImageGet(fun, NULL, "bitpix=-64")) ) -\& gerror(stderr, "could not FunImageGet: %s\en", iname); -.Ve -.PP -will extract the image while converting to type double. -.PP -On success, a pointer to the image buffer is returned. (This will be -the same as the second argument, if \s-1NULL\s0 is not passed to the latter.) -On error, \s-1NULL\s0 is returned. -.PP -In summary, to retrieve image or row data into a binned image, you simply -call \fIFunOpen()\fR followed by -\&\fIFunImageGet()\fR. Generally, you -then will want to call -\&\fIFunInfoGet()\fR -to retrieve the -axis dimensions (and data type) of the section you are processing -(so as to take account of sectioning and blocking of the original data): -.PP -.Vb 4 -\& double *buf; -\& int i, j; -\& int dim1, dim2; -\& ... other declarations, etc. -.Ve -.PP -.Vb 3 -\& /* open the input FITS file */ -\& if( !(fun = FunOpen(argv[1], "rc", NULL)) ) -\& gerror(stderr, "could not FunOpen input file: %s\en", argv[1]); -.Ve -.PP -.Vb 3 -\& /* extract and bin the data section into a double float image buffer */ -\& if( !(buf = FunImageGet(fun, NULL, "bitpix=-64")) ) -\& gerror(stderr, "could not FunImageGet: %s\en", argv[1]); -.Ve -.PP -.Vb 2 -\& /* get dimension information from funtools structure */ -\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0); -.Ve -.PP -.Vb 4 -\& /* loop through pixels and reset values below limit to value */ -\& for(i=0; i<dim1*dim2; i++){ -\& if( buf[i] <= blimit ) buf[i] = bvalue; -\& } -.Ve -.PP -Another useful plist string value is \*(L"mask=all\*(R", which returns an -image populated with regions id values. Image pixels within a region -will contain the associated region id (region values start at 1), and -otherwise will contain a 0 value. Thus, the returned image is a -region mask which can be used to process the image data (which -presumably is retrieved by a separate call to FunImageGet) pixel by -pixel. -.PP -If a \s-1FITS\s0 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 \fBbincols=(x,y)\fR keyword: -.PP -.Vb 1 -\& funcnts "foo.ev[EVENTS,bincols=(detx,dety)]" -.Ve -.PP -The full form of the \fBbincols=\fR specifier is: -.PP -.Vb 1 -\& bincols=([xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]]]) -.Ve -.PP -where the tlmin, tlmax, and binsiz specifiers determine the image binning -dimensions: -.PP -.Vb 2 -\& dim = (tlmax - tlmin)/binsiz (floating point data) -\& dim = (tlmax - tlmin)/binsiz + 1 (integer data) -.Ve -.PP -These tlmin, tlmax, and binsiz specifiers can be omitted if \s-1TLMIN\s0, -\&\s-1TLMAX\s0, and \s-1TDBIN\s0 header parameters (respectively) are present in the -\&\s-1FITS\s0 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. -.PP -If \fBbincols\fR is not specified on the command line, Funtools tries -to use appropriate defaults: it looks for the environment variable -\&\s-1FITS_BINCOLS\s0 (or \s-1FITS_BINKEY\s0). Then it looks for the Chandra -parameters \s-1CPREF\s0 (or \s-1PREFX\s0) in the \s-1FITS\s0 binary table header. Failing -this, it looks for columns named \*(L"X\*(R" and \*(L"Y\*(R" and if these are not -found, it looks for columns containing the characters \*(L"X\*(R" and \*(L"Y\*(R". -.PP -See Binning \s-1FITS\s0 Binary Tables and -Non-FITS Event Files for more information. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funimageput.3 b/funtools/man/man3/funimageput.3 deleted file mode 100644 index 9618944..0000000 --- a/funtools/man/man3/funimageput.3 +++ /dev/null @@ -1,225 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funimageput 3" -.TH funimageput 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunImagePut \- put an image to a Funtools file -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 2 -\& int FunImagePut(Fun fun, void *buf, int dim1, int dim2, int bitpix, -\& char *plist) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunImagePut()\fB\fR routine outputs an image array to a \s-1FITS\s0 -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 \s-1HDU\s0 is written. Otherwise, an -image extension is written. -.PP -The first argument is the Funtools handle returned by -\&\fIFunOpen()\fR. The second \fBbuf\fR -argument is a pointer to a data buffer to write. The \fBdim1\fRand -\&\fBdim2\fR arguments that follow specify the dimensions of the image, -where dim1 corresponds to naxis1 and dim2 corresponds to naxis2. The -\&\fBbitpix\fR argument specifies the data type of the image and can -have the following FITS-standard values: -.IP "\(bu" 4 -8 unsigned char -.IP "\(bu" 4 -16 short -.IP "\(bu" 4 -32 int -.IP "\(bu" 4 -\&\-32 float -.IP "\(bu" 4 -\&\-64 double -.PP -When \fIFunTableRowPut()\fR is first -called for a given image, Funtools checks to see if the primary header -has already been written (by having previously written an image or a -binary table.) If not, this image is written to the primary \s-1HDU\s0. -Otherwise, it is written to an image extension. -.PP -Thus, a simple program to generate a \s-1FITS\s0 image might look like this: -.PP -.Vb 16 -\& int i; -\& int dim1=512, dim2=512; -\& double *dbuf; -\& Fun fun; -\& dbuf = malloc(dim1*dim2*sizeof(double)); -\& /* open the output FITS image, preparing to copy input params */ -\& if( !(fun = FunOpen(argv[1], "w", NULL)) ) -\& gerror(stderr, "could not FunOpen output file: %s\en", argv[1]); -\& for(i=0; i<(dim1*dim2); i++){ -\& ... fill dbuf ... -\& } -\& /* put the image (header will be generated automatically */ -\& if( !FunImagePut(fun, buf, dim1, dim2, \-64, NULL) ) -\& gerror(stderr, "could not FunImagePut: %s\en", argv[1]); -\& FunClose(fun); -\& free(dbuf); -.Ve -.PP -In addition, if a -Funtools reference handle -was specified when this table was opened, the -parameters from this -Funtools reference handle -are merged into the new image -header. Furthermore, if a reference image was specified during -\&\fIFunOpen()\fR, the values of -\&\fBdim1\fR, \fBdim2\fR, and \fBbitpix\fR 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 \s-1FITS\s0 file. See the -imblank example code. -.PP -The data are assumed to be in the native machine format and will -automatically be swapped to \s-1FITS\s0 big-endian format if necessary. This -behavior can be over-ridden with the \fBconvert=[true|false]\fR -keyword in the \fBplist\fR param list string. -.PP -When you are finished writing the image, you should call -\&\fIFunFlush()\fR to write out the \s-1FITS\s0 -image padding. However, this is not necessary if you subsequently call -\&\fIFunClose()\fR without doing any other I/O to the \s-1FITS\s0 file. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funimagerowget.3 b/funtools/man/man3/funimagerowget.3 deleted file mode 100644 index 50a0979..0000000 --- a/funtools/man/man3/funimagerowget.3 +++ /dev/null @@ -1,215 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funimagerowget 3" -.TH funimagerowget 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunImageRowGet \- get row(s) of an image -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 2 -\& void *FunImageRowGet(Fun fun, void *buf, int rstart, int rstop, -\& char *plist) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunImageRowGet()\fB\fR 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 -\&\fBbincols=\fR keyword (using appropriate default columns as needed), -after which the image section and bin factors are applied. -.PP -The first argument is the Funtools handle returned by -\&\fIFunOpen()\fR. The second \fBbuf\fR -argument is a pointer to a data buffer to fill. If \s-1NULL\s0 is specified, -\&\fIFunImageGet()\fR will allocate a buffer of the appropriate size. -.PP -The third and fourth arguments specify the first and last row to -retrieve. Rows are counted starting from 1, up to the value of -\&\s-1FUN_YMAX\s0(fun). The final \fBplist\fR (i.e., parameter list) argument -is a string containing one or more comma-delimited -\&\fBkeyword=value\fR parameters. It can be used to specify the return -data type using the \fBbitpix=\fR 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 -\&\s-1FITS\s0 binary tables. -.PP -If the \fBbitpix=\fRvalue is supplied in the plist string, the data -type of the returned image will be one of the supported \s-1FITS\s0 image -data types: -.IP "\(bu" 4 -8 unsigned char -.IP "\(bu" 4 -16 short -.IP "\(bu" 4 -32 int -.IP "\(bu" 4 -\&\-32 float -.IP "\(bu" 4 -\&\-64 double -.PP -For example: -.PP -.Vb 17 -\& double *drow; -\& Fun fun; -\& ... open files ... -\& /* get section dimensions */ -\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0); -\& /* allocate one line's worth */ -\& drow = malloc(dim1*sizeof(double)); -\& /* retrieve and process each input row (starting at 1) */ -\& for(i=1; i <= dim2; i++){ -\& if( !FunImageRowGet(fun, drow, i, i, "bitpix=-64") ) -\& gerror(stderr, "can't FunImageRowGet: %d %s\en", i, iname); -\& /* reverse the line */ -\& for(j=1; j<=dim1; j++){ -\& ... process drow[j-1] ... -\& } -\& } -\& ... -.Ve -.PP -On success, a pointer to the image buffer is returned. (This will be -the same as the second argument, if \s-1NULL\s0 is not passed to the latter.) -On error, \s-1NULL\s0 is returned. Note that the considerations described -above for specifying binning columns in -\&\fIFunImageGet()\fR also apply to -\&\fB\f(BIFunImageRowGet()\fB\fR. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funimagerowput.3 b/funtools/man/man3/funimagerowput.3 deleted file mode 100644 index e76bc7f..0000000 --- a/funtools/man/man3/funimagerowput.3 +++ /dev/null @@ -1,202 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funimagerowput 3" -.TH funimagerowput 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunImageRowPut \- put row(s) of an image -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 2 -\& void *FunImageRowPut(Fun fun, void *buf, int rstart, int rstop, -\& int dim1, int dim2, int bitpix, char *plist) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunImageRowPut()\fB\fR routine writes one or more image rows to -the specified \s-1FITS\s0 image file. The first argument is the Funtools -handle returned by \fIFunOpen()\fR. -The second \fBbuf\fR 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. -.PP -The \fBdim1\fRand \fBdim2\fR arguments that follow specify the -dimensions, where dim1 corresponds to naxis1 and dim2 corresponds to -naxis2. The \fBbitpix\fR argument data type of the image and can -have the following FITS-standard values: -.IP "\(bu" 4 -8 unsigned char -.IP "\(bu" 4 -16 short -.IP "\(bu" 4 -32 int -.IP "\(bu" 4 -\&\-32 float -.IP "\(bu" 4 -\&\-64 double -.PP -For example: -.PP -.Vb 16 -\& double *drow; -\& Fun fun, fun2; -\& ... open files ... -\& /* get section dimensions */ -\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0); -\& /* allocate one line's worth */ -\& drow = malloc(dim1*sizeof(double)); -\& /* retrieve and process each input row (starting at 1) */ -\& for(i=1; i <= dim2; i++){ -\& if( !FunImageRowGet(fun, drow, i, i, "bitpix=-64") ) -\& gerror(stderr, "can't FunImageRowGet: %d %s\en", i, iname); -\& ... process drow ... -\& if( !FunImageRowPut(fun2, drow, i, i, 64, NULL) ) -\& gerror(stderr, "can't FunImageRowPut: %d %s\en", i, oname); -\& } -\& ... -.Ve -.PP -The data are assumed to be in the native machine format and will -automatically be swapped to big-endian \s-1FITS\s0 format if necessary. This -behavior can be over-ridden with the \fBconvert=[true|false]\fR -keyword in the \fBplist\fR param list string. -.PP -When you are finished writing the image, you should call -\&\fIFunFlush()\fR to write out the \s-1FITS\s0 -image padding. However, this is not necessary if you subsequently call -\&\fIFunClose()\fR without doing any other I/O to the \s-1FITS\s0 file. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funinfoget.3 b/funtools/man/man3/funinfoget.3 deleted file mode 100644 index 6bb14c9..0000000 --- a/funtools/man/man3/funinfoget.3 +++ /dev/null @@ -1,335 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funinfoget 3" -.TH funinfoget 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunInfoGet \- get information from Funtools struct -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 1 -\& int FunInfoGet(Fun fun, int type, char *addr, ...) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunInfoGet()\fB\fR 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. -.PP -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: -.PP -.Vb 3 -\& FUN_SECT_DIM1 int /* dim1 for section */ -\& FUN_SECT_DIM2 int /* dim2 for section */ -\& FUN_SECT_BITPIX int /* bitpix for section */ -.Ve -.PP -These would be used to determine the dimensions and data type of image -data retrieved using the -\&\fIFunImageGet()\fR routine. For -example: -.PP -.Vb 17 -\& /* extract and bin the data section into an image buffer */ -\& buf = FunImageGet(fun, NULL, NULL); -\& /* get required information from funtools structure. -\& this should come after the FunImageGet() call, in case the call -\& changed sect_bitpix */ -\& FunInfoGet(fun, -\& FUN_SECT_BITPIX, &bitpix, -\& FUN_SECT_DIM1, &dim1, -\& FUN_SECT_DIM2, &dim2, -\& 0); -\& /* loop through pixels and reset values below limit to value */ -\& for(i=0; i<dim1*dim2; i++){ -\& switch(bitpix){ -\& case 8: -\& if( cbuf[i] <= blimit ) cbuf[i] = bvalue; -\& ... -\& } -.Ve -.PP -It is important to bear in mind that the call to -\&\fIFunImageGet()\fR -can change the value of \s-1FUN_SECT_BITPIX\s0 (e.g. if \*(L"bitpix=n\*(R" is passed -in the param list). Therefore, a call to -\&\fIFunInfoGet()\fR -should be made \fBafter\fR the call to -\&\fIFunImageGet()\fR, -in order to retrieve the updated bitpix value. -See the imblank example code for more -details. -.PP -It also can be useful to retrieve the World Coordinate System -information from the Funtools structure. Funtools uses the the \s-1WCS\s0 -Library developed by Doug Mink at \s-1SAO\s0, which is available -here. -(More information about the WCSTools project in general can be found -here.) -The \fIFunOpen()\fR routine initializes -two \s-1WCS\s0 structures that can be used with this \s-1WCS\s0 Library. -Applications can retrieve either of these two \s-1WCS\s0 structures using -\&\fB\f(BIFunInfoGet()\fB\fR: -.PP -.Vb 2 -\& FUN_WCS struct WorldCoor * /* wcs structure, for image coordinates*/ -\& FUN_WCS0 struct WorldCoor * /* wcs structure, for physical coordinates */ -.Ve -.PP -The structure retrieved by \s-1FUN_WCS\s0 is a \s-1WCS\s0 library handle containing -parameters suitable for use with image coordinates, regardless of whether the -data are images or tables. For this structure, the \s-1WCS\s0 reference point -(\s-1CRPIX\s0) has been converted to image coordinates if the underlying file -is a table (and therefore in physical coordinates). You therefore must -ensure that the positions being passed to a routine like pix2wcs are in -image coordinates. The \s-1FUN_WCS0\s0 structure has not had its \s-1WCS\s0 -reference point converted to image coordinates. It therefore is useful -when passing processing physical coordinates from a table. -.PP -Once a \s-1WCS\s0 structure has been retrieved, it can be used as the first -argument to the \s-1WCS\s0 library routines. (If the structure is \s-1NULL\s0, no -\&\s-1WCS\s0 information was contained in the file.) The two important \s-1WCS\s0 routines -that Funtools uses are: -.PP -.Vb 5 -\& #include <wcs.h> -\& void pix2wcs (wcs,xpix,ypix,xpos,ypos) -\& struct WorldCoor *wcs; /* World coordinate system structure */ -\& double xpix,ypix; /* x and y coordinates in pixels */ -\& double *xpos,*ypos; /* RA and Dec in degrees (returned) */ -.Ve -.PP -which converts pixel coordinates to sky coordinates, and: -.PP -.Vb 5 -\& void wcs2pix (wcs, xpos, ypos, xpix, ypix, offscl) -\& 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 */ -.Ve -.PP -which converts sky coordinates to pixel coordinates. Again, please note -that the wcs structure returned by \s-1FUN_WCS\s0 assumes that image coordinates -are passed to the pix2wcs routine, while \s-1FUN_WCS0\s0 assumes that physical -coordinates are passed. -.PP -Note that funtools.h file automatically includes wcs.h. An example -program that utilizes these \s-1WCS\s0 structure to call \s-1WCS\s0 Library routines -is twcs.c. -.PP -The following is the complete list of information that can be returned: -.PP -.Vb 52 -\& 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 (naxis2) */ -\& FUN_ROWSIZE int /* size of user row struct */ -\& FUN_BINCOLS char * /* specified binning columns */ -\& FUN_OVERFLOW int /* overflow detected during binning? */ -\& /* 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' (sum), 'a' (average) 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 */ -.Ve -.PP -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 evnext example code. 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. -.PP -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 \s-1FUN_RAWBUF\s0 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. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funinfoput.3 b/funtools/man/man3/funinfoput.3 deleted file mode 100644 index 986fa9c..0000000 --- a/funtools/man/man3/funinfoput.3 +++ /dev/null @@ -1,246 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funinfoput 3" -.TH funinfoput 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunInfoPut \- put information into a Funtools struct -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 1 -\& int FunInfoPut(Fun fun, int type, char *addr, ...) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunInfoPut()\fB\fR 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. -.PP -The full list of available information is described above with the -\&\fIFunInfoPut()\fR 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. -.PP -For input, multiple extensions are handled by calling -\&\fIFunOpen()\fR 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 (including their -header parameters) to a single output file. To accomplish this, you -open successive input extensions using -\&\fIFunOpen()\fR and then call -\&\fB\f(BIFunInfoPut()\fB\fR to set the -Funtools reference handle -of the output file to that of the newly opened input extension: -.PP -.Vb 4 -\& /* open a new input extension */ -\& ifun=FunOpen(tbuf, "r", NULL)) ) -\& /* make the new extension the reference handle for the output file */ -\& FunInfoPut(ofun, FUN_IFUN, &ifun, 0); -.Ve -.PP -Resetting \s-1FUN_IFUN\s0 has same effect as when a funtools handle is passed -as the final argument to -\&\fIFunOpen()\fR. 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. -.PP -For example, in a binary table, after resetting \s-1FUN_IFUN\s0 you can then -call \fIFunColumnSelect()\fR to -select the columns for output. When you then call -\&\fIFunImagePut()\fR or <A -HREF=\*(L"./library.html#funtablerowput\*(R">\fIFunTableRowPut()\fR, a new -extension will be written that contains the header parameters from the -reference extension. Remember to call -\&\fIFunFlush()\fR to complete output of a -given extension. -.PP -A complete example of this capability is given -in the evcol example code. -The central algorithm is: -.IP "\(bu" 4 -open the output file without a reference handle -.IP "\(bu" 4 -loop: open each input extension in turn -.RS 4 -.IP "\(bu" 4 -set the reference handle for output to the newly opened input extension -.IP "\(bu" 4 -read the input rows or image and perform processing -.IP "\(bu" 4 -write new rows or image to the output file -.IP "\(bu" 4 -flush the output -.IP "\(bu" 4 -close input extension -.RE -.RS 4 -.RE -.IP "\(bu" 4 -close output file -.PP -Note that \fIFunFlush()\fR is called -after processing each input extension in order to ensure that the -proper padding is written to the output file. A call to -\&\fIFunFlush()\fR also ensures that the -extension header is written to the output file in the case where there -are no rows to output. -.PP -If you wish to output a new extension without using a -Funtools reference handle, you can -call \fIFunInfoPut()\fR to reset the \s-1FUN_OPS\s0 value directly. For a binary -table, you would then call \fIFunColumnSelect()\fR to set up the columns for -this new extension. -.PP -.Vb 6 -\& /* reset the operations performed on this handle */ -\& int ops=0; -\& FunInfoPut(ofun, FUN_OPS, &ops, 0); -\& FunColumnSelect(fun, sizeof(EvRec), NULL, -\& "MYCOL", "J", "w", FUN_OFFSET(Ev, mycol), -\& NULL); -.Ve -.PP -Once the \s-1FUN_OPS\s0 variable has been reset, the next I/O call on the -output extension will output the header, as expected. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funlib.3 b/funtools/man/man3/funlib.3 deleted file mode 100644 index 6b4456a..0000000 --- a/funtools/man/man3/funlib.3 +++ /dev/null @@ -1,525 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funlib 3" -.TH funlib 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunLib \- the Funtools Programming Interface -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -A description of the Funtools library. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBIntroduction to the Funtools Programming Interface\fR -.PP -To create a Funtools application, you need to include -the funtools.h definitions file in your code: -.PP -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -You then call Funtools subroutines and functions to access Funtools data. -The most important routines are: -.IP "\(bu" 4 -FunOpen: open a Funtools file -.IP "\(bu" 4 -FunInfoGet: get info about an image or table -.IP "\(bu" 4 -FunImageGet: retrieve image data -.IP "\(bu" 4 -FunImageRowGet: retrieve image data by row -.IP "\(bu" 4 -FunImagePut: output image data -.IP "\(bu" 4 -FunImageRowPut: output image data by row -.IP "\(bu" 4 -FunColumnSelect: select columns in a table for access -.IP "\(bu" 4 -FunTableRowGet: retrieve rows from a table -.IP "\(bu" 4 -FunTableRowPut: output rows to a table -.IP "\(bu" 4 -FunClose: close a Funtools file -.PP -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: -.IP "\(bu" 4 -\&\-lsocket \-lnsl for socket support -.IP "\(bu" 4 -\&\-ldl for dynamic loading -.PP -For example, on a Solaris system using gcc, use the following link line: -.PP -.Vb 1 -\& gcc \-o foo foo.c \-lfuntools \-lsocket \-lnsl \-ldl \-lm -.Ve -.PP -On a Solaris system using Solaris cc, use the following link line: -.PP -.Vb 1 -\& gcc \-o foo foo.c \-lfuntools \-lsocket \-lnsl \-lm -.Ve -.PP -On a Linux system using gcc, use the following link line: -.PP -.Vb 1 -\& gcc \-o foo foo.c \-lfuntools \-ldl \-lm -.Ve -.PP -Once configure has built a Makefile on your platform, the required -\&\*(L"extra\*(R" libraries (aside from \-lm, which always is required) are -specified in that file's \s-1EXTRA_LIBS\s0 variable. For example, under -Linux you will find: -.PP -.Vb 3 -\& grep EXTRA_LIBS Makefile -\& EXTRA_LIBS = \-ldl -\& ... -.Ve -.PP -The Funtools library contains both the zlib library -(http://www.gzip.org/zlib/) and Doug Mink's \s-1WCS\s0 library -(http://tdc\-www.harvard.edu/software/wcstools/). 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. -.PP -\&\fBFuntools Programming Tutorial\fR -.PP -The -\&\fIFunOpen()\fR -function is used to open a \s-1FITS\s0 file, an array, or a raw event file: -.PP -.Vb 4 -\& /* open the input FITS file for reading */ -\& ifun = FunOpen(iname, "r", NULL); -\& /* open the output FITS file for writing, and connect it to the input file */ -\& ofun = FunOpen(iname, "w", ifun); -.Ve -.PP -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 -\&\fIFunOpen()\fR -call as shown above. -.PP -For image data, you then can call -\&\fIFunImageGet()\fR -to read an image into memory. -.PP -.Vb 3 -\& float buf=NULL; -\& /* extract and bin the data section into an image buffer */ -\& buf = FunImageGet(fun, NULL, "bitpix=-32"); -.Ve -.PP -If the (second) buf argument to this call is \s-1NULL\s0, buffer space is allocated -automatically. The (third) plist argument can be used to specify the -return data type of the array. If \s-1NULL\s0 is specified, the data type of -the input file is used. -.PP -To process an image buffer, you would generally make a call to -\&\fIFunInfoGet()\fR to determine the -dimensions of the image (which may have been changed from the original -file dimensions due to Funtools image -sectioning on the command line). In a \s-1FITS\s0 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: -.PP -.Vb 7 -\& buf = FunImageGet(fun, NULL, "bitpix=-32"); -\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0); -\& for(i=1; i<=dim2; i++){ -\& for(j=1; j<=dim1; j++){ -\& ... process buf[((i-1)*dim1)+(j-1)] ... -\& } -\& } -.Ve -.PP -or: -.PP -.Vb 5 -\& buf = FunImageGet(fun, NULL, "bitpix=-32"); -\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0); -\& for(i=0; i<(dim1*dim2); i++){ -\& ... process buf[i] ... -\& } -.Ve -.PP -Finally, you can write the resulting image to disk using -\&\fIFunImagePut()\fR: -.PP -.Vb 1 -\& FunImagePut(fun2, buf, dim1, dim2, \-32, NULL); -.Ve -.PP -Note that Funtools automatically takes care of book-keeping tasks such as -reading and writing \s-1FITS\s0 headers (although you can, of course, write -your own header or add your own parameters to a header). -.PP -For binary tables and raw event files, a call to -\&\fIFunOpen()\fR -will be followed by a call to the -\&\fIFunColumnSelect()\fR -routine to select columns to be read from the input file and/or -written to the output file: -.PP -.Vb 8 -\& typedef struct evstruct{ -\& double time; -\& int time2; -\& } *Ev, EvRec; -\& FunColumnSelect(fun, sizeof(EvRec), NULL, -\& "time", "D", "rw", FUN_OFFSET(Ev, time), -\& "time2", "J", "w", FUN_OFFSET(Ev, time2), -\& NULL); -.Ve -.PP -Columns whose (third) mode argument contains an \*(L"r\*(R" are \*(L"readable\*(R", -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 \*(L"w\*(R" are -\&\*(L"writable\*(R", i.e., these values will be written to the output file. -The -\&\fIFunColumnSelect()\fR -routine also offers the option of automatically merging user -columns with the original input columns when writing the output -rows. -.PP -Once a set of columns has been specified, you can retrieve rows using -\&\fIFunTableRowGet()\fR, -and write the rows using -\&\fIFunTableRowPut()\fR: -.PP -.Vb 17 -\& Ev ebuf, ev; -\& /* get rows -- let routine allocate the array */ -\& while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ -\& /* process all rows */ -\& for(i=0; i<got; i++){ -\& /* point to the i'th row */ -\& ev = ebuf+i; -\& /* time2 is generated here */ -\& ev->time2 = (int)(ev->time+.5); -\& /* change the input time as well */ -\& ev->time = -(ev->time/10.0); -\& } -\& /* write out this batch of rows with the new column */ -\& FunTableRowPut(fun2, (char *)ebuf, got, 0, NULL); -\& /* free row data */ -\& if( ebuf ) free(ebuf); -\& } -.Ve -.PP -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 -\&\s-1FITS\s0 headers (although you can, of course, write your own header or -add your own parameters to a header). -.PP -When all processing is done, you can call -\&\fIFunClose()\fR -to close the file(s): -.PP -.Vb 2 -\& FunClose(fun2); -\& FunClose(fun); -.Ve -.PP -These are the basics of processing \s-1FITS\s0 files (and arrays or raw event -data) 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. -.PP -\&\fBCompiling and Linking\fR -.PP -To create a Funtools application, a software developer will include -the funtools.h definitions file in Funtools code: -.PP -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -The program is linked against the libfuntools.a library, along with the -math library (and the dynamic load library, if the latter is available -on your system): -.PP -.Vb 1 -\& gcc \-o foo foo.c \-lfuntools \-ldl \-lm -.Ve -.PP -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. -.PP -Funtools has been built on the following systems: -.IP "\(bu" 4 -Sun/Solaris 5.X -.IP "\(bu" 4 -Linux/RedHat Linux 5.X,6.X,7.X -.IP "\(bu" 4 -Dec Alpha/OSF1 V4.X -.IP "\(bu" 4 -WindowsNT/Cygwin 1.0 -.IP "\(bu" 4 -\&\s-1SGI/IRIX64\s0 6.5 -.PP -\&\fBA Short Digression on Subroutine Order\fR -.PP -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 \*(L"natural order\*(R" 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. -.PP -For example, if you open a new funtools file for writing using -\&\fIFunOpen()\fR, -then generate an array of image data and call -\&\fIFunImagePut()\fR, -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 -\&\fIFunParamPut()\fR -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. -.PP -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: -.IP "\(bu" 4 -When specifying that input extensions be copied to an output file -via a reference handle, open the output file \fBbefore\fR reading the -input file. (Otherwise the initial copy will not occur). -.IP "\(bu" 4 -Always write parameters to an output file using one of the -\&\fIFunParamPut()\fR calls -\&\fBbefore\fR writing any data. (This is a good idea for all \s-1FITS\s0 -libraries, to avoid having to recopy data is the \s-1FITS\s0 header needs -to be extended by adding a single parameter.) -.IP "\(bu" 4 -If you retrieve an image, and need to know the data -type, use the \s-1FUN_SECT_BITPIX\s0 option of -\&\fIFunInfoGet()\fR, -\&\fBafter\fR calling -\&\fIFunImageGet()\fR, since -it is possible to change the value of \s-1BITPIX\s0 from the latter. -.IP "\(bu" 4 -When specifying that input extensions be copied to an output file -via a reference handle, close the output file \fBbefore\fR closing -input file, or else use -\&\fIFunFlush()\fR -explicitly on the output file -\&\fBbefore\fR closing the input file. (Otherwise the final copy will -not occur). -.PP -We believe that these are the natural rules that are implied in most -\&\s-1FITS\s0 programming tasks. However, we recognize that making explicit use -of \*(L"natural order\*(R" 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. -.PP -\&\fBFuntools Programming Examples\fR -.PP -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: -.IP "\(bu" 4 -evread.c: read and write binary tables -.IP "\(bu" 4 -evcols.c: add column and rows to binary tables -.IP "\(bu" 4 -evmerge.c: merge new columns with existing columns -.IP "\(bu" 4 -evnext.c: manipulate raw data pointers -.IP "\(bu" 4 -imblank.c: blank out image values below a threshold -.IP "\(bu" 4 -asc2fits.c: convert a specific \s-1ASCII\s0 table to \s-1FITS\s0 binary table -.PP -\&\fBThe Funtools Programming Reference Manual\fR -.PP -#include <funtools.h> -.PP -Fun FunOpen(char *name, char *mode, Fun ref) -.PP -void *FunImageGet(Fun fun, void *buf, char *plist) -.PP -int FunImagePut(Fun fun, void *buf, int dim1, int dim2, int bitpix, char *plist) -.PP -void * FunImageRowGet(Fun fun, void *buf, int rstart, int rstop, char *plist) -.PP -void * FunImageRowPut(Fun fun, void *buf, int rstart, int rstop, int dim1, int dim2, int bitpix, char *plist) -.PP -int FunColumnSelect(Fun fun, int size, char *plist, ...) -.PP -void FunColumnActivate(Fun fun, char *s, char *plist) -.PP -int FunColumnLookup(Fun fun, char *s, int which, char **name, int *type, int *mode, int *offset, int *n, int *width) -.PP -void *FunTableRowGet(Fun fun, void *rows, int maxrow, char *plist, int *nrow) -.PP -int FunTableRowPut(Fun fun, void *rows, int nev, int idx, char *plist) -.PP -int FunParamGetb(Fun fun, char *name, int n, int defval, int *got) -.PP -int FunParamGeti(Fun fun, char *name, int n, int defval, int *got) -.PP -double FunParamGetd(Fun fun, char *name, int n, double defval, int *got) -.PP -char *FunParamGets(Fun fun, char *name, int n, char *defval, int *got) -.PP -int FunParamPutb(Fun fun, char *name, int n, int value, char *comm, int append) -.PP -int FunParamPuti(Fun fun, char *name, int n, int value, char *comm, int append) -.PP -int FunParamPutd(Fun fun, char *name, int n, double value, int prec, char *comm, int append) -.PP -int FunParamPuts(Fun fun, char *name, int n, char *value, char *comm, int append) -.PP -int FunInfoGet(Fun fun, int type, ...) -.PP -int FunInfoPut(Fun fun, int type, ...) -.PP -void FunFlush(Fun fun, char *plist) -.PP -void FunClose(Fun fun) -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funopen.3 b/funtools/man/man3/funopen.3 deleted file mode 100644 index f185ea5..0000000 --- a/funtools/man/man3/funopen.3 +++ /dev/null @@ -1,272 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funopen 3" -.TH funopen 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunOpen \- open a Funtools data file -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 1 -\& Fun FunOpen(char *name, char *mode, Fun ref); -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunOpen()\fB\fR routine opens a Funtools data file for reading or -appending, or creates a new \s-1FITS\s0 file for writing. The \fBname\fR -argument specifies the name of the Funtools data file to open. You can -use IRAF-style bracket notation to specify -Funtools Files, Extensions, and Filters. -A separate call should be made each time a different \s-1FITS\s0 extension is -accessed: -.PP -.Vb 7 -\& Fun fun; -\& char *iname; -\& ... -\& if( !(fun = FunOpen(iname, "r", NULL)) ){ -\& fprintf(stderr, "could not FunOpen input file: %s\en", iname); -\& exit(1); -\& } -.Ve -.PP -If \fBmode\fR is \*(L"r\*(R", the file is opened for reading, and processing -is set up to begin at the specified extension. For reading, -\&\fBname\fR can be \fBstdin\fR, in which case the standard input is read. -.PP -If \fBmode\fR is \*(L"w\*(R", 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 \fBname\fR can be \fBstdout\fR, -in which case the standard output is readied for processing. -.PP -If \fBmode\fR is \*(L"a\*(R", the file is created if it does not exist, or -opened if it does exist. Processing starts at the end of the file. -The \fBname\fR can be \fBstdout\fR, in which case the standard -output is readied for processing. -.PP -When a Funtools file is opened for writing or appending, a previously -opened Funtools reference -handle 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 (extension) -header parameters from the input file: -.PP -.Vb 8 -\& Fun fun, fun2; -\& ... -\& /* open input file */ -\& if( !(fun = FunOpen(argv[1], "r", NULL)) ) -\& gerror(stderr, "could not FunOpen input file: %s\en", argv[1]); -\& /* open the output FITS image, inheriting params from input */ -\& if( !(fun2 = FunOpen(argv[2], "w", fun)) ) -\& gerror(stderr, "could not FunOpen output file: %s\en", argv[2]); -.Ve -.PP -Thus, in the above example, the output \s-1FITS\s0 binary table file will -inherit all of the parameters associated with the input binary table -extension. -.PP -A file opened for writing with a -Funtools reference handle also -inherits the selected columns (i.e. those columns chosen for -processing using the -\&\fIFunColumnSelect()\fR routine) -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 -\&\fIFunColumnSelect()\fR routine. -In particular, it is easy to merge user-defined columns with the input -columns to generate a new file. See the -evmerge for a complete example. -.PP -In addition, when a -Funtools reference handle -is supplied in a \fIFunOpen()\fR call, -it is possible also to specify that all other extensions from the -reference file (other than the input extension being processed) should -be copied from the reference file to the output file. This is useful, -for example, in a case where you are processing a \s-1FITS\s0 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 \*(L"C\*(R" or \*(L"c\*(R" to the mode string of the -\&\fIFunOpen()\fR call of the input -reference file. If \*(L"C\*(R" is specified, then other extensions are -\&\fBalways\fR copied (i.e., copy is forced by the application). If -\&\*(L"c\*(R" is used, then other extensions are copied if the user requests -copying by adding a plus sign \*(L"+\*(R" to the extension name in the bracket -specification. For example, the \fBfuntable\fR program utilizes -\&\*(L"c\*(R" mode, giving users the option of copying all other extensions: -.PP -.Vb 6 -\& /* open input file -- allow user copy of other extensions */ -\& if( !(fun = FunOpen(argv[1], "rc", NULL)) ) -\& gerror(stderr, "could not FunOpen input file: %s\en", argv[1]); -\& /* open the output FITS image, inheriting params from input */ -\& if( !(fun2 = FunOpen(argv[2], "w", fun)) ) -\& gerror(stderr, "could not FunOpen output file: %s\en", argv[2]); -.Ve -.PP -Thus, \fBfuntable\fR supports either of these command lines: -.PP -.Vb 4 -\& # copy only the EVENTS extension -\& csh> funtable "test.ev[EVENTS,circle(512,512,10)]" foo.ev -\& # copy ALL extensions -\& csh> funtable "test.ev[EVENTS+,circle(512,512,10)]" foo.ev -.Ve -.PP -Use of a Funtools reference -handle implies that the input file is opened before the output -file. However, it is important to note that if copy mode (\*(L"c\*(R" or \*(L"C\*(R") -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 -\&\fIFunClose()\fR -if the output file is -closed before the input file. Alternatively, it can be done explicitly -by \fIFunFlush()\fR, but again, this -assumes that the input file still is open. -.PP -Upon success \fIFunOpen()\fR returns a -Fun handle that is used in subsequent Funtools calls. On error, \s-1NULL\s0 -is returned. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funparamget.3 b/funtools/man/man3/funparamget.3 deleted file mode 100644 index 1609aae..0000000 --- a/funtools/man/man3/funparamget.3 +++ /dev/null @@ -1,262 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funparamget 3" -.TH funparamget 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunParamGet \- get a Funtools param value -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 1 -\& int FunParamGetb(Fun fun, char *name, int n, int defval, int *got) -.Ve -.PP -.Vb 1 -\& int FunParamGeti(Fun fun, char *name, int n, int defval, int *got) -.Ve -.PP -.Vb 1 -\& double FunParamGetd(Fun fun, char *name, int n, double defval, int *got) -.Ve -.PP -.Vb 1 -\& char *FunParamGets(Fun fun, char *name, int n, char *defval, int *got) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The four routines \fB\f(BIFunParamGetb()\fB\fR, \fB\f(BIFunParamGeti()\fB\fR, -\&\fB\f(BIFunParamGetd()\fB\fR, and \fB\f(BIFunParamGets()\fB\fR, return the value of -a \s-1FITS\s0 header parameter as a boolean, int, double, and string, -respectively. The string returned by \fB\f(BIFunParamGets()\fB\fR is a malloc'ed -copy of the header value and should be freed when no longer needed. -.PP -The first argument is the Fun handle associated with the \s-1FITS\s0 header -being accessed. Normally, the header is associated with the \s-1FITS\s0 -extension that you opened with \fB\f(BIFunOpen()\fB\fR. However, you can use -\&\fIFunInfoPut()\fR to specify access of the primary header. In particular, -if you set the \s-1FUN_PRIMARYHEADER\s0 parameter to 1, then the primary -header is used for all parameter access until the value is reset to -0. For example: -.PP -.Vb 9 -\& int val; -\& FunParamGeti(fun, "NAXIS", 1, 0, &got); # current header -\& val=1; -\& FunInfoPut(fun, FUN_PRIMARYHEADER, &val, 0); # switch to ... -\& FunParamGeti(fun, "NAXIS", 1, 0, &got); # ... primary header -\& FunParamGeti(fun, "NAXIS", 2, 0, &got); # ... primary header -\& val=0; -\& FunInfoPut(fun, FUN_PRIMARYHEADER, &val, 0); # switch back to ... -\& FunParamGeti(fun, "NAXIS", 2, 0, &got); # current header -.Ve -.PP -Alternatively, you can use the \s-1FUN_PRIMARY\s0 macro to access parameters -from the primary header on a per-parameter basis: -.PP -.Vb 2 -\& FunParamGeti(fun, "NAXIS1", 0, 0, &got); # current header -\& FunParamGeti(FUN_PRIMARY(fun), "NAXIS1", 0, 0, &got); # primary header -.Ve -.PP -\s-1NB - \s0 \s-1FUN_PRIMARY\s0 is deprecated. -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 \fIFunInfoPut()\fR to switch between the -extension header and the primary header. -.PP -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. -.PP -The second argument is the name of the parameter to access. The third -\&\fBn\fR 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 \s-1TLMIN\s0 and \s-1TLMAX\s0 for each column in a binary -table, you can use: -.PP -.Vb 4 -\& for(i=0, got=1; got; i++){ -\& fun->cols[i]->tlmin = (int)FunParamGeti(fun, "TLMIN", i+1, 0.0, &got); -\& fun->cols[i]->tlmax = (int)FunParamGeti(fun, "TLMAX", i+1, 0.0, &got); -\& } -.Ve -.PP -The fourth \fBdefval\fR 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 \fIFunParamGet()\fR call. The final -\&\fBgot\fR argument will be 0 if no param was found. Otherwise the -data type of the parameter is returned as follows: \s-1FUN_PAR_UNKNOWN\s0 -('u'), \s-1FUN_PAR_COMMENT\s0 ('c'), \s-1FUN_PAR_LOGICAL\s0 ('l'), \s-1FUN_PAR_INTEGER\s0 -('i'), \s-1FUN_PAR_STRING\s0 ('s'), \s-1FUN_PAR_REAL\s0 ('r'), \s-1FUN_PAR_COMPLEX\s0 ('x'). -.PP -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. -.PP -By default, \fB\f(BIFunParamGets()\fB\fR returns the string value of the -named parameter. However, you can use \fIFunInfoPut()\fR to retrieve the -raw 80\-character \s-1FITS\s0 card instead. In particular, if you set the -\&\s-1FUN_RAWPARAM\s0 parameter to 1, then card images will be returned by -\&\fIFunParamGets()\fR until the value is reset to 0. -.PP -Alternatively, if the \s-1FUN_RAW\s0 macro is applied to the name, then the -80\-character raw \s-1FITS\s0 card is returned instead. -\s-1NB - \s0 \s-1FUN_RAW\s0 is deprecated. -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 \fIFunInfoPut()\fR to switch between the -extension header and the primary header. -.PP -Note that in addition to the behaviors described above, the -routine \fB\f(BIFunParamGets()\fB\fR will return the 80 raw characters of the -\&\fBnth\fR \s-1FITS\s0 card (including the comment) if \fBname\fR is specified as -\&\s-1NULL\s0 and \fBn\fR is positive. For example, to loop through all \s-1FITS\s0 -header cards in a given extension and print out the raw card, use: -.PP -.Vb 9 -\& for(i=1; ;i++){ -\& if( (s = FunParamGets(fun, NULL, i, NULL, &got)) ){ -\& fprintf(stdout, "%.80s\en", s); -\& free(s); -\& } -\& else{ -\& break; -\& } -\& } -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funparamput.3 b/funtools/man/man3/funparamput.3 deleted file mode 100644 index db90dcc..0000000 --- a/funtools/man/man3/funparamput.3 +++ /dev/null @@ -1,256 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funparamput 3" -.TH funparamput 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunParamPut \- put a Funtools param value -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 2 -\& int FunParamPutb(Fun fun, char *name, int n, int value, char *comm, -\& int append) -.Ve -.PP -.Vb 2 -\& int FunParamPuti(Fun fun, char *name, int n, int value, char *comm, -\& int append) -.Ve -.PP -.Vb 2 -\& int FunParamPutd(Fun fun, char *name, int n, double value, int prec, -\& char *comm, int append) -.Ve -.PP -.Vb 2 -\& int FunParamPuts(Fun fun, char *name, int n, char *value, char *comm, -\& int append) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The four routines \fB\f(BIFunParamPutb()\fB\fR, \fB\f(BIFunParamPuti()\fB\fR, -\&\fB\f(BIFunParamPutd()\fB\fR, and \fB\f(BIFunParamPuts()\fB\fR, will set the value -of a \s-1FITS\s0 header parameter as a boolean, int, double, and string, -respectively. -.PP -The first argument is the Fun handle associated with the \s-1FITS\s0 header -being accessed. Normally, the header is associated with the \s-1FITS\s0 -extension that you opened with \fB\f(BIFunOpen()\fB\fR. -However, you can use \fIFunInfoPut()\fR to specify that use of the primary -header. In particular, if you set the \s-1FUN_PRIMARYHEADER\s0 parameter to -1, then the primary header is used for all parameter access until the -value is reset to 0. For example: -.PP -.Vb 5 -\& int val; -\& FunParamPuti(fun, "NAXIS1", 0, 10, NULL, 1); # current header -\& val=1; -\& FunInfoPut(fun, FUN_PRIMARYHEADER, &val, 0); # switch to ... -\& FunParamPuti(fun, "NAXIS1", 0, 10, NULL, 1); # primary header -.Ve -.PP -(You also can use the deprecated \s-1FUN_PRIMARY\s0 macro, to access -parameters from the primary header.) -.PP -The second argument is the \fBname\fR of the parameter. ( -In accordance with \s-1FITS\s0 standards, the special names \fB\s-1COMMENT\s0\fR -and \fB\s-1HISTORY\s0\fR, as well as blank names, are output without the \*(L"= \*(R" -value indicator in columns 9 and 10. -.PP -The third \fBn\fR 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 \s-1TLMIN\s0 and \s-1TLMAX\s0 for each column in a -binary table, you can use: -.PP -.Vb 4 -\& for(i=0; i<got; i++){ -\& FunParamPutd(fun, "TLMIN", i+1, tlmin[i], 7, "min column val", 1); -\& FunParamPutd(fun, "TLMAX", i+1, tlmax[i], 7, "max column val", 1); -\& } -.Ve -.PP -The fourth \fBdefval\fR argument is the value to set. Note that the -data type of this argument is different for each specific -\&\fIFunParamPut()\fR call. The \fBcomm\fR argument is the comment -string to add to this header parameter. Its value can be \s-1NULL\s0. The -final \fBappend\fR 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. -.PP -Note that the double precision routine \fIFunParamPutd()\fR supports an -extra \fBprec\fR argument after the \fBvalue\fR argument, in order -to specify the precision when converting the double value to \s-1ASCII\s0. In -general a 20.[prec] format is used (since 20 characters are alloted to -a floating point number in \s-1FITS\s0) as follows: if the double value being -put to the header is less than 0.1 or greater than or equal to -10**(20\-2\-[prec]), then \f(CW%20\fR.[prec]e format is used (i.e., scientific -notation); otherwise \f(CW%20\fR.[prec]f format is used (i.e., numeric -notation). -.PP -As a rule, parameters should be set before writing the table or image. -It is, however, possible to update the value of an \fBexisting\fR -parameter after writing an image or table (but not to add a new -one). 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. -.PP -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: -.PP -.Vb 8 -\& /* add blank card to be used as a place holder for IPAR1 update */ -\& FunParamPuts(fun, NULL, 0, "IPAR1", "INTEGER Param", 0); -\& ... -\& /* write header and data */ -\& FunTableRowPut(fun, events, got, 0, NULL); -\& ... -\& /* update param in file after writing data -- note append = 2 here */ -\& FunParamPuti(fun, "IPAR", 1, 400, "INTEGER Param", 2); -.Ve -.PP -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. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funref.3 b/funtools/man/man3/funref.3 deleted file mode 100644 index 7c6156a..0000000 --- a/funtools/man/man3/funref.3 +++ /dev/null @@ -1,287 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funref 3" -.TH funref 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunRef \- the Funtools Reference Handle -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -A description of how to use a Funtools reference handle to connect a -Funtools input file to an output file. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The Funtools reference handle connects a Funtools input file to a -Funtools output file so that parameters (or even whole extensions) 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 -\&\fIFunOpen()\fR call for the output file: -.PP -.Vb 4 -\& if( !(ifun = FunOpen(argv[1], "r", NULL)) ) -\& gerror(stderr, "could not FunOpen input file: %s\en", argv[1]); -\& if( !(ofun = FunOpen(argv[2], "w", ifun)) ) -\& gerror(stderr, "could not FunOpen output file: %s\en", argv[2]); -.Ve -.PP -It does not matter what type of input or output file (or extension) is -opened, or whether they are the same type. When the output image or -binary table is written using -\&\fIFunImagePut()\fR -or -\&\fIFunTableRowPut()\fR -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 \s-1TFORM\s0, \s-1TUNIT\s0, -etc. parameters will not be copied to the output. -.PP -Use of a reference handle also allows default values to be passed -to -\&\fIFunImagePut()\fR 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: -.PP -.Vb 5 -\& fun = FunOpen(argv[1], "r", NULL); -\& fun2 = FunOpen(argv[2], "w", fun); -\& buf = FunImageGet(fun, NULL, NULL); -\& ... process image data ... -\& FunImagePut(fun2, buf, 0, 0, 0, NULL); -.Ve -.PP -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: -.PP -.Vb 7 -\& fun = FunOpen(argv[1], "r", NULL); -\& fun2 = FunOpen(argv[2], "w", fun); -\& buf = FunImageGet(fun, NULL, NULL); -\& FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, -\& FUN_SECT_BITPIX, &bitpix, 0); -\& ... process image data ... -\& FunImagePut(fun2, buf, dim1, dim2, bitpix, NULL); -.Ve -.PP -It is possible to change the reference handle for a given output Funtools -handle using the -\&\fIFunInfoPut()\fR routine: -.PP -.Vb 2 -\& /* make the new extension the reference handle for the output file */ -\& FunInfoPut(fun2, FUN_IFUN, &fun, 0); -.Ve -.PP -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: -.PP -.Vb 18 -\& /* open a new output FITS file */ -\& if( !(fun2 = FunOpen(argv[2], "w", NULL)) ) -\& gerror(stderr, "could not FunOpen output file: %s\en", argv[2]); -\& /* process each input extension in turn */ -\& for(ext=0; ;ext++){ -\& /* get new extension name */ -\& sprintf(tbuf, "%s[%d]", argv[1], ext); -\& /* open it -- if we cannot open it, we are done */ -\& if( !(fun=FunOpen(tbuf, "r", NULL)) ) -\& break; -\& /* make the new extension the reference handle for the output file */ -\& FunInfoPut(fun2, FUN_IFUN, &fun, 0); -\& ... process ... -\& /* flush output extension (write padding, etc.) */ -\& FunFlush(fun2, NULL); -\& /* close the input extension */ -\& FunClose(fun); -\& } -.Ve -.PP -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. -.PP -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 \*(L"C\*(R" or \*(L"c\*(R" to the mode string of the -\&\fIFunOpen()\fR -call \fBof the input reference file\fR. If \*(L"C\*(R" is specified, then -other extensions are \fBalways\fR copied (i.e., copy is forced by the -application). If \*(L"c\*(R" is used, then other extensions are copied if the -user requests copying by adding a plus sign \*(L"+\*(R" to the extension name -in the bracket specification. For example, the \fBfuntable\fR -program utilizes user-specified \*(L"c\*(R" mode so that the second example -below will copy all extensions: -.PP -.Vb 4 -\& # copy only the EVENTS extension -\& csh> funtable "test.ev[EVENTS,circle(512,512,10)]" foo.ev -\& # copy ALL extensions -\& csh> funtable "test.ev[EVENTS+,circle(512,512,10)]" foo.ev -.Ve -.PP -When extension copy is specified in the input file, the call to -\&\fIFunOpen()\fR -on the input file delays the actual file open until the output file -also is opened (or until I/O is performed on the input file, which -ever happens first). 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. -.PP -When extension processing is complete, the remaining extensions need to -be copied from input to output. This can be done explicitly, using the -\&\fIFunFlush()\fR -call with the \*(L"copy=remaining\*(R" plist: -.PP -.Vb 1 -\& FunFlush(fun, "copy=remaining"); -.Ve -.PP -Alternatively, this will happen automatically, if the output file -is closed \fBbefore\fR the input file: -.PP -.Vb 5 -\& /* we could explicitly flush remaining extensions that need copying */ -\& /* FunFlush(fun2, "copy=remaining"); */ -\& /* but if we close output before input, end flush is done automatically */ -\& FunClose(fun2); -\& FunClose(fun); -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funtablerowget.3 b/funtools/man/man3/funtablerowget.3 deleted file mode 100644 index 7554781..0000000 --- a/funtools/man/man3/funtablerowget.3 +++ /dev/null @@ -1,216 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funtablerowget 3" -.TH funtablerowget 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunTableRowGet \- get Funtools rows -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 2 -\& void *FunTableRowGet(Fun fun, void *rows, int maxrow, char *plist, -\& int *nrow) -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunTableRowGet()\fB\fR routine retrieves rows from a Funtools -binary table or raw event file, and places the values of columns -selected by \fIFunColumnSelect()\fR -into an array of user structs. Selected column values are -automatically converted to the specified user data type (and to native -data format) as necessary. -.PP -The first argument is the Fun handle associated with this row data. -The second \fBrows\fR argument is the array of user structs into -which the selected columns will be stored. If \s-1NULL\s0 is passed, the -routine will automatically allocate space for this array. (This -includes proper allocation of pointers within each struct, if the \*(L"@\*(R" -pointer type is used in the selection of columns. Note that if you -pass \s-1NULL\s0 in the second argument, you should free this space using the -standard \fIfree()\fR system call when you are finished with the array of -rows.) The third \fBmaxrow\fR argument specifies the maximum number -of rows to be returned. Thus, if \fBrows\fR is allocated by the -user, it should be at least of size maxrow*sizeof(evstruct). -.PP -The fourth \fBplist\fR argument is a param list string. Currently, -the keyword/value pair \*(L"mask=transparent\*(R" 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 (instead of just rows passing -the filter). This is only useful when -\&\fIFunColumnSelect()\fR also is -used to specify \*(L"$region\*(R" 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 (corresponding to the region id of the region in which -they are located), 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 \*(L"mask=transparent\*(R" 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. -.PP -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 \s-1NULL\s0 if there was an error. (This pointer -will be the same as the second argument, if the latter is non\-NULL). -.PP -.Vb 16 -\& /* get rows -- let routine allocate the row array */ -\& while( (buf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ -\& /* process all rows */ -\& for(i=0; i<got; i++){ -\& /* point to the i'th row */ -\& ev = buf+i; -\& /* rearrange some values. etc. */ -\& ev->energy = (ev->pi+ev->pha)/2.0; -\& ev->pha = \-ev->pha; -\& ev->pi = \-ev->pi; -\& } -\& /* write out this batch of rows */ -\& FunTableRowPut(fun2, buf, got, 0, NULL); -\& /* free row data */ -\& if( buf ) free(buf); -\& } -.Ve -.PP -As shown above, successive calls to -\&\fIFunTableRowGet()\fR 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 -\&\fIfread()\fR. See evmerge example code for a -more complete example. -.PP -Note that \fIFunTableRowGet()\fR also can be called as \fIFunEventsGet()\fR, for -backward compatibility. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man3/funtablerowput.3 b/funtools/man/man3/funtablerowput.3 deleted file mode 100644 index 533bd43..0000000 --- a/funtools/man/man3/funtablerowput.3 +++ /dev/null @@ -1,297 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funtablerowput 3" -.TH funtablerowput 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunTableRowPut \- put Funtools rows -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -int FunTableRowPut(Fun fun, void *rows, int nev, int idx, char *plist) -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunTableRowPut()\fB\fR routine writes rows to a \s-1FITS\s0 binary -table, taking its input from an array of user structs that contain -column values selected by a previous call to -\&\fIFunColumnSelect()\fR. Selected -column values are automatically converted from native data format to -\&\s-1FITS\s0 data format as necessary. -.PP -The first argument is the Fun handle associated with this row data. -The second \fBrows\fR argument is the array of user structs to -output. The third \fBnrow\fR argument specifies the number number of -rows to write. The routine will write \fBnrow\fR records, starting -from the location specified by \fBrows\fR. -.PP -The fourth \fBidx\fR 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 (see below). Note -that this \fBidx\fR value is has nothing to do with the -row buffer specified in argument 1. It merely matches the row -being written with its corresponding (hidden) 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 \fBidx\fR -should be 0: -.PP -.Vb 14 -\& Ev ebuf, ev; -\& /* get rows -- let routine allocate the row array */ -\& while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ -\& /* process all rows */ -\& for(i=0; i<got; i++){ -\& /* point to the i'th row */ -\& ev = ebuf+i; -\& ... -\& } -\& /* write out this batch of rows, starting with the first */ -\& FunTableRowPut(fun2, (char *)ebuf, got, 0, NULL); -\& /* free row data */ -\& if( ebuf ) free(ebuf); -\& } -.Ve -.PP -On the other hand, if you write out the rows one at a time (possibly -skipping rows), then, when writing the i'th row from the input -array of rows, set \fBidx\fR to the value of i: -.PP -.Vb 14 -\& Ev ebuf, ev; -\& /* get rows -- let routine allocate the row array */ -\& while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ -\& /* process all rows */ -\& for(i=0; i<got; i++){ -\& /* point to the i'th row */ -\& ev = ebuf+i; -\& ... -\& /* write out the current (i.e., i'th) row */ -\& FunTableRowPut(fun2, (char *)ev, 1, i, NULL); -\& } -\& /* free row data */ -\& if( ebuf ) free(ebuf); -\& } -.Ve -.PP -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 nrow</B argument. -.PP -When \fIFunTableRowPut()\fR is first -called for a given binary table, Funtools checks to see of the primary -header has already been written (either by writing a previous row -table or by writing an image.) If not, a dummy primary header is -written to the file specifying that an extension should be expected. -After this, a binary table header is automatically written containing -information about the columns that will populate this table. In -addition, if a -Funtools reference handle -was specified when this table was opened, the parameters from this -Funtools reference handle -are merged into the new binary table header. -.PP -In a typical Funtools row loop, you read rows using -\&\fIFunTableRowGet()\fR() and write -rows using \fIFunTableRowPut()\fR. The columns written by -\&\fIFunTableRowPut()\fR() are those defined as writable by a previous call to -\&\fIFunColumnSelect()\fR. If -that call to FunColumnSelect also specified -\&\fBmerge=[update|replace|append]\fR, then the entire corresponding -raw input row record will be merged with the output row according -to the \fBmerge\fR specification (see -\&\fIFunColumnSelect()\fR above). -.PP -A call to write rows can either be done once, after all rows in -the input batch have been processed, or it can be done (slightly less -efficiently) one row at a time (or anything in between). We do -recommend that you write all rows associated with a given batch of -input rows before reading new rows. This is \fBrequired\fR if -you are merging the output rows with the raw input rows (since -the raw rows are destroyed with each successive call to get new rows). -.PP -For example: -.PP -.Vb 13 -\& Ev buf, ev; -\& ... -\& /* get rows -- let routine allocate the row array */ -\& while( (buf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ -\& /* point to the i'th row */ -\& ev = buf + i; -\& .... process -\& } -\& /* write out this batch of rows */ -\& FunTableRowPut(fun2, buf, got, 0, NULL); -\& /* free row data */ -\& if( buf ) free(buf); -\& } -.Ve -.PP -or -.PP -.Vb 16 -\& Ev buf, ev; -\& ... -\& /* get rows -- let routine allocate the row array */ -\& while( (buf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ -\& /* process all rows */ -\& for(i=0; i<got; i++){ -\& /* point to the i'th row */ -\& ev = buf + i; -\& ... process -\& /* write out this batch of rows with the new column */ -\& if( dowrite ) -\& FunTableRowPut(fun2, buf, 1, i, NULL); -\& } -\& /* free row data */ -\& if( buf ) free(buf); -\& } -.Ve -.PP -Note that the difference between these calls is that the first one -outputs \fBgot\fR rows all at once and therefore passes -\&\fBidx=0\fR in argument four, so that merging starts at the first raw -input row. In the second case, a check it made on each row to see -if it needs to be output. If so, the value of \fBidx\fR is passed as -the value of the \fBi\fR variable which points to the current row -being processed in the batch of input rows. -.PP -As shown above, successive calls to -\&\fIFunTableRowPut()\fR will write -rows sequentially. When you are finished writing all rows in a -table, you should call -\&\fIFunFlush()\fR to write out the \s-1FITS\s0 -binary table padding. However, this is not necessary if you -subsequently call \fIFunClose()\fR without doing any other I/O to the \s-1FITS\s0 -file. -.PP -Note that \fIFunTableRowPut()\fR also can be called as \fIFunEventsPut()\fR, for -backward compatibility. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funcombine.7 b/funtools/man/man7/funcombine.7 deleted file mode 100644 index b2e5dc4..0000000 --- a/funtools/man/man7/funcombine.7 +++ /dev/null @@ -1,248 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funcombine 7" -.TH funcombine 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunCombine \- Combining Region and Table Filters -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document discusses the conventions for combining region and table -filters, especially with regards to the comma operator. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBComma Conventions\fR -.PP -Filter specifications consist of a series of boolean expressions, -separated by commas. These expressions can be table filters, -spatial region filters, or combinations thereof. Unfortunately, -common usage requires that the comma operator must act differently -in different situations. Therefore, while its use is intuitive in -most cases, commas can be a source of confusion. -.PP -According to long-standing usage in \s-1IRAF\s0, when a comma separates two -table filters, it takes on the meaning of a boolean \fBand\fR. Thus: -.PP -.Vb 1 -\& foo.fits[pha==1,pi==2] -.Ve -.PP -is equivalent to: -.PP -.Vb 1 -\& foo.fits[pha==1 && pi==2] -.Ve -.PP -When a comma separates two spatial region filters, however, it has -traditionally taken on the meaning of a boolean \fBor\fR. Thus: -.PP -.Vb 1 -\& foo.fits[circle(10,10,3),ellipse(20,20,8,5)] -.Ve -.PP -is equivalent to: -.PP -.Vb 1 -\& foo.fits[circle(10,10,3) || ellipse(20,20,8,5)] -.Ve -.PP -(except that in the former case, each region is given a unique id -in programs such as funcnts). -.PP -Region and table filters can be combined: -.PP -.Vb 1 -\& foo.fits[circle(10,10,3),pi=1:5] -.Ve -.PP -or even: -.PP -.Vb 1 -\& foo.fits[pha==1&&circle(10,10,3),pi==2&&ellipse(20,20,8,5)] -.Ve -.PP -In these cases, it is not obvious whether the command should utilize an -\&\fBor\fR or \fBand\fR operator. We therefore arbitrarily chose to -implement the following rule: -.IP "\(bu" 4 -if both expressions contain a region, the operator used is \fBor\fR. -.IP "\(bu" 4 -if one (or both) expression(s) does not contain a region, the operator -used is \fBand\fR. -.PP -This rule handles the cases of pure regions and pure column filters properly. -It unambiguously assigns the boolean \fBand\fR to all mixed cases. Thus: -.PP -.Vb 1 -\& foo.fits[circle(10,10,3),pi=1:5] -.Ve -.PP -and -.PP -.Vb 1 -\& foo.fits[pi=1:5,circle(10,10,3)] -.Ve -.PP -both are equivalent to: -.PP -.Vb 1 -\& foo.fits[circle(10,10,3) && pi=1:5] -.Ve -.PP -[\s-1NB:\s0 This arbitrary rule \fBreplaces the previous arbitrary rule\fR -(pre\-funtools 1.2.3) which stated: -.IP "\(bu" 4 -if the 2nd expression contains a region, the operator used is \fBor\fR. -.IP "\(bu" 4 -if the 2nd expression does not contain a region, the operator -used is \fBand\fR. -.PP -In that scenario, the \fBor\fR operator was implied by: -.PP -.Vb 1 -\& pha==4,circle 5 5 1 -.Ve -.PP -while the \fBand\fR operator was implied by -.PP -.Vb 1 -\& circle 5 5 1,pha==4 -.Ve -.PP -Experience showed that this non-commutative treatment of the comma -operator was confusing and led to unexpected results.] -.PP -The comma rule must be considered provisional: comments and complaints -are welcome to help clarify the matter. Better still, we recommend -that the comma operator be avoided in such cases in favor of an -explicit boolean operator. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funds9.7 b/funtools/man/man7/funds9.7 deleted file mode 100644 index 963084a..0000000 --- a/funtools/man/man7/funds9.7 +++ /dev/null @@ -1,216 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funds9 7" -.TH funds9 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunDS9 \- Funtools and DS9 Image Display -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -Describes how funtools can be integrated into the ds9 Analysis menu. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -SAOImage/DS9 is an astronomical imaging and data visualization -application used by astronomers around the world. \s-1DS9\s0 can display -standard astronomical \s-1FITS\s0 images and binary tables, but also has -support for displaying raw array files, shared memory files, and data -files automatically retrieved via \s-1FTP\s0 and \s-1HTTP\s0. Standard functional -capabilities include multiple frame buffers, colormap and region -manipulation, and many data scaling algorithms. \s-1DS9\s0's advanced -features include TrueColor visuals, deep frame buffers, true -PostScript printing, and display of image mosaics. The program's -support of image tiling, \*(L"blinking\*(R", arbitrary zoom, rotation, and pan -is unparalleled in astronomy. It also has innovative support for -automatic retrieval and display of standard image data such as the -Digital Sky Survey (using servers at \s-1SAO\s0, StScI, or \s-1ESO\s0). -.PP -\&\s-1DS9\s0 can communicate with external programs such as Funtools using the -\&\s-1XPA\s0 -messaging system. In addition, programs can be integrated directly -into the \s-1DS9\s0 \s-1GUI\s0 by means of a configurable Analysis menu. By -default, the \s-1DS9\s0 Analysis menu contains algorithms deemed essential to -the core functions of \s-1DS9\s0, e.g., display cross-cuts of data, -iso-intensity contours, and \s-1WCS\s0 grids. However, new programs can be -added to \s-1DS9\s0 by creating a set-up file which can be loaded into \s-1DS9\s0 -to reconfigure the Analysis menu. -.PP -The basic format of the analysis set-up file is: -.PP -.Vb 6 -\& # -\& # Analysis command descriptions: -\& # menu label/description -\& # file templates for this command -\& # "menu" (add to menu) |"bind" (bind to key) -\& # analysis command line -.Ve -.PP -For example, the funcnts program can be specified in this way: -.PP -.Vb 4 -\& Funcnts (counts in source/bkgd regions; options: none) -\& * -\& menu -\& funcnts $filename $regions(source,,) $regions(background,,) | $text -.Ve -.PP -As shown above, \s-1DS9\s0 supports a macro facility to provide information -as well as task support to command lines. For example, the \f(CW$regions\fR -macro is expanded by \s-1DS9\s0 to provide the current source and/or -background region to the analysis command. The \f(CW$text\fR macro is expanded -to generate a text window display. It also is possible to query for -parameters using a \f(CW$param\fR macro, plot data using a \f(CW$plot\fR macro, -etc. See the \s-1DS9\s0 documentation for further details. -.PP -A set-up file called funtools.ds9 will -load some useful Funtools applications (counts in regions, radial -profile, X\-ray light curve and energy spectrum, 1D histogram) into the \s-1DS9\s0 -Analysis menu (version 2.1 and above). The file resides in the bin -directory where Funtools programs are installed. It can be manually -loaded into \s-1DS9\s0 from the \fBLoad Analysis Commands ...\fR option of -the \fBAnalysis\fR menu. Alternatively, you can tell \s-1DS9\s0 to load -this file automatically at start-up time by adding the pathname to the -\&\fBEdit\fR\->\fBPreferences\fR\->\fBAnalysis Menu\fR\->Analysis -File menu option. (\s-1NB:\s0 make sure you select -\&\fBEdit\fR\->\fBPreferences\fR\->\fBSave Preferences\fR after setting -the pathname.) -.PP -The tasks in this setup file generally process the original disk-based -\&\s-1FITS\s0 file. Funcnts-based results (radial profile, counts in regions) -are presented in \s-1WCS\s0 units, if present in the \s-1FITS\s0 header. For -situations where a disk file is not available (e.g., image data -generated and sent to \s-1DS9\s0's 'fits' \s-1XPA\s0 access point), versions of the -radial profile and counts in regions tasks also are also offered -utilizing \s-1DS9\s0's internal image data. Results are presented in pixels. -Aside from the units, the results should be identical to the file-based -results. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funenv.7 b/funtools/man/man7/funenv.7 deleted file mode 100644 index 4b29218..0000000 --- a/funtools/man/man7/funenv.7 +++ /dev/null @@ -1,352 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funenv 7" -.TH funenv 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunEnv \- Funtools Environment Variables -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -Describes the environment variables which can be used to tailor the overall -Funtools environment. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The following environment variables are supported by Funtools: -.IP "\(bu" 4 -\&\fB\s-1FITS_EXTNAME\s0\fR -.Sp -The \fB\s-1FITS_EXTNAME\s0\fR environment variable specifies the -default \s-1FITS\s0 extension name when \fIFunOpen()\fR is called on a file lacking -a primary image. Thus, -.Sp -.Vb 1 -\& setenv FITS_EXTNAME "NEWEV" -.Ve -.Sp -will allow you to call \fIFunOpen()\fR on files without specifying \s-1NEWEV\s0 in -the -Funtools bracket specification. -If no \s-1FITS_EXTNAME\s0 variable is defined and the extension name also is -not passed in the bracket specification, then the default will be to -look for standard X\-ray event table extension names \*(L"\s-1EVENTS\s0\*(R" or -\&\*(L"\s-1STDEVT\s0\*(R" (we are, after all, and X\-ray astronomy group at heart!). -.IP "\(bu" 4 -\&\fB\s-1FITS_EXTNUM\s0\fR -.Sp -The \fB\s-1FITS_EXTNUM\s0\fR environment variable specifies the -default \s-1FITS\s0 extension number when \fIFunOpen()\fR is called on a file lacking -a primary image. Thus, -.Sp -.Vb 1 -\& setenv FITS_EXTNUM 7 -.Ve -.Sp -will allow you to call \fIFunOpen()\fR on files to open the seventh -extension without specifying the number in the -Funtools bracket specification. -.IP "\(bu" 4 -\&\fB\s-1FITS_BINCOLS\s0\fR and \fB\s-1EVENTS_BINCOLS\s0\fR -.Sp -These environment variable specifies the default binning key for -\&\s-1FITS\s0 binary tables and raw event files, respectively. They can be -over-ridden using the \fBbincols=[naxis1,naxis2]\fR keyword in a -Funtools bracket specification. -The value of each environment variable -is a pair of comma-delimited columns, enclosed in parentheses, to use -for binning. For example, if you want to bin on detx and dety by -default, then use: -.Sp -.Vb 1 -\& setenv FITS_BINCOLS "(detx,dety)" -.Ve -.Sp -in preference to adding a bincols specification to each filename: -.Sp -.Vb 1 -\& foo.fits[bincols=(detx,dety)] -.Ve -.IP "\(bu" 4 -\&\fB\s-1FITS_BITPIX\s0\fR and \fB\s-1EVENTS_BITPIX\s0\fR -.Sp -These environment variable specifies the default bitpix value for -binning \s-1FITS\s0 binary tables and raw event files, respectively. They can -be over-ridden using the \fBbitpix=[value]\fR keyword in a -Funtools bracket specification. The value -of each environment variable is one of the standard \s-1FITS\s0 bitpix values -(8,16,32,\-32,\-64). For example, if you want binning routines to -create a floating array, then use: -.Sp -.Vb 1 -\& setenv FITS_BITPIX \-32 -.Ve -.Sp -in preference to adding a bitpix specification to each filename: -.Sp -.Vb 1 -\& foo.fits[bitpix=-32] -.Ve -.IP "\(bu" 4 -\&\fB\s-1ARRAY\s0\fR -.Sp -The \fB\s-1ARRAY\s0\fR environment variable specifies the default -definition of an array file for Funtools. -It is used if there is no array specification passed in the -\&\fB\s-1\f(BIARRAY\s0()\fB\fR directive in a -Non-FITS Array specification. -The value of the environment variable is a valid array specification such as: -.Sp -.Vb 2 -\& setenv ARRAY "s100.150" -\& foo.arr[ARRAY()] -.Ve -.Sp -This can be defined in preference to adding the specification to each filename: -.Sp -.Vb 1 -\& foo.arr[ARRAY(s100.150)] -.Ve -.IP "\(bu" 4 -\&\fB\s-1EVENTS\s0\fR -.Sp -The \fB\s-1EVENTS\s0\fR environment variable specifies the default -definition of an raw event file for Funtools. -It is used if there is no \s-1EVENTS\s0 specification passed in the -\&\fB\s-1\f(BIEVENTS\s0()\fB\fR directive in a -Non-FITS \s-1EVENTS\s0 specification. -The value of the environment variable is a valid \s-1EVENTS\s0 specification such as: -.Sp -.Vb 2 -\& setenv EVENTS "x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024" -\& foo.ev[EVENTS()] -.Ve -.Sp -This can be defined in preference to adding the specification to each filename: -.Sp -.Vb 1 -\& foo.ev[EVENTS(x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024)] -.Ve -.PP -The following filter-related environment variables are supported by Funtools: -.IP "\(bu" 4 -\&\fB\s-1FILTER_PTYPE\s0\fR -.Sp -The \fB\s-1FILTER_PTYPE\s0\fR environment variable specifies how to -build a filter. There are three possible methods: -.RS 4 -.IP "\(bu" 4 -process or p -.Sp -The filter is compiled and linked against the funtools library (which -must therefore be accessible in the original install directory) to produce -a slave program. This program is fed events or image data and returns -filter results. -.IP "\(bu" 4 -dynamic or d (gcc only) -.Sp -The filter is compiled and linked against the funtools library (which -must therefore be accessible in the original install directory) to produce -a dynamic shared object, which is loaded into the funtools program and -executed as a subroutine. (Extensive testing has shown that, contrary to -expectations, this method is no faster than using a slave process.) -.IP "\(bu" 4 -contained or c -.Sp -The filter and all supporting region code is compiled and linked -without reference to the funtools library to produce a slave program -(which is fed events or image data and returns filter results). This method -is slower than the other two, because of the time it takes to compile the -region filtering code. It is used by stand-alone programs such as ds9, -which do not have access to the funtools library. -.RE -.RS 4 -.Sp -By default, \fBdynamic\fR is generally used for gcc compilers and -\&\fBprocess\fR for other compilers. However the filter building algorithm -will check for required external files and will use \fBcontained\fR is -these are missing. -.RE -.IP "\(bu" 4 -\&\fB\s-1FUN_MAXROW\s0\fR -.Sp -The \fB\s-1FUN_MAXROW\s0\fR environment variable is used by core -row-processing Funtools programs (funtable, fundisp, funcnts, funhist, -funmerge, and funcalc) to set the maximum number of rows read at once -(i.e. it sets the third argument to the \fIFunTableRowGet()\fR call). The -default is 8192. Note that this variable is a convention only: it will -not be a part of a non-core Funtools program unless code is explicitly -added, since each call to \fIFunTableRowGet()\fR specifies its own maximum -number of rows to read. \s-1NB:\s0 if you make this value very large, you -probably will need to increase \fB\s-1FUN_MAXBUFSIZE\s0\fR (see below) as well. -.IP "\(bu" 4 -\&\fB\s-1FUN_MAXBUFSIZE\s0\fR -.Sp -The \fB\s-1FUN_MAXBUFSIZE\s0\fR environment variable is used to limit the -max buffer size that will be allocated to hold table row data. This -buffer size is calculated to be the row size of the table multiplied -by the maximum number of rows read at once (see above). Since the -row size is unlimited (and we have examples of it being larger than 5 -Mb), it is possible that the total buffer size will exceed the machine -capabilities. We therefore set a default value of 5Mb for the max buffer -size, and adjust maxrow so that the total size calculated is less than -this max buffer size. (If the row size is greater than this max buffer -size, then maxrow is set to 1.) This environment variable will change -the max buffer size allowed. -.IP "\(bu" 4 -\&\fB\s-1FILTER_CC\s0\fR -.Sp -The \fB\s-1FILTER_CC\s0\fR environment variable specifies the compiler to -use for compiling a filter specification. You also can use the \fB\s-1CC\s0\fR -environment variable. If neither has been set, then gcc will be used -if available. Otherwise cc is used if available. -.IP "\(bu" 4 -\&\fB\s-1FILTER_EXTRA\s0\fR -.Sp -The \fB\s-1FILTER_EXTRA\s0\fR environment variable specifies extra options -to add to a filter compile command line. In principle, you can add libraries, -include files, and compiler switches. This variable should be used with care. -.IP "\(bu" 4 -\&\fB\s-1FILTER_TMPDIR\s0\fR -.Sp -The \fB\s-1FILTER_TMPDIR\s0\fR environment variable specifies the temporary -directory for filter compilation intermediate files. You also can use -the \fB\s-1TMPDIR\s0\fR and \fB\s-1TMP\s0\fR variables. By default, /tmp is used -as the temporary directory. -.IP "\(bu" 4 -\&\fB\s-1FILTER_KEEP\s0\fR -.Sp -The \fB\s-1FILTER_KEEP\s0\fR environment variable specifies whether the -intermediate filter files (i.e. C source file and compile log file) -should be saved after a filter is built. The default is \*(L"false\*(R", so that -these intermediate files are deleted. This variable is useful for debugging, -but care should be taken to reset its value to false when debugging is -complete. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funfiles.7 b/funtools/man/man7/funfiles.7 deleted file mode 100644 index f401833..0000000 --- a/funtools/man/man7/funfiles.7 +++ /dev/null @@ -1,802 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funfiles 7" -.TH funfiles 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunFiles \- Funtools Data Files -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document describes the data file formats (\s-1FITS\s0, array, raw -events) as well as the file types (gzip, socket, etc.) supported -by Funtools. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Funtools supports \s-1FITS\s0 images and binary tables, and binary files -containing array (homogeneous) data or event (heterogeneous) data. -IRAF-style brackets are appended to the filename to specify various -kinds of information needed to characterize these data: -.PP -.Vb 3 -\& file[ext|ind|ARRAY()|EVENTS(),section][filters] -\& or -\& file[ext|ind|ARRAY()|EVENTS(),section,filters] -.Ve -.PP -where: -.IP "\(bu" 4 -\&\fBfile\fR is the Funtools file name -.IP "\(bu" 4 -\&\fBext\fR is the \s-1FITS\s0 extension name -.IP "\(bu" 4 -\&\fBind\fR is the \s-1FITS\s0 extension number -.IP "\(bu" 4 -\&\fB\s-1\f(BIARRAY\s0()\fB\fR is an array specification -.IP "\(bu" 4 -\&\fB\s-1\f(BIEVENTS\s0()\fB\fR is an event specification -.IP "\(bu" 4 -\&\fBsection\fR is the image section specification -.IP "\(bu" 4 -\&\fBfilters\fR are spatial region and table (row) filters -.PP -\&\fBSupported Data Formats\fR -.PP -Funtools programs (and the underlying libraries) support the -following data file formats: -.IP "\(bu" 4 -\&\s-1FITS\s0 images (and image extensions) -.IP "\(bu" 4 -\&\s-1FITS\s0 binary tables -.IP "\(bu" 4 -binary files containing an array of homogeneous data -.IP "\(bu" 4 -binary files containing events, i.e. records of heterogeneous data -.IP "\(bu" 4 -column-based text files, which are documented here -.IP "\(bu" 4 -non-disk files and lists of files -.PP -Information needed to identify and characterize -the event or image data can be specified on the command line -using IRAF-style bracket notation appended to the filename: -.PP -.Vb 5 -\& foo.fits # open FITS default extension -\& image.fits[3] # open FITS extension #3 -\& events.fits[EVENTS] # open EVENTS extension -\& array.file[ARRAY(s1024)] # open 1024x1024 short array -\& events.file[EVENTS(x:1024,y:1024...)] # open non-FITS event list -.Ve -.PP -Note that in many Unix shells (e.g., csh and tcsh), filenames must -be enclosed in quotes to protect the brackets from shell processing. -.PP -\&\fB\s-1FITS\s0 Images and Binary Tables\fR -.PP -When \fIFunOpen()\fR opens a \s-1FITS\s0 file -without a bracket specifier, the default behavior is to look for a -valid image in the primary \s-1HDU\s0. In the absence of a primary image, -Funtools will try to open an extension named either \fB\s-1EVENTS\s0\fR or -\&\fB\s-1STDEVT\s0\fR, if one of these exists. This default behavior supports -both \s-1FITS\s0 image processing and standard X\-ray event list processing -(which, after all, is what we at \s-1SAO/HEAD\s0 do). -.PP -In order to open a \s-1FITS\s0 binary table or image extension explicitly, it -is necessary to specify either the extension name or the extension -number in brackets: -.PP -.Vb 3 -\& foo.fits[1] # open extension #1: the primary HDU -\& foo.fits[3] # open extension #3 of a FITS file -\& foo.fits[GTI] # open GTI extension of a FITS file -.Ve -.PP -The ext argument specifies the name of the \s-1FITS\s0 extension (i.e. the -value of the \s-1EXTENSION\s0 header parameter in a \s-1FITS\s0 extension), while -the index specifies the value of the \s-1FITS\s0 \s-1EXTVER\s0 header parameter. -Following \s-1FITS\s0 conventions, extension numbers start at 1. -.PP -When a \s-1FITS\s0 data file is opened for reading using -\&\fIFunOpen()\fR, the specified extension -is automatically located and is used to initialize the Funtools internal -data structures. -.PP -\&\fBNon-FITS Raw Event Files\fR -.PP -In addition to \s-1FITS\s0 tables, Funtools programs and libraries can operate -on non-FITS files containing heterogeneous event records. To specify -such an event file, use: -.IP "\(bu" 4 -file[\s-1EVENTS\s0(event\-spec)] -.IP "\(bu" 4 -file[\s-1\fIEVENTS\s0()\fR] -.PP -where \fBevent-spec\fR is a string that specified the names, data -types, and optional image dimensions for each element of the event -record: -.IP "\(bu" 4 -[name]:[n][type]:[(lodim:)hidim] -.PP -Data types follow standard conventions for \s-1FITS\s0 binary tables, but include -two extra unsigned types ('U' and 'V'): -.IP "\(bu" 4 -\&\fBB\fR \*(-- unsigned 8-bit char -.IP "\(bu" 4 -\&\fBI\fR \*(-- signed 16-bit int -.IP "\(bu" 4 -\&\fBJ\fR \*(-- signed 32-bit int -.IP "\(bu" 4 -\&\fBK\fR \*(-- signed 64-bit int -.IP "\(bu" 4 -\&\fBE\fR \*(-- 32-bit float -.IP "\(bu" 4 -\&\fBD\fR \*(-- 64-bit float -.IP "\(bu" 4 -\&\fBU\fR \*(-- unsigned 16-bit int -.IP "\(bu" 4 -\&\fBV\fR \*(-- unsigned 32-bit int -.PP -An optional integer value \fBn\fR can be prefixed to the type to indicate -that the element is an array of n values. For example: -.PP -.Vb 1 -\& foo.fits[EVENTS(x:I,y:I,status:4J)] -.Ve -.PP -defines x and y as 16-bit ints and status as an array of 4 32-bit ints. -.PP -Furthermore, image dimensions can be attached to the event specification -in order to tell Funtools how to bin the events into an image. They -follow the conventions for the \s-1FITS\s0 \s-1TLMIN/TLMAX\s0 keywords. If the low -image dimension is not specified, it defaults to 1. Thus: -.IP "\(bu" 4 -\&\s-1RAWX:J:1:100\s0 -.IP "\(bu" 4 -\&\s-1RAWX:J:100\s0 -.PP -both specify that the dimension of this column runs from 1 to 100. -.PP -\&\s-1NB:\s0 it is required that all padding be specified in the record -definition. Thus, when writing out whole C structs instead of -individual record elements, great care must be taken to include -the compiler-added padding in the event definition. -.PP -For example, suppose a \s-1FITS\s0 binary table has the following set of column -definitions: -.PP -.Vb 22 -\& TTYPE1 = 'X ' / Label for field -\& TFORM1 = '1I ' / Data type for field -\& TLMIN1 = 1 / Min. axis value -\& TLMAX1 = 10 / Max. axis value -\& TTYPE2 = 'Y ' / Label for field -\& TFORM2 = '1I ' / Data type for field -\& TLMIN2 = 2 / Min. axis value -\& TLMAX2 = 11 / Max. axis value -\& TTYPE3 = 'PHA ' / Label for field -\& TFORM3 = '1I ' / Data type for field -\& TTYPE4 = 'PI ' / Label for field -\& TFORM4 = '1J ' / Data type for field -\& TTYPE5 = 'TIME ' / Label for field -\& TFORM5 = '1D ' / Data type for field -\& TTYPE6 = 'DX ' / Label for field -\& TFORM6 = '1E ' / Data type for field -\& TLMIN6 = 1 / Min. axis value -\& TLMAX6 = 10 / Max. axis value -\& TTYPE7 = 'DY ' / Label for field -\& TFORM7 = '1E ' / Data type for field -\& TLMIN7 = 3 / Min. axis value -\& TLMAX7 = 12 / Max. axis value -.Ve -.PP -An raw event file containing these same data would have the event -specification: -.PP -.Vb 1 -\& EVENTS(X:I:10,Y:I:2:11,PHA:I,PI:J,TIME:D,DX:E:10,DY:E:3:12) -.Ve -.PP -If no event specification string is included within the \s-1\fIEVENTS\s0()\fR operator, -then the event specification is taken from the \fB\s-1EVENTS\s0\fR environment -variable: -.PP -.Vb 1 -\& setenv EVENTS "X:I:10,Y:I:10,PHA:I,PI:J,TIME:D,DX:E:10,DY:E:10" -.Ve -.PP -In addition to knowing the data structure, it is necessary to know the -\&\fIendian\fR ordering of the data, i.e., whether or not the data is -in \fIbigendian\fR format, so that we can convert to the native -format for this platform. This issue does not arise for \s-1FITS\s0 Binary -Tables because all \s-1FITS\s0 files use big-endian ordering, regardless of -platform. But for non-FITS data, big-endian data produced on a Sun -workstation but read on a Linux \s-1PC\s0 needs to be byte\-swapped, since PCs -use little-endian ordering. To specify an ordering, use the -\&\fIbigendian=\fR or \fIendian=\fR keywords on the command-line -or the \s-1EVENTS_BIGENDIAN\s0 or \s-1EVENTS_ENDIAN\s0 environment variables. The -value of the \fIbigendian\fR variables should be \*(L"true\*(R" or \*(L"false\*(R", -while the value of the \fIendian\fR variables should be \*(L"little\*(R" or -\&\*(L"big\*(R". -.PP -For example, a \s-1PC\s0 can access data produced by a Sun using: -.PP -.Vb 7 -\& hrc.nepr[EVENTS(),bigendian=true] -\&or -\& hrc.nepr[EVENTS(),endian=big] -\&or -\& setenv EVENTS_BIGENDIAN true -\&or -\& setenv EVENTS_ENDIAN big -.Ve -.PP -If none of these are specified, the data are assumed to follow the -format for that platform and no byte-swapping is performed. -.PP -\&\fBNon-FITS Array Files\fR -.PP -In addition to \s-1FITS\s0 images, Funtools programs and libraries can operate -on non-FITS files containing arrays of homogeneous data. To specify -an array file, use: -.IP "\(bu" 4 -file[\s-1ARRAY\s0(array\-spec)] -.IP "\(bu" 4 -file[\s-1\fIARRAY\s0()\fR] -.PP -where array-spec is of the form: -.IP "\(bu" 4 -[type][dim1][.dim2][:skip][endian] -.PP -and where [type] is: -.IP "\(bu" 4 -b (8-bit unsigned char) -.IP "\(bu" 4 -s (16-bit short int) -.IP "\(bu" 4 -u (16-bit unsigned short int) -.IP "\(bu" 4 -i (32-bit int) -.IP "\(bu" 4 -r,f (32-bit float) -.IP "\(bu" 4 -d (64-bit float) -.PP -The dim1 specification is required, but dim2 is optional and defaults -to dim1. The skip specification is optional and defaults to 0. The -optional endian specification can be 'l' or 'b' and defaults to the -endian type for the current machine. -.PP -If no array specification is included within the \s-1\fIARRAY\s0()\fR operator, -then the array specification is taken from the \fB\s-1ARRAY\s0\fR environment -variable. For example: -.PP -.Vb 7 -\& foo.arr[ARRAY(r512)] # bitpix=-32 dim1=512 dim2=512 -\& foo.arr[ARRAY(r512.400)] # bitpix=-32 dim1=512 dim2=400 -\& foo.arr[ARRAY(r512.400]) # bitpix=-32 dim1=512 dim2=400 -\& foo.arr[ARRAY(r512.400:2880)] # bitpix=-32 dim1=512 dim2=400 skip=2880 -\& foo.arr[ARRAY(r512l)] # bitpix=-32 dim1=512 dim2=512 endian=little -\& setenv ARRAY "r512.400:2880" -\& foo.arr[ARRAY()] # bitpix=-32 dim1=512 dim2=400 skip=2880 -.Ve -.PP -\&\fBSpecifying Image Sections\fR -.PP -Once a data file (and possibly, a \s-1FITS\s0 extension) has been specified, -the next (optional) part of a bracket specification can be used to -select image \fBsection\fR information, i.e., to specify the x,y -limits of an image section, as well as the blocking factor to apply to -that section. This information can be added to any file specification but -only is used by Funtools image processing routines. -.PP -The format of the image section specification is one of the following: -.IP "\(bu" 4 -file[xy0:xy1,block] -.IP "\(bu" 4 -file[x0:x1,y0:y1,block] -.IP "\(bu" 4 -file[x0:x1,*,block] -.IP "\(bu" 4 -file[*,y0:y1,block] -.IP "\(bu" 4 -file[*,block] -.PP -where the limit values can be ints or \*(L"*\*(R" for default. A single \*(L"*\*(R" -can be used instead of val:val, as shown. Note that blocking is -applied to the section after it is extracted. -.PP -In addition to image sections specified by the lo and hi x,y limits, image -sections using center positions can be specified: -.IP "\(bu" 4 -file[dim1@xcen,dim2@ycen] -.IP "\(bu" 4 -file[xdim2@xcen@ycen] -.IP "\(bu" 4 -file[dim1@xcen,dim2@ycen,block] -.IP "\(bu" 4 -file[dim@xcen@ycen,block] -.PP -Note that the (float) values for dim, dim1, dim2, xcen, ycen must be -specified or else the expression does not make sense! -.PP -In all cases, block is optional and defaults to 1. An 's' or 'a' can -be appended to signify \*(L"sum\*(R" or \*(L"average\*(R" blocking (default is \*(L"sum\*(R"). -Section specifications are given in image coordinates by default. If you -wish to specify physical coordinates, add a 'p' as the last character -of the section specification, before the closing bracket. -For example: -.IP "\(bu" 4 -file[\-8:\-7,\-8:\-7p] -.IP "\(bu" 4 -file[\-8:\-7,\-8:\-7,2p] -.PP -A section can be specified in any Funtools file name. If the operation -to be applied to that file is an imaging operation, then the -specification will be utilized. If the operation is purely a table -operation, then the section specification is ignored. -.PP -Do not be confused by: -.PP -.Vb 2 -\& foo.fits[2] -\& foo.fits[*,2] -.Ve -.PP -The former specifies opening the second extension of the \s-1FITS\s0 file. -The latter specifies application of block 2 to the image section. -.PP -Note that the section specification must come after -any of \s-1FITS\s0 \fBext\fR name or \fBind\fR number, -but all sensible defaults are supported: -.IP "\(bu" 4 -file[ext] -.IP "\(bu" 4 -file[ext,index] -.IP "\(bu" 4 -file[index] -.IP "\(bu" 4 -file[ext,section] -.IP "\(bu" 4 -file[ext,index,section] -.IP "\(bu" 4 -file[index,section] -.IP "\(bu" 4 -file[section] -.PP -\&\fBBinning \s-1FITS\s0 Binary Tables and Non-FITS Event Files\fR -.PP -If a \s-1FITS\s0 binary table or a non-FITS raw event file is to be binned -into a 2D image (e.g., using the -funimage -program), it is necessary to specify the two columns to be used for the -binning, as well as the dimensions of the image. Funtools first looks -for a specifier of the form: -.PP -.Vb 1 -\& bincols=([xnam[:tlmin[:tlmax:[binsiz]]]],[ynam[:tlmin[:tlmax[:binsiz]]]]) -.Ve -.PP -in bracket syntax, and uses the column names thus specified. The tlmin, tlmax, -and binsiz specifiers determine the image binning dimensions using: -.PP -.Vb 2 -\& dim = (tlmax - tlmin)/binsiz (floating point data) -\& dim = (tlmax - tlmin)/binsiz + 1 (integer data) -.Ve -.PP -These tlmin, tlmax, and binsiz specifiers can be omitted if \s-1TLMIN\s0, -\&\s-1TLMAX\s0, and \s-1TDBIN\s0 header parameters are present in the \s-1FITS\s0 binary -table header, respectively. If only one parameter is specified, it is -assumed to be tlmax, and tlmin defaults to 1. If two parameters are -specified, they are assumed to be tlmin and tlmax. -.PP -For example, to bin an \s-1HRC\s0 event list columns \*(L"\s-1VPOS\s0\*(R" and \*(L"\s-1UPOS\s0\*(R", use: -.PP -.Vb 1 -\& hrc.nepr[bincols=(VPOS,UPOS)] -.Ve -.PP -or -.PP -.Vb 1 -\& hrc.nepr[bincols=(VPOS:49152,UPOS:4096)] -.Ve -.PP -Note that you can optionally specify the dimensions of these columns -to cover cases where neither \s-1TLMAX\s0 keywords are defined in -the header. If either dimension is specified, then both must be specified. -.PP -You can set the \s-1FITS_BINCOLS\s0 or \s-1EVENTS_BINCOLS\s0 environment variable as -an alternative to adding the \*(L"bincols=\*(R" specifier to each file name -for \s-1FITS\s0 binary tables and raw event files, respectively. If no -binning keywords or environment variables are specified, or if the -specified columns are not in the binary table, the Chandra parameters -\&\s-1CPREF\s0 (or \s-1PREFX\s0) are searched for in the \s-1FITS\s0 binary table header. -Failing this, columns named \*(L"X\*(R" and \*(L"Y\*(R" are sought. If these are not -found, the code looks for columns containing the characters \*(L"X\*(R" and -\&\*(L"Y\*(R". Thus, you can bin on \*(L"\s-1DETX\s0\*(R" and \*(L"\s-1DETX\s0\*(R" columns without -specifying them, if these are the only column names containing the \*(L"X\*(R" -and \*(L"Y\*(R" characters. -.PP -Ordinarily, each event or row contributes one count to an image pixel -during the 2D binning process. Thus, if five events all have the same -(x,y) position, the image pixel value for that position will have a -value of five. It is possible to specify a variable contribution -for each event by using the vcol=[colname] filter spec: -.PP -.Vb 1 -\& vcol=[colname] -.Ve -.PP -The vcol colname is a column containing a numeric value in each event row -that will be used as the contribution of the given event to its image -pixel. For example, consider an event file that has the following content: -.PP -.Vb 10 -\& x:e:4 y:e:4 v:e -\& ------ ------ ---- -\& 1 1 1.0 -\& 2 2 2.0 -\& 3 3 3.0 -\& 4 4 0.0 -\& 1 1 1.0 -\& 2 2 2.0 -\& 3 3 3.0 -\& 4 4 4.0 -.Ve -.PP -There are two events with x,y value of (1,1) so ordinarily a 2D image will -have a value of 2 in the (1,1) pixel. If the v column is specified as the -value column: -.PP -.Vb 1 -\& foo.fits'[vcol=v]' -.Ve -.PP -then each pixel will contain the additive sum of the associated (x,y) -column values from the v column. For example, image pixel (1,1) will -contain 1. + 1. = 2, image pixel (2,2) will contain (2 + 2) = 4, etc. -.PP -An important variation on the use of a value column to specify the -contribution an event makes to an image pixel is when the value column -contains the reciprocal of the event contribution. For this case, the -column name should be prefixed with a / (divide sign) thus: -.PP -.Vb 1 -\& foo.fits'[vcol=/v]' -.Ve -.PP -Each image pixel value will then be the sum of the reciprocals of the value -column. A zero in the value column results in NaN (not a number). -Thus, in the above example, image pixel (1.1) will contain 1/1 + 1/1 = 2, -image pixel (2,2) will contain (1/2 + 1/2) = 1, etc. Image pixel (4,4) -will contain (1/0 + 1/4) = NaN. -.PP -You can set the \s-1FITS_VCOL\s0 or \s-1EVENTS_VCOL\s0 environment variable as -an alternative to adding the \*(L"vcol=\*(R" specifier to each file name -for \s-1FITS\s0 binary tables and raw event files, respectively. -.PP -Finally, when binning events, the data type of the resulting 2D image -must be specified. This can be done with the \*(L"bitpix=[n]\*(R" keyword in -the bracket specification. For example: -.PP -.Vb 1 -\& events.fits[bincols=(VPOS,UPOS),bitpix=-32] -.Ve -.PP -will create a floating point image binned on columns \s-1VPOS\s0 and \s-1UPOS\s0. -If no bitpix keyword is specified, bitpix=32 is assumed. As with -bincols values, you also can use the \s-1FITS_BITPIX\s0 and \s-1EVENTS_BITPIX\s0 -environment variables to set this value for \s-1FITS\s0 binary tables and -raw event files, respectively. -.PP -The \fBfunimage\fR program also allows you to create a 1D image projection -along any column of a table by using the \fBbincols=[column]\fR -filter specification and specifying a single column. -For example, the following command projects a 1D image along -the chipx column of a table: -.PP -.Vb 1 -\& funimage ev.fits'[bincols=chipx]' im.fits -.Ve -.PP -See funimage for more -information about creating 1D and 2D images. -.PP -Finally, please note that Funtools supports most \s-1FITS\s0 standards. -We will add missing support as required by the community. In general, -however, we do not support non-standard extensions. For example, we -sense the presence of the binary table 'variable length array' -proposed extension and we pass it along when copying and filtering -files, but we do not process it. We will add support for new standards -as they become official. -.PP -\&\fBTable and Spatial Region Filters\fR -.PP -Note that, in addition extensions and image sections, Funtools bracket -notation can be used to specify table and spatial region filters. These -filters are always placed after the image section information. They -can be specified in the same bracket or in a separate bracket -immediately following: -.IP "\(bu" 4 -file[ext|ind|\fIARRAY()\fR|\fIEVENTS()\fR,section][filters] -.IP "\(bu" 4 -file[ext|ind|\fIARRAY()\fR|\fIEVENTS()\fR,section,filters] -.PP -where: -.IP "\(bu" 4 -\&\fBfile\fR is the Funtools file name -.IP "\(bu" 4 -\&\fB\s-1\f(BIARRAY\s0()\fB\fR is an array specification -.IP "\(bu" 4 -\&\fB\s-1\f(BIEVENTS\s0()\fB\fR is an event list specification -.IP "\(bu" 4 -\&\fBext\fR is the \s-1FITS\s0 extension name -.IP "\(bu" 4 -\&\fBind\fR is the \s-1FITS\s0 extension number -.IP "\(bu" 4 -\&\fBsection\fR is the image section to extract -.IP "\(bu" 4 -\&\fBfilters\fR are spatial region and table (row) filters to apply -.PP -The topics of table and region filtering are covered in detail in: -.IP "\(bu" 4 -Table Filtering -.IP "\(bu" 4 -Spatial Region Filtering -.PP -\&\fBDisk Files and Other Supported File Types\fR -.PP -The specified \fBfile\fR usually is an ordinary disk file. In -addition, gzip'ed files are supported in Funtools: gzip'ed input files -are automatically uncompressed as they are read, and gzip'ed output -files are compressed as they are written. \s-1NB:\s0 if a \s-1FITS\s0 binary table -is written in gzip format, the number of rows in the table will be set -to \-1. Such a file will work with Funtools programs but will not work -with other \s-1FITS\s0 programs such as ds9. -.PP -The special keywords \*(L"stdin\*(R" and \*(L"stdout\*(R" designate Unix standard -input and standard output, respectively. The string \*(L"\-\*(R" (hyphen) will -be taken to mean \*(L"stdin\*(R" if the file is opened for reading and -\&\*(L"stdout\*(R" if the file is opened for writing. -.PP -A file also can be an \s-1INET\s0 socket on the same or another machine using -the syntax: -.PP -.Vb 1 -\& machine:port -.Ve -.PP -Thus, for example: -.PP -.Vb 1 -\& karapet:1428 -.Ve -.PP -specifies that I/O should be performed to/from port 1428 on the -machine karapet. If no machine name is specified, the default is to -use the current machine: -.PP -.Vb 1 -\& :1428 -.Ve -.PP -This means to open port 1428 on the current machine. Socket support -allows you to generate a distributed pipe: -.PP -.Vb 2 -\& on karapet: funtask1 in.fits bynars:1428 -\& on bynars: funtask2 :1428 out.fits -.Ve -.PP -The socket mechanism thus supports simple parallel processing using -\&\fBprocess decomposition\fR. Note that parallel processing using -\&\fBdata decomposition\fR is supported via the \fBsection\fR specifier (see -below), and the \fBrow#\fR specifier, which is part of -Table Filtering. -.PP -A file also can be a pointer to shared memory using the syntax: -.PP -.Vb 1 -\& shm:[id|@key][:size] -.Ve -.PP -A shared memory segment is specified with a \fBshm:\fR prefix, -followed by either the shared memory id or the shared memory key -(where the latter is prefixed by the '@' character). The size (in -bytes) of the shared memory segment can then be appended (preceded by -the ':' character). If the size specification is absent, the code will -attempt to determine the length automatically. -.PP -If the open mode contains the string \*(L"w+\*(R", then the memory segment will be -created if it does not exist. (It also will be released and deleted when the -file is closed.) In the case where a memory segment is being created, the -length of the segment is required. -.PP -A file also can be Unix piped command (i.e. a program to run) using the syntax: -.PP -.Vb 1 -\& "pipe: command arg1 ... argn" -.Ve -.PP -The output from the command must be a valid \s-1FITS\s0 file. It is important -to use quotes to protect spaces so that command arguments are passed -correctly. A silly example is: -.PP -.Vb 1 -\& fundisp "pipe: funtable 'foo.fits[cir 512 512 .1]' stdout" -.Ve -.PP -This seemed like a good idea at the time ... -.PP -\&\fBLists of Files\fR -.PP -Funtools also will process a list of files as a single file using the -syntax: -.PP -.Vb 1 -\& "list: file1 file2 ... filen" -.Ve -.PP -The files in the list are separated by whitespace. Any of the -above file types can be used. For example, if two files, foo1.fits and -foo2.fits, are part of the same observation, they can be processed as -a single file (using their own filters): -.PP -.Vb 17 -\& fundisp "list: foo1.fits[cir(512,512,10)] foo2.fits[cir(511,511,10)]" -\& X Y PHA PI TIME DX DY -\& -------- -------- -------- -------- --------------------- -------- -------- -\& 512 512 6 7 79493997.45854475 578 574 -\& 512 512 8 9 79494575.58943175 579 573 -\& 512 512 5 6 79493631.03866175 578 575 -\& 512 512 5 5 79493290.86521725 578 575 -\& 512 512 8 9 79493432.00990875 579 573 -\& 511 511 5 5 79488631.09462625 580 575 -\& 511 511 10 11 79488780.60006675 580 573 -\& 511 511 4 4 79494562.35474326 580 575 -\& 511 511 6 6 79488203.01561825 580 575 -\& 511 511 6 6 79488017.99730176 580 575 -\& 511 511 4 4 79494332.45355175 580 575 -\& 511 511 9 10 79492685.94014275 581 574 -\& 511 511 5 5 79487708.71298325 580 575 -\& 511 511 8 9 79493719.00160225 581 573 -.Ve -.PP -Again, note that it is important to avoid spaces in the filters -because the list separator also is whitespace. To protect whitespace -in a filter, enclose the file specification in quotes: -.PP -.Vb 1 -\& fundisp "list: 'foo1.fits[cir 512 512 .1]' foo2.fits[cir(511,511,.1)]" -.Ve -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funfilters.7 b/funtools/man/man7/funfilters.7 deleted file mode 100644 index 3c96e6d..0000000 --- a/funtools/man/man7/funfilters.7 +++ /dev/null @@ -1,464 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funfilters 7" -.TH funfilters 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -Funfilters \- Filtering Rows in a Table -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document contains a summary of the user interface for -filtering rows in binary tables. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Table filtering allows a program to select rows from an table (e.g., -X\-ray event list) by checking each row against one or more expressions -involving the columns in the table. When a table is filtered, only -valid rows satisfying these expressions are passed through for processing. -.PP -A filter expression is specified using bracket notation appended to -the filename of the data being processed: -.PP -.Vb 1 -\& foo.fits[pha==1&&pi==2] -.Ve -.PP -It is also possible to put region specification inside a file and -then pass the filename in bracket notation: -.PP -.Vb 1 -\& foo.fits[@my.reg] -.Ve -.PP -Filters must be placed after the extension and image section -information, when such information is present. The correct order is: -.IP "\(bu" 4 -file[fileinfo,sectioninfo][filters] -.IP "\(bu" 4 -file[fileinfo,sectioninfo,filters] -.PP -where: -.IP "\(bu" 4 -\&\fBfile\fR is the Funtools file name -.IP "\(bu" 4 -\&\fBfileinfo\fR is an \s-1ARRAY\s0, \s-1EVENT\s0, \s-1FITS\s0 extension, or \s-1FITS\s0 index -.IP "\(bu" 4 -\&\fBsectioninfo\fR is the image section to extract -.IP "\(bu" 4 -\&\fBfilters\fR are spatial region and table (row) filters to apply -.PP -See Funtools Files for more information -on file and image section specifications. -.PP -\&\fBFilter Expressions\fR -.PP -Table filtering can be performed on columns of data in a \s-1FITS\s0 -binary table or a raw event file. Table filtering is accomplished by -means of \fBtable filter specifications\fR. An table filter -specification consists of one or more \fBfilter expressions\fR Filter -specifications also can contain comments and local/global processing -directives. -.PP -More specifically, a filter specification consist of one or more lines -containing: -.PP -.Vb 13 -\& # comment until end of line -\& # include the following file in the table descriptor -\& @file -\& # each row expression can contain filters separated by operators -\& [filter_expression] BOOLOP [filter_expression2], ... -\& # each row expression can contain filters separated by the comma operator -\& [filter_expression1], [filter_expression2], ... -\& # the special row# keyword allows a range of rows to be processed -\& row#=m:n -\& # or a single row -\& row#=m -\& # regions are supported -- but are described elsewhere -\& [spatial_region_expression] -.Ve -.PP -A single filter expression consists of an arithmetic, logical, or -other operations involving one or more column values from a -table. Columns can be compared to other columns, to header values, -or to numeric constants. Standard math functions can be applied to -columns. Separate filter expressions can be combined using boolean operators. -Standard C semantics can be used when constructing expressions, with -the usual precedence and associativity rules holding sway: -.PP -.Vb 15 -\& Operator Associativity -\& -------- ------------- -\& () left to right -\& !! (logical not) right to left -\& ! (bitwise not) - (unary minus) right to left -\& * / left to right -\& + - left to right -\& < <= > >= left to right -\& == != left to right -\& & (bitwise and) left to right -\& ^ (bitwise exclusive or) left to right -\& | (bitwise inclusive or) left to right -\& && (logical and) left to right -\& || (logical or) left to right -\& = right to left -.Ve -.PP -For example, if energy and pha are columns in a table, -then the following are valid expressions: -.PP -.Vb 4 -\& pha>1 -\& energy == pha -\& (pha>1) && (energy<=2) -\& max(pha,energy)>=2.5 -.Ve -.PP -Comparison values can be integers or floats. Integer comparison values can be -specified in decimal, octal (using '0' as prefix), hex (using '0x' as prefix) -or binary (using '0b' as prefix). Thus, the following all specify the same -comparison test of a status mask: -.PP -.Vb 4 -\& (status & 15) == 8 # decimal -\& (status & 017) == 010 # octal -\& (status & 0xf) == 0x8 # hex -\& (status & 0b1111) == 0b1000 # binary -.Ve -.PP -The special keyword row# allows you to process a range of rows. -When row# is specified, the filter code skips to the designated -row and only processes the specified number of rows. The -\&\*(L"*\*(R" character can be utilized as the high limit value to denote -processing of the remaining rows. Thus: -.PP -.Vb 1 -\& row#=100:109 -.Ve -.PP -processes 10 rows, starting with row 100 (counting from 1), -while: -.PP -.Vb 1 -\& row#=100:* -.Ve -.PP -specifies that all but the first 99 rows are to be processed. -.PP -Spatial region filtering allows a program to select regions of an -image or rows of a table (e.g., X\-ray events) using simple geometric -shapes and boolean combinations of shapes. For a complete description -of regions, see Spatial Region Filtering. -.PP -\&\fBSeparators Also Are Operators\fR -.PP -As mentioned previously, multiple filter expressions can be specified -in a filter descriptor, separated by commas or new\-lines. -When such a comma or new-line separator is used, the boolean \s-1AND\s0 operator -is automatically generated in its place. Thus and expression such as: -.PP -.Vb 1 -\& pha==1,pi=2:4 -.Ve -.PP -is equivalent to: -.PP -.Vb 1 -\& (pha==1) && (pi>=2&&pi<=4) -.Ve -.PP -[Note that the behavior of separators is different for filter expressions -and spatial region expressions. The former uses \s-1AND\s0 as the operator, while -the latter user \s-1OR\s0. See -Combining Region and Table Filters -for more information about these conventions and how they are treated -when combined.] -.PP -\&\fBRange Lists\fR -.PP -Aside from the standard C syntax, filter expressions can make use of -IRAF-style \fBrange lists\fR which specify a range of values. The -syntax requires that the column name be followed by an '=' sign, which -is followed by one or more comma-delimited range expressions of the form: -.PP -.Vb 4 -\& col = vv # col == vv in range -\& col = :vv # col <= vv in range -\& col = vv: # col >= vv in range -\& col = vv1:vv2 # vv1 <= col <= vv2 in range -.Ve -.PP -The vv's above must be numeric constants; the right hand side of a -range list cannot contain a column name or header value. -.PP -Note that, unlike an ordinary comma separator, the comma separator used -between two or more range expressions denotes \s-1OR\s0. Thus, when two or -more range expressions are combined with a comma separator, the resulting -expression is a shortcut for more complicated boolean logic. For example: -.PP -.Vb 1 -\& col = :3,6:8,10: -.Ve -.PP -is equivalent to: -.PP -.Vb 1 -\& (col=6 && col =10) -.Ve -.PP -Note also that the single-valued rangelist: -.PP -.Vb 1 -\& col = val -.Ve -.PP -is equivalent to the C\-based filter expression: -.PP -.Vb 1 -\& col == val -.Ve -.PP -assuming, of course, that val is a numeric constant. -.PP -\&\fBMath Operations and Functions\fR -.PP -It is permissible to specify C math functions as part of the filter syntax. -When the filter parser recognizes a function call, it automatically -includes the math.h and links in the C math library. Thus, it is -possible to filter rows by expressions such as these: -.IP "\(bu" 4 -(pi+pha)>(2+log(pi)\-pha) -.IP "\(bu" 4 -min(pi,pha)*14>x -.IP "\(bu" 4 -max(pi,pha)==(pi+1) -.IP "\(bu" 4 -feq(pi,pha) -.IP "\(bu" 4 -div(pi,pha)>0 -.PP -The function feq(a,b) returns true (1) if the difference between a and b -(taken as double precision values) is less than approximately 10E\-15. -The function div(a,b) divides a by b, but returns NaN (not a number) -if b is 0. It is a safe way to avoid floating point errors when -dividing one column by another. -.PP -\&\fBInclude Files\fR -.PP -The special \fB@filename\fR directive specifies an include file -containing filter expressions. This file is processed as part of -the overall filter descriptor: -.PP -.Vb 1 -\& foo.fits[pha==1,@foo] -.Ve -.PP -\&\fBHeader Parameters\fR -.PP -The filter syntax supports comparison between a column value and a -header parameter value of a \s-1FITS\s0 binary tables (raw event files have no -such header). The header parameters can be taken from the binary -table header or the primary header. For example, assuming there is a -header value \s-1MEAN_PHA\s0 in one of these headers, you can select photons -having exactly this value using: -.IP "\(bu" 4 -pha==MEAN_PHA -.PP -Table filtering is more easily described by means of examples. -Consider data containing the following table structure: -.IP "\(bu" 4 -double \s-1TIME\s0 -.IP "\(bu" 4 -int X -.IP "\(bu" 4 -int Y -.IP "\(bu" 4 -short \s-1PI\s0 -.IP "\(bu" 4 -short \s-1PHA\s0 -.IP "\(bu" 4 -int \s-1DX\s0 -.IP "\(bu" 4 -int \s-1DY\s0 -.PP -Tables can be filtered on these columns using \s-1IRAF/QPOE\s0 range syntax or -any valid C syntax. The following examples illustrate the possibilities: -.IP "\(bu" 4 -pha=10 -.IP "\(bu" 4 -pha==10 -.Sp -select rows whose pha value is exactly 10 -.IP "\(bu" 4 -pha=10:50 -.Sp -select rows whose pha value is in the range of 10 to 50 -.IP "\(bu" 4 -pha=10:50,100 -.Sp -select rows whose pha value is in the range of 10 to 50 or is -equal to 100 -.IP "\(bu" 4 -pha>=10 && pha<=50 -.Sp -select rows whose pha value is in the range of 10 to 50 -.IP "\(bu" 4 -pi=1,2&&pha>3 -.Sp -select rows whose pha value is 1 or 2 and whose pi value is 3 -.IP "\(bu" 4 -pi=1,2 || pha>3 -.Sp -select rows whose pha value is 1 or 2 or whose pi value is 3 -.IP "\(bu" 4 -pha==pi+1 -.Sp -select rows whose pha value is 1 less than the pi value -.IP "\(bu" 4 -(pha==pi+1) && (time>50000.0) -.Sp -select rows whose pha value is 1 less than the pi value -and whose time value is greater than 50000 -.IP "\(bu" 4 -(pi+pha)>20 -.Sp -select rows in which the sum of the pi and pha values is greater -than 20 -.IP "\(bu" 4 -pi%2==1 -.Sp -select rows in which the pi value is odd -.PP -Currently, integer range list limits cannot be specified in binary -notation (use decimal, hex, or octal instead). Please contact us if -this is a problem. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funidx.7 b/funtools/man/man7/funidx.7 deleted file mode 100644 index bf87bb8..0000000 --- a/funtools/man/man7/funidx.7 +++ /dev/null @@ -1,327 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funidx 7" -.TH funidx 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -Funidx \- Using Indexes to Filter Rows in a Table -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document contains a summary of the user interface for -filtering rows in binary tables with indexes. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Funtools Table Filtering allows rows in a -table to be selected based on the values of one or more columns in the -row. Because the actual filter code is compiled on the fly, it is very -efficient. However, for very large files (hundreds of Mb or larger), -evaluating the filter expression on each row can take a long time. Therefore, -funtools supports index files for columns, which are used automatically during -filtering to reduce dramatically the number of row evaluations performed. -The speed increase for indexed filtering can be an order of magnitude or -more, depending on the size of the file. -.PP -The funindex program creates an -index on one or more columns in a binary table. For example, to create an index -for the column pi in the file huge.fits, use: -.PP -.Vb 1 -\& funindex huge.fits pi -.Ve -.PP -This will create an index named huge_pi.idx. -.PP -When a filter expression is initialized for row evaluation, funtools -looks for an index file for each column in the filter expression. If -found, and if the file modification date of the index file is later -than that of the data file, then the index will be used to reduce the -number of rows that are evaluated in the filter. When -Spatial Region Filtering is part of the -expression, the columns associated with the region are checked for index -files. -.PP -If an index file is not available for a given column, then in general, -all rows must be checked when that column is part of a filter -expression. This is not true, however, when a non-indexed column is -part of an \s-1AND\s0 expression. In this case, only the rows that pass the -other part of the \s-1AND\s0 expression need to be checked. Thus, in some cases, -filtering speed can increase significantly even if all columns are not -indexed. -.PP -Also note that certain types of filter expression syntax cannot make -use of indices. For example, calling functions with column names as -arguments implies that all rows must be checked against the function -value. Once again, however, if this function is part of an \s-1AND\s0 -expression, then a significant improvement in speed still is possible -if the other part of the \s-1AND\s0 expression is indexed. -.PP -For example, note below the dramatic speedup in searching a 1 Gb -file using an \s-1AND\s0 filter, even when one of the columns (pha) has no -index: -.PP -.Vb 22 -\& time fundisp \e -\& huge.fits'[idx_activate=0,idx_debug=1,pha=2348&&cir 4000 4000 1]' \e -\& "x y pha" -\& x y pha -\& ---------- ----------- ---------- -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 42.36u 13.07s 6:42.89 13.7% -.Ve -.PP -.Vb 26 -\& time fundisp \e -\& huge.fits'[idx_activate=1,idx_debug=1,pha=2348&&cir 4000 4000 1]' \e -\& "x y pha" -\& x y pha -\& ---------- ----------- ---------- -\& idxeq: [INDEF] -\& idxand sort: x[ROW 8037025:8070128] y[ROW 5757665:5792352] -\& idxand(1): INDEF [IDX_OR_SORT] -\& idxall(1): [IDX_OR_SORT] -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 3999.48 4000.47 2348 -\& 1.55u 0.37s 1:19.80 2.4% -.Ve -.PP -When all columns are indexed, the increase in speed can be even more dramatic: -.PP -.Vb 22 -\& time fundisp \e -\& huge.fits'[idx_activate=0,idx_debug=1,pi=770&&cir 4000 4000 1]' \e -\& "x y pi" -\& x y pi -\& ---------- ----------- ---------- -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 42.60u 12.63s 7:28.63 12.3% -.Ve -.PP -.Vb 27 -\& time fundisp \e -\& huge.fits'[idx_activate=1,idx_debug=1,pi=770&&cir 4000 4000 1]' \e -\& "x y pi" -\& x y pi -\& ---------- ----------- ---------- -\& idxeq: pi start=9473025,stop=9492240 => pi[ROW 9473025:9492240] -\& idxand sort: x[ROW 8037025:8070128] y[ROW 5757665:5792352] -\& idxor sort/merge: pi[ROW 9473025:9492240] [IDX_OR_SORT] -\& idxmerge(5): [IDX_OR_SORT] pi[ROW] -\& idxall(1): [IDX_OR_SORT] -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 3999.48 4000.47 770 -\& 1.67u 0.30s 0:24.76 7.9% -.Ve -.PP -The miracle of indexed filtering (and indeed, of any indexing) is the -speed of the binary search on the index, which is of order log2(n) -instead of n. (The funtools binary search method is taken from -http://www.tbray.org/ongoing/When/200x/2003/03/22/Binary, to whom -grateful acknowledgement is made.) This means that the larger the -file, the better the performance. Conversely, it also means that for -small files, using an index (and the overhead involved) can slow -filtering down somewhat. Our tests indicate that on a file containing -a few tens of thousands of rows, indexed filtering can be 10 to 20 -percent slower than non-indexed filtering. Of course, your mileage -will vary with conditions (disk access speed, amount of available -memory, process load, etc.) -.PP -Any problem encountered during index processing will result in -indexing being turned off, and replaced by filtering all rows. You can turn -filtering off manually by setting the idx_activate variable to 0 (in a filter -expression) or the \s-1FILTER_IDX_ACTIVATE\s0 environment variable to 0 (in the global -environment). Debugging output showing how the indexes are being processed can -be displayed to stderr by setting the idx_debug variable to 1 (in a filter -expression) or the \s-1FILTER_IDX_DEBUG\s0 environment variable to 1 (in the global -environment). -.PP -Currently, indexed filtering only works with \s-1FITS\s0 binary tables and raw -event files. It does not work with text files. This restriction might be -removed in a future release. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funregions.7 b/funtools/man/man7/funregions.7 deleted file mode 100644 index 5c17572..0000000 --- a/funtools/man/man7/funregions.7 +++ /dev/null @@ -1,678 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funregions 7" -.TH funregions 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunRegions \- Spatial Region Filtering -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document contains a summary of the user interface for spatial -region filtering images and tables. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Spatial region filtering allows a program to select regions of an -image or rows of a table (e.g., X\-ray events) to process using -simple geometric shapes and boolean combinations of shapes. When an -image is filtered, only pixels found within these shapes are -processed. When a table is filtered, only rows found within these -shapes are processed. -.PP -Spatial region filtering for images and tables is accomplished by -means of \fBregion specifications\fR. A region specification -consists of one or more \fBregion expressions\fR, which are geometric -shapes,combined according to the rules of boolean algebra. Region -specifications also can contain comments and local/global processing -directives. -.PP -Typically, region specifications are specified using bracket notation -appended to the filename of the data being processed: -.PP -.Vb 1 -\& foo.fits[circle(512,512,100)] -.Ve -.PP -It is also possible to put region specification inside a file and -then pass the filename in bracket notation: -.PP -.Vb 1 -\& foo.fits[@my.reg] -.Ve -.PP -When region filters are passed in bracket notation in this manner, the -filtering is set up automatically when the file is opened and all -processing occurs through the filter. Programs also can use the filter -library \s-1API\s0 to open filters explicitly. -.PP -\&\fBRegion Expressions\fR -.PP -More specifically, region specifications consist of one or more lines -containing: -.PP -.Vb 9 -\& # comment until end of line -\& global keyword=value keyword=value ... # set global value(s) -\& # include the following file in the region descriptor -\& @file -\& # use the FITS image as a mask (cannot be used with other regions) -\& @fitsimage -\& # each region expression contains shapes separated by operators -\& [region_expression1], [region_expression2], ... -\& [region_expression], [region_expression], ... -.Ve -.PP -A single region expression consists of: -.PP -.Vb 2 -\& # parens and commas are optional, as is the + sign -\& [+-]shape(num , num , ...) OP1 shape num num num OP2 shape ... -.Ve -.PP -e.g.: -.PP -.Vb 3 -\& ([+-]shape(num , num , ...) && shape num num || shape(num, num) -\& # a comment can come after a region -- reserved for local properties -\& [+-]shape(num , num , ...) # local properties go here, e.g. color=red -.Ve -.PP -Thus, a region descriptor consists of one or more region -expressions or \fBregions\fR, separated by comas, new\-lines, or -semi\-colons. Each \fBregion\fR consists of one or more geometric -shapes combined using standard boolean operation. Several types -of shapes are supported, including: -.PP -.Vb 11 -\& shape: arguments: -\& ----- ---------------------------------------- -\& ANNULUS xcenter ycenter inner_radius outer_radius -\& BOX xcenter ycenter xwidth yheight (angle) -\& CIRCLE xcenter ycenter radius -\& ELLIPSE xcenter ycenter xwidth yheight (angle) -\& FIELD none -\& LINE x1 y1 x2 y2 -\& PIE xcenter ycenter angle1 angle2 -\& POINT x1 y1 -\& POLYGON x1 y1 x2 y2 ... xn yn -.Ve -.PP -In addition, the following regions accept \fBaccelerator\fR syntax: -.PP -.Vb 13 -\& shape arguments -\& ----- ------------------------------------------ -\& ANNULUS xcenter ycenter radius1 radius2 ... radiusn -\& ANNULUS xcenter ycenter inner_radius outer_radius n=[number] -\& BOX xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle) -\& BOX xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle) -\& CIRCLE xcenter ycenter r1 r2 ... rn # same as annulus -\& CIRCLE xcenter ycenter rinner router n=[number] # same as annulus -\& ELLIPSE xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle) -\& ELLIPSE xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle) -\& PIE xcenter ycenter angle1 angle2 (angle3) (angle4) (angle5) ... -\& PIE xcenter ycenter angle1 angle2 (n=[number]) -\& POINT x1 y1 x2 y2 ... xn yn -.Ve -.PP -Note that the circle accelerators are simply aliases for the annulus -accelerators. See region geometry -for more information about accelerators. -.PP -Finally, the following are combinations of pie with different shapes -(called \*(L"panda\*(R" for \*(L"Pie \s-1AND\s0 Annulus\*(R") allow for easy specification of -radial sections: -.PP -.Vb 6 -\& shape: arguments: -\& ----- --------- -\& PANDA xcen ycen ang1 ang2 nang irad orad nrad # circular -\& CPANDA xcen ycen ang1 ang2 nang irad orad nrad # circular -\& BPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # box -\& EPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # ellipse -.Ve -.PP -The panda and cpanda specify combinations of annulus and circle with pie, -respectively and give identical results. The bpanda combines box and pie, -while epanda combines ellipse and pie. -See region geometry -for more information about pandas. -.PP -The following \*(L"shapes\*(R" are ignored by funtools (generated by ds9): -.PP -.Vb 8 -\& shape: arguments: -\& ----- --------- -\& PROJECTION x1 y1 x2 y2 width # NB: ignored by funtools -\& RULER x1 y1 x2 y2 # NB: ignored by funtools -\& TEXT x y # NB: ignored by funtools -\& GRID # NB: ignored by funtools -\& TILE # NB: ignored by funtools -\& COMPASS # NB: ignored by funtools -.Ve -.PP -All arguments to regions are real values; integer values are -automatically converted to real where necessary. All angles are in -degrees and run from the positive image x\-axis to the positive image -y\-axis. If a rotation angle is part of the associated \s-1WCS\s0 header, that -angle is added implicitly as well. -.PP -Note that 3\-letter abbreviations are supported for all shapes, so that -you can specify \*(L"circle\*(R" or \*(L"cir\*(R". -.PP -\&\fBColumns Used in Region Filtering\fR -.PP -By default, the x,y values in a region expression refer to the two -\&\*(L"image binning\*(R" columns, i.e. the columns that would be used to -bin the data into an image. For images, these are just the 2 dimensions -of the image. For tables, these usually default to x and y but -can be changed as required. For example, in Funtools, new binning -columns are specified using a bincols=(col1,col2) statement within -the bracket string on the command line. -.PP -Alternate columns for region filtering can be specified by the syntax: -.PP -.Vb 1 -\& (col1,col2)=region(...) -.Ve -.PP -e.g.: -.PP -.Vb 3 -\& (X,Y)=annulus(x,y,ri,ro) -\& (PHA,PI)=circle(x,y,r) -\& (DX,DY)=ellipse(x,y,a,b[,angle]) -.Ve -.PP -\&\fBRegion Algebra\fR -.PP -(See also Region Algebra for more complete -information.) -.PP -Region shapes can be combined together using Boolean operators: -.PP -.Vb 6 -\& Symbol Operation Use -\& -------- --------- ----------------------------------- -\& ! not Exclude this shape from this region -\& & or && and Include only the overlap of these shapes -\& | or || inclusive or Include all of both shapes -\& ^ exclusive or Include both shapes except their overlap -.Ve -.PP -Note that the !region syntax must be combined with another region in order -that we be able to assign a region id properly. That is, -.PP -.Vb 1 -\& !circle(512,512,10) -.Ve -.PP -is not a legal region because there is no valid region id to work with. -To get the full field without a circle, combine the above with \fIfield()\fR, -as in: -.PP -.Vb 1 -\& field() && !circle(512,512,10) -.Ve -.PP -\&\fB Region Separators Also Are Operators\fR -.PP -As mentioned previously, multiple region expressions can be specified -in a region descriptor, separated by commas, new\-lines, or -semi\-colons. When such a separator is used, the boolean \s-1OR\s0 operator -is automatically generated in its place but, unlike explicit use of -the \s-1OR\s0 operator, the region \s-1ID\s0 is incremented (starting from 1). -.PP -For example, the two shapes specified in this example are given the -same region value: -.PP -.Vb 1 -\& foo.fits[circle(512,512,10)||circle(400,400,20)] -.Ve -.PP -On the other hand, the two shapes defined in the following example are -given different region values: -.PP -.Vb 1 -\& foo.fits[circle(512,512,10),circle(400,400,20)] -.Ve -.PP -Of course these two examples will both mask the same table rows or -pixels. However, in programs that distinguish region id's (such as -funcnts ), they will act -differently. The explicit \s-1OR\s0 operator will result in one region -expression consisting of two shapes having the same region id and -funcnts will report a single region. The comma operator will cause -funcnts to report two region expressions, each with one shape, in -its output. -.PP -In general, commas are used to separate region expressions entered -in bracket notation on the command line: -.PP -.Vb 2 -\& # regions are added to the filename in bracket notation -\& foo.fits[circle(512,512,100),circle(400,400,20)] -.Ve -.PP -New-lines are used to separate region -expressions in a file: -.PP -.Vb 4 -\& # regions usually are separated by new-lines in a file -\& # use @filename to include this file on the command line -\& circle(512,512,100) -\& circle(400,400,20) -.Ve -.PP -Semi-colons are provided for backward compatibility with the original -\&\s-1IRAF/PROS\s0 implementation and can be used in either case. -.PP -If a pixel is covered by two different regions expressions, it is -given the mask value of the \fBfirst\fR region that contains that -pixel. That is, successive regions \fBdo not\fR overwrite previous -regions in the mask, as was the case with the original \s-1PROS\s0 regions. -In this way, an individual pixel is covered by one and only one -region. This means that one must sometimes be careful about the order -in which regions are defined. If region N is fully contained within -region M, then N should be defined \fBbefore\fR M, or else it will be -\&\*(L"covered up\*(R" by the latter. -.PP -\&\fBRegion Exclusion\fR -.PP -Shapes also can be globally excluded from all the region specifiers in -a region descriptor by using a minus sign before a region: -.PP -.Vb 4 -\& operator arguments: -\& -------- ----------- -\& - Globally exclude the region expression following '-' sign -\& from ALL regions specified in this file -.Ve -.PP -The global exclude region can be used by itself; in such a case, \fIfield()\fR is -implied. -.PP -A global exclude differs from the local exclude (i.e. a shape prefixed -by the logical not \*(L"!\*(R" symbol) in that global excludes are logically -performed last, so that no region will contain pixels from a globally -excluded shape. A local exclude is used in a boolean expression with -an include shape, and only excludes pixels from that include shape. -Global excludes cannot be used in boolean expressions. -.PP -\&\fBInclude Files\fR -.PP -The \fB@filename\fR directive specifies an include file -containing region expressions. This file is processed as part of -the overall region descriptor: -.PP -.Vb 1 -\& foo.fits[circle(512,512,10),@foo] -.Ve -.PP -A filter include file simply includes text without changing the state -of the filter. It therefore can be used in expression. That is, if the -file foo1 contains \*(L"pi==1\*(R" and foo2 contains \*(L"pha==2\*(R" then -the following expressions are equivalent: -.PP -.Vb 3 -\& "[@foo1&&@foo2]" is equivalent to "[pi==1&&pha==2]" -\& "[pha==1||@foo2]" is equivalent to "[pi==1||pha==2]" -\& "[@foo1,@foo2]" is equivalent to "[pi==1,pha==2]" -.Ve -.PP -Be careful that you specify evaluation order properly using -parenthesis, especially if the include file contains multiple -filter statements. For example, consider a file containing two -regions such as: -.PP -.Vb 2 -\& circle 512 512 10 -\& circle 520 520 10 -.Ve -.PP -If you want to include only events (or pixels) that are in these regions -and have a pi value of 4, then the correct syntax is: -.PP -.Vb 1 -\& pi==4&&(@foo) -.Ve -.PP -since this is equivalent to: -.PP -.Vb 1 -\& pi==4 && (circle 512 512 10 || circle 520 520 10) -.Ve -.PP -If you leave out the parenthesis, you are filtering this statement: -.PP -.Vb 1 -\& pi==4 && circle 512 512 10 || circle 520 520 10) -.Ve -.PP -which is equivalent to: -.PP -.Vb 1 -\& (pi==4 && circle 512 512 10) || circle 520 520 10) -.Ve -.PP -The latter syntax only applies the pi test to the first region. -.PP -For image-style filtering, the \fB@filename\fR can specify an 8-bit -or 16-bit \s-1FITS\s0 image. In this case, the pixel values in the mask image -are used as the region mask. The valid pixels in the mask must have -positive values. Zero values are excluded from the mask and negative -values are not allowed. Moreover, the region id value is taken as -the image pixel value and the total number of regions is taken to be -the highest pixel value. The dimensions of the image mask must be less -than or equal to the image dimensions of the data. The mask will be -replicated as needed to match the size of the image. (Thus, best -results are obtained when the data dimensions are an even multiple of -the mask dimensions.) -.PP -An image mask can be used in any image filtering operation, regardless -of whether the data is of type image or table. For example, the -funcnts ) -program performs image filtering on images or tables, and so -\&\s-1FITS\s0 image masks are valid input for either type of data in this -program.. An image mask cannot be used in a program such as -fundisp ) -when the input data is a table, because fundisp displays -rows of a table and processes these rows using event-style filtering. -.PP -\&\fBGlobal and Local Properties of Regions\fR -.PP -The ds9 image display program describes a host of properties such as -color, font, fix/free state, etc. Such properties can be specified -globally (for all regions) or locally (for an individual region). -The \fBglobal\fR keyword specifies properties and qualifiers for all -regions, while local properties are specified in comments on the same -line as the region: -.PP -.Vb 4 -\& global color=red -\& circle(10,10,2) -\& circle(20,20,3) # color=blue -\& circle(30,30,4) -.Ve -.PP -The first and third circles will be red, which the second circle will -be blue. Note that funtools currently ignores region properties, as -they are used in display only. -.PP -\&\fB Coordinate Systems\fR -.PP -For each region, it is important to specify the coordinate system -used to interpret the region, i.e., to set the context in which position and -size values are interpreted. For this purpose, the following keywords -are recognized: -.PP -.Vb 12 -\& name description -\& ---- ------------------------------------------ -\& PHYSICAL pixel coords of original file using LTM/LTV -\& IMAGE pixel coords of current file -\& FK4, B1950 sky coordinate systems -\& FK5, J2000 sky coordinate systems -\& GALACTIC sky coordinate systems -\& ECLIPTIC sky coordinate systems -\& ICRS currently same as J2000 -\& LINEAR linear wcs as defined in file -\& AMPLIFIER mosaic coords of original file using ATM/ATV -\& DETECTOR mosaic coords of original file using DTM/DTV -.Ve -.PP -\&\fBSpecifying Positions, Sizes, and Angles\fR -.PP -The arguments to region shapes can be floats or integers describing -positions and sizes. They can be specified as pure numbers or using -explicit formatting directives: -.PP -.Vb 11 -\& position arguments description -\& ------------------ ------------------------------ -\& [num] context-dependent (see below) -\& [num]d degrees -\& [num]r radians -\& [num]p physical pixels -\& [num]i image pixels -\& [num]:[num]:[num] hms for 'odd' position arguments -\& [num]:[num]:[num] dms for 'even' position arguments -\& [num]h[num]m[num]s explicit hms -\& [num]d[num]m[num]s explicit dms -.Ve -.PP -.Vb 9 -\& size arguments description -\& -------------- ----------- -\& [num] context-dependent (see below) -\& [num]" arc seconds -\& [num]' arc minutes -\& [num]d degrees -\& [num]r radians -\& [num]p physical pixels -\& [num]i image pixels -.Ve -.PP -When a \*(L"pure number\*(R" (i.e. one without a format directive such as 'd' -for 'degrees') is specified, its interpretation depends on the context -defined by the 'coordsys' keyword. In general, the rule is: -.PP -All pure numbers have implied units corresponding to the current -coordinate system. -.PP -If no such system is explicitly specified, the default system is -implicitly assumed to be \s-1PHYSICAL\s0. -.PP -In practice this means that for \s-1IMAGE\s0 and \s-1PHYSICAL\s0 systems, pure -numbers are pixels. Otherwise, for all systems other than linear, -pure numbers are degrees. For \s-1LINEAR\s0 systems, pure numbers are in the -units of the linear system. This rule covers both positions and -sizes. -.PP -The input values to each shape can be specified in several coordinate -systems including: -.PP -.Vb 12 -\& name description -\& ---- ---------------------------- -\& IMAGE pixel coords of current file -\& LINEAR linear wcs as defined in file -\& FK4, B1950 various sky coordinate systems -\& FK5, J2000 -\& GALACTIC -\& ECLIPTIC -\& ICRS -\& PHYSICAL pixel coords of original file using LTM/LTV -\& AMPLIFIER mosaic coords of original file using ATM/ATV -\& DETECTOR mosaic coords of original file using DTM/DTV -.Ve -.PP -If no coordinate system is specified, \s-1PHYSICAL\s0 is assumed. \s-1PHYSICAL\s0 or -a World Coordinate System such as J2000 is preferred and most general. -The coordinate system specifier should appear at the beginning of the -region description, on a separate line (in a file), or followed by a -new-line or semicolon; e.g., -.PP -.Vb 2 -\& global coordsys physical -\& circle 6500 9320 200 -.Ve -.PP -The use of celestial input units automatically implies \s-1WORLD\s0 -coordinates of the reference image. Thus, if the world coordinate -system of the reference image is J2000, then -.PP -.Vb 1 -\& circle 10:10:0 20:22:0 3' -.Ve -.PP -is equivalent to: -.PP -.Vb 1 -\& circle 10:10:0 20:22:0 3' # j2000 -.Ve -.PP -Note that by using units as described above, you may mix coordinate -systems within a region specifier; e.g., -.PP -.Vb 1 -\& circle 6500 9320 3' # physical -.Ve -.PP -Note that, for regions which accept a rotation angle: -.PP -ellipse (x, y, r1, r2, angle) -box(x, y, w, h, angle) -.PP -the angle is relative to the specified coordinate system. In -particular, if the region is specified in \s-1WCS\s0 coordinates, the angle -is related to the \s-1WCS\s0 system, not x/y image coordinate axis. For \s-1WCS\s0 -systems with no rotation, this obviously is not an issue. However, -some images do define an implicit rotation (e.g., by using a non-zero -\&\s-1CROTA\s0 value in the \s-1WCS\s0 parameters) and for these images, the angle -will be relative to the \s-1WCS\s0 axes. In such case, a region specification -such as: -.PP -fk4;ellipse(22:59:43.985, +58:45:26.92,320\*(L", 160\*(R", 30) -.PP -will not, in general, be the same region specified as: -.PP -physical;ellipse(465, 578, 40, 20, 30) -.PP -even when positions and sizes match. The angle is relative to \s-1WCS\s0 axes -in the first case, and relative to physical x,y axes in the second. -.PP -More detailed descriptions are available for: -Region Geometry, -Region Algebra, -Region Coordinates, and -Region Boundaries. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funtext.7 b/funtools/man/man7/funtext.7 deleted file mode 100644 index b24b317..0000000 --- a/funtools/man/man7/funtext.7 +++ /dev/null @@ -1,713 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funtext 7" -.TH funtext 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -Funtext \- Support for Column\-based Text Files -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document contains a summary of the options for processing column-based -text files. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Funtools will automatically sense and process \*(L"standard\*(R" -column-based text files as if they were \s-1FITS\s0 binary tables without any -change in Funtools syntax. In particular, you can filter text files -using the same syntax as \s-1FITS\s0 binary tables: -.PP -.Vb 3 -\& fundisp foo.txt'[cir 512 512 .1]' -\& fundisp \-T foo.txt > foo.rdb -\& funtable foo.txt'[pha=1:10,cir 512 512 10]' foo.fits -.Ve -.PP -The first example displays a filtered selection of a text file. The -second example converts a text file to an \s-1RDB\s0 file. The third example -converts a filtered selection of a text file to a \s-1FITS\s0 binary table. -.PP -Text files can also be used in Funtools image programs. In this case, -you must provide binning parameters (as with raw event files), using -the bincols keyword specifier: -.PP -.Vb 1 -\& bincols=([xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]] -.Ve -.PP -For example: -.PP -.Vb 1 -\& funcnts foo'[bincols=(x:1024,y:1024)]' "ann 512 512 0 10 n=10" -.Ve -.PP -\&\fBStandard Text Files\fR -.PP -Standard text files have the following characteristics: -.IP "\(bu" 4 -Optional comment lines start with # -.IP "\(bu" 4 -Optional blank lines are considered comments -.IP "\(bu" 4 -An optional table header consists of the following (in order): -.RS 4 -.IP "\(bu" 4 -a single line of alpha-numeric column names -.IP "\(bu" 4 -an optional line of unit strings containing the same number of cols -.IP "\(bu" 4 -an optional line of dashes containing the same number of cols -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Data lines follow the optional header and (for the present) consist of - the same number of columns as the header. -.IP "\(bu" 4 -Standard delimiters such as space, tab, comma, semi\-colon, and bar. -.PP -Examples: -.PP -.Vb 5 -\& # rdb file -\& foo1 foo2 foo3 foos -\& ---- ---- ---- ---- -\& 1 2.2 3 xxxx -\& 10 20.2 30 yyyy -.Ve -.PP -.Vb 5 -\& # multiple consecutive whitespace and dashes -\& foo1 foo2 foo3 foos -\& --- ---- ---- ---- -\& 1 2.2 3 xxxx -\& 10 20.2 30 yyyy -.Ve -.PP -.Vb 2 -\& # comma delims and blank lines -\& foo1,foo2,foo3,foos -.Ve -.PP -.Vb 2 -\& 1,2.2,3,xxxx -\& 10,20.2,30,yyyy -.Ve -.PP -.Vb 4 -\& # bar delims with null values -\& foo1|foo2|foo3|foos -\& 1||3|xxxx -\& 10|20.2||yyyy -.Ve -.PP -.Vb 3 -\& # header-less data -\& 1 2.2 3 xxxx -\& 10 20.2 30 yyyy -.Ve -.PP -The default set of token delimiters consists of spaces, tabs, commas, -semi\-colons, and vertical bars. Several parsers are used -simultaneously to analyze a line of text in different ways. One way -of analyzing a line is to allow a combination of spaces, tabs, and -commas to be squashed into a single delimiter (no null values between -consecutive delimiters). Another way is to allow tab, semi\-colon, and -vertical bar delimiters to support null values, i.e. two consecutive -delimiters implies a null value (e.g. \s-1RDB\s0 file). A successful parser -is one which returns a consistent number of columns for all rows, with -each column having a consistent data type. More than one parser can -be successful. For now, it is assumed that successful parsers all -return the same tokens for a given line. (Theoretically, there are -pathological cases, which will be taken care of as needed). Bad parsers -are discarded on the fly. -.PP -If the header does not exist, then names \*(L"col1\*(R", \*(L"col2\*(R", etc. are -assigned to the columns to allow filtering. Furthermore, data types -for each column are determined by the data types found in the columns -of the first data line, and can be one of the following: string, int, -and double. Thus, all of the above examples return the following -display: -.PP -.Vb 4 -\& fundisp foo'[foo1>5]' -\& FOO1 FOO2 FOO3 FOOS -\& ---------- --------------------- ---------- ------------ -\& 10 20.20000000 30 yyyy -.Ve -.PP -\&\fBComments Convert to Header Params\fR -.PP -Comments which precede data rows are converted into header parameters and -will be written out as such using funimage or funhead. Two styles of comments -are recognized: -.PP -1. FITS-style comments have an equal sign \*(L"=\*(R" between the keyword and -value and an optional slash \*(L"/\*(R" to signify a comment. The strict \s-1FITS\s0 -rules on column positions are not enforced. In addition, strings only -need to be quoted if they contain whitespace. For example, the following -are valid FITS-style comments: -.PP -.Vb 5 -\& # fits0 = 100 -\& # fits1 = /usr/local/bin -\& # fits2 = "/usr/local/bin /opt/local/bin" -\& # fits3c = /usr/local/bin /opt/local/bin /usr/bin -\& # fits4c = "/usr/local/bin /opt/local/bin" / path dir -.Ve -.PP -Note that the fits3c comment is not quoted and therefore its value is the -single token \*(L"/usr/local/bin\*(R" and the comment is \*(L"opt/local/bin /usr/bin\*(R". -This is different from the quoted comment in fits4c. -.PP -2. Free-form comments can have an optional colon separator between the -keyword and value. In the absence of quote, all tokens after the -keyword are part of the value, i.e. no comment is allowed. If a string -is quoted, then slash \*(L"/\*(R" after the string will signify a comment. -For example: -.PP -.Vb 4 -\& # com1 /usr/local/bin -\& # com2 "/usr/local/bin /opt/local/bin" -\& # com3 /usr/local/bin /opt/local/bin /usr/bin -\& # com4c "/usr/local/bin /opt/local/bin" / path dir -.Ve -.PP -.Vb 4 -\& # com11: /usr/local/bin -\& # com12: "/usr/local/bin /opt/local/bin" -\& # com13: /usr/local/bin /opt/local/bin /usr/bin -\& # com14c: "/usr/local/bin /opt/local/bin" / path dir -.Ve -.PP -Note that com3 and com13 are not quoted, so the whole string is part of -the value, while comz4c and com14c are quoted and have comments following -the values. -.PP -Some text files have column name and data type information in the header. -You can specify the format of column information contained in the -header using the \*(L"hcolfmt=\*(R" specification. See below for a detailed -description. -.PP -\&\fBMultiple Tables in a Single File\fR -.PP -Multiple tables are supported in a single file. If an RDB-style file -is sensed, then a ^L (vertical tab) will signify end of -table. Otherwise, an end of table is sensed when a new header (i.e., -all alphanumeric columns) is found. (Note that this heuristic does not -work for single column tables where the column type is \s-1ASCII\s0 and the -table that follows also has only one column.) You also can specify -characters that signal an end of table condition using the \fBeot=\fR -keyword. See below for details. -.PP -You can access the nth table (starting from 1) in a multi-table file -by enclosing the table number in brackets, as with a \s-1FITS\s0 extension: -.PP -.Vb 1 -\& fundisp foo'[2]' -.Ve -.PP -The above example will display the second table in the file. -(Index values start at 1 in oder to maintain logical compatibility -with \s-1FITS\s0 files, where extension numbers also start at 1). -.PP -\&\fB\s-1\f(BITEXT\s0()\fB Specifier\fR -.PP -As with \s-1\fIARRAY\s0()\fR and \s-1\fIEVENTS\s0()\fR specifiers for raw image arrays and raw -event lists respectively, you can use \s-1\fITEXT\s0()\fR on text files to pass -key=value options to the parsers. An empty set of keywords is -equivalent to not having \s-1\fITEXT\s0()\fR at all, that is: -.PP -.Vb 2 -\& fundisp foo -\& fundisp foo'[TEXT()]' -.Ve -.PP -are equivalent. A multi-table index number is placed before the \s-1\fITEXT\s0()\fR -specifier as the first token, when indexing into a multi\-table: -.PP -.Vb 1 -\& fundisp foo'[2,TEXT(...)]' -.Ve -.PP -The filter specification is placed after the \s-1\fITEXT\s0()\fR specifier, separated -by a comma, or in an entirely separate bracket: -.PP -.Vb 2 -\& fundisp foo'[TEXT(...),circle 512 512 .1]' -\& fundisp foo'[2,TEXT(...)][circle 512 512 .1]' -.Ve -.PP -\&\fB\f(BIText()\fB Keyword Options\fR -.PP -The following is a list of keywords that can be used within the \s-1\fITEXT\s0()\fR -specifier (the first three are the most important): -.IP "\(bu" 4 -delims=\*(L"[delims]\*(R" -.Sp -Specify token delimiters for this file. Only a single parser having these -delimiters will be used to process the file. -.Sp -.Vb 2 -\& fundisp foo.fits'[TEXT(delims="!")]' -\& fundisp foo.fits'[TEXT(delims="\et%")]' -.Ve -.IP "\(bu" 4 -comchars=\*(L"[comchars]\*(R" -.Sp -Specify comment characters. You must include \*(L"\en\*(R" to allow blank lines. -These comment characters will be used for all standard parsers (unless delims -are also specified). -.Sp -.Vb 1 -\& fundisp foo.fits'[TEXT(comchars="!\en")]' -.Ve -.IP "\(bu" 4 -cols=\*(L"[name1:type1 ...]\*(R" -.Sp -Specify names and data type of columns. This overrides header -names and/or data types in the first data row or default names and -data types for header-less tables. -.Sp -.Vb 1 -\& fundisp foo.fits'[TEXT(cols="x:I,y:I,pha:I,pi:I,time:D,dx:E,dy:e")]' -.Ve -.Sp -If the column specifier is the only keyword, then the cols= is not -required (in analogy with \s-1\fIEVENTS\s0()\fR): -.Sp -.Vb 1 -\& fundisp foo.fits'[TEXT(x:I,y:I,pha:I,pi:I,time:D,dx:E,dy:e)]' -.Ve -.Sp -Of course, an index is allowed in this case: -.Sp -.Vb 1 -\& fundisp foo.fits'[2,TEXT(x:I,y:I,pha:I,pi:I,time:D,dx:E,dy:e)]' -.Ve -.IP "\(bu" 4 -eot=\*(L"[eot delim]\*(R" -.Sp -Specify end of table string specifier for multi-table files. \s-1RDB\s0 -files support ^L. The end of table specifier is a string and the whole -string must be found alone on a line to signify \s-1EOT\s0. For example: -.Sp -.Vb 1 -\& fundisp foo.fits'[TEXT(eot="END")]' -.Ve -.Sp -will end the table when a line contains \*(L"\s-1END\s0\*(R" is found. Multiple lines -are supported, so that: -.Sp -.Vb 1 -\& fundisp foo.fits'[TEXT(eot="END\enGAME")]' -.Ve -.Sp -will end the table when a line contains \*(L"\s-1END\s0\*(R" followed by a line -containing \*(L"\s-1GAME\s0\*(R". -.Sp -In the absence of an \s-1EOT\s0 delimiter, a new table will be sensed when a new -header (all alphanumeric columns) is found. -.IP "\(bu" 4 -null1=\*(L"[datatype]\*(R" -.Sp -Specify data type of a single null value in row 1. -Since column data types are determined by the first row, a null value -in that row will result in an error and a request to specify names and -data types using cols=. If you only have a one null in row 1, you don't -need to specify all names and columns. Instead, use null1=\*(L"type\*(R" to -specify its data type. -.IP "\(bu" 4 -alen=[n] -.Sp -Specify size in bytes for \s-1ASCII\s0 type columns. -\&\s-1FITS\s0 binary tables only support fixed length \s-1ASCII\s0 columns, so a -size value must be specified. The default is 16 bytes. -.IP "\(bu" 4 -nullvalues=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Specify whether to expect null values. -Give the parsers a hint as to whether null values should be allowed. The -default is to try to determine this from the data. -.IP "\(bu" 4 -whitespace=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Specify whether surrounding white space should be kept as part of -string tokens. By default surrounding white space is removed from -tokens. -.IP "\(bu" 4 -header=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Specify whether to require a header. This is needed by tables -containing all string columns (and with no row containing dashes), in -order to be able to tell whether the first row is a header or part of -the data. The default is false, meaning that the first row will be -data. If a row dashes are present, the previous row is considered the -column name row. -.IP "\(bu" 4 -units=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Specify whether to require a units line. -Give the parsers a hint as to whether a row specifying units should be -allowed. The default is to try to determine this from the data. -.IP "\(bu" 4 -i2f=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Specify whether to allow int to float conversions. -If a column in row 1 contains an integer value, the data type for that -column will be set to int. If a subsequent row contains a float in -that same column, an error will be signaled. This flag specifies that, -instead of an error, the float should be silently truncated to -int. Usually, you will want an error to be signaled, so that you can -specify the data type using cols= (or by changing the value of -the column in row 1). -.IP "\(bu" 4 -comeot=[\*(L"true\*(R"|\*(L"false\*(R"|0|1|2] -.Sp -Specify whether comment signifies end of table. -If comeot is 0 or false, then comments do not signify end of table and -can be interspersed with data rows. If the value is true or 1 (the -default for standard parsers), then non-blank lines (e.g. lines -beginning with '#') signify end of table but blanks are allowed -between rows. If the value is 2, then all comments, including blank -lines, signify end of table. -.IP "\(bu" 4 -lazyeot=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Specify whether \*(L"lazy\*(R" end of table should be permitted (default is -true for standard formats, except rdb format where explicit ^L is required -between tables). A lazy \s-1EOT\s0 can occur when a new table starts directly -after an old one, with no special \s-1EOT\s0 delimiter. A check for this \s-1EOT\s0 -condition is begun when a given row contains all string tokens. If, in -addition, there is a mismatch between the number of tokens in the -previous row and this row, or a mismatch between the number of string -tokens in the prev row and this row, a new table is assumed to have -been started. For example: -.Sp -.Vb 4 -\& ival1 sval3 -\& ----- ----- -\& 1 two -\& 3 four -.Ve -.Sp -.Vb 4 -\& jval1 jval2 tval3 -\& ----- ----- ------ -\& 10 20 thirty -\& 40 50 sixty -.Ve -.Sp -Here the line \*(L"jval1 ...\*(R" contains all string tokens. In addition, -the number of tokens in this line (3) differs from the number of -tokens in the previous line (2). Therefore a new table is assumed -to have started. Similarly: -.Sp -.Vb 4 -\& ival1 ival2 sval3 -\& ----- ----- ----- -\& 1 2 three -\& 4 5 six -.Ve -.Sp -.Vb 4 -\& jval1 jval2 tval3 -\& ----- ----- ------ -\& 10 20 thirty -\& 40 50 sixty -.Ve -.Sp -Again, the line \*(L"jval1 ...\*(R" contains all string tokens. The number of -string tokens in the previous row (1) differs from the number of -tokens in the current \fIrow\fR\|(3). We therefore assume a new table as been -started. This lazy \s-1EOT\s0 test is not performed if lazyeot is explicitly -set to false. -.IP "\(bu" 4 -hcolfmt=[header column format] -.Sp -Some text files have column name and data type information in the header. -For example, VizieR catalogs have headers containing both column names -and data types: -.Sp -.Vb 3 -\& #Column e_Kmag (F6.3) ?(k_msigcom) K total magnitude uncertainty (4) [ucd=ERROR] -\& #Column Rflg (A3) (rd_flg) Source of JHK default mag (6) [ucd=REFER_CODE] -\& #Column Xflg (I1) [0,2] (gal_contam) Extended source contamination (10) [ucd=CODE_MISC] -.Ve -.Sp -while Sextractor files have headers containing column names alone: -.Sp -.Vb 4 -\& # 1 X_IMAGE Object position along x [pixel] -\& # 2 Y_IMAGE Object position along y [pixel] -\& # 3 ALPHA_J2000 Right ascension of barycenter (J2000) [deg] -\& # 4 DELTA_J2000 Declination of barycenter (J2000) [deg] -.Ve -.Sp -The hcolfmt specification allows you to describe which header lines -contain column name and data type information. It consists of a string -defining the format of the column line, using \*(L"$col\*(R" (or \*(L"$name\*(R") to -specify placement of the column name, \*(L"$fmt\*(R" to specify placement of the -data format, and \*(L"$skip\*(R" to specify tokens to ignore. You also can -specify tokens explicitly (or, for those users familiar with how -sscanf works, you can specify scanf skip specifiers using \*(L"%*\*(R"). -For example, the VizieR hcolfmt above might be specified in several ways: -.Sp -.Vb 3 -\& Column $col ($fmt) # explicit specification of "Column" string -\& $skip $col ($fmt) # skip one token -\& %*s $col ($fmt) # skip one string (using scanf format) -.Ve -.Sp -while the Sextractor format might be specified using: -.Sp -.Vb 2 -\& $skip $col # skip one token -\& %*d $col # skip one int (using scanf format) -.Ve -.Sp -You must ensure that the hcolfmt statement only senses actual column -definitions, with no false positives or negatives. For example, the -first Sextractor specification, \*(L"$skip \f(CW$col\fR\*(R", will consider any header -line containing two tokens to be a column name specifier, while the -second one, \*(L"%*d \f(CW$col\fR\*(R", requires an integer to be the first token. In -general, it is preferable to specify formats as explicitly as -possible. -.Sp -Note that the VizieR-style header info is sensed automatically by the -funtools standard VizieR-like parser, using the hcolfmt \*(L"Column \f(CW$col\fR -($fmt)\*(R". There is no need for explicit use of hcolfmt in this case. -.IP "\(bu" 4 -debug=[\*(L"true\*(R"|\*(L"false\*(R"] -.Sp -Display debugging information during parsing. -.PP -\&\fBEnvironment Variables\fR -.PP -Environment variables are defined to allow many of these \s-1\fITEXT\s0()\fR values to be -set without having to include them in \s-1\fITEXT\s0()\fR every time a file is processed: -.PP -.Vb 10 -\& keyword environment variable -\& ------- -------------------- -\& delims TEXT_DELIMS -\& comchars TEXT_COMCHARS -\& cols TEXT_COLUMNS -\& eot TEXT_EOT -\& null1 TEXT_NULL1 -\& alen TEXT_ALEN -\& bincols TEXT_BINCOLS -\& hcolfmt TEXT_HCOLFMT -.Ve -.PP -\&\fBRestrictions and Problems\fR -.PP -As with raw event files, the '+' (copy extensions) specifier is not -supported for programs such as funtable. -.PP -String to int and int to string data conversions are allowed by the -text parsers. This is done more by force of circumstance than by -conviction: these transitions often happens with VizieR catalogs, -which we want to support fully. One consequence of allowing these -transitions is that the text parsers can get confused by columns which -contain a valid integer in the first row and then switch to a -string. Consider the following table: -.PP -.Vb 4 -\& xxx yyy zzz -\& ---- ---- ---- -\& 111 aaa bbb -\& ccc 222 ddd -.Ve -.PP -The xxx column has an integer value in row one a string in row two, -while the yyy column has the reverse. The parser will erroneously -treat the first column as having data type int: -.PP -.Vb 5 -\& fundisp foo.tab -\& XXX YYY ZZZ -\& ---------- ------------ ------------ -\& 111 'aaa' 'bbb' -\& 1667457792 '222' 'ddd' -.Ve -.PP -while the second column is processed correctly. This situation can be avoided -in any number of ways, all of which force the data type of the first column -to be a string. For example, you can edit the file and explicitly quote the -first row of the column: -.PP -.Vb 4 -\& xxx yyy zzz -\& ---- ---- ---- -\& "111" aaa bbb -\& ccc 222 ddd -.Ve -.PP -.Vb 5 -\& [sh] fundisp foo.tab -\& XXX YYY ZZZ -\& ------------ ------------ ------------ -\& '111' 'aaa' 'bbb' -\& 'ccc' '222' 'ddd' -.Ve -.PP -You can edit the file and explicitly set the data type of the first column: -.PP -.Vb 4 -\& xxx:3A yyy zzz -\& ------ ---- ---- -\& 111 aaa bbb -\& ccc 222 ddd -.Ve -.PP -.Vb 5 -\& [sh] fundisp foo.tab -\& XXX YYY ZZZ -\& ------------ ------------ ------------ -\& '111' 'aaa' 'bbb' -\& 'ccc' '222' 'ddd' -.Ve -.PP -You also can explicitly set the column names and data types of all columns, -without editing the file: -.PP -.Vb 5 -\& [sh] fundisp foo.tab'[TEXT(xxx:3A,yyy:3A,zzz:3a)]' -\& XXX YYY ZZZ -\& ------------ ------------ ------------ -\& '111' 'aaa' 'bbb' -\& 'ccc' '222' 'ddd' -.Ve -.PP -The issue of data type transitions (which to allow and which to disallow) -is still under discussion. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/funtools.7 b/funtools/man/man7/funtools.7 deleted file mode 100644 index 6d188be..0000000 --- a/funtools/man/man7/funtools.7 +++ /dev/null @@ -1,379 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funtools 7" -.TH funtools 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -Funtools \- FITS Users Need Tools -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document is the Table of Contents for Funtools. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -Funtools, is a \*(L"minimal buy\-in\*(R" \s-1FITS\s0 library and utility package developed -at the the High Energy Astrophysics Division of \s-1SAO\s0. The Funtools -library provides simplified access to a wide array of file types: -standard astronomical \s-1FITS\s0 images and binary tables, raw arrays and -binary event lists, and even tables of \s-1ASCII\s0 column data. A -sophisticated region filtering library (compatible with ds9) filters -images and tables using boolean operations between geometric shapes, -support world coordinates, etc. Funtools also supports advanced -capabilities such as optimized data searching using index files. -.PP -The main goal of the Funtools project has been to develop a minimal buy-in -\&\s-1FITS\s0 library for researchers who are occasional (but serious) coders. In -this case, \*(L"minimal buy\-in\*(R" means \*(L"easy to learn, easy to use, and easy to -re-learn next month\*(R". We have tried to achieve this goal by emphasizing two -essential capabilities. The first is the ability to develop \s-1FITS\s0 programs -without knowing much about \s-1FITS\s0, i.e., without having to deal with the -arcane rules for generating a properly formatted \s-1FITS\s0 file. The second is -to support the use of already-familiar C/Unix facilities, especially C -structs and Unix stdio. Taken together, these two capabilities should allow -researchers to leverage their existing programming expertise while -minimizing the need to learn new and complex coding rules. -.PP -Choose from the following topics: -.IP "\(bu" 4 -Funtools User Programs -.RS 4 -.IP "\(bu" 4 -funcalc: Funtools calculator (for binary tables) -[\fIfuncalc\fR\|(1)] -.IP "\(bu" 4 -funcen: find centroid (for binary tables) -[\fIfuncen\fR\|(1)] -.IP "\(bu" 4 -funcnts: count photons in specified regions -[\fIfuncnts\fR\|(1)] -.IP "\(bu" 4 -funcone: cone search on \s-1RA\s0, Dec columns -[\fIfuncone\fR\|(1)] -.IP "\(bu" 4 -fundisp: display data in a Funtools data file -[\fIfundisp\fR\|(1)] -.IP "\(bu" 4 -funhead: display a header in a Funtools file -[\fIfunhead\fR\|(1)] -.IP "\(bu" 4 -funhist: create a 1D histogram of a column -[\fIfunhist\fR\|(1)] -.IP "\(bu" 4 -funimage: create a \s-1FITS\s0 image from a Funtools data file -[\fIfunimage\fR\|(1)] -.IP "\(bu" 4 -funindex: create an index on a column in a binary table -[\fIfunindex\fR\|(1)] -.IP "\(bu" 4 -funjoin: join two or more \s-1FITS\s0 binary tables on specified columns -[\fIfunjoin\fR\|(1)] -.IP "\(bu" 4 -funmerge: merge one or more Funtools table files -[\fIfunmerge\fR\|(1)] -.IP "\(bu" 4 -funsky: convert between image and sky coordinates, using \s-1WCS\s0 info from a \s-1FITS\s0 header -[\fIfunsky\fR\|(1)] -.IP "\(bu" 4 -funtable: copy selected rows from a Funtools file to a \s-1FITS\s0 binary table -[\fIfuntable\fR\|(1)] -.IP "\(bu" 4 -funtbl: extract a table from -Funtools \s-1ASCII\s0 output -[\fIfuntbl\fR\|(1)] -.IP "\(bu" 4 -funtools and ds9 image display -[funds9(7)] -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Funtools Programming -.RS 4 -.IP "\(bu" 4 -Funtools Programming Summary -[\fIfunlib\fR\|(3)] -.IP "\(bu" 4 -Funtools Programming Tutorial -[\fIfunlib\fR\|(3)] -.IP "\(bu" 4 -A Short Digression on Subroutine Order -[\fIfunlib\fR\|(3)] -.IP "\(bu" 4 -Compiling and Linking -[\fIfunlib\fR\|(3)] -.IP "\(bu" 4 -The Funtools Reference Handle -[\fIfunlib\fR\|(3)] -.IP "\(bu" 4 -The Funtools Programming Reference Manual -.RS 4 -.IP "\(bu" 4 -FunOpen: open a Funtools file -[\fIfunopen\fR\|(3)] -.IP "\(bu" 4 -FunImageGet: retrieve image data -[\fIfunimageget\fR\|(3)] -.IP "\(bu" 4 -FunImagePut: output image data -[\fIfunimageput\fR\|(3)] -.IP "\(bu" 4 -FunImageRowGet: retrieve image data by row -[\fIfunimagerowget\fR\|(3)] -.IP "\(bu" 4 -FunImageRowPut: output image data by row -[\fIfunimagerowput\fR\|(3)] -.IP "\(bu" 4 -FunTableRowGet: retrieve rows from a table -[\fIfuntablerowget\fR\|(3)] -.IP "\(bu" 4 -FunTableRowPut: output rows to a table -[\fIfuntablerowput\fR\|(3)] -.IP "\(bu" 4 -FunColumnSelect: select columns in a table for access -[\fIfuncolumnselect\fR\|(3)] -.IP "\(bu" 4 -FunColumnActivate: activate columns in a table for read/write -[\fIfuncolumnactivate\fR\|(3)] -.IP "\(bu" 4 -FunColumnLookup: lookup info about the columns in a table -[\fIfuncolumnlookup\fR\|(3)] -.IP "\(bu" 4 -FunInfoGet: get info about an image or table -[\fIfuninfoget\fR\|(3)] -.IP "\(bu" 4 -FunInfoPut: put info about an image or table -[\fIfuninfoput\fR\|(3)] -.IP "\(bu" 4 -FunParamGet: get header param -[\fIfunparamget\fR\|(3)] -.IP "\(bu" 4 -FunParamPut: put header param -[\fIfunparamput\fR\|(3)] -.IP "\(bu" 4 -FunFlush: flush I/O in a Funtools file -[\fIfunflush\fR\|(3)] -.IP "\(bu" 4 -FunClose: close a Funtools file -[\fIfunclose\fR\|(3)] -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Funtools Programming Examples -[\fIfunlib\fR\|(3)] -.RS 4 -.IP "\(bu" 4 -evmerge: merge new columns with existing columns -.IP "\(bu" 4 -evcols: add column and rows to binary tables -.IP "\(bu" 4 -imblank: blank out image values below a threshold -.RE -.RS 4 -.RE -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Funtools Data Files -[funfiles(7)] -.RS 4 -.IP "\(bu" 4 -Supported Data Formats -.RS 4 -.IP "\(bu" 4 -\&\s-1FITS\s0 File and Extensions -.IP "\(bu" 4 -Non-FITS Raw Event Files -.IP "\(bu" 4 -Non-FITS Array Files -.IP "\(bu" 4 -Column-based Text (\s-1ASCII\s0) Files -.IP "\(bu" 4 -Database Views of Tables -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Image Sections and Blocking -.IP "\(bu" 4 -Binning \s-1FITS\s0 Binary Tables and Non-FITS Event Files -.IP "\(bu" 4 -Disk Files and Other Supported File Types -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Funtools Data Filtering -.RS 4 -.IP "\(bu" 4 -Table Filtering -[funfilters(7)] -.IP "\(bu" 4 -Fast Table Filtering using Indexes -[funidx(7)] -.IP "\(bu" 4 -Spatial Region Filtering -[funregions(7)] -.RS 4 -.IP "\(bu" 4 -Region Geometry -[reggeometry(7)] -.IP "\(bu" 4 -Region Algebra -[regalgebra(7)] -.IP "\(bu" 4 -Region Coordinates -[regcoords(7)] -.IP "\(bu" 4 -Region Boundaries -[regbounds(7)] -.IP "\(bu" 4 -Differences Between Funtools and \s-1IRAF\s0 Regions -[regdiff(7)] -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Combining Table and Region Filters -[funcombine(7)] -.RE -.RS 4 -.RE -.IP "\(bu" 4 -Miscellaneous -.RS 4 -.IP "\(bu" 4 -Funtools Environment Variables -[funenv(7)] -.IP "\(bu" 4 -Funtools ChangeLog -.RE -.RS 4 -.RE diff --git a/funtools/man/man7/funview.7 b/funtools/man/man7/funview.7 deleted file mode 100644 index 06a0d56..0000000 --- a/funtools/man/man7/funview.7 +++ /dev/null @@ -1,523 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funview 7" -.TH funview 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -Funview \- Database View Support for Tables -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document contains a summary of the options for utilizing -database-inspired Views of tables. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBDatabase Views\fR -.PP -In database parlance, a \fBView\fR defines a \*(L"virtual table\*(R", i.e., -a description of row and/or column selection filters (but with no -permanent storage space allocated). When used in place of a table, a -View selects the specified rows and/or columns from one or more real -tables. Views enable you to see complicated data tables in a more -convenient format. They also can be used as a security mechanism, by -restricting user access to specific columns and/or rows. [See: -.PP -http://www.cs.unibo.it/~ciaccia/COURSES/RESOURCES/SQLTutorial/sqlch5.htm -.PP -for a good discussion of \s-1SQL\s0 Views.] -.PP -Funtools supports an expanded notion of Views for all tabular data -(\s-1FITS\s0 tables, raw binary tables, and \s-1ASCII\s0 column files). Funtools -Views allow you to pre-set values for the filter specification, the -columns to activate, and display format (though the latter is for -fundisp only). Setting the filter and column activation values -provides functionality equivalent to that of a classical database -View, while the ability to set the format is similar to classical -report writing capabilities. -.PP -\&\fBFuntools View Attributes\fR -.PP -A Funtools View is a text file containing one or more of the following -columns: -.PP -.Vb 7 -\& column description -\& ------ ----------------------------- -\& view name of view -\& file data file name or template -\& filter filter specification -\& columns columns to activate -\& format fundisp format specification -.Ve -.PP -All of the attribute columns are optional, including -the \fBview\fR name itself. This means that a View can be named or -unnamed. Unnamed Views can refer to a specific file or a template of -files (obviously if neither the view or the file column is specified, -the input View specification will never be used). You can specify any -combination of filter, column, and format parameters. (It also is -possible to apply file-specific View to other files; see the discussion -on \fBView Lists\fR below). Each column has a size limit of 1024 characters. -.PP -For example, consider the following View file: -.PP -.Vb 13 -\& view file format columns filter -\& ---- ---------------------- ------ ------------ ------- -\& x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1 -\& x2 ${HOME}/data/snr.ev x y pi pha cir 512 512 .1 -\& x1 ${HOME}/data/snr.ev cir 512 512 .1 -\& x1a ${HOME}/data/snr.ev x y pi pha -\& x0 ${HOME}/data/snr.ev -\& xf I=%4d -\& xc x y pi pha -\& xr cir 512 512 .1 -\& *.ev x y pi pha -\& *.fit x y dx dy cir 400 400 3 -\& *.fits I=%3d x y dx dy cir 400 400 3 -.Ve -.PP -This database example is in rdb format, i.e. using tab delimiters and -permitting null values. Any valid \s-1ASCII\s0 table format is acceptable, -but if you use a format that does not permit null values, it will be -necessary to quote the null strings. -.PP -The first five entries (x3, x2, x1, x1a, x0) are named entries defining -default values specifically for the snr.ev data file. Typically, you -would use these Views by specifying View name, and the corresponding -file, filter, column, and format values would be used. Note that the x0 -View is essentially an alias for the pathname of this file. -.PP -The next three entries define defaults that can be applied to any -file. You typically would use these View names in conjunction with -a specific file name (see \fBView Lists\fR below) so that the associated -parameter(s) were applied to that file. -.PP -The last three entry in the database define unnamed Views that -pertains to all files ending with the specified templates. In these -cases, any View that specifies a file name matching the file template -would be processed with the associated parameter attributes. -.PP -\&\fBInvoking a Funtools View (in Place of an Input File)\fR -.PP -To use a Funtools View, you simply pre-pend the \*(L"v:\*(R" prefix to a View name or -a file name where an input file name usually is specified. For example: -.PP -.Vb 1 -\& fundisp v:x3 -.Ve -.PP -specifies that the View named x3 (with its file name and associated -parameters) is processed as the input file to fundisp. Using the -example database, above, this is equivalent to: -.PP -.Vb 1 -\& fundisp \-f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha" -.Ve -.PP -That is, the format is used with fundisp's \-f (format) switch, while the -filename and extension are composed of the x3 View's filename and -region filter. -.PP -Similarly, executing a command such as: -.PP -.Vb 1 -\& fundisp v:foo.fit -.Ve -.PP -will match the unnamed View associated with the template \*(L"*.fit\*(R". -This is equivalent to executing: -.PP -.Vb 1 -\& fundisp foo.fit'[cir 400 400 3]' "x y dx dy" -.Ve -.PP -Of course, if you omit the \*(L"v:\*(R" prefix, then no View processing takes place: -.PP -.Vb 2 -\& fundisp foo.fit # process foo.fit without any View parameters -\& fundisp x3 # error (assuming there is no file named x3) -.Ve -.PP -\&\fBBasic View Matching Rules\fR -.PP -When a \*(L"v:\*(R" prefix is recognized, Funtools searches for a View database -file in the following order: -.PP -.Vb 5 -\& location description -\& ------------ ------------------------------------ -\& FUN_VIEWFILE environment variable (any file name) -\& ./.funtools.vu hidden file, default name -\& $HOME/.funtools.vu hidden file, default name -.Ve -.PP -The first View database file located is used to construct a new -filename, as well as an activation column specification and a format -specification. The following rules are used: -.PP -1. An attempt is made to match the input name (i.e., the part of the -input View after the \*(L"v:\*(R" prefix) against the \fBview\fR column value -(if present) of each row in the database. If a match is found, the -values of all non-blank columns are saved for later use. Also note -that the first match terminates the search: i.e., the order of the -database rows matters. -.PP -2. If no \fBview\fR match is made, an attempt is made to match the input -name against the \fBfile\fR column value (if present). Matching is -performed on the full pathname of both the input name and the -database file name, and on the non-directory (root) part of these -files. This means that the root specification: -.PP -.Vb 1 -\& fundisp v:snr.ev -.Ve -.PP -will match a row in the database that has a full pathname in the file, -allowing you to use a \fBfile\fR\-matched View without having to -specify the full pathname. In this example, the \*(L"v:snr.ev\*(R" View -specification will match the first row (v:x3) in the database: -.PP -.Vb 1 -\& x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1 -.Ve -.PP -even though the row contains a fully qualified pathname as the file -value. Once again, values of all non-blank columns are saved, and the -first match terminates the search. -.PP -3. If neither a \fBview\fR or a \fBview\fR match has been found, -then a simple template match is attempted against the \fBview\fR -values. Template matching supports a simplified version of file -globbing (not a regular expression), with support for a single \*(L"*\*(R" -(all characters), \*(L"?\*(R" (single character), or \*(L"[...]\*(R" (range) specification. -.PP -4. If no template match was found on the \fBview\fR column, then a -simple template match is attempted against the \fBfile\fR columns. -.PP -5. If no match is found, then the filename (minus the \*(L"v:\*(R" prefix) is -returned. -.PP -More on View Matching Rules - Single vs. Multiple Matches -.PP -The matching rules described above stop after the first match, -regardless of whether that match provides values for all three -parameters (filter, columns, and format). In cases where a \fBview\fR -or \fBfile\fR match does not provide all three values, it is possible -that a template match might do so. With regard to the example View -database above, the x1 View provides only a filter, while omitting -both the format and columns values. But note that the final rows in -the database could provide the values via a template match on the -filename. This sort of multiple matching is especially valuable in -order to provide \*(L"global\*(R" values to several Views. -.PP -Obviously, multiple matching might not be wanted in every -case. Therefore, we support both multiple matching and single matching -according to the value of the \s-1FUN_VIEWMATCH\s0 environment variable. If -the \s-1FUN_VIEWMATCH\s0 environment variable exists and if its value begins -with \*(L"s\*(R", then a single match is used and missing parameters are not -filled in with subsequent template matches on the file name. That is, -matching rules above are followed exactly as explained above. If the -value of this environment variable begins with \*(L"m\*(R" (or does not exist), -then multiple matches are used to try to fill in missing parameters. -In this case, template matching always takes place and missing values are -taken from these template matches. -.PP -Thus, in the example above, the View specification: -.PP -.Vb 1 -\& fundisp v:x1 -.Ve -.PP -will take the file name and filter value from the x1 View: -.PP -.Vb 1 -\& x1 ${HOME}/data/snr.ev cir 512 512 .1 -.Ve -.PP -The column value then will be taken from the \*(L"*.ev\*(R" file template match -against the x1 file name: -.PP -.Vb 1 -\& *.ev x y pi pha -.Ve -.PP -Note once again that order is important: missing values are taken in the -order in which the template matches are processed. -.PP -View Lists - Applying a View to Any File -.PP -It is possible to apply a named View, or even several Views, to any -data file by appending a \fBviewlist\fR immediately after the standard \*(L"v:\*(R" -prefix. A viewlist takes the form: -.PP -.Vb 1 -\& :v1,v2,...vn: -.Ve -.PP -where v1, v2, etc. are named Views. The two \*(L":\*(R" colon characters surrounding -the list are required. Thus, the syntax for applying a viewlist to a file is: -.PP -.Vb 1 -\& v::view1,view2,...viewn:filename -.Ve -.PP -Note that the name after the last \*(L":\*(R" is assumed to be a file; it is -not permissible (or sensible) to use a View name. -.PP -For example, the View specification: -.PP -.Vb 1 -\& fundisp v::x2:foo -.Ve -.PP -applies the x2 View to the file foo (even if there is a View named foo) -and (in using our example database) is equivalent to: -.PP -.Vb 1 -\& ./fundisp foo'[cir 512 512 .1] "x y pi pha" -.Ve -.PP -The same command can be effected using a list of Views: -.PP -.Vb 1 -\& fundisp v::x1,x1a:foo -.Ve -.PP -What happens if a viewlist is used and the file also matches a -template? Consider, for example, this View specification: -.PP -.Vb 1 -\& fundisp v::x2:foo.fit -.Ve -.PP -Here, the x2 View will supply filter and column values, while the -template *.fit can also supply (different) filter and column -values. In this case, the explicitly specified Views of the viewlist -trump the matched view values. -.PP -On the other hand, if a file template match can supply a View value -that is not supplied by the viewlist, then that value will be taken -from the file template match. For example: -.PP -.Vb 1 -\& fundisp v::x2:foo.fits -.Ve -.PP -does not explicitly supply a format value, but the file match on *.fits -can and does. You can avoid supplying missing values using file template -matching by replacing the first \*(L":\*(R" with a \*(L"\-\*(R" in a viewlist -specification: -.PP -.Vb 1 -\& fundisp v:-x2:foo.fits -.Ve -.PP -The use of \*(L":+\*(R" to explicitly allow file template matching is also -supported, but is the same as the default case. Note that the nuances -of viewlist support are subject to change as our experience and -understanding grow. -.PP -\&\fBOverriding Values Associated with a View\fR -.PP -To override values associated with a View, simply supply the override -values in the correct place on the command line. Thus, given -the example database described above, the command: -.PP -.Vb 1 -\& fundisp v:x3 -.Ve -.PP -specifies that the View named x3, along with its file name and -associated parameters, be processed as the input file to fundisp in -this way: -.PP -.Vb 1 -\& fundisp \-f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha" -.Ve -.PP -To override one or more of these values, simply specify a new value -for the format, filter, or columns. For example, if your input View file -contains a filter, then the View will use that filter as an override -of the View filter: -.PP -.Vb 1 -\& fundisp v:x3'[cir 400 400 3]' -.Ve -.PP -will use the columns and format of the x3 View but not the x3 filter. Further -examples are: -.PP -.Vb 2 -\& fundisp v:x3 "x y dx dy" # activate a different set of columns -\& fundisp \-f "I=%3d" v:x3 # use a different format statement -.Ve -.PP -Note that extension names, extension index values, and other -non-filter specifications \fBdo not\fR override the View -filter. Thus: -.PP -.Vb 1 -\& fundisp v:foo.fit[3] -.Ve -.PP -will still use the filter associated with the .fit template (see above), since -the \*(L"3\*(R" is an extension index, not a filter. -.PP -\&\fBEnvironment Variables\fR -.PP -The following environment variables are used by Funtools Views: -.IP "\(bu" 4 -\&\fB\s-1FUN_VIEWNAME\s0\fR -.Sp -The \fB\s-1FUN_VIEWNAME\s0\fR environment variable specifies the -name and location of the View database file. If not present, the -files ./.funtools.vu and \f(CW$HOME\fR/.funtools.vu are searched for, in -that order. -.IP "\(bu" 4 -\&\fB\s-1FUN_VIEWMATCH\s0\fR -.Sp -The \fB\s-1FUN_VIEWMATCH\s0\fR environment variable specifies whether a -single match or multiple match algorithm is used to locate parameter -values. If the value of this environment variable begins with \*(L"s\*(R", -then a single match is used and missing parameters are not filled in -with subsequent template matches on the file name. If the value begins -with \*(L"m\*(R", then multiple matches are used to try to fill in missing -parameters. The default is to use multiple matches. -.PP -\&\fBRestrictions and Problems\fR -.PP -Support for overriding a filter (while not overriding extension names, -extension indexes, etc.) requires that we can sense the presence of a -filter in a bracket specification. It is unclear yet whether our -algorithm is perfect. -.PP -Go to Funtools Help Index -.PP -Last updated: August 3, 2007 diff --git a/funtools/man/man7/regalgebra.7 b/funtools/man/man7/regalgebra.7 deleted file mode 100644 index 93cb985..0000000 --- a/funtools/man/man7/regalgebra.7 +++ /dev/null @@ -1,400 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "regalgebra 7" -.TH regalgebra 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -RegAlgebra \- Boolean Algebra on Spatial Regions -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document describes the boolean arithmetic defined for -region expressions. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -When defining a region, several shapes can be combined using boolean -operations. The boolean operators are (in order of precedence): -.PP -.Vb 6 -\& Symbol Operator Associativity -\& ------ -------- ------------- -\& ! not right to left -\& & and left to right -\& ^ exclusive or left to right -\& | inclusive or left to right -.Ve -.PP -For example, to create a mask consisting of a large circle with a -smaller box removed, one can use the \fBand\fR and \fBnot\fR -operators: -.PP -.Vb 1 -\& CIRCLE(11,11,15) & !BOX(11,11,3,6) -.Ve -.PP -and the resulting mask is: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 1:1111111111111111111111.................. -\& 2:1111111111111111111111.................. -\& 3:11111111111111111111111................. -\& 4:111111111111111111111111................ -\& 5:111111111111111111111111................ -\& 6:1111111111111111111111111............... -\& 7:1111111111111111111111111............... -\& 8:1111111111111111111111111............... -\& 9:111111111...1111111111111............... -\& 10:111111111...1111111111111............... -\& 11:111111111...1111111111111............... -\& 12:111111111...1111111111111............... -\& 13:111111111...1111111111111............... -\& 14:111111111...1111111111111............... -\& 15:1111111111111111111111111............... -\& 16:1111111111111111111111111............... -\& 17:111111111111111111111111................ -\& 18:111111111111111111111111................ -\& 19:11111111111111111111111................. -\& 20:1111111111111111111111.................. -\& 21:1111111111111111111111.................. -\& 22:111111111111111111111................... -\& 23:..11111111111111111..................... -\& 24:...111111111111111...................... -\& 25:.....11111111111........................ -\& 26:........................................ -\& 27:........................................ -\& 28:........................................ -\& 29:........................................ -\& 30:........................................ -\& 31:........................................ -\& 32:........................................ -\& 33:........................................ -\& 34:........................................ -\& 35:........................................ -\& 36:........................................ -\& 37:........................................ -\& 38:........................................ -\& 39:........................................ -\& 40:........................................ -.Ve -.PP -A three-quarter circle can be defined as: -.PP -.Vb 1 -\& CIRCLE(20,20,10) & !PIE(20,20,270,360) -.Ve -.PP -and looks as follows: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 1:........................................ -\& 2:........................................ -\& 3:........................................ -\& 4:........................................ -\& 5:........................................ -\& 6:........................................ -\& 7:........................................ -\& 8:........................................ -\& 9:........................................ -\& 10:........................................ -\& 11:...............111111111................ -\& 12:..............11111111111............... -\& 13:............111111111111111............. -\& 14:............111111111111111............. -\& 15:...........11111111111111111............ -\& 16:..........1111111111111111111........... -\& 17:..........1111111111111111111........... -\& 18:..........1111111111111111111........... -\& 19:..........1111111111111111111........... -\& 20:..........1111111111111111111........... -\& 21:..........1111111111.................... -\& 22:..........1111111111.................... -\& 23:..........1111111111.................... -\& 24:..........1111111111.................... -\& 25:...........111111111.................... -\& 26:............11111111.................... -\& 27:............11111111.................... -\& 28:..............111111.................... -\& 29:...............11111.................... -\& 30:........................................ -\& 31:........................................ -\& 32:........................................ -\& 33:........................................ -\& 34:........................................ -\& 35:........................................ -\& 36:........................................ -\& 37:........................................ -\& 38:........................................ -\& 39:........................................ -\& 40:........................................ -.Ve -.PP -Two non-intersecting ellipses can be made into the same region: -.PP -.Vb 1 -\& ELL(20,20,10,20,90) | ELL(1,1,20,10,0) -.Ve -.PP -and looks as follows: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 1:11111111111111111111.................... -\& 2:11111111111111111111.................... -\& 3:11111111111111111111.................... -\& 4:11111111111111111111.................... -\& 5:1111111111111111111..................... -\& 6:111111111111111111...................... -\& 7:1111111111111111........................ -\& 8:111111111111111......................... -\& 9:111111111111............................ -\& 10:111111111............................... -\& 11:...........11111111111111111............ -\& 12:........111111111111111111111111........ -\& 13:.....11111111111111111111111111111...... -\& 14:....11111111111111111111111111111111.... -\& 15:..11111111111111111111111111111111111... -\& 16:.1111111111111111111111111111111111111.. -\& 17:111111111111111111111111111111111111111. -\& 18:111111111111111111111111111111111111111. -\& 19:111111111111111111111111111111111111111. -\& 20:111111111111111111111111111111111111111. -\& 21:111111111111111111111111111111111111111. -\& 22:111111111111111111111111111111111111111. -\& 23:111111111111111111111111111111111111111. -\& 24:.1111111111111111111111111111111111111.. -\& 25:..11111111111111111111111111111111111... -\& 26:...11111111111111111111111111111111..... -\& 27:.....11111111111111111111111111111...... -\& 28:.......111111111111111111111111......... -\& 29:...........11111111111111111............ -\& 30:........................................ -\& 31:........................................ -\& 32:........................................ -\& 33:........................................ -\& 34:........................................ -\& 35:........................................ -\& 36:........................................ -\& 37:........................................ -\& 38:........................................ -\& 39:........................................ -\& 40:........................................ -.Ve -.PP -You can use several boolean operations in a single region expression, -to create arbitrarily complex regions. With the important exception -below, you can apply the operators in any order, using parentheses if -necessary to override the natural precedences of the operators. -.PP -\&\s-1NB:\s0 Using a panda shape is always much more efficient than explicitly -specifying \*(L"pie & annulus\*(R", due to the ability of panda to place a -limit on the number of pixels checked in the pie shape. If you are -going to specify the intersection of pie and annulus, use panda -instead. -.PP -As described in \*(L"help regreometry\*(R", the \fB\s-1PIE\s0\fR slice goes to the -edge of the field. To limit its scope, \fB\s-1PIE\s0\fR usually is is -combined with other shapes, such as circles and annuli, using boolean -operations. In this context, it is worth noting that that there is a -difference between \fB\-PIE\fR and \fB&!PIE\fR. The former is a -global exclude of all pixels in the \fB\s-1PIE\s0\fR slice, while the latter -is a local excludes of pixels affecting only the region(s) with which -the \fB\s-1PIE\s0\fR is combined. For example, the following region uses -\&\fB&!PIE\fR as a local exclude of a single circle. Two other circles -are also defined and are unaffected by the local exclude: -.PP -.Vb 3 -\& CIRCLE(1,8,1) -\& CIRCLE(8,8,7)&!PIE(8,8,60,120)&!PIE(8,8,240,300) -\& CIRCLE(15,8,2) -.Ve -.PP -.Vb 17 -\& 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 -\& - - - - - - - - - - - - - - - -\& 15: . . . . . . . . . . . . . . . -\& 14: . . . . 2 2 2 2 2 2 2 . . . . -\& 13: . . . 2 2 2 2 2 2 2 2 2 . . . -\& 12: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 11: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 10: . . . . 2 2 2 2 2 2 2 . . . . -\& 9: . . . . . . 2 2 2 . . . . 3 3 -\& 8: 1 . . . . . . . . . . . . 3 3 -\& 7: . . . . . . 2 2 2 . . . . 3 3 -\& 6: . . . . 2 2 2 2 2 2 2 . . . . -\& 5: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 4: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 3: . . . 2 2 2 2 2 2 2 2 2 . . . -\& 2: . . . . 2 2 2 2 2 2 2 . . . . -\& 1: . . . . . . . . . . . . . . . -.Ve -.PP -Note that the two other regions are not affected by the \fB&!PIE\fR, -which only affects the circle with which it is combined. -.PP -On the other hand, a \fB\-PIE\fR is an global exclude that does -affect other regions with which it overlaps: -.PP -.Vb 5 -\& CIRCLE(1,8,1) -\& CIRCLE(8,8,7) -\& \-PIE(8,8,60,120) -\& \-PIE(8,8,240,300) -\& CIRCLE(15,8,2) -.Ve -.PP -.Vb 17 -\& 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 -\& - - - - - - - - - - - - - - - -\& 15: . . . . . . . . . . . . . . . -\& 14: . . . . 2 2 2 2 2 2 2 . . . . -\& 13: . . . 2 2 2 2 2 2 2 2 2 . . . -\& 12: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 11: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 10: . . . . 2 2 2 2 2 2 2 . . . . -\& 9: . . . . . . 2 2 2 . . . . . . -\& 8: . . . . . . . . . . . . . . . -\& 7: . . . . . . 2 2 2 . . . . . . -\& 6: . . . . 2 2 2 2 2 2 2 . . . . -\& 5: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 4: . . 2 2 2 2 2 2 2 2 2 2 2 . . -\& 3: . . . 2 2 2 2 2 2 2 2 2 . . . -\& 2: . . . . 2 2 2 2 2 2 2 . . . . -\& 1: . . . . . . . . . . . . . . . -.Ve -.PP -The two smaller circles are entirely contained within the two exclude -\&\fB\s-1PIE\s0\fR slices and therefore are excluded from the region. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/regbounds.7 b/funtools/man/man7/regbounds.7 deleted file mode 100644 index 40a1648..0000000 --- a/funtools/man/man7/regbounds.7 +++ /dev/null @@ -1,305 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "regbounds 7" -.TH regbounds 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -RegBounds \- Region Boundaries -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -Describes how spatial region boundaries are handled. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The golden rule for spatial region filtering was first enunciated by -Leon VanSpeybroeck in 1986: -.PP -Each photon will be counted once, and no photon will be counted -more than once. -.PP -This means that we must be careful about boundary -conditions. For example, if a circle is contained in an annulus such -that the inner radius of the annulus is the same as the radius of the -circle, then photons on that boundary must always be assigned to one -or the other region. That is, the number of photons in both regions -must equal the sum of the number of photons in each region taken -separately. -.PP -With this in mind, the rules for determining whether a boundary image -pixel or table row are assigned to a region are defined below. -.PP -\&\fBImage boundaries - radially-symmetric shapes (circle, annuli, ellipse)\fR -.PP -For image filtering, pixels whose center is inside the boundary are -included. This also applies non-radially-symmetric shapes. When a -pixel center is exactly on the boundary, the pixel assignment rule is: -.IP "\(bu" 4 -the outer boundary of a symmetric shape does not include such pixels -.IP "\(bu" 4 -the inner boundary of a symmetric shape (annulus) includes such pixels -.PP -In this way, an annulus with radius from 0 to 1, centered exactly on a -pixel, includes the pixel on which it is centered, but none of its -neighbors. -.PP -These rules ensure that when defining concentric shapes, no pixels are -omitted between concentric regions and no pixels are claimed by two -regions. When applied to small symmetric shapes, the shape is less -likely to be skewed, as would happen with non-radially-symmetric -rules. These rules differ from the rules for box-like shapes, which -are more likely to be positioned adjacent to one another. -.PP -\&\fBImage Boundaries: non-radially symmetric shapes (polygons, boxes)\fR -.PP -For image filtering, pixels whose center is inside the boundary are -included. This also applies radially-symmetric shapes. When a pixel -center is exactly on the boundary of a non-radially symmetric region, -the pixel is included in the right or upper region, but not the left -or lower region. This ensures that geometrically adjoining regions -touch but don't overlap. -.PP -\&\fBRow Boundaries are Analytic\fR -.PP -When filtering table rows, the boundary rules are the same as for -images, except that the calculation is not done on the center of a -pixel, (since table rows, especially X\-ray events rows, often have -discrete, floating point positions) but are calculated exactly. That -is, an row is inside the boundary without regard to its integerized -pixel value. For rows that are exactly on a region boundary, the -above rules are applied to ensure that all rows are counted once and -no row is counted more than once. -.PP -Because row boundaries are calculated differently from image boundaries, -certain programs will give different results when filtering the same -region file. In particular, fundisp/funtable (which utilize analytic -row filtering) perform differently from funcnts (which performs image -filtering, even on tables). -.PP -\&\fBImage Boundaries vs. Row Boundaries: Practical Considerations\fR -.PP -You will sometimes notice a discrepancy between running funcnts on an -binary table file and running fundisp on the same file with the same filter. -For example, consider the following: -.PP -.Vb 2 -\& fundisp test1.fits"[box(4219,3887,6,6,0)]" | wc -\& 8893 320148 3752846 -.Ve -.PP -Since fundisp has a 2\-line header, there are actually 8891 photons -that pass the filter. But then run funtable and select only the -rows that pass this filter, placing them in a new file: -.PP -.Vb 1 -\& ./funtable test1.fits"[box(4219,3887,6,6,0)]" test2.fits -.Ve -.PP -Now run funcnts using the original filter on the derived file: -.PP -.Vb 1 -\& ./funcnts test2.fits "physical; box(4219,3887,6,6,0)" -.Ve -.PP -.Vb 1 -\& [... lot of processed output ...] -.Ve -.PP -.Vb 4 -\& # the following source and background components were used: -\& source region(s) -\& ---------------- -\& physical; box(4219,3887,6,6,0) -.Ve -.PP -.Vb 3 -\& reg counts pixels -\& ---- ------------ --------- -\& 1 7847.000 36 -.Ve -.PP -There are 1044 rows (events) that pass the row filter in fundisp (or -funtable) but fail to make it through funcnts. Why? -.PP -The reason can be traced to how analytic row filtering (fundisp, funtable) -differs from integerized pixel filtering(funcnts, funimage). Consider the -region: -.PP -.Vb 1 -\& box(4219,3887,6,6,0) -.Ve -.PP -Analytically (i.e., using row filtering), positions will pass this -filter successfully if: -.PP -.Vb 2 -\& 4216 <= x <= 4222 -\& 3884 <= y <= 3890 -.Ve -.PP -For example, photons with position values of x=4216.4 or y=3884.08 will pass. -.PP -Integerized image filtering is different in that the pixels that will -pass this filter have centers at: -.PP -.Vb 2 -\& x = 4217, 4218, 4219, 4220, 4221, 4222 -\& y = 3885, 3886, 3887, 3888, 3889, 3890 -.Ve -.PP -Note that there are 6 pixels in each direction, as specified by the region. -That means that positions will pass the filter successfully if: -.PP -.Vb 2 -\& 4217 <= (int)x <= 4222 -\& 3885 <= (int)y <= 3890 -.Ve -.PP -Photons with position values of x=4216.4 or y=3884.08 will \s-1NOT\s0 pass. -.PP -Note that the position values are integerized, in effect, binned into -image values. This means that x=4222.4 will pass this filter, but not -the analytic filter above. We do this to maintain the design goal that -either all counts in a pixel are included in an integerized filter, or -else none are included. -.PP -[It could be argued that the correct photon limits for floating point -row data really should be: -.PP -.Vb 2 -\& 4216.5 <= x <= 4222.5 -\& 3884.5 <= y <= 3890.5 -.Ve -.PP -since each pixel extends for .5 on either side of the center. We chose -to the maintain integerized algorithm for all image-style filtering so -that funcnts would give the exact same results regardless of whether -a table or a derived non-blocked binned image is used.] -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/regcoords.7 b/funtools/man/man7/regcoords.7 deleted file mode 100644 index fd7615e..0000000 --- a/funtools/man/man7/regcoords.7 +++ /dev/null @@ -1,345 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "regcoords 7" -.TH regcoords 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -RegCoords \- Spatial Region Coordinates -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document describes the specification of coordinate systems, and the -interpretation of coordinate values, for spatial region filtering. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBPixel coordinate systems\fR -.PP -The default coordinate system for regions is \s-1PHYSICAL\s0, which means -that region position and size values are taken from the original -data. (Note that this is a change from the original \s-1IRAF/PROS\s0 -implementation, in which the \s-1IMAGE\s0 coordinate system was the default.) -\&\s-1PHYSICAL\s0 coordinates always refer to pixel positions on the original -image (using \s-1IRAF\s0 \s-1LTM\s0 and \s-1LTV\s0 keywords). With \s-1PHYSICAL\s0 coordinates, -if a set of coordinates specifies the position of an object in an -original \s-1FITS\s0 file, the same coordinates will specify the same object -in any \s-1FITS\s0 derived from the original. Physical coordinates are -invariant with blocking of \s-1FITS\s0 files or taking sections of images, -even when a blocked section is written to a new file. -.PP -Thus, although a value in pixels refers, by default, to the \s-1PHYSICAL\s0 -coordinate system, you may specify that position values refer to the -image coordinate system using the \fBglobal\fR or \fBlocal\fR -properties commands: -.PP -.Vb 2 -\& global coordsys image -\& circle 512 512 100 -.Ve -.PP -The \fBglobal\fR command changes the coordinate system for all -regions that follow, while the \fBlocal\fR command changes the -coordinate system only for the region immediately following: -.PP -.Vb 3 -\& local coordsys image -\& circle 512 512 100 -\& circle 1024 1024 200 -.Ve -.PP -This changes the coordinate system only for the region that follows. -In the above example, the second region uses the global coordinate -system (\s-1PHYSICAL\s0 by default). -.PP -\&\fBWorld Coordinate Systems\fR -.PP -If World Coordinate System information is contained in the data file -being filtered, it also is possible to define regions using a sky -coordinate system. Supported systems include: -.PP -.Vb 10 -\& name description -\& ---- ----------- -\& PHYSICAL pixel coords of original file using LTM/LTV -\& IMAGE pixel coords of current file -\& FK4, B1950 sky coordinate systems -\& FK5, J2000 sky coordinate systems -\& GALACTIC sky coordinate systems -\& ECLIPTIC sky coordinate systems -\& ICRS currently same as J2000 -\& LINEAR linear wcs as defined in file -.Ve -.PP -In addition, two mosaic coordinate systems have been defined that -utilize the (evolving) \s-1IRAF\s0 mosaic keywords: -.PP -.Vb 4 -\& name description -\& ---- ----------- -\& AMPLIFIER mosaic coords of original file using ATM/ATV -\& DETECTOR mosaic coords of original file using DTM/DTV -.Ve -.PP -Again, to use one of these coordinate systems, the \fBglobal\fR or -\&\fBlocal\fR properties commands are used: -.PP -.Vb 1 -\& global coordsys galactic -.Ve -.PP -\&\fB\s-1WCS\s0 Positions and Sizes\fR -.PP -In addition to pixels, positional values in a WCS-enabled region can -be specified using sexagesimal or degrees format: -.PP -.Vb 11 -\& position arguments description -\& ------------------ ----------- -\& [num] context-dependent (see below) -\& [num]d degrees -\& [num]r radians -\& [num]p physical pixels -\& [num]i image pixels -\& [num]:[num]:[num] hms for 'odd' position arguments -\& [num]:[num]:[num] dms for 'even' position arguments -\& [num]h[num]m[num]s explicit hms -\& [num]d[num]m[num]s explicit dms -.Ve -.PP -If ':' is used as sexagesimal separator, the value is considered to be -specifying hours/minutes/seconds if it is the first argument of a -positional pair, and degrees/minutes/seconds for the second argument -of a pair (except for galactic coordinates, which always use degrees): -.PP -.Vb 7 -\& argument description -\& ----------- ----------- -\& 10:20:30.0 10 hours, 20 minutes, 30 seconds for 1st positional argument -\& 10 degrees, 20 minutes, 30 seconds for 2nd positional argument -\& 10h20m30.0 10 hours, 20 minutes, 30 seconds -\& 10d20m30.0 10 degrees, 20 minutes, 30 seconds -\& 10.20d 10.2 degrees -.Ve -.PP -Similarly, the units of size values are defined by the formating -character(s) attached to a number: -.PP -.Vb 9 -\& size arguments description -\& -------------- ----------- -\& [num] context-dependent (see below) -\& [num]" arc seconds -\& [num]' arc minutes -\& [num]d degrees -\& [num]r radians -\& [num]p physical pixels -\& [num]i image pixels -.Ve -.PP -For example: -.PP -.Vb 8 -\& argument description -\& ----------- ----------- -\& 10 ten pixels -\& 10' ten minutes of arc -\& 10" ten seconds of arc -\& 10d ten degrees -\& 10p ten pixels -\& 0.5r half of a radian -.Ve -.PP -An example of using sky coordinate systems follows: -.PP -.Vb 4 -\& global coordsys B1950 -\& \-box 175.54d 20.01156d 10' 10' -\& local coordsys J2000 -\& pie 179.57d 22.4d 0 360 n=4 && annulus 179.57d 22.4d 3' 24' n=5 -.Ve -.PP -At the \s-1FK4\s0 1950 coordinates 175.54d \s-1RA\s0, 20.01156d \s-1DEC\s0 exclude a 10 -minute by 10 minute box. Then at the \s-1FK5\s0 2000 coordinates 179.57d \s-1RA\s0 -22.4d \s-1DEC\s0 draw a radial profile regions pattern with 4 quadrants and 5 -annuli ranging from 3 minutes to 24 minutes in diameter. In this -example, the default coordinate system is overridden by the commands -in the regions spec. -.PP -\&\fB\s-1NB:\s0 The Meaning of Pure Numbers Are Context Sensitive\fR -.PP -When a \*(L"pure number\*(R" (i.e. one without a format directive such as 'd' -for 'degrees') is specified as a position or size, its interpretation -depends on the context defined by the 'coordsys' keyword. In general, -the rule is: -.PP -All pure numbers have implied units corresponding to the current -coordinate system. -.PP -If no coordinate system is explicitly specified, the default system is -implicitly assumed to be \s-1PHYSICAL\s0. In practice this means that for -\&\s-1IMAGE\s0 and \s-1PHYSICAL\s0 systems, pure numbers are pixels. Otherwise, -for all systems other than \s-1LINEAR\s0, pure numbers are degrees. For -\&\s-1LINEAR\s0 systems, pure numbers are in the units of the linear system. -This rule covers both positions and sizes. -.PP -As a corollary, when a sky-formatted number is used with the \s-1IMAGE\s0 -or \s-1PHYSICAL\s0 coordinate system (which includes the default case of no -coordsys being specified), the formatted number is assumed to be in -the units of the \s-1WCS\s0 contained in the current file. If no sky \s-1WCS\s0 is -specified, an error results. -.PP -Examples: -.PP -.Vb 2 -\& circle(512,512,10) -\& ellipse 202.44382d 47.181656d 0.01d 0.02d -.Ve -.PP -In the absence of a specified coordinate system, the circle uses the -default \s-1PHYSICAL\s0 units of pixels, while the ellipse explicitly uses degrees, -presumably to go with the \s-1WCS\s0 in the current file. -.PP -.Vb 5 -\& global coordsys=fk5 -\& global color=green font="system 10 normal" -\& circle 202.44382 47.181656 0.01 -\& circle 202.44382 47.181656 10p -\& ellipse(512p,512p,10p,15p,20) -.Ve -.PP -Here, the circles use the \s-1FK5\s0 units of degrees (except for the -explicit use of pixels in the second radius), while the ellipse -explicitly specifies pixels. The ellipse angle is in degrees. -.PP -Note that Chandra data format appears to use \*(L"coordsys=physical\*(R" -implicitly. Therefore, for most Chandra applications, valid regions -can be generated safely by asking ds9 to save/display regions in -pixels using the \s-1PHYSICAL\s0 coordsys. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/regdiff.7 b/funtools/man/man7/regdiff.7 deleted file mode 100644 index c9f6f6a..0000000 --- a/funtools/man/man7/regdiff.7 +++ /dev/null @@ -1,181 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "regdiff 7" -.TH regdiff 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -RegDiff \- Differences Between Funtools and IRAF Regions -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -Describes the differences between Funtools/ds9 regions and the old \s-1IRAF/PROS\s0 -regions. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -We have tried to make Funtools regions compatible with their -predecessor, \s-1IRAF/PROS\s0 regions. For simple regions and simple boolean -algebra between regions, there should be no difference between the two -implementations. The following is a list of differences and -incompatibilities between the two: -.IP "\(bu" 4 -If a pixel is covered by two different regions expressions, -Funtools assigns the mask value of the \fBfirst\fR region that -contains that pixel. That is, successive regions \fBdo not\fR -overwrite previous regions in the mask, as was the case with the -original \s-1PROS\s0 regions. This means that one must define overlapping -regions in the reverse order in which they were defined in \s-1PROS\s0. If -region N is fully contained within region M, then N should be defined -\&\fBbefore\fR M, or else it will be \*(L"covered up\*(R" by the latter. This -change is necessitated by the use of optimized filter compilation, i.e., -Funtools only tests individual regions until a proper match is made. -.IP "\(bu" 4 -The \fB\s-1PANDA\s0\fR region has replaced the old \s-1PROS\s0 syntax in which -a \fB\s-1PIE\s0\fR accelerator was combined with an \fB\s-1ANNULUS\s0\fR accelerator -using \fB\s-1AND\s0\fR. That is, -.Sp -.Vb 1 -\& ANNULUS(20,20,0,15,n=4) & PIE(20,20,0,360,n=3) -.Ve -.Sp -has been replaced by: -.Sp -.Vb 1 -\& PANDA(20,20,0,360,3,0,15,4) -.Ve -.Sp -The \s-1PROS\s0 syntax was inconsistent with the meaning of the \fB\s-1AND\s0\fR operator. -.IP "\(bu" 4 -The meaning of pure numbers (i.e., without format specifiers) in -regions has been clarified, as has the syntax for specifying coordinate -systems. See the general discussion on -Spatial Region Filtering -for more information. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages diff --git a/funtools/man/man7/reggeometry.7 b/funtools/man/man7/reggeometry.7 deleted file mode 100644 index 8eb15e7..0000000 --- a/funtools/man/man7/reggeometry.7 +++ /dev/null @@ -1,1271 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "reggeometry 7" -.TH reggeometry 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -RegGeometry \- Geometric Shapes in Spatial Region Filtering -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -This document describes the geometry of regions available for spatial -filtering in \s-1IRAF/PROS\s0 analysis. -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBGeometric shapes\fR -.PP -Several geometric shapes are used to describe regions. The valid -shapes are: -.PP -.Vb 11 -\& shape: arguments: -\& ----- ---------------------------------------- -\& ANNULUS xcenter ycenter inner_radius outer_radius -\& BOX xcenter ycenter xwidth yheight (angle) -\& CIRCLE xcenter ycenter radius -\& ELLIPSE xcenter ycenter xwidth yheight (angle) -\& FIELD none -\& LINE x1 y1 x2 y2 -\& PIE xcenter ycenter angle1 angle2 -\& POINT x1 y1 -\& POLYGON x1 y1 x2 y2 ... xn yn -.Ve -.PP -All arguments are real values; integer values are automatically -converted to real where necessary. All angles are in degrees and -specify angles that run counter-clockwise from the positive y\-axis. -.PP -Shapes can be specified using \*(L"command\*(R" syntax: -.PP -.Vb 1 -\& [shape] arg1 arg2 ... -.Ve -.PP -or using \*(L"routine\*(R" syntax: -.PP -.Vb 1 -\& [shape](arg1, arg2, ...) -.Ve -.PP -or by any combination of the these. (Of course, the parentheses must -balance and there cannot be more commas than necessary.) The shape -keywords are case\-insensitive. Furthermore, any shape can be -specified by a three-character unique abbreviation. For example, one -can specify three circular regions as: -.PP -.Vb 1 -\& "foo.fits[CIRCLE 512 512 50;CIR(128 128, 10);cir(650,650,20)]" -.Ve -.PP -(Quotes generally are required to protect the region descriptor -from being processed by the Unix shell.) -.PP -The \fBannulus\fR shape specifies annuli, centered at xcenter, -ycenter, with inner and outer radii (r1, r2). For example, -.PP -.Vb 1 -\& ANNULUS 25 25 5 10 -.Ve -.PP -specifies an annulus centered at 25.0 25.0 with an inner radius of 5.0 and -an outer radius of 10. Assuming (as will be done for all examples in this -document, unless otherwise noted) this shape is used in a mask of size 40x40, -it will look like this: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:....................111111111........... -\& 33:...................11111111111.......... -\& 32:.................111111111111111........ -\& 31:.................111111111111111........ -\& 30:................11111111111111111....... -\& 29:...............1111111.....1111111...... -\& 28:...............111111.......111111...... -\& 27:...............11111.........11111...... -\& 26:...............11111.........11111...... -\& 25:...............11111.........11111...... -\& 24:...............11111.........11111...... -\& 23:...............11111.........11111...... -\& 22:...............111111.......111111...... -\& 21:...............1111111.....1111111...... -\& 20:................11111111111111111....... -\& 19:.................111111111111111........ -\& 18:.................111111111111111........ -\& 17:...................11111111111.......... -\& 16:....................111111111........... -\& 15:........................................ -\& 14:........................................ -\& 13:........................................ -\& 12:........................................ -\& 11:........................................ -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:........................................ -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -The \fBbox\fR shape specifies an orthogonally oriented box, -centered at xcenter, ycenter, of size xwidth, yheight. It requires four -arguments and accepts an optional fifth argument to specify a rotation angle. -When the rotation angle is specified (in degrees), the box is rotated by -an angle that runs counter-clockwise from the positive y\-axis. -.PP -The \fBbox\fR shape specifies a rotated box, centered at -xcenter, ycenter, of size xwidth, yheight. The box is rotated by an angle -specified in degrees that runs counter-clockwise from the positive y\-axis. -If the angle argument is omitted, it defaults to 0. -.PP -The \fBcircle\fR shape specifies a circle, centered at xcenter, -ycenter, of radius r. It requires three arguments. -.PP -The \fBellipse\fR shape specifies an ellipse, centered at -xcenter, ycenter, with y\-axis width a and the y\-axis length b defined such -that: -.PP -.Vb 1 -\& x**2/a**2 + y**2/b**2 = 1 -.Ve -.PP -Note that a can be less than, equal to, or greater than b. The ellipse -is rotated the specified number of degrees. The rotation is done according -to astronomical convention, counter-clockwise from the positive y\-axis. -An ellipse defined by: -.PP -.Vb 1 -\& ELLIPSE 20 20 5 10 45 -.Ve -.PP -will look like this: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:........................................ -\& 33:........................................ -\& 32:........................................ -\& 31:........................................ -\& 30:........................................ -\& 29:........................................ -\& 28:........................................ -\& 27:............111111...................... -\& 26:............11111111.................... -\& 25:............111111111................... -\& 24:............11111111111................. -\& 23:............111111111111................ -\& 22:............111111111111................ -\& 21:.............111111111111............... -\& 20:.............1111111111111.............. -\& 19:..............111111111111.............. -\& 18:...............111111111111............. -\& 17:...............111111111111............. -\& 16:................11111111111............. -\& 15:..................111111111............. -\& 14:...................11111111............. -\& 13:.....................111111............. -\& 12:........................................ -\& 11:........................................ -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:........................................ -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -The \fBfield\fR shape specifies the entire field as a -region. It is not usually specified explicitly, but is used implicitly in the -case where no regions are specified, that is, in cases where either a null -string or some abbreviation of the string \*(L"none\*(R" is input. -\&\fBField\fR takes no arguments. -.PP -The \fBpie\fR shape specifies an angular wedge of the entire field, -centered at xcenter, ycenter. The wedge runs between the two specified angles. -The angles are given in degrees, running counter-clockwise from the positive -x\-axis. For example, -.PP -.Vb 1 -\& PIE 20 20 90 180 -.Ve -.PP -defines a region from 90 degrees to 180 degrees, i.e., quadrant 2 of the -Cartesian plane. The display of such a region looks like this: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:11111111111111111111.................... -\& 39:11111111111111111111.................... -\& 38:11111111111111111111.................... -\& 37:11111111111111111111.................... -\& 36:11111111111111111111.................... -\& 35:11111111111111111111.................... -\& 34:11111111111111111111.................... -\& 33:11111111111111111111.................... -\& 32:11111111111111111111.................... -\& 31:11111111111111111111.................... -\& 30:11111111111111111111.................... -\& 29:11111111111111111111.................... -\& 28:11111111111111111111.................... -\& 27:11111111111111111111.................... -\& 26:11111111111111111111.................... -\& 25:11111111111111111111.................... -\& 24:11111111111111111111.................... -\& 23:11111111111111111111.................... -\& 22:11111111111111111111.................... -\& 21:11111111111111111111.................... -\& 20:........................................ -\& 19:........................................ -\& 18:........................................ -\& 17:........................................ -\& 16:........................................ -\& 15:........................................ -\& 14:........................................ -\& 13:........................................ -\& 12:........................................ -\& 11:........................................ -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:........................................ -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -The pie slice specified is always a counter-clockwise sweep between -the angles, starting at the first angle and ending at the second. Thus: -.PP -.Vb 1 -\& PIE 10 15 30 60 -.Ve -.PP -describes a 30 degree sweep from 2 o'clock to 1 o'clock, while: -.PP -.Vb 1 -\& PIE 10 15 60 30 -.Ve -.PP -describes a 330 degree counter-clockwise sweep from 1 o'clock to 2 o'clock -passing through 12 o'clock (0 degrees). Note in both of these examples that -the center of the slice can be anywhere on the plane. The second mask looks -like this: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:111111111111111111111111................ -\& 39:11111111111111111111111................. -\& 38:11111111111111111111111................. -\& 37:1111111111111111111111.................. -\& 36:1111111111111111111111.................. -\& 35:111111111111111111111................... -\& 34:11111111111111111111.................... -\& 33:11111111111111111111.................... -\& 32:1111111111111111111....................1 -\& 31:1111111111111111111..................111 -\& 30:111111111111111111.................11111 -\& 29:111111111111111111................111111 -\& 28:11111111111111111...............11111111 -\& 27:1111111111111111..............1111111111 -\& 26:1111111111111111.............11111111111 -\& 25:111111111111111............1111111111111 -\& 24:111111111111111..........111111111111111 -\& 23:11111111111111.........11111111111111111 -\& 22:11111111111111........111111111111111111 -\& 21:1111111111111.......11111111111111111111 -\& 20:111111111111......1111111111111111111111 -\& 19:111111111111....111111111111111111111111 -\& 18:11111111111....1111111111111111111111111 -\& 17:11111111111..111111111111111111111111111 -\& 16:1111111111.11111111111111111111111111111 -\& 15:1111111111111111111111111111111111111111 -\& 14:1111111111111111111111111111111111111111 -\& 13:1111111111111111111111111111111111111111 -\& 12:1111111111111111111111111111111111111111 -\& 11:1111111111111111111111111111111111111111 -\& 10:1111111111111111111111111111111111111111 -\& 9:1111111111111111111111111111111111111111 -\& 8:1111111111111111111111111111111111111111 -\& 7:1111111111111111111111111111111111111111 -\& 6:1111111111111111111111111111111111111111 -\& 5:1111111111111111111111111111111111111111 -\& 4:1111111111111111111111111111111111111111 -\& 3:1111111111111111111111111111111111111111 -\& 2:1111111111111111111111111111111111111111 -\& 1:1111111111111111111111111111111111111111 -.Ve -.PP -The pie slice goes to the edge of the field. To limit its scope, pie -usually is is combined with other shapes, such as circles and annuli, -using boolean operations. (See below and in \*(L"help regalgebra\*(R"). -.PP -Pie Performance Notes: -.PP -Pie region processing time is proportional to the size of the image, -and not the size of the region. This is because the pie shape is the -only infinite length shape, and we essentially must check all y rows -for inclusion (unlike other regions, where the y limits can be -calculated beforehand). Thus, pie can run very slowly on large images. -In particular, it will run \s-1MUCH\s0 more slowly than the panda shape in -image-based region operations (such as funcnts). We recommend use of -panda over pie where ever possible. -.PP -If you must use pie, always try to put it last in a boolean && -expression. The reason for this is that the filter code is optimized -to exit as soon as the result is know. Since pie is the slowest -region, it is better to avoid executing it if another region can decide -the result. Consider, for example, the difference in time required to -process a Chandra \s-1ACIS\s0 file when a pie and circle are combined in -two different orders: -.PP -.Vb 2 -\& time ./funcnts nacis.fits "circle 4096 4096 100 && pie 4096 4096 10 78" -\&2.87u 0.38s 0:35.08 9.2% -.Ve -.PP -.Vb 2 -\& time ./funcnts nacis.fits "pie 4096 4096 10 78 && circle 4096 4096 100 " -\&89.73u 0.36s 1:03.50 141.8% -.Ve -.PP -Black-magic performance note: -.PP -Panda region processing uses a \fBquick test\fR pie region instead of -the normal pie region when combining its annulus and pie shapes. This -\&\fBqtpie\fR shape differs from the normal pie in that it utilizes the -y limits from the previous region with which it is combined. In a -panda shape, which is a series of annuli combined with pies, the -processing time is thus reduced to that of the annuli. -.PP -You can use the qtpie shape instead of pie in cases where you are -combining pie with another shape using the && operator. This will -cause the pie limits to be set using limits from the other shape, and -will speed up the processing considerably. For example, the above -execution of funcnts can be improved considerably using this technique: -.PP -.Vb 2 -\& time ./funcnts nacis.fits "circle 4096 4096 100 && qtpie 4096 4096 10 78" -\&4.66u 0.33s 0:05.87 85.0% -.Ve -.PP -We emphasize that this is a quasi-documented feature and might change in -the future. The qtpie shape is not recognized by ds9 or other programs. -.PP -The \fBline\fR shape allows single pixels in a line between (x1,y1) and -(x2,y2) to be included or excluded. For example: -.PP -.Vb 1 -\& LINE (5,6, 24,25) -.Ve -.PP -displays as: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:........................................ -\& 33:........................................ -\& 32:........................................ -\& 31:........................................ -\& 30:........................................ -\& 29:........................................ -\& 28:........................................ -\& 27:........................................ -\& 26:........................................ -\& 25:.......................1................ -\& 24:......................1................. -\& 23:.....................1.................. -\& 22:....................1................... -\& 21:...................1.................... -\& 20:..................1..................... -\& 19:.................1...................... -\& 18:................1....................... -\& 17:...............1........................ -\& 16:..............1......................... -\& 15:.............1.......................... -\& 14:............1........................... -\& 13:...........1............................ -\& 12:..........1............................. -\& 11:.........1.............................. -\& 10:........1............................... -\& 9:.......1................................ -\& 8:......1................................. -\& 7:.....1.................................. -\& 6:....1................................... -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -The \fBpoint\fR shape allows single pixels to be included or -excluded. Although the (x,y) values are real numbers, they are truncated -to integer and the corresponding pixel is included or excluded, as specified. -.PP -Several points can be put in one region declaration; unlike the -original \s-1IRAF\s0 implementation, each now is given a different region mask value. -This makes it easier, for example, for funcnts to determine the number of -photons in the individual pixels. For example, -.PP -.Vb 1 -\& POINT (5,6, 10,11, 20,20, 35,30) -.Ve -.PP -will give the different region mask values to all four points, as shown below: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:........................................ -\& 33:........................................ -\& 32:........................................ -\& 31:........................................ -\& 30:..................................4..... -\& 29:........................................ -\& 28:........................................ -\& 27:........................................ -\& 26:........................................ -\& 25:........................................ -\& 24:........................................ -\& 23:........................................ -\& 22:........................................ -\& 21:........................................ -\& 20:...................3.................... -\& 19:........................................ -\& 18:........................................ -\& 17:........................................ -\& 16:........................................ -\& 15:........................................ -\& 14:........................................ -\& 13:........................................ -\& 12:........................................ -\& 11:.........2.............................. -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:....1................................... -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -The \fBpolygon\fR shape specifies a polygon with vertices -(x1, y1) ... (xn, yn). The polygon is closed automatically: one should -not specify the last vertex to be the same as the first. Any number of -vertices are allowed. For example, the following polygon defines a -right triangle as shown below: -.PP -.Vb 1 -\& POLYGON (10,10, 10,30, 30,30) -.Ve -.PP -looks like this: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:........................................ -\& 33:........................................ -\& 32:........................................ -\& 31:........................................ -\& 30:..........11111111111111111111.......... -\& 29:..........1111111111111111111........... -\& 28:..........111111111111111111............ -\& 27:..........11111111111111111............. -\& 26:..........1111111111111111.............. -\& 25:..........111111111111111............... -\& 24:..........11111111111111................ -\& 23:..........1111111111111................. -\& 22:..........111111111111.................. -\& 21:..........11111111111................... -\& 20:..........1111111111.................... -\& 19:..........111111111..................... -\& 18:..........11111111...................... -\& 17:..........1111111....................... -\& 16:..........111111........................ -\& 15:..........11111......................... -\& 14:..........1111.......................... -\& 13:..........111........................... -\& 12:..........11............................ -\& 11:..........1............................. -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:........................................ -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -Note that polygons can get twisted upon themselves if edge lines -cross. Thus: -.PP -.Vb 1 -\& POL (10,10, 20,20, 20,10, 10,20) -.Ve -.PP -will produce an area which is two triangles, like butterfly wings, as shown -below: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:........................................ -\& 33:........................................ -\& 32:........................................ -\& 31:........................................ -\& 30:........................................ -\& 29:........................................ -\& 28:........................................ -\& 27:........................................ -\& 26:........................................ -\& 25:........................................ -\& 24:........................................ -\& 23:........................................ -\& 22:........................................ -\& 21:........................................ -\& 20:........................................ -\& 19:..........1........1.................... -\& 18:..........11......11.................... -\& 17:..........111....111.................... -\& 16:..........1111..1111.................... -\& 15:..........1111111111.................... -\& 14:..........1111..1111.................... -\& 13:..........111....111.................... -\& 12:..........11......11.................... -\& 11:..........1........1.................... -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:........................................ -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -The following are combinations of pie with different shapes -(called \*(L"panda\*(R" for \*(L"Pie \s-1AND\s0 Annulus\*(R") allow for easy specification of -radial sections: -.PP -.Vb 6 -\& shape: arguments: -\& ----- --------- -\& PANDA xcen ycen ang1 ang2 nang irad orad nrad # circular -\& CPANDA xcen ycen ang1 ang2 nang irad orad nrad # circular -\& BPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # box -\& EPANDA xcen ycen ang1 ang2 nang xwlo yhlo xwhi yhhi nrad (ang) # ellipse -.Ve -.PP -The \fBpanda\fR (\fBP\fRies \fB\s-1AND\s0\fR \fBA\fRnnuli) shape can be -used to create combinations of pie and annuli markers. It is analogous -to a Cartesian product on those shapes, i.e., the result is several -shapes generated by performing a boolean \s-1AND\s0 between pies and -annuli. Thus, the panda and cpanda specify combinations of annulus and -circle with pie, respectively and give identical results. The bpanda -combines box and pie, while epanda combines ellipse and pie. -.PP -Consider the example shown below: -.PP -.Vb 1 -\& PANDA(20,20, 0,360,3, 0,15,4) -.Ve -.PP -Here, 3 pie slices centered at 20, 20 are combined with 4 annuli, also -centered at 20, 20. The result is a mask with 12 regions (displayed in -base 16 to save characters): -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:..............44444444444............... -\& 33:............444444444444444............. -\& 32:...........88444444444444444............ -\& 31:.........888844443333344444444.......... -\& 30:........88888833333333333444444......... -\& 29:........88888733333333333344444......... -\& 28:.......8888877733333333333344444........ -\& 27:......888887777332222233333344444....... -\& 26:......888877777622222222333334444....... -\& 25:.....88887777766622222222333334444...... -\& 24:.....88887777666622222222233334444...... -\& 23:.....88887777666651111222233334444...... -\& 22:.....88877776666551111122223333444...... -\& 21:.....88877776666555111122223333444...... -\& 20:.....888777766665559999aaaabbbbccc...... -\& 19:.....888777766665559999aaaabbbbccc...... -\& 18:.....888777766665599999aaaabbbbccc...... -\& 17:.....88887777666659999aaaabbbbcccc...... -\& 16:.....888877776666aaaaaaaaabbbbcccc...... -\& 15:.....888877777666aaaaaaaabbbbbcccc...... -\& 14:......8888777776aaaaaaaabbbbbcccc....... -\& 13:......888887777bbaaaaabbbbbbccccc....... -\& 12:.......88888777bbbbbbbbbbbbccccc........ -\& 11:........888887bbbbbbbbbbbbccccc......... -\& 10:........888888bbbbbbbbbbbcccccc......... -\& 9:.........8888ccccbbbbbcccccccc.......... -\& 8:...........88ccccccccccccccc............ -\& 7:............ccccccccccccccc............. -\& 6:..............ccccccccccc............... -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -Several regions with different mask values can be combined in the -same mask. This supports comparing data from the different regions. -(For information on how to combine different shapes into a single -region, see \*(L"help regalgebra\*(R".) For example, consider the following -set of regions: -.PP -.Vb 3 -\& ANNULUS 25 25 5 10 -\& ELLIPSE 20 20 5 10 315 -\& BOX 15 15 5 10 -.Ve -.PP -The resulting mask will look as follows: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........................................ -\& 35:........................................ -\& 34:....................111111111........... -\& 33:...................11111111111.......... -\& 32:.................111111111111111........ -\& 31:.................111111111111111........ -\& 30:................11111111111111111....... -\& 29:...............1111111.....1111111...... -\& 28:...............111111.......111111...... -\& 27:...............11111.222222..11111...... -\& 26:...............111112222222..11111...... -\& 25:...............111112222222..11111...... -\& 24:...............111112222222..11111...... -\& 23:...............111112222222..11111...... -\& 22:...............111111222222.111111...... -\& 21:..............211111112222.1111111...... -\& 20:............322211111111111111111....... -\& 19:............32222111111111111111........ -\& 18:............22222111111111111111........ -\& 17:............222222211111111111.......... -\& 16:............22222222111111111........... -\& 15:............222222222................... -\& 14:............22222222.................... -\& 13:............222222...................... -\& 12:............33333....................... -\& 11:............33333....................... -\& 10:........................................ -\& 9:........................................ -\& 8:........................................ -\& 7:........................................ -\& 6:........................................ -\& 5:........................................ -\& 4:........................................ -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -Note that when a pixel is in 2 or more regions, it is arbitrarily -assigned to a one of the regions in question (often based on how a -give C compiler optimizes boolean expressions). -.PP -\&\fBRegion accelerators\fR -.PP -Two types of \efBaccelerators, to simplify region specification, -are provided as natural extensions to the ways shapes are described. -These are: extended lists of parameters, specifying multiple regions, -valid for annulus, box, circle, ellipse, pie, and points; and -\&\fBn=\fR, valid for annulus, box, circle, ellipse, and pie (not -point). In both cases, one specification is used to define several -different regions, that is, to define shapes with different mask -values in the region mask. -.PP -The following regions accept \fBaccelerator\fR syntax: -.PP -.Vb 13 -\& shape arguments -\& ----- ------------------------------------------ -\& ANNULUS xcenter ycenter radius1 radius2 ... radiusn -\& ANNULUS xcenter ycenter inner_radius outer_radius n=[number] -\& BOX xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle) -\& BOX xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle) -\& CIRCLE xcenter ycenter r1 r2 ... rn # same as annulus -\& CIRCLE xcenter ycenter rinner router n=[number] # same as annulus -\& ELLIPSE xcenter ycenter xw1 yh1 xw2 yh2 ... xwn yhn (angle) -\& ELLIPSE xcenter ycenter xwlo yhlo xwhi yhhi n=[number] (angle) -\& PIE xcenter ycenter angle1 angle2 (angle3) (angle4) (angle5) ... -\& PIE xcenter ycenter angle1 angle2 (n=[number]) -\& POINT x1 y1 x2 y2 ... xn yn -.Ve -.PP -Note that the circle accelerators are simply aliases for the annulus -accelerators. -.PP -For example, several annuli at the same center can be specified in one -region expression by specifying more than two radii. If \fBN\fR -radii are specified, then \fBN\fR\-1 annuli result, with the outer -radius of each preceding annulus being the inner radius of the -succeeding annulus. Each annulus is considered a separate region, and -is given a separate mask value. For example, -.PP -.Vb 1 -\& ANNULUS 20 20 0 2 5 10 15 20 -.Ve -.PP -specifies five different annuli centered at 20 20, and is equivalent to: -.PP -.Vb 5 -\& ANNULUS 20.0 20.0 0 2 -\& ANNULUS 20.0 20.0 2 5 -\& ANNULUS 20.0 20.0 5 10 -\& ANNULUS 20.0 20.0 10 15 -\& ANNULUS 20.0 20.0 15 20 -.Ve -.PP -The mask is shown below: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:.............5555555555555.............. -\& 38:...........55555555555555555............ -\& 37:.........555555555555555555555.......... -\& 36:........55555555555555555555555......... -\& 35:......555555555555555555555555555....... -\& 34:.....55555555544444444444555555555...... -\& 33:....5555555544444444444444455555555..... -\& 32:....5555555444444444444444445555555..... -\& 31:...555555444444444444444444444555555.... -\& 30:..55555544444444444444444444444555555... -\& 29:..55555544444443333333334444444555555... -\& 28:.5555554444444333333333334444444555555.. -\& 27:.5555544444433333333333333344444455555.. -\& 26:555555444444333333333333333444444555555. -\& 25:555554444443333333333333333344444455555. -\& 24:555554444433333332222233333334444455555. -\& 23:555554444433333322222223333334444455555. -\& 22:555554444433333222222222333334444455555. -\& 21:555554444433333222111222333334444455555. -\& 20:555554444433333222111222333334444455555. -\& 19:555554444433333222111222333334444455555. -\& 18:555554444433333222222222333334444455555. -\& 17:555554444433333322222223333334444455555. -\& 16:555554444433333332222233333334444455555. -\& 15:555554444443333333333333333344444455555. -\& 14:555555444444333333333333333444444555555. -\& 13:.5555544444433333333333333344444455555.. -\& 12:.5555554444444333333333334444444555555.. -\& 11:..55555544444443333333334444444555555... -\& 10:..55555544444444444444444444444555555... -\& 9:...555555444444444444444444444555555.... -\& 8:....5555555444444444444444445555555..... -\& 7:....5555555544444444444444455555555..... -\& 6:.....55555555544444444444555555555...... -\& 5:......555555555555555555555555555....... -\& 4:........55555555555555555555555......... -\& 3:.........555555555555555555555.......... -\& 2:...........55555555555555555............ -\& 1:.............5555555555555.............. -.Ve -.PP -For boxes and ellipses, if an odd number of arguments is specified, -then the last argument is assumed to be an angle. Otherwise, the -angle is assumed to be zero. For example: -.PP -.Vb 1 -\& ellipse 20 20 3 5 6 10 9 15 12 20 45 -.Ve -.PP -specifies an 3 ellipses at a 45 degree angle: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:........................................ -\& 38:........................................ -\& 37:........................................ -\& 36:........33333333........................ -\& 35:......333333333333...................... -\& 34:.....3333333333333333................... -\& 33:....333333333333333333.................. -\& 32:....33333332222233333333................ -\& 31:...3333332222222222333333............... -\& 30:...33333222222222222233333.............. -\& 29:...333332222222222222223333............. -\& 28:...3333222222211112222223333............ -\& 27:...33332222211111111222223333........... -\& 26:...333322222111111111122223333.......... -\& 25:...3333222211111111111122223333......... -\& 24:....3332222111111..1111122223333........ -\& 23:....333322211111.....11112222333........ -\& 22:....33332222111.......11112223333....... -\& 21:.....33322221111.......11122223333...... -\& 20:.....33332221111.......11112223333...... -\& 19:.....33332222111.......11112222333...... -\& 18:......33332221111.......11122223333..... -\& 17:.......33322221111.....111112223333..... -\& 16:.......3333222211111..1111112222333..... -\& 15:........3333222211111111111122223333.... -\& 14:.........333322221111111111222223333.... -\& 13:..........33332222211111111222223333.... -\& 12:...........3333222222111122222223333.... -\& 11:............333322222222222222233333.... -\& 10:.............33333222222222222233333.... -\& 9:..............3333332222222222333333.... -\& 8:...............33333333222223333333..... -\& 7:.................333333333333333333..... -\& 6:..................3333333333333333...... -\& 5:.....................333333333333....... -\& 4:.......................33333333......... -\& 3:........................................ -\& 2:........................................ -\& 1:........................................ -.Ve -.PP -Note in the above example that the lower limit is not part of the -region for boxes, circles, and ellipses. This makes circles and annuli -equivalent, i.e.: -.PP -.Vb 2 -\& circle 20 20 5 10 15 20 -\& annulus 20 20 5 10 15 20 -.Ve -.PP -both give the following region mask: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........................................ -\& 39:.............3333333333333.............. -\& 38:...........33333333333333333............ -\& 37:.........333333333333333333333.......... -\& 36:........33333333333333333333333......... -\& 35:......333333333333333333333333333....... -\& 34:.....33333333322222222222333333333...... -\& 33:....3333333322222222222222233333333..... -\& 32:....3333333222222222222222223333333..... -\& 31:...333333222222222222222222222333333.... -\& 30:..33333322222222222222222222222333333... -\& 29:..33333322222221111111112222222333333... -\& 28:.3333332222222111111111112222222333333.. -\& 27:.3333322222211111111111111122222233333.. -\& 26:333333222222111111111111111222222333333. -\& 25:333332222221111111111111111122222233333. -\& 24:33333222221111111.....11111112222233333. -\& 23:3333322222111111.......1111112222233333. -\& 22:333332222211111.........111112222233333. -\& 21:333332222211111.........111112222233333. -\& 20:333332222211111.........111112222233333. -\& 19:333332222211111.........111112222233333. -\& 18:333332222211111.........111112222233333. -\& 17:3333322222111111.......1111112222233333. -\& 16:33333222221111111.....11111112222233333. -\& 15:333332222221111111111111111122222233333. -\& 14:333333222222111111111111111222222333333. -\& 13:.3333322222211111111111111122222233333.. -\& 12:.3333332222222111111111112222222333333.. -\& 11:..33333322222221111111112222222333333... -\& 10:..33333322222222222222222222222333333... -\& 9:...333333222222222222222222222333333.... -\& 8:....3333333222222222222222223333333..... -\& 7:....3333333322222222222222233333333..... -\& 6:.....33333333322222222222333333333...... -\& 5:......333333333333333333333333333....... -\& 4:........33333333333333333333333......... -\& 3:.........333333333333333333333.......... -\& 2:...........33333333333333333............ -\& 1:.............3333333333333.............. -.Ve -.PP -As a final example, specifying several angles in one pie slice -expression is equivalent to specifying several separate slices with -the same center. As with the annulus, if \fBN\fR angles are -specified, then \fBN\fR\-1 slices result, with the ending angle of -each preceding slice being the starting angle of the succeeding slice. -Each slice is considered a separate region, and is given a separate -mask value. For example, -.PP -.Vb 1 -\& PIE 12 12 315 45 115 270 -.Ve -.PP -specifies three regions as shown below: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:2222222222222222222222222222222222222222 -\& 39:2222222222222222222222222222222222222221 -\& 38:2222222222222222222222222222222222222211 -\& 37:2222222222222222222222222222222222222111 -\& 36:2222222222222222222222222222222222221111 -\& 35:3222222222222222222222222222222222211111 -\& 34:3222222222222222222222222222222222111111 -\& 33:3322222222222222222222222222222221111111 -\& 32:3322222222222222222222222222222211111111 -\& 31:3332222222222222222222222222222111111111 -\& 30:3332222222222222222222222222221111111111 -\& 29:3333222222222222222222222222211111111111 -\& 28:3333222222222222222222222222111111111111 -\& 27:3333322222222222222222222221111111111111 -\& 26:3333322222222222222222222211111111111111 -\& 25:3333322222222222222222222111111111111111 -\& 24:3333332222222222222222221111111111111111 -\& 23:3333332222222222222222211111111111111111 -\& 22:3333333222222222222222111111111111111111 -\& 21:3333333222222222222221111111111111111111 -\& 20:3333333322222222222211111111111111111111 -\& 19:3333333322222222222111111111111111111111 -\& 18:3333333332222222221111111111111111111111 -\& 17:3333333332222222211111111111111111111111 -\& 16:3333333333222222111111111111111111111111 -\& 15:3333333333222221111111111111111111111111 -\& 14:3333333333322211111111111111111111111111 -\& 13:3333333333322111111111111111111111111111 -\& 12:33333333333.1111111111111111111111111111 -\& 11:3333333333331111111111111111111111111111 -\& 10:333333333333.111111111111111111111111111 -\& 9:333333333333..11111111111111111111111111 -\& 8:333333333333...1111111111111111111111111 -\& 7:333333333333....111111111111111111111111 -\& 6:333333333333.....11111111111111111111111 -\& 5:333333333333......1111111111111111111111 -\& 4:333333333333.......111111111111111111111 -\& 3:333333333333........11111111111111111111 -\& 2:333333333333.........1111111111111111111 -\& 1:333333333333..........111111111111111111 -.Ve -.PP -The annulus, box, circle, ellipse, and pie shapes also accept an -\&\fBn=[int]\fR syntax for specifying multiple regions. The -\&\fBn=[int]\fRsyntax interprets the previous (shape\-dependent) -arguments as lower and upper limits for the region and creates n -shapes with evenly spaced boundaries. For example, if \fBn=[int]\fR -is specified in an annulus, the two immediately preceding radii -(\fBrn\fR and \fBrm\fR) are divided into \fBint\fR annuli, such -that the inner radius of the first is \fBrn\fR and the outer radius -of the last is \fBrm\fR. For example, -.PP -.Vb 1 -\& ANNULUS 20 20 5 20 n=3 -.Ve -.PP -is equivalent to: -.PP -.Vb 1 -\& ANNULUS 20 20 5 10 15 20 -.Ve -.PP -If this syntax is used with an ellipse or box, then the two preceding -pairs of values are taken to be lower and upper limits for a set of -ellipses or boxes. A circle uses the two preceding arguments for upper -and lower radii. For pie, the two preceding angles are divided into n -wedges such that the starting angle of the first is the lower bound -and the ending angle of the last is the upper bound. In all cases, -the \fBn=[int]\fR syntax allows any single alphabetic character -before the \*(L"=\*(R", i.e, i=3, z=3, etc. are all equivalent. -.PP -Also note that for boxes and ellipses, the optional angle argument is -always specified after the \fBn=[int]\fR syntax. For example: -.PP -.Vb 1 -\& ellipse 20 20 4 6 16 24 n=3 45 -.Ve -.PP -specifies 3 elliptical regions at an angle of 45 degrees: -.PP -.Vb 42 -\& 1234567890123456789012345678901234567890 -\& ---------------------------------------- -\& 40:........33333333........................ -\& 39:.....33333333333333..................... -\& 38:....33333333333333333................... -\& 37:...33333333333333333333................. -\& 36:..33333333333333333333333............... -\& 35:.3333333333222223333333333.............. -\& 34:3333333322222222222233333333............ -\& 33:33333332222222222222223333333........... -\& 32:333333222222222222222222333333.......... -\& 31:3333322222222222222222222333333......... -\& 30:33333222222222111122222222333333........ -\& 29:333332222222111111112222222333333....... -\& 28:3333222222211111111111222222333333...... -\& 27:3333222222111111111111112222233333...... -\& 26:33332222221111111111111112222233333..... -\& 25:33332222211111111.111111112222233333.... -\& 24:333322222111111......111111222223333.... -\& 23:333322222111111.......111112222233333... -\& 22:33333222221111.........11111222223333... -\& 21:333332222211111.........11112222233333.. -\& 20:.33332222211111.........11111222223333.. -\& 19:.33333222221111.........111112222233333. -\& 18:..33332222211111.........11112222233333. -\& 17:..333332222211111.......111111222233333. -\& 16:...333322222111111......111111222223333. -\& 15:...333332222211111111.111111112222233333 -\& 14:....333332222211111111111111122222233333 -\& 13:.....33333222221111111111111122222233333 -\& 12:.....33333322222211111111111222222233333 -\& 11:......3333332222222111111112222222333333 -\& 10:.......333333222222221111222222222333333 -\& 9:........33333322222222222222222222333333 -\& 8:.........333333222222222222222222333333. -\& 7:..........33333332222222222222223333333. -\& 6:...........3333333322222222222233333333. -\& 5:.............3333333333222223333333333.. -\& 4:..............33333333333333333333333... -\& 3:................33333333333333333333.... -\& 2:..................33333333333333333..... -\& 1:....................33333333333333...... -.Ve -.PP -Both the variable argument syntax and the \fBn=[int]\fR syntax must -occur alone in a region descriptor (aside from the optional angle for -boxes and ellipses). They cannot be combined. Thus, it is not valid -to precede or follow an \fBn=[int]\fR accelerator with more angles or -radii, as in this example: -.PP -.Vb 3 -\& # INVALID -- one too many angles before a=5 ... -\& # and no angles are allowed after a=5 -\& PIE 12 12 10 25 50 a=5 85 135 -.Ve -.PP -Instead, use three separate specifications, such as: -.PP -.Vb 3 -\& PIE 12 12 10 25 -\& PIE 12 12 25 50 a=5 -\& PIE 12 12 85 135 -.Ve -.PP -The original (\s-1IRAF\s0) implementation of region filtering permitted this -looser syntax, but we found it caused more confusion than it was worth -and therefore removed it. -.PP -\&\s-1NB:\s0 Accelerators may be combined with other shapes in a boolean -expression in any order. (This is a change starting with funtools -v1.1.1. Prior to this release, the accelerator shape had to be -specified last). The actual region mask id values returned depend on the -order in which the shapes are specified, although the total number of -pixels or rows that pass the filter will be consistent. For this -reason, use of accelerators in boolean expressions is discouraged in -programs such as funcnts, where region mask id values are used -to count events or image pixels. -.PP -[All region masks displayed in this document were generated using the -\&\fBfundisp\fR routine and the undocumented \*(L"mask=all\*(R" argument (with -spaced removed using sed ): -.PP -.Vb 2 -\& fundisp "funtools/funtest/test40.fits[ANNULUS 25 25 5 10]" mask=all |\e -\& sed 's/ //g' -.Ve -.PP -Note that you must supply an image of the appropriate size \*(-- in this case, -a \s-1FITS\s0 image of dimension 40x40 is used.] -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages |