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 ("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: mArchiveExec

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, mAdd, which automates the process of retrieving a list of archive images.

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

help(mArchiveExec)

Help on built-in function mArchiveExec in module MontagePy.main:

mArchiveExec(...)
    mArchiveExec loops over a list of images (with URLs), downloading them all.
    
    Parameters
    ----------
    tblfile : str
        Table file list of input images.
    path : str, optional
        Directory to write retrieved files.
    restart : int, optional
        Restart record, if download interupted.
    timeout : int, optional
        Download timeout (sec) per image.
    debug : int, optional
        Debugging output flag.
    
    
    Returns
    -------
    status : int
        Return status (0: OK, 1:ERROR).
    msg : str
        Return message (for errors).
    count : int
        Total number of images.
    failed : int
        Count where download failed.

mArchiveExec Example

mArchiveExec reads through the list of images returned by mArchiveList and uses mArchiveGet to retreive each one. One of the arguments is the output directory and it is up to the user to make sure it exists before calling the function.

rtn = mArchiveExec('M17/remote.tbl', 'work/M17/raw')

print(rtn)

{'status': '0', 'count': 49, 'failed': 0}

Montage functions return JSON structures. They always include a status (0: success; 1: error) and a variable number of informational parameters. Here 36 images were asked for and none of them failed.

mArchiveExec Error Handling

If mArchiveExec 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 inputs a table that is not an archive list:

rtn = mArchiveExec('M17/unknown.tbl', 'work/M17/raw')

print(rtn)

{'status': '1', 'msg': b"Table M17/unknown.tbl needs column 'URL' or 'url' and can optionally have columns 'fname'/'file' and pixel ranges 'imin'..'jmax'"}

 

Classic Montage: mArchiveExec as a Stand-Alone Program

mArchiveExec Unix/Windows Command-line Arguments

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

Usage: mArchiveExec [-d level][-p outputdir][-r startrec][-t timeout] region.tbl

 

mArchiveExec as a Library Call

If you are writing in C/C++ on Linux or OSX, mArchiveExec can be accessed as a library function:

/*-*****************************************************************/
/*                                                                 */
/*  mArchiveExec                                                   */
/*                                                                 */
/*  Reads a listing archive images and calls mArchiveGet to get    */
/*  each one.                                                      */
/*                                                                 */
/*   char *tblfile     Table file list of images to get.           */
/*                                                                 */
/*   char *path        Directory to write retrieved files.         */
/*   int nrestart      Restart record, if download interupted.     */
/*   int timeout       Download timeout (sec) per image.           */
/*   int debug         Debug flag.                                 */
/*                                                                 */
/*******************************************************************/

struct mArchiveExecReturn *mArchiveExec(char *tblfile, int nrestart, int timeout, int debug)

Return Structure

struct mArchiveExecReturn
{
   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 retrieved
   int    failed;        // Number of retrievals that failed
};