M

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: mProjExec

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, mProjExec, which is used to reproject a set of images.

Visit Building a Mosaic with Montage to see how mProjExec 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.

In [1]:
from MontagePy.main import mProjExec, mViewer

help(mProjExec)
Help on built-in function mProjExec in module MontagePy.main:

mProjExec(...)
    mProjExec loops over a list of images, reprojecting each of them using mProject, mProjectPP or mProjectQL.
    
    Parameters
    ----------
    path : str
        Path to raw image directory.
    tblfile : str
        Table file list of raw images .
    template : str
        FITS header file used to define the desired output.
    projdir : str, optional
        Path to output projected image directory.
    quickMode : bool, optional
        Flag to force use of mProjectQL function.
    exact : bool, optional
        Flag to force use of mProject over mProjectPP function.  No-op if quickMode is used.
    wholeImages : bool, optional
        Flag to force reprojection of all of each image, even outside template region.
    energyMode : bool, optional
        Pixel values are total energy rather than energy density.
    border : str, optional
        Optional string that contains either a border width or comma-separated 'x1,y1,x2,y2, ...' pairs defining a pixel region polygon where we keep only the data inside.
    scaleCol : str, optional
        Table file can have columns defining scale.
    weightCol : str, optional
        and weighting values to be applied to data and 'area' output files.
    restart : int, optional
        Bulk reprojection sometimes needs to be restarted part way through the list. This is the record in the table to start with.
    stats : str, optional
        The programs keeps statistics on each reprojection in this file.
    debug : int, optional
        Debugging output level.
    
    
    Returns
    -------
    status : int
        Return status (0: OK, 1:ERROR).
    msg : str
        Return message (for errors).
    count : int
        Total number of images.
    failed : int
        Number of reprojections that failed.
    nooverlap : int
        Number of images not overlapping the region of interest.

Example

A mosaic image can contain hundreds or thousands of input image, especially from large uniform surveys like 2MASS or SDSS. Each one must be reprojected to a common frame so mProjExec is a convenience wrapper around the Montage reprojection functions (mProject, mProjectPP, mProjectQL) that simplifies this, looping over an image list an calling the correct function for each one.

Most of the optional arguments to mProjExec are passed-through to the projection function. In its own right the principle arguments are the path to the input image directory, the list of input images (a metadata table), the output image header template, an output directory, and an ouput table for run statistics.

In [2]:
rtn = mProjExec('M17/raw',
                'M17/rimages.tbl', 
                'M17/M17.hdr', 
                'work/M17/projected')

print(rtn)
{'status': '0', 'count': 49, 'failed': 0, 'nooverlap': 0}

The 'count' shows the number of images reprojected; 'failed' the ones that did not work; and 'nooverlap' the number outside the region of interest.

 

Error Handling

If mFitExec 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 specifies a table that doesn't exist:

In [3]:
rtn = mProjExec('M17/raw',
                'M17/unknown.tbl', 
                'M17/region.hdr', 
                'work/M17/projected')

print(rtn)
{'status': '1', 'msg': b'Image metadata file (M17/unknown.tbl) does not exist'}

 

Classic Montage: mProjExec as a Stand-Alone Program

mProjExec Unix/Windows Command-line Arguments

mProjExec can also be run as a command-line tool in Linux, OS X, and Windows:

Usage: mProjExec [-q(uick-mode)][-p rawdir] [-d] [-e(xact)] [-X(whole image)] [-b border] [-r restartrec] [-s statusfile] [-W weightColumn] [-x scaleColumn] images.tbl template.hdr projdir stats.tbl

 

If you are writing in C/C++, mProjExec can be accessed as a library function:

/*-***********************************************************************/
/*                                                                       */
/*  mProjExec                                                            */
/*                                                                       */
/*  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, mProjExec, runs one of the reprojection routines        */
/*  (mProject, mProjectPP or mProjectQL) on a set of images to get them  */
/*  all into a common projection.                                        */
/*                                                                       */
/*   char  *path           Path to raw image directory                   */
/*   char  *tblfile        Table file list of raw images                 */
/*   char  *template       FITS header file used to define the desired   */
/*                         output                                        */
/*                                                                       */
/*   char  *projdir        Path to output projected image directory      */
/*   int    quickMode      Flag to force use of mProjectQL function      */
/*   int    exact          Flag to force use of mProject over mProjectPP */
/*                         function.  No-op if quickMode is used.        */
/*                                                                       */
/*   int    expand         Flag to force reprojection of all of each     */
/*                         image, even outside template region           */
/*                                                                       */
/*   int    energyMode     Pixel values are total energy rather than     */
/*                         energy density.                               */
/*                                                                       */
/*   char  *borderStr      Optional string that contains either a border */
/*                         width or comma-separated 'x1,y1,x2,y2, ...'   */
/*                         pairs defining a pixel region polygon where   */
/*                         we keep only the data inside.                 */
/*                                                                       */
/*   char  *scaleCol       Table file can have columns defining scale    */
/*   char  *weightCol      and weighting values to be applied to data    */
/*                         and 'area' output files.                      */
/*                                                                       */
/*   int    restart        Bulk reprojection sometimes needs to be       */
/*                         restarted part way through the list. This is  */
/*                         the record in the table to start with.        */
/*                                                                       */
/*   char  *stats          The programs keeps statistics on each         */
/*                         reprojection in this file.                    */
/*                                                                       */
/*   int    debug          Debugging output level                        */
/*                                                                       */
/*************************************************************************/

struct mProjExecReturn *mProjExec(char *path, char *tblfile, char *template, char *projdir, int quickMode,
                                  int exact, int expand, int energyMode, char *borderStr, char *scaleCol,
                                  char *weightCol, int restart, char *stats, int debugin)

Return Structure

struct mProjExecReturn
{
   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 reprojected
   int    failed;        // Number of reprojections that failed
   int    nooverlap;     // number of images that do not overlap the area of interest
};