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: mAddCube¶
Most of Montage is focused on 2D astronomical image mosaics: reprojection, background matching, coaddition and so on. But there is also a need for tools that operate on data "cubes": three- or four-dimensional arrays where two of the axes represent the same projected sky coordinates as we find in the 2D images. Usually, the third axis is some form of wavelength.
The problem sets are not completely parallel: datacubes do not generally need background matching but you do frequently want cutouts in the none spatial dimensions and to transpose axes.
Montage includes a set of routines for manipulating datacubes:
- mmProjectCube — Reproject the spatial dimensions.
- mAddCube — Reproject the cube.
- mShrinkCube — Rescale a cube (integer scaling in the non-spatial dimensions).
- mSubCube —Cut a portion out of a cube.
- mTranspose — Transpose a cube's axes.
This routine, mAddCube, coadds a set of reprojected datacubes. It is essentially a multi-dimensional analog to the routine mAdd and uses the same fractional pixel weighting logic (area coverage files primarily generated by the reprojection code).
Note: The MontagePy python package has no external dependencies. We include other utilities on this page to aid in visualizing MontagePy package results.
from MontagePy.main import mAddCube, mViewer
help(mAddCube)
mAddCube Example¶
mAddCube is the tail end of the datacube mosaicking process. At this point we have a set of reprojected cubes and have generated a metadata table listing them all. The last step is to coadd them, properly weighting things like fractional pixels, to produce the final mosaic.
The basic inputs are the datacubes themselves (the path to them and the table of metadata), the header template for the output (which by now should match, except for integer pixel offsets, the headers in each cube), and the name of the desired output datacube file.
mAdd has a few extra controls that can be used to tell it whether to "shrink-wrap" the mosaic (remove empty border pixel areas) and whether the input images have associated "area" images (for proper weighting of fractional pixel coaddition). In addition, the user has the option of overriding the default coaddition mode (mean) and instead return the median or just the count of the input pixels.
See previous steps in the process for details on the header template.
Datacubes are inherently substantially bigger than 2D images, so even our test example here will take 4-5 minutes to process. Be patient.
rtn = mAddCube('GALFA/projected',
'GALFA/pimages.tbl',
'GALFA/galfa.hdr',
'work/GALFA/GALFAmosaic.fits')
print(rtn)
Here is a one of the input images (or more exactly a few wavelengths from one of the images averaged):
from IPython.display import Image
mViewer('-ct 0 -gray "GALFA/shrunken/GALFA_HI_RA+DEC_004.00+26.35_N.fits[0][60:64]" \
-2s max gaussian-log -out work/GALFA/GALFA_HI_RA+DEC_004.00+26.35_N.png',
'', mode=2)
Image(filename='work/GALFA/GALFA_HI_RA+DEC_004.00+26.35_N.png')
And here is the complete mosaic (same wavelengths and with an overlay of the original image outlines):
mViewer('-color yellow -imginfo GALFA/simages.tbl \
-ct 0 -gray "work/GALFA/GALFAmosaic.fits[0][60:64]" \
-2s max gaussian-log -out work/GALFA/GALFAmosaic.png',
'', mode=2 )
Image(filename='work/GALFA/GALFAmosaic.png')
mAddCube Error Handling¶
If mAddCube 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 table that does not exist:
rtn = mAddCube('GALFA/projected',
'GALFA/unknown.tbl',
'GALFA/galfa.hdr',
'work/GALFA/GALFAmosaic.fits')
print(rtn)
Classic Montage: mAddCube as a Stand-Alone Program¶
mAddCube Unix/Windows Command-line Arguments¶
mAddCube can also be run as a command-line tool in Linux, OS X, and Windows:
Usage: mAddCube [-p imgdir] [-n(o-areas)] [-a mean|median|count] [-e(xact-size)] [-d level] [-s statusfile] images.tbl template.hdr out.fits
If you are writing in C/C++, mAddCube can be accessed as a library function:
/*-***********************************************************************/
/* */
/* mAddCube */
/* */
/* 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, mCubeAdd, reads sets of flux / area coverage datacubes */
/* (the output of mCubeProj) which have already been projected / */
/* resampled onto the same pixel space. The fluxs, scaled by total */
/* input area, are then coadded into a single output composite. */
/* */
/* char *path Directory containing files to be coadded */
/* char *tblfile Table file list of reprojected files to */
/* coadd */
/* char *template_file FITS header file used to define the desired */
/* output */
/* char *outfile Final mosaic FITS file */
/* */
/* int shrink Shrink-wrap to remove blank border areas */
/* int haveAreas Area files exist for weighting the coadd */
/* int coadd Image stacking: 0 (MEAN), 1 (MEDIAN) */
/* 2 (COUNT) */
/* */
/* int debug Debugging output level */
/* */
/*************************************************************************/
struct mAddCubeReturn *mAddCube(char *path, char *tblfile, char *template_file, char *outfile,
int shrink, int haveAreas, int coadd, int debugin)
Return Structure
struct mAddCubeReturn
{
int status; // Return status (0: OK, 1:ERROR)
char msg [1024]; // Return message (for error return)
char json[4096]; // Return parameters as JSON string
double time; // Run time (sec)
};