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: mViewer¶
The Montage toolkit is primarily involved in reprojecting, background matching, and mosaicking astronomical images but it also has fairly sophisticated tools for image display (PNG/JPEG generation). This notebook entry shows the basics of using mViewer to create a full-color image from three wavelength bands that have already been reprojected and mosaicked.
In this example, we will focus on the image data but mViewer can also build visualizations where the image data is secondary or invisible.
from MontagePy.main import mViewer
help(mViewer)
Example¶
The number of arguments to mViewer is a little large for a standard keyword list so we use a couple of structured strings for control. For simple plots we have a brief syntax that is modeled on the stand-alone command line (see below). We'll show an example of that later. For more involved plots we use JSON.
Here we create the JSON as a simple string (note the triple quotes which let us make thisa multi-line with embedded quotes, etc.).
imgjson = """
{
"image_type":"png",
"true_color":1.50,
"font_scale":1.1,
"blue_file":
{
"fits_file":"SDSS/SDSS_u.fits",
"stretch_min":"-0.1s",
"stretch_max":"max",
"stretch_mode":"gaussian-log"
},
"green_file":
{
"fits_file":"SDSS/SDSS_g.fits",
"stretch_min":"-0.1s",
"stretch_max":"max",
"stretch_mode":"gaussian-log"
},
"red_file":
{
"fits_file":"SDSS/SDSS_r.fits",
"stretch_min":"-0.1s",
"stretch_max":"max",
"stretch_mode":"gaussian-log"
},
"overlays":
[
{
"type":"grid",
"coord_sys":"Equ J2000",
"color":"8080ff"
},
{
"type":"imginfo",
"data_file":"SDSS/irspeakup.tbl",
"coord_sys":"Equ J2000",
"color":"ff9090"
},
{
"type":"catalog",
"data_file":"SDSS/fp_2mass.tbl",
"data_column":"j_m",
"data_ref":16,
"data_type":"mag",
"symbol":"circle",
"sym_size":1.0,
"coord_sys":"Equ J2000",
"color":"ffff00"
}
]
}
"""
This defines a full-color image made with three Sloan Digital Sky Survey (SDSS) mosaics made from archive data, each with its own stretch, plus three overlays (a coordinate grid, the 2MASS catalog, and image metadata from the Spitzer Space Telescope).
There are additional controls for other overlays. See http://montage.ipac.caltech.edu/mViewer for details.
With this, it is simple to run mViewer:
rtn = mViewer(imgjson, 'work/SDSS/SDSS.png', mode=1)
print(rtn)
The return contains details of the individual image stretching, image size, and so on.
Here is the output image:
from IPython.display import Image
Image(filename='work/SDSS/SDSS.png')
The call to mViewer above specified "mode=1", meaning that the control string was JSON. For simpler plots, you can get a way with a simpler (and the default) syntax:
rtn = mViewer('-ct 1 -gray SDSS/SDSS_g.fits -2s max gaussian-log',
'work/SDSS/SDSS_g.png',
mode=2)
print(rtn)
Image(filename='work/SDSS/SDSS_g.png')
Error Handling¶
If mViewer encounters an error, including in the arguments in the control string, 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 an image that doesn't exist:
rtn = mViewer('-ct 1 -gray SDSS/unknown.fits -2s max gaussian-log',
'work/gray.png', mode=2)
print(rtn)
Classic Montage: mViewer as a Stand-Alone Program¶
mViewer Unix/Windows Command-line Arguments¶
mViewer can also be run as a command-line tool in Linux, OS X, and Windows:
Usage: Parameters: [-d] [-nowcs] [-noflip] [-t(rue-color) power] [-ct color-table] [-grid csys [epoch]] -gray in.fits minrange maxrange [logpower/gaussian] -red red.fits rminrange rmaxrange [rlogpower/gaussian] -green green.fits gminrange gmaxrange [glogpower/gaussian] -blue blue.fits bminrange bmaxrange [blogpower/gaussian] -out out.png
There are additional controls for other overlays. See http://montage.ipac.caltech.edu/mViewer for details.
If you are writing in C/C++, mViewer can be accessed as a library function:
/*-***************************************************************************/ /* */ /* mViewer */ /* */ /* This program generates a JPEG image file from a FITS file (or a set */ /* of three FITS files in color). A data range for each image can */ /* be defined and the data can be stretch by any power of the log() */ /* function (including zero: linear). Pseudo-color color tables can */ /* be applied in single-image mode. */ /* */ /* Scaled symbols (individually or for a catalog table), image outlines, */ /* and labels (individually or from a table) and coordinate grids can be */ /* overlaid on the image. The details of the command syntax for this are */ /* too involved to document here. See the mViewer documentation on-line */ /* or delivered with the Montage source. */ /* */ /* char *params The parameters string (arguments or JSON) or JSON */ /* file. */ /* */ /* char *outFile Output PNG/JPEG */ /* */ /* int mode Type of the command string: 0 for a JSON file, */ /* 1 for a JSON string, and 2 for a command string. */ /* */ /* char *fontFile Font file (overrides default) */ /* */ /* char *outFmt 'png' or 'jpeg' */ /* */ /* int debug Debugging output level */ /* */ /*****************************************************************************/ struct mViewerReturn *mViewer(char *params, char *outFile, int mode, char *outFmt, char *fontFile, int debugin)
Return Structure
struct mViewerReturn
{
int status; // Return status (0: OK, 1:ERROR)
char msg [1024]; // Return message (for error return)
char json[4096]; // Return parameters as JSON string
char type[32]; // Whether the output is 'color' or 'grayscale'
int nx; // Width of the image in pixels
int ny; // Height of the image in pixels
double grayminval; // Minimum stretch data value (grayscale)
double grayminpercent; // Percentile level in histogram for min stretch value (gray)
double grayminsigma; // 'Sigma' level in histogram for min stretch value (gray)
double graymaxval; // Maximum stretch data value (grayscale)
double graymaxpercent; // Percentile level in histogram for min stretch value (gray)
double graymaxsigma; // 'Sigma' level in histogram for min stretch value (gray)
double blueminval; // Minimum stretch data value (color: blue image)
double blueminpercent; // Percentile level in histogram for min stretch value (blue)
double blueminsigma; // 'Sigma' level in histogram for min stretch value (blue)
double bluemaxval; // Maximum stretch data value (color: blue image)
double bluemaxpercent; // Percentile level in histogram for max stretch value (blue)
double bluemaxsigma; // 'Sigma' level in histogram for min stretch value (blue)
double greenminval; // Minimum stretch data value (color: green image)
double greenminpercent; // Percentile level in histogram for min stretch value (green)
double greenminsigma; // 'Sigma' level in histogram for min stretch value (green)
double greenmaxval; // Maximum stretch data value (color: green image)
double greenmaxpercent; // Percentile level in histogram for max stretch value (green)
double greenmaxsigma; // 'Sigma' level in histogram for min stretch value (green)
double redminval; // Minimum stretch data value (color: red image)
double redminpercent; // Percentile level in histogram for min stretch value (red)
double redminsigma; // 'Sigma' level in histogram for min stretch value (red)
double redmaxval; // Maximum stretch data value (color: red image)
double redmaxpercent; // Percentile level in histogram for max stretch value (red)
double redmaxsigma; // 'Sigma' level in histogram for min stretch value (red)
double graydatamin; // Minimum data value for grayscale image
double graydatamax; // Maximum data value for grayscale image
double bdatamin; // Minimum data value for blue image
double bdatamax; // Maximum data value for blue image
double gdatamin; // Minimum data value for green image
double gdatamax; // Maximum data value for green image
double rdatamin; // Minimum data value for red image
double rdatamax; // Maximum data value for red image
int flipX; // Boolean: whether the image X axis was flipped
int flipY; // Boolean: whether the image Y axis was flipped
int colortable; // Grayscale: pseudo-color lookup table index
char bunit[256]; // Flux units in data files (from BUNIT header keyword)
};