Provided by: montage_6.0+dfsg-7build8_amd64 bug

NAME

       mImgtbl - Generate metadata from a set of FITS images

SYNOPSIS

       mImgtbl [-rcadb] [-s statusfile] [-f fieldlistfile] [-t imglist] directory images.tbl

DESCRIPTION

       mImgtbl  extracts  the FITS header geometry information from a set of files and creates an
       ASCII image metadata table which is used by  several  of  the  other  programs.   It  only
       collects  data  from  headers  that  comply with the FITS standard, but reports a count of
       images that fail that check.

OPTIONS

       -r     mImgtbl can also be used as a standalone program to gather image metadata for other
              purposes  (to  populate a database, as a basis for spatial coverage searches, etc.)
              In this case it is often desirable to collect information on all  the  files  in  a
              directory  tree recursively.  The "-r" (recursive) flag instructs mImgtbl to search
              the given directory and all its subdirectories recursively.

       -c     The "-c" (corners) option in mImgtbl will cause eight extra columns to be added  to
              the  output  metadata table containing the RA, Dec coordinates (ra1, dec1, ... ra4,
              dec4) of the image corners.  The output is always Equatorial  J2000,  even  if  the
              input is some other system.  Though not required for the core proessing modules, we
              recommend using this option, as some of the utilities may require corner  locations
              to function properly.

       -C     The original version of mImgtbl ignored cube structure in the files; it only looked
              at the first two dimensions and associated WCS parameters.   When  cube  processing
              was  added  to Montage, it was necessary to examine the third and fourth dimensions
              (if they exist) and so some additional columns were added  to  the  mImgtbl  output
              (e.g.,  NAXIS4,  CRVAL3).   It is still often the case where all of the new columns
              would be blank, so to save space the old mode output can be invoked using the  "-C"
              (no-cube) option.  This is cosmetic for the most part, since the "four-dimensional"
              output is perfectly valid for further processing of 2D data.

       -a     By  default,  mImgtbl  ignores  FITS  files  with  names  ending  in  _area   (i.e.
              name_area.fits),  assuming  them to be Montage-created area images.  If you want to
              generate information on these images, or if you have images with _area in the title
              other  than  those  generated  by  Montage,  you  should turn on this flag to force
              mImgtbl to look at all images in the directory.

       -d     Turn on debugging

       -b     When this switch is set, mImgtbl will explicitly output each  FITS  file  it  finds
              that does not appear to be valid, along with information on the error.

       -s statusfile
              Output and errors are written to statusfile instead of being written to stdout.

       -f fieldlistfile
              Used  to  specify  a fieldlist, which will list additional keywords to be read from
              the FITS headers and included in the output table.  Fieldlists should  specify  the
              keyword name, type (int,char,double), and size. Example: example.fieldlist.

       -t imglist
              mImgtbl will only process files with names specified in table imglist, ignoring any
              other files in the directory. Example: example.imglist.

ARGUMENTS

       directory
              Path to directory containing set of input FITS files.

       images.tbl
              Path of output metadata table.

RESULT

       Output table contains metadata information from all readable FITS files in  the  directory
       specified  by  directory.  count is the number of records in the table, and badfits is the
       number of files for which FITS metadata could not be extracted.

OUTPUT COLUMNS

       cntr   A unique counter (row number)

       ra,dec Image position in decimal degree format

       cra,cdec
              Right ascension in HHMMSS.SS format. Declination in DDMMSS.S format

       naxis1, naxis2
              The size of the image in pixels for dimensions 1 and 2

       ctype1, ctype2
              The coordinate system (the first four characters)  and  WCS  map  projection  (last
              three characters) for dimensions 1 and 2

       crpix1, crpix2
              The  pixel  coordinates of the reference location (can be fractional and can be off
              the image) for dimensions 1 and 2

       crval1, crval2
              The coordinates of a reference location on the sky (often  at  the  center  of  the
              image) for dimensions 1 and 2

       cdelt1, cdelt2
              The  pixel  scale  (in  degrees on the sky per pixel) at the reference location for
              dimensions 1 and 2

       crota2 The rotation angle from the "up" direction to the celestial pole

       equinox
              Precessional year associated with the coordinate system

       hdu    Numerical identifier for the FITS extension that the image info is extracted  from,
              for FITS files with multiple HDUs.

       size   Filesize (in bytes) of the input FITS file

       fname  The path to the input FITS file

MESSAGES

       OK     [struct stat="OK", count=count, badfits=badfits]

       ERROR  Illegal argument: -arg

       ERROR  Cannot open status file: statusfile

       ERROR  Cannot open field list file: fieldlistfile

       ERROR  Cannot open image list file: imgfile

       ERROR  Image table needs column fname/file

       ERROR  Illegal field name: string]

       ERROR  Illegal field type: string]

       ERROR  Cannot access directory

       ERROR  directory is not a directory

       ERROR  Can't open output table.

       ERROR  Can't open copy table.

       ERROR  Can't open tmp (in) table.

       ERROR  Can't open tmp (out) table.

       ERROR  Can't open final table.

       ERROR  FITS library error

EXAMPLES

       The following example runs mImgtbl on a directory containing 14 2MASS images:

       $ mImgtbl input/2mass images.tbl
              [struct stat="OK", count=14, badfits=0]

       Output: images.tbl.

       Running mImgtbl on a directory that contains 3 bad FITS images, with the -c switch on:

       $ mImgtbl -c input/2mass-bad images-corners.tbl
              [struct stat="OK", count=14, badfits=3]

       The  output  file  is identical to the first example, but with the addition of 8 "corners"
       columns: images-corners.tbl.  The badfits counter in the output  message  reports  on  how
       many images were found containing invalid header information.

       When passed a field list file like this example, extra columns are extracted from the FITS
       headers and inserted in the table:

       $ mImgtbl -f example.fieldlist input/2mass images-expanded.tbl
              [struct stat="OK", count=14, badfits=0]

       The output file has additional columns as specified: images-expanded.tbl.

BUGS

       The drizzle algorithm has been implemented but has not been tested in this release.

       If a header template contains  carriage  returns  (i.e.,  created/modified  on  a  Windows
       machine),  the cfitsio library will be unable to read it properly, resulting in the error:
       [struct stat="ERROR", status=207, msg="illegal character in keyword"]

       It is best for the background correction algorithms if the area described  in  the  header
       template  completely encloses all of the input images in their entirety. If parts of input
       images are "chopped off" by  the  header  template,  the  background  correction  will  be
       affected.  We  recommend  you  use  an expanded header for the reprojection and background
       modeling steps, returning to the originally desired header size for the final  coaddition.
       The default background matching assumes that there are no non-linear background variations
       in the individual images (and therefore in the  overlap  differences).  If  there  is  any
       uncertainty  in  this  regard, it is safer to turn on the "level only" background matching
       (the "-l" flag in mBgModel.

       We recommend use of the "-c" option when running mImgtbl to include the locations  of  the
       four  corners  of  each image in the output metadata table. Some other modules may require
       the corner locations to function correctly.

COPYRIGHT

       2001-2015 California Institute of Technology, Pasadena, California

       If your research  uses  Montage,  please  include  the  following  acknowledgement:  "This
       research  made use of Montage. It is funded by the National Science Foundation under Grant
       Number ACI-1440620, and was previously  funded  by  the  National  Aeronautics  and  Space
       Administration's  Earth Science Technology Office, Computation Technologies Project, under
       Cooperative Agreement Number  NCC5-626  between  NASA  and  the  California  Institute  of
       Technology."

       The  Montage  distribution  includes an adaptation of the MOPEX algorithm developed at the
       Spitzer Science Center.