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

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 module, mArchiveGet, which retrieves a single archive image.

Visit Building a Mosaic with Montage to see how mArchiveGet is used as part of a workflow to create 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 mArchiveGet, mViewer

help(mArchiveGet)

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

mArchiveGet(...)
    mArchiveGet retrieves an image file by URL from one of several archives.
    
    Parameters
    ----------
    url : str
        Directory containing files to be coadded.
    datafile : str
        Table file list of reprojected files to coadded.
    timeout : int, optional
        Timeout in seconds.
    debug : int, optional
        Debugging output level.
    
    
    Returns
    -------
    status : int
        Return status (0: OK, 1:ERROR).
    msg : str
        Return message (for errors).
    count : int
        Size of file in bytes.

mArchiveGet Example

mArchiveGet can be used stand-alone but is really just meant for use by mArchiveExec when retreiving a list of images. Stand-alone it has no advantage over tools like wget and curl. The two main arguments are the URL to retreive and the local file to write it to:

rtn = mArchiveGet('http://irsa.ipac.caltech.edu/ibe/data/twomass/full/full/990502s/s134/image/ji1340186.fits.gz', 
                  'work/M17/raw/2mass-atlas-990502s-j1340186.fits')

print(rtn)

{'status': '0', 'count': 1633635}

Montage modules return JSON structures. They always include a status (0: success; 1: error) and a variable number of informational parameters. Here the returned file had 1633635 bytes.

Returned Data

To verify the download, we can take a look at the image:

from IPython.display import Image

rtn = mViewer("-ct 1 -gray work/M17/raw/2mass-atlas-990502s-j1340186.fits \
               -2s max gaussian-log -out work/M17/2mass-atlas-990502s-j1340186.png",
              "", mode=2)

Image(filename='work/M17/2mass-atlas-990502s-j1340186.png')

mArchiveGet Error Handling

If mArchiveGet 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 URL that doesn't exist:

rtn = mArchiveGet('http://unknown.edu/image/ji1340186.fits.gz', 
                  'work/M17/raw/2mass-atlas-990502s-j1340186.fits')

print(rtn)

{'status': '1', 'msg': b'Unable to resolve URL.'}

 

Classic Montage: mArchiveGet as a Stand-Alone Program

Unix/Windows Command-line Arguments

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

Usage: mArchiveGet [-d][-t timeout] remoteref localfile

 

mArchiveGet as a Library Call

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

/*-*****************************************************************************/
/*                                                                             */
/* Unfortunately, simple URL access to some archive data has become more       */
/* complex.  It used to be that most data was available via a simple socket    */
/* connection to an HTTP server.  Now many sites use secure sockets (even      */
/* when they don't need to), redirection (often because of the secure sockets) */
/* and so on.                                                                  */
/*                                                                             */
/* We don't want to recreate all the infrastructure in programs like wget      */
/* and curl that deals with all this, so we have opted for using utilities     */
/* like wget or curl.                                                          */
/*                                                                             */
/* Since one or the other of these are default on almost all Linux and OSX     */
/* platforms (though neither is there by default on both platforms), we have   */
/* opted to do the following: First try a fork/exec of wget and parse the      */
/* output string (limited by the -nv flag to be minimal information).  If      */
/* this fails, try the same with curl (limiting the output string here as      */
/* well to just the output file size).  An added twist is that wget sends      */
/* its output to stderr and curl to stdout but we can take care of this        */
/* by being specific about which stream is redirected back to the parent       */
/* process.                                                                    */
/*                                                                             */
/*******************************************************************************/

struct mArchiveGetReturn *mArchiveGet(char *url, char *datafile, int timeout, int debug)

Return Structure

struct mArchiveGetReturn
{
   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;         // Size of the file in bytes
};