Python Montage wrapper (montage_wrapper
)¶
Introduction¶
This Astropy-affiliated package provides a python wrapper to the Montage Astronomical Image Mosaic Engine, including both functions to access individual Montage commands, and high-level functions to facilitate mosaicking and re-projecting.
Installation¶
This package is a wrapper, not a replacement, for the IPAC Montage mosaicking software. Therefore, Montage will need to be downloaded from http://montage.ipac.caltech.edu. Once you have downloaded the latest release on Montage from that website, the installation should look like:
tar xvzf Montage_v3.3.tar.gz
cd Montage_v3.3
make
then move the Montage_v3.3
directory to wherever you would like to keep
the installation, and add <installation_dir>/Montage_v3.3/bin
to your
$PATH
, where <installation_dir>
is the directory inside which you put
Montage_v3.3
(Montage does not support make install
). To check that
Montage is correctly installed, you can type:
mAdd
If you see something like:
[struct stat="ERROR", msg="Usage: mAdd [-p imgdir] [-n(o-areas)] [-a mean|median|count] [-e(xact-size)] [-d level] [-s statusfile] images.tbl template.hdr out.fits"]
then the installation succeeded. Otherwise, if you see:
mAdd: command not found
then you will need to make sure that the Montage_v3.3/bin
contains
commands like mAdd
, and that the directory is correctly in your $PATH
.
Once the IPAC Montage package is installed, you can install the Python wrapper with:
tar xvzf montage-wrapper-x.x.x.tar.gz
cd montage-wrapper-x.x.x
python setup.py install
(replacing x.x.x
with the actual version number). The only dependencies
are numpy and astropy.
Using montage_wrapper
¶
Montage commands¶
The Montage wrapper is imported using:
>>> import montage_wrapper
or, for clarity:
>>> import montage_wrapper as montage
All Montage commands (except mJPEG
, mMakeImg
, and mTileImage
)
are accessible via Python functions. For example, to access mProject
, use:
>>> montage.mProject(...)
and see mProject()
for available options. Each
Montage command returns a Struct
object that
contains information/diagnostics. The following example shows how to use the
Montage command wrappers, and how to access the diagnostics:
>>> montage.mArchiveList('2MASS', 'K', 'm31', 0.5, 0.5, 'm31_list.tbl')
count : 18
stat : OK
>>> montage.mMakeHdr('m31_list.tbl', 'header.hdr', north_aligned=True)
count : 18
lat4 : 41.744136
stat : OK
lat1 : 40.912238
lat3 : 41.744136
latsize : 0.831951
clon : 10.717965
lonsize : 0.830562
posang : 0.0
lon4 : 11.274528
lat2 : 40.912238
lon1 : 11.267467
clat : 41.32951
lon2 : 10.168464
lon3 : 10.161403
>>> s = montage.mMakeHdr('m31_list.tbl', 'header.hdr', north_aligned=True)
>>> s.stat
'OK'
>>> s.lon1
11.267467
See Reference/API for a full list of available commands and documentation.
High-level functions¶
In addition to wrappers to the individual Montage commands, the following high-level functions are available:
reproject
: reproject a FITS filereproject_hdu
: reproject an FITS HDU objectmosaic
: mosaic all FITS files in a directory
For example, to mosaic all FITS files in a directory called raw
using background matching, use:
>>> montage.mosaic('raw', 'mosaic', background_match=True)
In this specific example, a mosaic header will automatically be constructed from the input files.
For more details on how to use these, see the Reference/API section.
MPI¶
A few Montage commands can be run using MPI for parallelization (see here).
For MPI-enabled commands (such as mProjExec
), the use of
MPI is controlled via the mpi= argument. For example, to call mProjExec
using MPI, call montage.mProjExec(..., mpi=True)
(rather than
montage.mProjExecMPI
, which does not exist). Note however that this
requires the MPI versions of the Montage commands to be installed (which is
not the case by default).
Different MPI installations require different commands (e.g. mpirun
vs
mpiexec
) as well as different options, so it is possible to customize the
MPI command:
>>> import montage_wrapper as montage
>>> montage.set_mpi_command('mpiexec -n {n_proc} {executable}')
The command string should include {n_proc}
, which will be replaced by the
number of proceses, and {executable}
, which will be replaced by the
appropriate Montage executable. The current MPI command can be accessed with:
>>> from montage_wrapper.mpi import MPI_COMMAND
>>> MPI_COMMAND
'mpiexec -n {n_proc} {executable}'
Reference/API¶
montage_wrapper.wrappers Module¶
Functions¶
mProject_auto (*args, **kwargs) |
Run mProject, automatically selecting whether to run mProject or mProjectPP if possible (fast plane-to-plane projection). |
mosaic (input_dir, output_dir[, header, ...]) |
Combine FITS files into a mosaic |
reproject (in_images, out_images[, header, ...]) |
General-purpose reprojection routine. |
reproject_cube (in_image, out_image[, ...]) |
Cube reprojection routine. |
reproject_hdu (in_hdu, **kwargs) |
Reproject an image (HDU version) |
montage_wrapper.commands Module¶
Functions¶
mAdd (images_table, template_header, out_image) |
Coadd the reprojected images in an input list to form an output mosaic with FITS header keywords specified in a header file. |
mAddExec (images_table, template_header, ...) |
Builds a series of outputs (which together make up a tiled output) through multiple executions of the mAdd modules. |
mArchiveExec (region_table[, debug_level]) |
Given a table of archive images (generated by mArchiveList), calls mArchiveGet on each one in sequence to retrieve all the files into the current directory. |
mArchiveGet (remote_ref, local_file[, debug, raw]) |
Retrieve a single FITS image from a remote archive, using a basic URL GET but with a structured output. |
mArchiveList (survey, band, ...) |
Given a location on the sky, archive name, and size in degrees, contact the IRSA server to retrieve a list of archive images. |
mBackground (in_image, out_image, A, B, C[, ...]) |
Remove a background plane from a FITS image. |
mBackground_tab (in_image, out_image, ...[, ...]) |
Remove a background plane from a FITS image. |
mBestImage (images_table, ra, dec[, debug]) |
Given a list of images and a position on the sky, determine which image covers the location “best” (i.e., the one where the position is farthest from the nearest edge). |
mBgExec (images_table, corrections_table, ...) |
Runs mBackground on all the images in a metadata table, using the corrections generated by mFitExec. |
mBgModel (images_table, fits_table, ...[, ...]) |
mBgModel is a modelling/fitting program. It uses the image-to-image |
mCatMap (in_table, out_image, template_header) |
mCatMap is a point-source imaging program. The user defines a general |
mConvert (in_image, out_image[, debug_level, ...]) |
mConvert changes the datatype of an image. When converting to floating |
mCoverageCheck (in_table, out_table, mode[, ...]) |
mCoverageCheck can be used to subset an image metadata table (containing |
mDiff (in_image_1, in_image_2, out_image, ...) |
mDiff calculates a simple difference between a single pair of overlapping |
mDiffExec (diffs_table, template_header, diff_dir) |
Runs mDiff on all the pairs identified by mOverlaps. |
mDiffFitExec (diffs_table, fits_table, diff_dir) |
Using the table of overlaps found by mOverlaps, mDiffFitExec runs both mDiff and mFitplane for each record. |
mExec (survey, band[, raw_dir, n_tile_x, ...]) |
The mExec module is a mosaicking executive for 2MASS, SDSS, and DSS data. |
mFitExec (diffs_table, fits_table, diff_dir) |
Runs mFitplane on all the difference images identified by mOverlaps and generated by mDiff or mDiffExec. |
mFitplane (in_image[, border, debug_level, ...]) |
Uses least squares to fit a plane (excluding outlier pixels) to an image. |
mFixNaN (in_image, out_image[, debug_level, ...]) |
Converts NaNs found in the image to some other value (given by the user), or converts a range of supplied values into NaNs. |
mFlattenExec (images_table, flat_dir[, ...]) |
Runs both mFitPlane and mBackground on a set of images. |
mGetHdr (in_image, img_header[, debug, hdu, ...]) |
Reads in the header from a FITS image and prints it out to a text file. |
mHdr (object_or_location, width, out_file[, ...]) |
Connects to the IRSA service HdrTemplate to create a header template based on a location, size, resolution and rotation. |
mHdrCheck (in_image[, status_file]) |
mHdrCheck reads in the header from a FITS image (or an ASCII header |
mHdrtbl (directory, images_table[, ...]) |
mHdrtbl operates in a fashion similar to mImgtbl, but is used on a set of |
mImgtbl (directory, images_table[, ...]) |
mImgtbl extracts the FITS header geometry information from a set of files |
mMakeHdr (images_table, template_header[, ...]) |
From a list of images to be mosaicked together, mMakeHdr generates the FITS header that best describes the output image. |
mOverlaps (images_table, diffs_table[, ...]) |
Analyze an image metadata table to determine a list of overlapping images. |
mPix2Coord (template_header, ixpix, jypix[, ...]) |
Takes an image FITS header template and a pixel (x,y) coordinate, and outputs the corresponding sky location. |
mProjExec (images_table, template_header, ...) |
An executive which runs mProject (or, if possible for the input/output projections, mProjectPP) for each image in an image metadata table. |
mProject (in_image, out_image, template_header) |
mProject reprojects a single image to the scale defined in a FITS header |
mProjectPP (in_image, out_image, template_header) |
mProjectPP reprojects a single image to the scale defined in an alternate |
mPutHdr (in_image, out_image, template_header) |
Replaces the header of the input file with one supplied by the user. |
mRotate (in_image, out_image[, debug_level, ...]) |
Rotates a FITS image by an arbitrary angle. |
mShrink (in_image, out_image, factor[, ...]) |
A utility for reducing the size of a FITS file, by averaging blocks of pixels. |
mSubimage (in_image, out_image, ra, dec, xsize) |
Creates a subimage (or “cutout”) of a FITS file. |
mSubimage_pix (in_image, out_image, ...[, ...]) |
Creates a subimage (or “cutout”) of a FITS file (‘pixel’ mode) |
mSubset (images_table, template_header, ...) |
Generates a table of images that is a subset of the input table, containing only those images that cover the area defined by a given FITS header. |
mTANHdr (orig_header, new_header[, debug, ...]) |
Analyzes a template file and determines if there would be an adequate equivalent distorted TAN projection, within a specified tolerance, and outputs the alternate header. |
mTblSort (in_table, column_name, out_table[, ...]) |
Sorts a table on numeric values. |
mTileHdr (orig_header, new_header, n_x, n_y, ...) |
Takes a header template file and creates another which represents one of a regular set of tiles covering the original. |
mTileImage (in_image, tiles_x, tiles_y[, ...]) |
mTileImage splits up an image into a given number of tiles. |
montage_wrapper.status Module¶
Functions¶
parse_struct (command, string) |
|
simplify (value) |
Classes¶
MontageError |
|
Struct (command, string) |
Class Inheritance Diagram¶