Tutorial: A KELT Coverage Map with mViewer

Contents

 

 

 

Sky Maps

This tutorial shows how to use the Montage module mViewer to create maps of the sky with (or without) an underlying image. While we use an all-sky example, any region, scale, and projection can be used (basically, if you can define the "FITS header" WCS for a region, you can make the map).

 

 

mViewer as a Sky Graphics Engine

The primary role of mViewer is creating PNG visualizations of one, two, or three astronomical (FITS) images. It supports all WCS projections and a wide array of data stretching and color capabilities, some unique.

mViewer also has considerable graphics capabilities, primarily for adding overlays to images but there are occasions when the graphics become central, with the background image secondary. This tutorial focuses on one of those cases.

mViewer is a command-line tool (though it can be used in interactive visualization scenarios through Python and web GUIs). It can easily be embedded in pipelines and in conjunction with other Montage modules can provide adaptive support for building visualizations for presentation and reporting. mViewer overlay "commands" are actually a set of (repeatable) command-line directives, as will be illustrated here. The complete set of directives can be found in the mViewer documentation.

In the context of this tutorial, mViewer has directives that support the following:

  • Single marker symbols (standard polygon plus "starred" and "skeletal" modes) drawn on the sky rather than in pixel space (which can matter for projections like the Aitoff shown here). Optionally, these can be placed by pixel cartesian coordinates.

  • Symbols drawn at locations from an input table, optionally scaled linear/log/magnitude based on a table column value. There are a few specialty symbols like a compass rose as well.

  • Labels, either singly or from a table. Font files can be swapped in (at the moment just one at a time), allowing any language or symbol set.

  • Image outlines, from an image metadata file (four corners or WCS parameters).

  • Coordinate grids (galactic, ecliptic, equatorial with any equinox).

 

 

"Steps" in the Process

 Top

Making the KELT coverage map above is actually a single command (which we show later) but we will build it up piece by piece to illustrate the inputs. The background is an all-sky image, which in this case is is a galactic dust map. The projection and size of the output PNG are derived from this image, though this can be finessed if all that is desired are the drawn overlays.

To this are added "overlays", one at a time, with any necessary setting of color, data coordinate system, and so on. For this image, these are the following:

  • Equatorial coordinate grid, in light gray.
  • Kepler field footprint, in red.
  • K2 footprints for the first few campaigns, also in red.
  • KELT fields, colors specified in the data table.
  • KELT field labels (from the same file), in red.
 

 

Background Image

 Top
SIMPLE  =                    T
BITPIX  =                  -64
NAXIS   =                    2
NAXIS1  =                 1476
NAXIS2  =                  738
CTYPE1  = 'RA---AIT'
CTYPE2  = 'DEC--AIT'
CRVAL1  =                 180.
CRVAL2  =                   0.
CRPIX1  =                738.5
CRPIX2  =                369.5
CDELT1  =          -0.21972656
CDELT2  =           0.21972656
CROTA2  =                  0.0
END

The background image we use here is an Aitoff all-sky infrared map made from the IRAS/ISSA and COBE/DIRBE 100 micron data as reprocessed by Schlegel et. al. This image was actually reprojected (using Montage) from a higher-resolution Galactic version made from the original data. The FITS header for the image we used above is show on the left.

The original image data can equally well be reprojected into any other WCS.

 

 

Coordinate Grid

 Top
mViewer -ct 1 \
        -color "#808080"  \
        -grid   equ j2000 \
        -gray   equatorial.fits -0.5s max gaussian-log \
        -out    KELT.png

The basic mViewer command to generate a reverse grayscale PNG of the fits file is described in more detail in the mViewer documentation. Here it has been augmented with two additional directives, one to set the overlay color and the second to draw an Equatorial J2000 grid.

This command could be given on one line; we use continuations here and below for clarity.

For overlays, the directives given mViewer are processed in command-line order and settings like color (and symbol size/shape and coordinate system) are "sticky": once set, they will be used for any subsequent directive where they would apply.

