MIMGTBL(1)

💖 MIMGTBL 💖

okay bestie, so you know how Montage is out here doing the absolute most with a whole pile of FITS images? This is the little icon that goes through them and writes down all their metadata so the rest of the squad knows what's up. mImgtbl — Generate metadata from a set of FITS images. it's giving librarian but make it astronomy. 👑

---

✨ SYNOPSIS ✨

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

like that's literally the whole vibe right there. 🫶

---

🌸 DESCRIPTION 🌸

mImgtbl goes through a whole set of files, yoinks the FITS header geometry info out of them, and builds an ASCII image metadata table. several of the other programs are OBSESSED with that table, they literally cannot function without it.

the important caveat though: it only collects data from headers that comply with the FITS standard. if a header is out here being messy and non-compliant, mImgtbl just... doesn't take it. but it IS nice about it and reports a count of the images that failed that check. 💅

---

🎀 OPTIONS 🎀

• -r — bestie, mImgtbl can also do its thing as a standalone program, like if you just want image metadata for other purposes (populating a database, doing spatial coverage searches, whatever you're on). and in those cases you often want info on every single file in a directory tree, not just the top level. the -r (recursive) flag tells mImgtbl to search the directory you gave it and all its subdirectories, recursively. no file left behind. 🧚
• -c — the -c (corners) option adds eight extra columns to the output metadata table containing the RA, Dec coordinates (ra1, dec1, ... ra4, dec4) of the image corners. heads up: the output is always Equatorial J2000, even if the input is some other system. it's not strictly required for the core processing modules, but we recommend using it, because some of the utilities may need corner locations to work properly. so like, just turn it on. 💖
• -C — story time: the original version of mImgtbl ignored cube structure in files entirely. it only looked at the first two dimensions and the associated WCS parameters. then cube processing got added to Montage, and suddenly it was necessary to examine the third and fourth dimensions (if they exist), so some extra columns got added to the mImgtbl output (e.g., NAXIS4, CRVAL3). but it's still super common for all those new columns to be blank, so to save space you can invoke the old mode output with the -C (no-cube) option. it's 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 whose names end in _area (i.e. name_area.fits), assuming they're Montage-created area images. but if you do want info on those images, or if you've got images with _area in the title that weren't generated by Montage, 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 doesn't appear to be valid, along with information on the error. so you actually get receipts. 🧾
• -s statusfile — output and errors get written to statusfile instead of being written to stdout.
• -f fieldlistfile — used to specify a fieldlist, which lists 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 💜

the 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. that's it, that's the whole result. 🎀

---

⭐ 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 🦋

here's the whole group chat of things mImgtbl might say to you. some of these are fine, some are... not. 😭

• 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 🍓

okay so first up, running mImgtbl on a directory containing 14 2MASS images:

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

output: images.tbl.

---

now 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. and the badfits counter in the output message reports on how many images were found containing invalid header information. so like, it's not hiding anything from you. 💅

---

and when you pass it a field list file like this example, extra columns get 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. so like, it's there. it's just... unsupervised. 🫣

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"]. windows line endings really said "not today". 🙈

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

---

and that's the whole thing bestie 🫶 this was Montage 5, from way back in Dec 2016 — iconic then, iconic now. go build your metadata table, you're gonna slay. 💖✨🎀