.help col2img Aug94 ftools.caltools 
.ih
NAME
col2img -- converts a collimator response dataset to an image (for 
display/diagnostic purposes only)
.ih
USAGE
col2img infil[ext#] outfil
.ih
DESCRIPTION

  In general, the collimator response of a collimated instrument is a 
function of spatial position and energy (where the latter arises due 
to photon scattering and/or transmission by the collimator). As a 
result, in the general case the OGIP format for such datasets consists 
of a single-row BINTABLE extension with a column containing the
3-dimensional (X,Y,E) array of collimator responses, along with 
other columns giving the spatial and energy grids used. Further 
information on the detailed format can be found in OGIP Calibration 
Memos CAL/GEN/92-022.

  This task is primarily for diagnostic/visualization purposes. The task reads
a 3-D (X,Y,E) collimator response dataset, compresses the energy dimension
(optionally over a user-defined energy range), to produce an output file
containing an (X vs Y) image in the Primary Array (optionally rebinned/remapped 
by user-defined factors).


.ih
SUPPORTED FITS FILE FORMATS

   Currently only the following OGIP standards are supported by this task
for the input file:
.ls For the OBSFACTOR extension:
.ls HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0'
.le
.ls HDUCLAS2/HDUVERS2= 'OBSFACTOR'/'1.1.0'
.le
.le

For further details see OGIP Calibration Memo CAL/GEN/92-022.

.ih
WARNINGS ON USAGE

  In order to handle the biggest arrays this task employs a number of
relatively large internal arrays. These arrays are dynamically allocated,
but problems can arise at execution if the local machine runs out of swap
space. When this occurs, often an appropriate system error message will be
displayed or the program may simply crash. Under these circumstances users
will have to free up space by closing unwanted applications (windows,
tasks etc). Under unix/ultrix, the total used/available swap space on the
local machine can be listed (in kbytes) using the command 'pstat -T'.

.ih
PARAMETERS
.ls infil [character string]
 The name of the FITS file containing the i/p collimator response
 (and extension number in square brackets). If no extension 
 number is specified, or an asterisk is supplied for the extension number, 
 then all extensions in the FITS file will first be searched for an extension 
 containing an OBSFACTOR dataset. If one (and only one) is found, then 
 that will be used, otherwise the task will search all the extensions
 for a COLLRESP dataset, using it if one (and only one) is found.
.le
.ls outfil [character string]
 The name of the o/p file to be written containing the derived image.
 For safety, the name of the o/p file CANNOT be the same as the i/p files.
 Under unix/ultrix, an o/p filename identical to a file which already exists  
 in the local area is also considered illegal, and the task will stop. However, 
 the existing file can be removed automatically, and the new file written if 
 the o/p filename is preceeded by "!" at the outfil prompt.
.le 
.ls (remap = no) [boolean]
 Whether the stored values of the collimator response are to be remapped
 onto a new, linear spatial coordinate grid for the production of the 
 image. If remap = yes, then a simple bi-linear interpolation scheme 
 is used to calculate the collimator response values at the new spatial 
 coordinates from the old values. Such a facility is useful to avoid 
 misleading distortions if the grid used to stored the datset is non-linear 
 (eg has a higher spatial resolution close to 'on-axis' than far off-axis) 
 and/or if the user wishes to zoom in/out of a given location.
.le 
.ls extrap = no [boolean]
 Whether the stored values of the collimator response are to be EXTRAPOLATED 
 to calculate values of the collimator response OUTSIDE the stored spatial 
 coordinate grid (only required when remap=yes). This facility should be 
 used with care.
.le 
.ls xmin [real]
 The minimum value of the first spatial coordinate required in the 
 output image (only required when remap=yes)
.le 
.ls xmax [real]
 The maximum value of the first spatial coordinate required in the 
 output image (only required when remap=yes)
.le 
.ls nxbins [integer]
 The number of bins required in the output image for the first 
 spatial coordinate (only required when remap=yes).
.le 
.ls ymin [real]
 The minimum value of the second spatial coordinate required in the 
 output image (only required when remap=yes)
.le 
.ls ymax [real]
 The maximum value of the second spatial coordinate required in the 
 output image (only required when remap=yes)
.le 
.ls nybins [integer]
 The number of bins required in the output image for the second  
 spatial coordinate (only required when remap=yes).
.le
.ls (emin=%) [pseudo-real]
 Lower energy discriminator (in keV) used to produce image from a COLLRESP 
 dataset. The default value ("%") indicates that the lowest energy of the
 i/p dataset is to be used (ie no low-energy cut will be made). This 
 parameter has no effect of the i/p dataset is a OBSFACTOR (and hence 
 independent of energy).
.le
.ls (emax=%) [pseudo-real]
 Upper energy discriminator (in keV) used to produce image from a COLLRESP 
 dataset. The default value ("%") indicates that the highest energy of the
 i/p dataset is to be used (ie no high-energy cut will be made). This 
 parameter has no effect of the i/p dataset is a OBSFACTOR (and hence 
 independent of energy).
.le
.ls (chatter = 9) [integer]
 Flag to indicate how chatty the task is at execution. A value of 9 is the
 default, with lower/higher values producing quieter/verbose output 
 respectively.
.le
.ls (clobber = false) [boolean]
 Flag specifying whether or not a pre-existing file with the same name as that 
 requested as the output file from this task will be overwritten.
.le

.ih
BUGS
None known

.ih
SEE ALSO
.br
.nj
CAL/GEN/92-022 
.ju

.ih
LOG OF SIGNIFICANT CHANGES

.ls v2.1.1 (1994 Dec)
    Public release version
.le
.ls v1.0.0 (1994 Jul)
    Beta-test version (for the XTE PCA team)
.le

.ih
PRIMARY AUTHOR

.nj
Ian M George
.br
.nj
HEASARC
.br
.nj
NASA/GFSC
.br
.nj
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
.br
.nj
(301) 286-6094
.ju


.endhelp
