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: mTANHdr¶
mTANHdr is a special utility that extends the range of the mProjectPP reprojection module. mProjectPP is much faster than the more general mProject but is limited to tangent-plane projections (e.g., TAN, SIN). It does, however, support focal-plane distortion parameters (e.g., TAN-SIP) so there is a trick we can use that lets is work with a range of other projections.
Many images we deal with in astronomy cover a fairly small area on the sky and in those areas it is often the case that many projections (e.g., cylindrical CAR) can be matched with a distorted TAN to very small fractions of a pixel and the extra time taken in fitting for the distortion parameter values is more that made up for by the speed-up in using mProjectPP for the reprojection.
from MontagePy.main import mTANHdr, mViewer
help(mTANHdr)
Example¶
One of the products in these examples is a mosaic of a one-degree square area around M17. This is normally done in TAN (gnomonic) projection but we can also so it in the simple cylindrical CAR projection, then reproject this mosaic to TAN either with mProject or with mProjectPP using a distorted TAN header made by mTANHdr:
rtn = mTANHdr("M17/mosaic_car.hdr", "work/M17/distorted.hdr")
print(rtn)
The error values in the return show the worst-case positional difference between the distorted TAN and original CAR projections, in pixels. In this case, since the pixels are 1 arcsecond, the maximum positional difference is around 10 milli-arcseconds.
Reprojecting the CAR image with mProject takes about 280 seconds. Using mProjectPP and this distorted TAN header takes only 12 seconds; a factor of 23 faster.
Here is the distorted TAN header that mTANHdr produced:
with open("work/M17/distorted.hdr", "r") as file:
for line in file:
print(line, end='')
Error Handling¶
If mTANHdr 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 specifies a header file that doesn't exist:
rtn = mTANHdr("input/M17/unknown.hdr", "work/M17/distorted.hdr")
print(rtn)
/*-***********************************************************************/
/* */
/* mTANHdr */
/* */
/* 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. */
/* */
/* There are two main reprojection modules, mProject and mProjectPP. */
/* The first can handle any projection transformation but is slow. The */
/* second can only handle transforms between tangent plane projections */
/* but is very fast. In many cases, however, a non-tangent-plane */
/* projection can be approximated by a TAN projection with pixel-space */
/* distortions (in particular when the region covered is small, which */
/* is often the case in practice). */
/* */
/* This module analyzes a template file and determines if there is */
/* an adequate equivalent distorted TAN projection that would be */
/* equivelent (i.e. location shifts less than, say, 0.01 pixels). */
/* mProjectPP can then be used to produce this distorted TAN image */
/* with the original non-TAN FITS header swapped in before writing */
/* to disk. */
/* */
/* */
/* NOTE: The 'reverse' error is the important one for deciding whether */
/* the new distorted-TAN header can be used in place of the original */
/* when reprojecting in mProjectPP since it is a measure of the */
/* process of going from distorted TAN to sky to original projection. */
/* Since the second part of this is exact, this error is all about how */
/* accurately the distorted-TAN maps to the right point of the sky. */
/* */
/* char *origtmpl Original image file FITS header */
/* char *newtmpl Output matching distorted-TAN header */
/* int order Polynomial order for distortions */
/* int maxiter Maximum number of iterations for fitting */
/* int tolerance Tolerance (maximum error) for fit */
/* int useOffscl Include in the fitting pixels that are */
/* just off the image */
/* */
/* int debug Debugging output flag */
/* */
/*************************************************************************/
struct mTANHdrReturn *mTANHdr(char *origtmpl, char *newtmpl, int order, int maxiter, double tolerance,
int useOffscl, int debugin)
Return Structure
struct mTANHdrReturn
{
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 fwdxerr; // Maximum error in X for forward transformation
double fwdyerr; // Maximum error in Y for forward transformation
double fwditer; // Number of iterations needed in forward transformation
double revxerr; // Maximum error in X for reverse transformation
double revyerr; // Maximum error in Y for reverse transformation
double reviter; // Number of iterations needed in reverse transformation
};