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.

In [1]:
from MontagePy.main import mArchiveExec

help(mArchiveExec)

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

mArchiveExec(...)

Parameters
----------
tblfile : str
Table file list of input images.
path : str, optional
Directory to write retrieved files.
restart : int, optional
timeout : int, optional
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



## 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.

In [4]:
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:

In [5]:
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 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
};