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

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, mFitExec, which fits planes to a set of images (most often overlap differences).

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

help(mFitExec)
Help on built-in function mFitExec in module MontagePy.main:

mFitExec(...)
    mFitExec loops over a list of difference images, fitting their level/slopes.
    
    Parameters
    ----------
    tblfile : str
        Table file list of input difference images.
    fitfile : str
        Table file for output difference fit info.
    diffdir : str, optional
        Directory for temporary difference files.
    levelOnly : bool, optional
        Flag to fit level of differences only, not slopes.
    debug : int, optional
        Debugging output flag.
    
    
    Returns
    -------
    status : int
        Return status (0: OK, 1:ERROR).
    msg : str
        Return message (for errors).
    count : int
        Total number of images.
    failed : int
        Count where fitting failed.
    warning : int
        Count where fitting produced warnings.
    missing : int
        Count of missing difference images.

mFitExec Example

mFitExec is a general utility for fitting a set of image differences with a plane. It's most common use is in the process of evaluating overlap area in a set of images as part of background rectification. That process consists of taking the output of the overlaps calculation (mOverlaps) and for each overlap pair doing the difference (mDiff), fitting it to determine offset between those two images (mFitplane).

There are two ways to do this in bulk. We can either generate all the differences first, then fit them all or we can loop over the differences, generating and fitting that difference before moving on to the next. This first approach uses more disks space as all the differences have to be stored in between steps. The second can clean up as it goes.

Obviously the second approach is preferable unless you want to keep the differences (possibly for quality evaluation).

mFitExec is part of the first approach. It runs mFitplane on difference file from the input list and stores the result in a table. This table will usually be handed to mBgModel to determine what corrections to make to each image to minimize background differences.

At this point in the processing, we already have a set of "like" images (same projection), have made a list of all the overlaps (normally using mOverlaps) and generated difference images. mFitExec loops over these images and fits a plane to each one.

In [6]:
rtn = mFitExec('M17/diffs.tbl', 
               'work/M17/fits.tbl',
               'M17/diffs')

print(rtn)
{'status': '0', 'count': 128, 'failed': 0, 'warning': 0, 'missing': 0}

The output is a set of planes representing the difference between two original images. This set will be sent to mBgModel for modelling into a set of corrections to the original images to bring the backgrounds in line.

In [7]:
import os
import numpy as np
import pandas as pd
from astropy.io import ascii

ipactable = ascii.read('work/M17/fits.tbl').to_pandas()

