mImgtbl(1)
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.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