Colors can be given by name for the basics (like "red" and "gray" or can be given in hex triplet syntax, as here.

 

 

Kepler and K2 Footprints

 Top
mViewer -ct 1 \
        -color   "#808080"  \
        -grid     equ j2000 \
        -color    red \
        -imginfo  k2_footprints.tbl \
        -color    red \
        -imginfo  kepler_footprint.tbl \
        -gray     equatorial.fits -0.5s max gaussian-log \
        -out      KELT.png

Image metadata tables contain either enough WCS information to fully characterize the outline or the four corners of each image as columns ra1,dec2 ... ra4,dec4. The Montage module mImglist can be used to generate such a list for a collection of images.

Here the input data for both Kepler and K2 templates come from tables the Kepler Project provides which have the same four-corner information and we can plot it just like we would image metadata.

 

 

KELT Fields

 Top
mViewer -ct 1 \
        -color   "#808080"  \
        -grid     equ j2000 \
        -colorcol color \
        -imginfo  KELT_fields.tbl \
        -color    red \
        -imginfo  k2_footprints.tbl \
        -color    red \
        -imginfo  kepler_footprint.tbl \
        -gray     equatorial.fits -0.5s max gaussian-log \
        -out      KELT.png

The KELT field data file also has four-corner information. Here, we let the file itself determine what colors will be used for which fields.

A color column can again contain a color name or a hex triplet. The file used is shown below.

| label|    ra      |     dec  | color  | ra1      | dec1     | ra2      | dec2     | ra3      | dec3     | ra4      | dec4     |
| char |  double    |   double | char   | double   | double   | double   | double   | double   | double   | double   | double   |
  KN01    1.50000000    31.6656  00b0b0  14.662264  18.419868  348.337736 18.419868  344.278874 43.136463  18.721126  43.136463  
  KN02   30.52009065    31.6656  00b0b0  43.682355  18.419868  17.357827  18.419868  13.298965  43.136463  47.741217  43.136463  
  KN03   59.54018131    31.6656  00b0b0  72.702445  18.419868  46.377917  18.419868  42.319055  43.136463  76.761307  43.136463  
  KN04   88.56027196    31.6656  00b0b0  101.722536 18.419868  75.398008  18.419868  71.339146  43.136463  105.781398 43.136463  
  KN05  117.58036261    31.6656  00b0b0  130.742627 18.419868  104.418099 18.419868  100.359237 43.136463  134.801489 43.136463  
  KN06  146.60045326    31.6656  00b0b0  159.762717 18.419868  133.438189 18.419868  129.379327 43.136463  163.821579 43.136463  
  KN07  175.62054392    31.6656  00b0b0  188.782808 18.419868  162.458280 18.419868  158.399418 43.136463  192.841670 43.136463  
  KN08  204.64063457    31.6656  00b0b0  217.802899 18.419868  191.478371 18.419868  187.419509 43.136463  221.861761 43.136463  
  KN09  233.66072522    31.6656  00b0b0  246.822989 18.419868  220.498461 18.419868  216.439599 43.136463  250.881851 43.136463  
  KN10  262.68081588    31.6656  00b0b0  275.843080 18.419868  249.518552 18.419868  245.459690 43.136463  279.901942 43.136463  
  KN11  291.70090653    31.6656  00b0b0  304.863171 18.419868  278.538643 18.419868  274.479781 43.136463  308.922033 43.136463  
  KN12  320.72099718    31.6656  00b0b0  333.883261 18.419868  307.558733 18.419868  303.499871 43.136463  337.942123 43.136463  
  KN13  349.74108783    31.6656  00b0b0  2.903352   18.419868  336.578824 18.419868  332.519962 43.136463  6.962214   43.136463  
  KS05   91.800          3.000   blue    104.454981 -9.550324  79.145019  -9.550324  78.850590  15.401451  104.749410 15.401451  
  KS06  114.900          3.000   blue    127.554981 -9.550324  102.245019 -9.550324  101.950590 15.401451  127.849410 15.401451  
  KS12  253.000          3.000   blue    265.654981 -9.550324  240.345019 -9.550324  240.050590 15.401451  265.949410 15.401451  
  KS13  276.000          3.000   blue    288.654981 -9.550324  263.345019 -9.550324  263.050590 15.401451  288.949410 15.401451  
  KS14  299.000          3.000   blue    311.654981 -9.550324  286.345019 -9.550324  286.050590 15.401451  311.949410 15.401451  
  KS17    0.000        -53.000   blue    28.344066  -62.931669 331.655934 -62.931669 343.840187 -39.081730 16.159813  -39.081730 
  KS18   23.000        -53.000   blue    51.344066  -62.931669 354.655934 -62.931669 6.840187   -39.081730 39.159813  -39.081730 
  KS19   46.000        -53.000   blue    74.344066  -62.931669 17.655934  -62.931669 29.840187  -39.081730 62.159813  -39.081730 
  KS20   69.000        -53.000   blue    97.344066  -62.931669 40.655934  -62.931669 52.840187  -39.081730 85.159813  -39.081730 
  KS21   91.800        -53.000   blue    120.144066 -62.931669 63.455934  -62.931669 75.640187  -39.081730 107.959813 -39.081730 
  KS22  138.000        -20.000   blue    152.745230 -31.916290 123.254770 -31.916290 125.426795 -7.045135  150.573205 -7.045135  
  KS23  161.000        -20.000   blue    175.745230 -31.916290 146.254770 -31.916290 148.426795 -7.045135  173.573205 -7.045135  
  KS24  184.000        -30.000   blue    200.777377 -41.543614 167.222623 -41.543614 170.957582 -16.797623 197.042418 -16.797623 
  KS25  207.000        -30.000   blue    223.777377 -41.543614 190.222623 -41.543614 193.957582 -16.797623 220.042418 -16.797623 
  KS26  230.000        -20.000   blue    244.745230 -31.916290 215.254770 -31.916290 217.426795 -7.045135  242.573205 -7.045135  
  KS27  299.000        -53.000   blue    327.344066 -62.931669 270.655934 -62.931669 282.840187 -39.081730 315.159813 -39.081730 
  KS28  322.000        -53.000   blue    350.344066 -62.931669 293.655934 -62.931669 305.840187 -39.081730 338.159813 -39.081730 
  KS29  345.000        -53.000   blue    13.344066  -62.931669 316.655934 -62.931669 328.840187 -39.081730 1.159813   -39.081730
 

 

KELT Field Labels

 Top
mViewer -ct 1 \
        -color   "#808080"  \
        -grid     equ j2000 \
        -colorcol color \
        -imginfo  KELT_fields.tbl \
        -symbol   none \
        -labelcol label \
        -catalog  KELT_fields.tbl \
        -color    red \
        -imginfo  k2_footprints.tbl \
        -color    red \
        -imginfo  kepler_footprint.tbl \
        -gray     equatorial.fits -0.5s max gaussian-log \
        -out      KELT.png

To get labels, we return to the same KELT field list file. mViewer supports displaying a set of labeled symbols. Here we suppress the symbol and just get the labels. The coordinates and text come from the table. We can also specify where the label is placed relative to the "symbol" but haven't bothered here.

 

 

Putting It All Together

 Top
mViewer -ct 1 \
        -color   "#808080"  \
        -grid     equ j2000 \
        -colorcol color \
        -imginfo  KELT_fields.tbl \
        -symbol   none \
        -labelcol label \
        -catalog  KELT_fields.tbl \
        -color    red \
        -imginfo  k2_footprints.tbl \
        -color    red \
        -imginfo  kepler_footprint.tbl \
        -gray     equatorial.fits -0.5s max gaussian-log \
        -out      KELT.png

Finally, here is the completed command-line to generate the image shown at the beginning.

The various data files used are available here.