Source Files

Release Notes

COL2IMG (Aug94)              ftools.caltools             COL2IMG (Aug94)



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