Montage Montage is an astronomical image toolkit with components for reprojection, background matching, coaddition and visualization of FITS files. It can be used as a set of command-line tools (Linux, OS X and Windows), C library calls (Linux and OS X) and as Python binary extension modules.
The Montage source is written in ANSI-C and code can be downloaded from GitHub ( https://github.com/Caltech-IPAC/Montage ). The Python package can be installed from PyPI ("</i>pip install MontagePy"). The package has no external dependencies. See http://montage.ipac.caltech.edu/ for details on the design and applications of Montage.
MontagePy.main modules: mImgtbl¶
The Montage modules are generally used as steps in a workflow to create a mosaic of a set of input images. These steps are: determine the geometry of the mosaic on the sky, reproject the images to a common frame and spatial sampling; rectify the backgrounds to a common level, and coadd the images into a mosaic. This page illustrates the use of one Montage module, mImgtbl, which is used to generate an image metadata summary for a set of images.
Visit Building a Mosaic with Montage to see how mImgtbl is used as part of a workflow to creage a mosaic (or the one shot version if you just want to see the commands). See the complete list of Montage Notebooks here.
from MontagePy.main import mImgtbl
help(mImgtbl)
mImgtbl Example¶
mImgtbl scans the input directory (optionally recursively) looking for FITS files with proper world coordinate system (WCS) parameters in the header. For multi-part files, each HDU is scanned separately. The results are written to the output table. These tables are of general utility (e.g., for constructing searchable archive metadata database tables), but their primary purpose in this mosaicking scenario is as lists of images to process and coverage information to determine image overlaps.
The following call generates a metadata table for a set of 2MASS J-band images near M17 a retreived by mArchiveList/mArchiveExec:
rtn = mImgtbl('M17/raw', 'work/M17/rimages.tbl')
print(rtn)
Montage modules return JSON structures. They always include a status (0: success; 1: error) and a variable number of informational parameters. Here the list contains 85 images.
Archive List Data¶
The returned table is in IPAC ASCII format, the default for Montage. You can read it into a Pandas dataframe with AstroPy. Here we extract the local file name and the center coordinates.
import os
import numpy as np
import pandas as pd
from astropy.io import ascii
ipactable = ascii.read('work/M17/rimages.tbl').to_pandas()
ipactable
Error Handling¶
If mImgtbl encounters an error, the return structure will just have two elements: a status of 1 ("error") and a message string that tries to diagnose the reason for the error.
For instance, if the user asks for a non-existent directory:
rtn = mImgtbl('M17/unknown', 'work/M17/rimages.tbl')
print(rtn)
Classic Montage: mImgtbl as a Stand-Alone Program¶
mImgtbl Unix/Windows Command-line Arguments¶
mImgtbl can also be run as a command-line tool in Linux, OS X, and Windows:
Usage: mImgtbl [-rcCaidbd][-s statusfile][-f fieldlistfile][-t imglist] directory images.tbl
If you are writing in C/C++, mImgtbl can be accessed as a library function:
/*-***********************************************************************/
/* */
/* mImgtbl */
/* */
/* Montage is a set of general reprojection / coordinate-transform / */
/* mosaicking programs. Any number of input images can be merged into */
/* an output FITS file. The attributes of the input are read from the */
/* input files; the attributes of the output are read a combination of */
/* the command line and a FITS header template file. */
/* */
/* This module, mImgtbl, makes a list (with WCS information) of all */
/* FITS image files in the named directory (and optionally recursively) */
/* */
/* mImgtbl supports a lot of variation in input (and a little in */
/* output) so there are lot of parameters on the call, most of which */
/* can be "defaulted" (i.e. set to zero / NULL). The full parameter */
/* list is: */
/* */
/* char *pathname Directory (or top of tree) for image file */
/* search (default to current directory). */
/* char *tblname Output table file name (no default). */
/* */
/* int recursiveMode Search for images recursively (default just */
/* top directory). */
/* int processAreaFiles Include "area" files in the list (not */
/* normally advisable). */
/* int haveCubes False if we know we don't have datacubes */
/* (fewer table columns) */
/* int noGZIP mImgtbl normally includes analysis of */
/* .fits.gz files. This turns that off. */
/* int showCorners Include ra1,dec1, ... dec4 image corner */
/* columns in output. */
/* int showinfo For HDUs that are are rejected, emit an */
/* INFO message. Best used in application */
/* mode or when debugging. */
/* int showbad Show running "INFO" messages for FITS files */
/* that cannot be opened by CFITSIO. */
/* */
/* char *imgListFile Rather than searching through directories, */
/* get the list of images from a table file. */
/* char *fieldListFile List of FITS keywords to include in output */
/* table (in addition to the standard WCS info. */
/* */
/* int debug Turn on debugging output (not for general */
/* use). */
/* */
/*************************************************************************/
struct mImgtblReturn *mImgtbl(char *pathnamein, char *tblname,
int recursiveModein, int processAreaFilesin, int haveCubes, int noGZIPin,
int showCornersin, int showinfo, int showbadin, char *imgListFile, char *fieldListFile,
int debugin)
Return Structure
struct mImgtblReturn
{
int status; // Return status (0: OK, 1:ERROR)
char msg [1024]; // Return message (for error return)
char json[4096]; // Return parameters as JSON string
int count; // Number of images found with valid headers (may be more than one per file).
int nfile; // Number of FITS files found.
int nhdu; // Total number of HDSs in all files.
int badfits; // Number of bad FITS files.
int badwcs; // Number of images rejected because of bad WCS information.
};