NAME

col2img -- converts a collimator response dataset to an image (for display/diagnostic purposes only)

USAGE

col2img infil[ext#] outfil

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

SUPPORTED FITS FILE FORMATS

   Currently only the following OGIP standards are supported by this task

for the input file:

For the OBSFACTOR extension:

HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0'

HDUCLAS2/HDUVERS2= 'OBSFACTOR'/'1.1.0'

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

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

PARAMETERS

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.

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.

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

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.

xmin [real]

The minimum value of the first spatial coordinate required in the output image (only required when remap=yes)

xmax [real]

The maximum value of the first spatial coordinate required in the output image (only required when remap=yes)

nxbins [integer]

The number of bins required in the output image for the first spatial coordinate (only required when remap=yes).

ymin [real]

The minimum value of the second spatial coordinate required in the output image (only required when remap=yes)

ymax [real]

The maximum value of the second spatial coordinate required in the output image (only required when remap=yes)

nybins [integer]

The number of bins required in the output image for the second spatial coordinate (only required when remap=yes).

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

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

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

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

BUGS

None known

SEE ALSO

CAL/GEN/92-022

LOG OF SIGNIFICANT CHANGES

v2.1.1 (1994 Dec)

Public release version

v1.0.0 (1994 Jul)

Beta-test version (for the XTE PCA team)

PRIMARY AUTHOR

Ian M George

HEASARC

NASA/GFSC

http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp

(301) 286-6094

CATEGORY