ipactable
Out[7]:
plus minus a b c crpix1 crpix2 xmin xmax ymin ymax xcenter ycenter npixel rms boxx boxy boxwidth boxheight boxang
0 0 8 1.268790e-03 4.644410e-04 0.410733 -1711.0 1756.5 1711 1789 -1756 -935 1750.15 -1343.07 52864 7.362550e-01 1749.9 -1346.0 821.2 77.3 -90.1
1 0 9 -2.523660e-03 1.653820e-03 6.969540 -1713.0 988.5 1713 1789 -988 -733 1751.01 -863.07 16232 7.125360e-01 1751.1 -861.0 255.3 76.9 -90.2
2 0 13 2.453210e-03 3.935060e-03 0.277418 -1286.0 986.5 1286 1361 -986 -732 1323.43 -862.04 16218 7.174900e-01 1323.5 -859.5 254.0 75.0 90.0
3 0 14 -2.490360e-03 8.991680e-04 4.436860 -1283.0 1755.5 1283 1361 -1755 -933 1322.70 -1342.62 52649 7.105830e-01 1322.3 -1344.5 822.2 77.3 89.9
4 0 21 -3.303240e-10 5.376120e-09 -1.130130 -1286.0 786.5 1286 1790 -786 -732 1537.86 -759.37 27003 7.587320e-06 1538.0 -759.5 54.0 504.0 90.0
5 0 24 -1.489270e-10 -5.884170e-09 0.561656 -1284.0 1756.5 1284 1787 -1756 -1702 1535.59 -1729.23 27090 7.108770e-06 1535.5 -1729.5 54.0 503.0 90.0
6 0 29 -1.230960e-03 5.115690e-04 -79.055300 -1710.0 994.5 1710 1790 -994 -733 1749.78 -865.65 16584 7.530540e-01 1749.9 -864.0 261.3 79.3 -90.2
7 0 31 2.329150e-03 1.100920e-03 -82.140500 -1708.0 1756.5 1708 1789 -1756 -941 1748.71 -1348.03 53097 7.707710e-01 1748.8 -1349.0 815.2 79.9 89.8
8 1 6 1.756510e-04 -2.708390e-04 -3.833850 426.0 789.5 -426 -351 -789 32 -387.36 -347.45 42063 9.129390e-01 -388.5 -378.5 822.0 75.0 90.0
9 1 11 -2.720230e-03 -5.054520e-04 -0.537130 -2.0 789.5 2 78 -789 31 40.09 -390.72 47921 8.727160e-01 40.0 -379.0 821.0 76.0 90.0
10 1 20 -5.109730e-19 -2.983720e-16 0.763428 425.0 789.5 -425 78 -789 -736 -172.39 -763.09 22413 4.641070e-15 -173.5 -763.0 53.0 503.0 90.0
11 1 27 1.084200e-19 -5.074070e-17 0.691162 426.0 -180.5 -426 77 180 233 -174.68 207.06 23318 7.921560e-16 -174.5 207.0 53.0 503.0 90.0
12 1 34 -4.281630e-03 6.650880e-04 -4.570030 426.0 20.5 -426 -351 -20 233 -388.07 106.65 14652 8.112380e-01 -388.5 106.5 254.0 75.0 90.0
13 1 41 -9.965350e-03 3.869090e-03 -0.521526 -2.0 21.5 2 77 -21 233 39.46 110.87 15314 9.693480e-01 39.5 106.0 255.0 75.0 90.0
14 2 5 5.910760e-03 9.426410e-04 5.666030 854.0 1757.5 -854 -777 -1757 -937 -815.22 -1354.16 49825 7.697600e-01 -815.4 -1347.5 820.1 76.4 90.1
15 2 6 -7.671010e-04 1.611060e-03 0.543132 854.0 990.5 -854 -778 -990 -734 -815.57 -864.23 14285 9.272300e-01 -816.0 -862.5 256.0 76.0 90.0
16 2 18 4.852270e-10 3.118610e-09 1.600290 1282.0 788.5 -1282 -778 -788 -734 -1029.37 -761.30 26871 7.403790e-06 -1030.0 -761.5 54.0 504.0 90.0
17 2 25 -3.896340e-04 9.108010e-04 6.162890 1281.0 1758.5 -1281 -1238 -1758 -933 -1260.25 -1335.75 24848 8.814390e-01 -1260.0 -1346.0 825.1 42.7 -89.9
18 2 26 6.081620e-03 1.740740e-03 13.644000 1282.0 986.5 -1282 -1240 -986 -735 -1260.26 -864.96 7125 1.006160e+00 -1261.0 -861.0 251.0 42.0 90.0
19 2 28 -3.959880e-20 -1.304840e-16 -0.597885 1280.0 1758.5 -1280 -777 -1758 -1704 -1028.23 -1731.35 24404 2.032750e-15 -1028.5 -1731.5 54.0 503.0 90.0
20 3 11 2.111740e-03 8.402230e-04 -2.689850 -431.0 784.5 431 505 -784 31 468.00 -378.34 50863 7.444600e-01 468.0 -376.5 816.0 74.0 90.0
21 3 13 3.627310e-03 1.314690e-03 -2.519670 -858.0 784.5 858 935 -784 37 896.00 -382.34 50308 7.361090e-01 896.5 -373.5 822.1 76.1 -90.1
22 3 17 2.483370e-10 -1.152390e-09 -0.965677 -431.0 784.5 431 934 -784 -731 682.61 -757.99 27199 7.623260e-06 682.5 -758.0 53.0 503.0 90.0
23 3 23 -3.036630e-11 1.690620e-09 -1.258960 -432.0 -185.5 432 935 185 238 683.50 212.00 27216 6.063610e-06 683.5 212.0 53.0 503.0 90.0
24 3 38 3.505620e-03 1.811340e-04 -3.260770 -860.0 15.5 860 935 -15 238 897.12 111.32 15496 7.787990e-01 897.5 111.5 254.0 75.0 90.0
25 3 41 5.486890e-03 1.928290e-03 -4.866100 -431.0 21.5 431 505 -21 238 468.22 108.40 15892 7.351890e-01 468.0 108.5 260.0 74.0 90.0
26 4 15 4.008290e-03 -9.678930e-04 6.493410 1747.0 -183.5 -1747 -1672 183 1005 -1708.71 591.93 43190 9.386600e-01 -1709.7 594.6 822.0 73.7 -89.9
27 4 18 -3.352750e-04 -2.270560e-03 -3.924300 1283.0 16.5 -1283 -1242 -16 234 -1262.86 106.53 7062 1.012440e+00 -1262.5 109.0 251.0 41.0 90.0
28 4 19 1.435180e-16 -1.116540e-14 -0.190674 1747.0 -952.5 -1747 -1244 974 983 -1493.10 978.90 47 3.698180e-16 -1495.5 979.5 54.0 503.0 90.0
29 4 26 2.168400e-18 4.445230e-18 1.108510 1745.0 17.5 -1745 -1242 -17 36 -1494.00 9.26 24954 3.432580e-16 -1493.5 9.5 54.0 503.0 90.0
... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
98 25 37 2.993400e-03 -9.639940e-04 1.930760 1743.0 1756.5 -1743 -1667 -1756 -934 -1704.44 -1368.87 43558 9.570520e-01 -1705.1 -1345.5 822.1 75.0 90.1
99 26 37 2.132510e-03 -7.878530e-04 1.137900 1743.0 987.5 -1743 -1669 -987 -732 -1704.94 -856.26 13175 8.965520e-01 -1706.0 -860.0 255.0 74.0 90.0
100 26 42 4.095660e-03 -1.870220e-03 4.653600 1745.0 786.5 -1745 -1670 -786 35 -1705.76 -365.01 44054 8.743800e-01 -1707.4 -375.5 822.0 74.3 90.1
101 27 33 2.527970e-18 -4.167670e-16 1.673900 426.0 -1150.5 -426 77 1150 1203 -173.40 1177.04 21881 6.513750e-15 -174.5 1177.0 53.0 503.0 90.0
102 27 34 3.071140e-03 1.595790e-03 -2.654820 426.0 -180.5 -426 -351 180 1002 -389.66 570.28 44329 9.364340e-01 -388.5 591.5 822.0 75.0 90.0
103 27 35 1.628030e-03 1.117010e-03 -0.391749 -3.0 -948.5 3 77 948 1203 40.62 1076.31 12992 1.003060e+00 40.0 1076.0 255.0 74.0 90.0
104 27 41 2.676220e-03 1.519470e-03 -1.326430 -2.0 -180.5 2 77 180 1001 40.10 570.35 46199 8.684200e-01 39.5 591.0 821.0 75.0 90.0
105 27 43 6.693140e-03 3.815910e-03 -3.391830 426.0 -949.5 -426 -352 949 1203 -390.89 1078.05 12730 1.083480e+00 -389.0 1076.5 254.0 74.0 90.0
106 29 30 -6.003610e-03 7.217340e-03 92.591200 -1716.0 18.5 1716 1798 -18 28 1757.75 4.26 3000 9.457370e-01 1757.0 5.0 47.0 82.0 90.0
107 29 31 3.228370e-09 3.008890e-09 2.299610 -1710.0 994.5 1710 1798 -994 -941 1754.05 -968.01 4791 7.628790e-06 1754.0 -968.0 53.0 88.0 90.0
108 30 44 1.178090e-15 1.691360e-17 -3.227810 -1718.0 -951.5 1718 1798 951 1004 1757.89 978.04 3747 2.755180e-14 1758.0 978.0 53.0 80.0 90.0
109 30 45 5.933540e-03 -1.243340e-03 -13.183500 -1716.0 -183.5 1716 1793 183 1004 1754.93 607.41 46514 8.592740e-01 1754.9 594.0 821.2 76.3 -90.2
110 32 35 1.212370e-03 -2.488770e-03 2.879520 -433.0 -1155.5 433 506 1155 1797 468.94 1573.64 27217 9.886340e-01 469.5 1476.5 642.0 73.0 90.0
111 32 36 -4.557880e-03 2.532880e-03 0.350670 -862.0 -1155.5 862 936 1155 1797 899.31 1465.39 37138 8.199690e-01 899.0 1476.5 642.0 74.0 90.0
112 33 35 5.023290e-03 2.110940e-03 -3.150380 -3.0 -1150.5 3 77 1150 1797 40.41 1487.34 35991 8.733230e-01 40.0 1474.0 647.0 74.0 90.0
113 33 43 3.743590e-03 1.023310e-03 -3.199060 426.0 -1150.5 -426 -352 1150 1797 -389.43 1485.53 33026 9.699490e-01 -389.0 1474.0 647.0 74.0 90.0
114 34 43 9.529120e-20 -1.970540e-17 -0.217102 855.0 -949.5 -855 -352 949 1002 -603.82 976.05 24455 3.088130e-16 -603.5 976.0 53.0 503.0 90.0
115 34 47 -5.801320e-04 -1.266650e-03 1.172310 855.0 -182.5 -855 -780 182 1002 -817.62 588.56 45873 8.761660e-01 -817.5 592.5 820.0 75.0 90.0
116 35 41 4.690440e-19 1.317850e-16 -0.366928 -3.0 -948.5 3 506 948 1001 254.91 974.98 26986 2.055550e-15 254.5 975.0 53.0 503.0 90.0
117 36 38 2.612920e-10 -1.019570e-09 1.721730 -861.0 -953.5 861 1364 953 1007 1111.91 980.63 26937 7.228180e-06 1112.5 980.5 54.0 503.0 90.0
118 36 39 -5.956260e-04 -7.872360e-04 -0.036234 -1291.0 -1154.5 1291 1366 1154 1797 1327.21 1483.97 36016 9.384890e-01 1328.3 1476.0 643.1 74.5 -90.1
119 36 45 -5.363510e-03 -4.439150e-03 11.325300 -1290.0 -953.5 1290 1365 953 1207 1327.66 1080.66 13662 9.161630e-01 1327.6 1080.5 254.4 74.4 89.7
120 37 42 1.569380e-17 9.454240e-17 0.765747 1801.0 786.5 -1801 -1670 -786 -732 -1735.80 -759.64 5746 1.590380e-15 -1735.5 -759.5 54.0 131.0 90.0
121 38 45 -3.689510e-03 -1.696570e-03 4.205390 -1289.0 -184.5 1289 1364 184 1006 1326.44 596.48 48646 8.512290e-01 1326.5 595.5 822.0 75.0 90.0
122 39 44 2.348420e-03 4.838670e-04 -3.615190 -1718.0 -1153.5 1718 1795 1153 1797 1756.99 1475.15 39354 7.699550e-01 1756.8 1475.5 644.3 76.8 -90.2
123 39 45 3.354750e-10 2.823240e-09 0.253280 -1291.0 -1153.5 1291 1794 1153 1207 1542.22 1180.83 27010 6.472080e-06 1542.5 1180.5 54.0 503.0 90.0
124 40 43 -1.941730e-03 1.361570e-03 -5.333800 856.0 -1152.5 -856 -781 1152 1797 -817.98 1464.43 34937 9.498680e-01 -818.3 1475.0 645.2 74.7 90.1
125 40 47 -7.749280e-11 2.229940e-09 -2.566560 1284.0 -1151.5 -1284 -781 1151 1205 -1032.04 1178.82 26883 7.354740e-06 -1032.5 1178.5 54.0 503.0 90.0
126 43 47 -8.581890e-04 -3.095250e-03 2.637200 855.0 -949.5 -855 -781 949 1205 -818.16 1078.88 14308 8.889450e-01 -818.0 1077.5 256.0 74.0 90.0
127 44 45 1.303560e-03 -1.999610e-03 -0.969453 -1718.0 -951.5 1718 1794 951 1206 1756.03 1080.04 14963 7.546190e-01 1756.0 1079.0 255.0 76.0 90.0

