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

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, mHdr, which creates an image header template from location and size information.

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

help(mHdr)

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

mHdr(...)
    mHdr creates a header template file from location, size, resolution and rotation inputs. In order to support object name lookup for the location string argument, this service must have a network connection available.
    
    Parameters
    ----------
    locstr : str
        A (quoted if necessary) string containing a coordinate or the name of an object on the sky.
    width : float
        Image width in degrees.
    height : float
        Image height in degrees.
    outfile : str
        Output FITS header file.
    csys : str, optional
        Coordinate system string (e.g. 'EquJ', 'Galactic', etc. Fairly forgiving.
    equinox : float, optional
        Coordinate system equinox (e.g. 2000.0).
    resolution : float, optional
        Image pixel resolution (in arcsec).
    rotation : float, optional
        Image rotation on the sky.
    band2MASS : str, optional
        Optional argument when mosaicking 2MASS, adds proper MAGZP value.
    debug : int, optional
        Debugging output level.
    
    
    Returns
    -------
    status : int
        Return status (0: OK, 1:ERROR).
    msg : str
        Return message (for errors).
    count : int
        Number of lines in output file.

mHdr Example:

Much of the Montage processing keys off a FITS header template. Sometimes these headers are extracted from a reference file (mGetHdr). Sometimes they are generated as a bounding box around a catalog of sources or other images (mMakeHdr) and sometimes there are just created manually with an editor.

mHdr can be used to build a simple (TAN projection) header given a location (coordinates or object name) and size.

To use mHdr with object names you must have a working network connection. Name resolution is done via a remote service. Width and height are in degrees and there are overrides for pixel scale (1 arcsecond by default), coordinate system (Equatorial J2000 by default) and rotation.

In [2]:
rtn = mHdr("M17", 1.0, 1.0, 'work/M17/M17.hdr')

print(rtn)

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

The output header looks like this:

In [3]:
with open("work/M17/M17.hdr", "r") as file:
  for line in file:
    print(line, end='')

SIMPLE  = T
BITPIX  = -64
NAXIS   = 2
NAXIS1  = 3601
NAXIS2  = 3600
CTYPE1  = 'RA---TAN'
CTYPE2  = 'DEC--TAN'
CRVAL1  =  275.196290
CRVAL2  =  -16.171530
CRPIX1  = 1801.000000
CRPIX2  = 1800.500000
CDELT1  =   -0.000277778
CDELT2  =    0.000277778
CROTA2  =    0.000000
EQUINOX = 2000.0
END

mHdr Error Handling

If mHdr 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 an unsupported dataset:

In [4]:
rtn = mHdr("dummy object", 1., 1., "output/bad.hdr")

print(rtn)

{'status': '1', 'msg': b"Can't open output file output/bad.hdr"}

 

Classic Montage: mHdr as a Stand-Alone Program

mHdr Unix/Windows Command-line Arguments

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

Usage: mHdr [-c system] [-e equinox] [-h height(deg)] [-p pixsize(arcsec)] [-r rotation] [-t 2mass-band] object|location width(deg) outfile (object/location must be a single argument string)

 

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

/*-***********************************************************************/
/*                                                                       */
/* mHdr -- Create a header template file from location, size, resolution */
/* and rotation inputs. In order to support object name lookup for the   */
/* location string argument, this service must have a network connection */
/* available.                                                            */
/*                                                                       */
/*   char  *locstr         A (quoted if necessary) string containing     */
/*                         a coordinate or the name of an object on      */
/*                         the sky                                       */
/*                                                                       */
/*   double width          Image width in degrees                        */
/*   double height         Image height in degrees                       */
/*                                                                       */
/*   char  *outfile        Output FITS header file                       */
/*                                                                       */
/*   char  *csys           Coordinate system string (e.g. 'EquJ',        */
/*                         'Galactic', etc. Fairly forgiving.            */
/*                                                                       */
/*   double equinox        Coordinate system equinox (e.g. 2000.0)       */
/*   double resolution     Image pixel resolution (in arcsec)            */
/*   double rotation       Image rotation on the sky                     */
/*                                                                       */
/*   char  *band2MASS      Optional argument when mosaicking 2MASS, adds */
/*                         proper MAGZP value                            */
/*                                                                       */
/*   int    debug          Debugging output level                        */
/*                                                                       */
/*************************************************************************/

struct mHdrReturn *mHdr(char *locstr, double width, double height, char *outfile, char *csys, double equinox, 
                        double resolution, double rotation, char *band2MASS, int debug)

Return Structure

struct mHdrReturn
{
   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 lines in output file.
};