Provided by: funtools_1.4.7-2_amd64 bug

NAME

       funimage - create a FITS image from a Funtools data file

SYNOPSIS

       funimage [-a] <iname> <oname> [bitpix=n] funimage [-l] <iname> <oname> <xcol:xdims>
       <ycol:ydims> <vcol> [bitpix=n] funimage [-p x⎪y] <iname> <oname> [bitpix=n]

OPTIONS

         -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

DESCRIPTION

       funimage creates a primary FITS image from the specified FITS Extension and/or Image
       Section of a FITS file, or from an Image Section of a non-FITS array, or from a raw event
       file.

       The first argument to the program specifies the FITS input image, array, or raw event file
       to process.  If "stdin" is specified, data are read from the standard input. Use Funtools
       Bracket Notation to specify FITS extensions, image sections, and filters.  The second
       argument is the output FITS file.  If "stdout" is specified, the FITS image is written to
       the standard output.  By default, the output pixel values are of the same data type as
       those of the input file (or type "int" when binning a table), but this can be overridden
       using an optional third argument of the form:

         bitpix=n

       where n is 8,16,32,-32,-64, for unsigned char, short, int, float and double, respectively.

       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 FITS
       primary image.  When an integer image containing the BSCALE and BZERO keywords is
       converted to float, the pixel values are scaled and the scaling keywords are deleted from
       the output header. When converting integer scaled data to integer (possibly of a different
       size), the pixels are not scaled and the scaling keywords are retained.

       If the input data is a binary table or raw event file, these are binned into an image,
       from which a section is extracted and blocked, and written to a primary FITS image.  In
       this case, it is necessary to specify the two columns that will be used in the 2D binning.
       This can be done on the command line using the bincols=(x,y) keyword:

         funcnts "foo.ev[EVENTS,bincols=(detx,dety)]"

       The full form of the bincols= specifier is:

         bincols=([xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]]])

       where the tlmin, tlmax, and binsiz specifiers determine the image binning dimensions:

         dim = (tlmax - tlmin)/binsiz     (floating point data)
         dim = (tlmax - tlmin)/binsiz + 1 (integer data)

       Using this syntax, it is possible to bin any two columns of a binary table at any bin
       size.  Note that the tlmin, tlmax, and binsiz specifiers can be omitted if TLMIN, TLMAX,
       and TDBIN header parameters (respectively) are present in the FITS binary table header for
       the column in question. Note also that if only one parameter is specified, it is assumed
       to be tlmax, and tlmin defaults to 1. If two parameters are specified, they are assumed to
       be tlmin and tlmax.  See Binning FITS Binary Tables and Non-FITS Event Files for more
       information about binning parameters.

       By default, a new 2D FITS image file is created and the image is written to the primary
       HDU.  If the -a (append) switch is specified, the image is appended to an existing FITS
       file as an IMAGE extension.  (If the output file does not exist, the switch is effectively
       ignored and the image is written to the primary HDU.)  This can be useful in a shell
       programming environment when processing multiple FITS images that you want to combine into
       a single final FITS file.

       funimage also can take input from a table containing columns of x, y, and value (e.g., the
       output from fundisp -l which displays each image x and y and the number of counts at that
       position.) When the -l (list) switch is used, the input file is taken to be a FITS or
       ASCII table containing (at least) three columns that specify the x and y image coordinates
       and the value of that image pixel. In this case, funimage requires four extra arguments:
       xcolumn:xdims, ycolumn:ydims, vcolumn and bitpix=n. The x and y col:dim information takes
       the form:

         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

       In particular, the min value should be used whenever the minimum coordinate value is
       something other than one. For example:

         funimage -l foo.lst foo.fits xcol:0:512 ycol:0:512 value bitpix=-32

       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:

         funimage -l stdin foo.fits "":0:512 "":0:512 "" bitpix=-32
         240 250 1
         255 256 2
         ...
         ^D

       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):

         x:I:1:10  y:I:1:10
         ------    ------
         0         0

       This text file defines two columns, x and y, each of data type 32-bit int and image
       dimension 10. The command:

         funimage foo.txt foo.fits bitpix=8

       will create an empty FITS image called foo.fits containing a 10x10 image of unsigned char:

         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

       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.)

       Furthermore, you can use the TEXT filter specification to obviate the need for an input
       text file altogether. The following command will create the same 10x10 char image without
       an actual input file:

         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

       You also can use either of these methods to generate a region mask simply by appending a
       region inside the filter brackets and specfying mask=all along with the bitpix. For
       example, the following command will generate a 10x10 char mask using 3 regions:

         funimage stdin'[TEXT(x:I:10,y:I:10),cir(5,5,4),point(10,1),-cir(5,5,2)]' \
         foo.fits bitpix=8,mask=all < /dev/null

       The resulting mask looks like this:

         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

       You can use funimage to create 1D image projections along the x or y axis using the -p
       [x⎪y] switch. This capability works for both images and tables. For example consider a
       FITS table named ev.fits containing the following rows:

                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

       A corresponding 5x5 image, called dim2.fits, would therefore contain:

                     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

       A projection along the y axis can be performed on either the table or the image:

         funimage -p y ev.fits stdout ⎪ fundisp stdin
                     1          2          3          4          5
            ---------- ---------- ---------- ---------- ----------
         1:          1          2          3          4          5

         funimage -p y dim2.fits stdout ⎪ fundisp stdin
                     1          2          3          4          5
            ---------- ---------- ---------- ---------- ----------
         1:          1          2          3          4          5

       Furthermore, you can create a 1D image projection along any column of a table by using the
       bincols=[column] 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 -p
       y switch:

         funimage ev.fits'[bincols=y]' stdout ⎪ fundisp stdin
                     1          2          3          4          5
            ---------- ---------- ---------- ---------- ----------
         1:          1          2          3          4          5

       Examples:

       Create a FITS image from a FITS binary table:

         [sh] funimage test.ev test.fits

       Display the FITS image generated from a blocked section of FITS binary table:

         [sh]  funimage "test.ev[2:8,3:7,2]" stdout ⎪ fundisp stdin
                           1         2         3
                   --------- --------- ---------
                1:        20        28        36
                2:        28        36        44

SEE ALSO

       See funtools(7) for a list of Funtools help pages