128 rows × 20 columns

 

Error Handling

If mFitExec 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 table that doesn't exist:

In [5]:
rtn = mFitExec('M17/unknown.tbl', 
               'work/M17/fits.tbl',
               'M17/diffs')
print(rtn)
{'status': '1', 'msg': b'Invalid diffs metadata file: M17/unknown.tbl'}

 

Classic Montage: mFitExec as a Stand-Alone Program

mFitExec Unix/Windows Command-line Arguments

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

Usage: mFitExec [-d] [-l(evel-only)] [-s statusfile] diffs.tbl fits.tbl diffdir

 

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

/*-*****************************************************************/
/*                                                                 */
/*  mFitExec                                                       */
/*                                                                 */
/*  After mDiffExec has been run using the table of overlaps found */
/*  by mOverlaps, use this executive to run mFitplane on each of   */
/*  the differences.  Write the fits to a file to be used by       */
/*  mBModel.                                                       */
/*                                                                 */
/*   char *tblfile     Table file list of images to fit.           */
/*   char *fitfile     Table file for output difference fits info. */
/*   char *diffdir     Directory for temporary output diff files.  */
/*   int levelOnly     Flag to fit level of diff only, not slopes. */
/*   int debug         Debug flag.                                 */
/*                                                                 */
/*******************************************************************/

struct mFitExecReturn *mFitExec(char *tblfile, char *fitfile, char *diffdir, int levelOnly, int debugin)

Return Structure

struct mFitExecReturn
{
   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 differences                
   int    failed;        // Number of fits to differences that failed
   int    warning;       // Number of fits to differences that produced warnings
   int    missing;       // Number of missing difference images
};