View Your Images In The World Wide Telescope With Montage

Purpose of this Tutorial

The WorldWide Telescope (WWT) (http://www.worldwidetelescope.org/) is a visualization tool for astronomical data, originally developed by Microsoft Corporation The American Astronomical Society (AAS) assumed responsbility for its management in January 2016, and at same time released the code with an Open Source license. The WWT offers Windows and Web Client interfaces, which allow users to pan and zoom across the sky, and disover and visualize image surveys and pointed observations.

Astronomical image data are almost always in the form of FITS (Flexible Image Transport System) files in a variety of sky projections, while WWT only consumes JPEG/PNG images in a custom projection called TOAST and tiled/named in a specific way. Montage supports the transformation of FITS data images with any standard astronomical projection into the WWT format and tiling scheme and this tutorial shows all the steps involved.

The data used in this tutorial comes from the Planck archive at IPAC. It started out life as a HEALPix FITS table, which we processed into image form using a process described in the Montage and HEALPix tutorial. We provide access to the image data we used in the end-to-end example at the end of this tutorial.

Here is an Aitoff projection map of the Planck data (for more on this, see the HEALPix tutorial):

Important Note: To use your data with the web version of WWT requires that the data files are URL-accessible under a web server like Apache. If you do not have direct control of such a location, you will have to make arrangements with someone who does.

Nomenclature

When viewed as a projection, HTM looks quite different from "normal" examples like gnomonic and simple cylindrical. There the transformation between pixel sky coordinates can be expressed by specific formulae. Determining what HTM cell or TOAST pixel corresponds to which location on the sky always requires starting with the base level HTM octant triangles and "drilling down"; finding arc midpoints, connecting them with great circle segments and determine which subcell we want based on vector dot- and cross-products.

All this seems like an awful lot of computation, especially when it has to be done for every corner of every pixel in an image. But in fact, given the simplicity of these vector operations, the total amount of computation involved is not that different from some existing "formulaic" projections, some of which require iterative solution or polynomial expansion with a large number of terms.

Another area where HTM/TOAST differs is that there are only a discrete set of pixel scales that are possible. We always start with the whole sky and we always subdivide the same way. So parameters from WCS like CDELT/CD (if they exist at all) are only informational with the "real" scaling being controlled by the HTM level parameter (which we have captured as keyword PV2_1).

Montage uses the WCS library distributed by SAO as part of their wcstools package. We have extended this to support TOAST (projection type TOA). Users must therefore call the version of the WCS library bundled with Montage.

Since Montage handles TOAST as a fully-function projection, the files produced are standard FITS images. They are still in data units and can be used by Montage as the basis of further reprojection and used as a set for background normalization, coaddition into mosaics, and so on.

SIMPLE  =                    T
BITPIX  =                  -64
NAXIS   =                    2
NAXIS1  =                  256 / All WWT tiles are
NAXIS2  =                  256 / 256x256 pixels.
CTYPE1  = 'RA---TOA'
CTYPE2  = 'DEC--TOA'
CRPIX1  =             -3072.50
CRPIX2  =             -1536.50
PV2_1   =                    5 / HTM level for this tile.
XTILE   =                   12 / X and Y tile indices
YTILE   =                    6 
CDELT1  =                 1.00 / The rest of the header
CDELT2  =                 1.00 / is really just boilerplate.
CRVAL1  =                   0. / Don't let the values get
CRVAL2  =                   0. / modified as it might affect
PC1_1   =                 1.00 / proper processing.
PC1_2   =                 0.00 
PC2_1   =                 0.00 
PC2_2   =                 1.00 
END

Here is an example TOAST FITS header. We have devised a formalism which is "good enough" for our principal use case of building tiles for use in WWT, but this may change somewhat if this TOA projection is formally incorporated into the FITS WCS framework.

Items to note:

• As mentioned earlier, the HTM level is given in keyword PV2_1.

• TOAST tiles (for WWT) are always 256x256 and are arranged in a regular XY array. We have included the "tile coordinates" in the parameters XTILE and YTILE, though these are not used anywhere in any computation. This is purely for informational purposes.

• The parameters CDELT, CRVAL, and the PC matrix are all fixed boilerplate (but for our use of the WCS library need to have these values.

• The CRPIX values are important and represent the pixel offset from the first pixel in our file and the edge of the "untiled" image for this HTM level (e.g., -256 * XTILE - 0.5).

• There is nothing to prevent this being used with datacubes (e.g., with wavelength as a third dimension) though WWT does not support such cases and the data would have to be cast into a single plane when generating TOAST PNG files.

Again, TOAST is a fully functional projection as far as Montage is concerned, so operations that work for any other projection work for TOAST as well. As long as the FITS header describing the TOAST file conforms to the above, both mProject and mProjectQL can be used to project to TOAST from any other projection (or from TOAST to any other for that matter).

While TOAST is targetted at visualization through WWT, the TOAST images themselves are not particularly well suited for direct inspection. This is most obvious in an all-sky image such as the one on the left. The image is mirror-imaged relative to a normal all-sky projection and there are serious discontinuities in the slopes of curves (as illustrated by the RA, Dec lines). Nevertheless, areas are reasonably well preserved and distances as well and this plus the feature that all pixel boundaries are identically great circle segments make it well suited to its primary task.

We are concentrating on the web version of WWT for this tutorial as we expect this is the mechanism most providers will use to get their data to the public. The Windows tool probably provides a little more flexibility, such as direct use of local files. For the web version, however, you must copy the PNG files generated above to a URL-accessible location.

In addition, you have to create an XML file describing this "collection", also as a URL-accessible file. There is a fair amount of flexibility in this XML but here is a basic template that works:

<?xml version="1.0" encoding="UTF-8"?>

<Folder Name="Montage Tests"
        Group="Explorer"
        Searchable="True"
        Type="Sky"
        Thumbnail="http://montage.ipac.caltech.edu/workspace/Planck/icon/color_AIT_small.png">


  <ImageSet Generic="False"
            DataSetType="Sky"
            BandPass="microwave"
            Name="Planck 857 GHz"
            Url="http://montage.ipac.caltech.edu/workspace/Planck/857/Planck{Q}.png"
            BaseTileLevel="0"
            TileLevels="5"
            BaseDegreesPerTile="180"
            FileType=".png"
            BottomsUp="False"
            Projection="Toast"
            QuadTreeMap="0123"
            CenterX="0"
            CenterY="0"
            OffsetX="0"
            OffsetY="0"
            Rotation="0"
            Sparse="False"
            ElevationModel="False"
            StockSet="False">

    <ThumbnailUrl>
       http://montage.ipac.caltech.edu/workspace/Planck/icon/Planck857_AIT_small.png
    </ThumbnailUrl>

    <Credits>
       Montage reverse grayscale example made from Planck HEALPIX 857 GHz data.
    </Credits>

    <CreditsUrl>
       http://montage.ipac.caltech.edu/
    </CreditsUrl>

  </ImageSet>

</Folder>

A few notes on this XML:

• We only show one <ImageSet> here; in our actual data we have several (one for each Planck wavelength and on color composite).

• The thumbnail images referenced were also generated by Montage using the same input data and an Aitoff (AIT) header:
  

• The choices of subdirectory names here are ours, not WWT's.

• The part WWT cares about is the tile naming expansion. This is controled by the {Q} in the tile URL template (which indicates we are using a nested quadrant scheme), the QuadTreeMap parameter ("0123") which indicates the ordering we used, and the TileLevels (5), which says how deep we went.

• The rest of it is boilerplate as far as we are concerned, though you may have reason to revisit this for you specific application.

Once you have put the data in a URL-accessible place, direct testing of access is easy, since you can retrieve and view individual tiles by entering their address in a browser. For instance, the highest resolution ρ Oph time we show above can be accessed (exactly as WWT will) at

      http://montage.ipac.caltech.edu/workspace/Planck/857/Planck2320.png

and you can poke at all the other tiles the same way.

At this point, you can load your data into WWT by bringing up the WWT interface

      http://www.worldwidetelescope.org/webclient/

Opening the menu item

      Explore / Open / Collection ...

      http://montage.ipac.caltech.edu/workspace/Planck/planck.xml

This example creates a complete tile set for WWT starting with the the Planck data described above. To fully complete it requires that you have access to file storage that is URL-accessible by www.worldwidetelescope.org. Specifically, the XML file you create in Step 8 is passed through a service on that machine rather than being used directly in the WWT client.

None of the directory and file names used here are required, though if you use something else you will have to remember to change those names wherever referenced.

Step 1 Setting up working directories:

Create a directory (e.g., "PlanckTiles") to contain all the working files and "cd" to it. Then create the subdirectories "hdr", "fits" and "png" which will each eventually contain 1365 files:

   mkdir PlanckTiles
   cd PlanckTiles
   mkdir hdr fits png

Step 2 Getting the input data:

The input image used by this tutorial can be downloaded here (400 MByte FITS file). Move it around in whatever way is easiest for you; if you have "wget", for instance, you can use:

   wget http://montage.ipac.caltech.edu/docs/WWT/images/Planck857.fits

Step 3 Generating tile headers:

As described above, the FITS headers needed for the WWT tiles can be generated using:

   mHdrWWTExec 5 hdr

The first argument is the maximum HTM level we want (~1 arcminute, which corresponds to the Planck data resolution).

Step 4 Generating tile FITS images:

This is the step that will take the longest, as it involves reprojecting the original Planck image into 1365 256x256 tiles of various resolutions. You have to be patient and let it finish:

   mProjWWTExec -d 1 5 Planck857.fits Planck hdr fits

Here we've turned on debugging at level 1, which for this program prints out each of the mProjectQL commands as it goes so you have something to watch while you wait.

Step 5 Generating tile PNG images:

Before generating the tile PNG files, we need to decide on a data stretch. As we said earlier, this is subjective, so the choices here were reached through trial and error. See the documentation on mHistogram/mViewer for more detail on what the parameters mean (or try out some different values yourself).

Once we have the stretch, we can generate the PNG files:

   mHistogram -file Planck857.fits min max gaussian -out Planck857.hist

   mPNGWWTExec -d 1 1 5 Planck fits Planck857.hist png

Step 6 Generating a thumbnail all-sky image:

You can use any image you want for the thumbnail that will be displayed in the WWT interface associated with your data. We've opted for an Aitoff all-sky version of the Planck data itself. This is just a regular reprojection and covered in other documentation (see here), so the steps are just outlined without comment:

   mProjectQL Planck857.fits Planck857_AIT.fits AIT.hdr

   mViewer -ct 1 -gray Planck857_AIT.fits -histfile Planck857.hist -out Planck857_AIT.png

   mShrink -f Planck857_AIT.fits Planck857_AIT_small.fits 90

   mViewer -ct 1 -gray Planck857_AIT_small.fits -histfile Planck857.hist -out Planck857_AIT_small.png

The first PNG file is really just for context; it gives you a reference for comparison in evaluating the thumbnail and the tile PNGs.

Step 7 Installing in a URL-accessible location:

The XML file describing your tile collection will have to reflect your server setup, so you first have to decide where you are going to put things on your machine. While not absolutely necessary, it is probably best to put a copy of the ./png directory, the thumbnail, and the XML file you will create in the next step in a directory named "Planck" in a location where the final URL path is also named "Planck".

You can go ahead and copy the Planck857_AIT_small.png file and the png directory to this location now. See the explanation above for the URL syntax to use to retrieve our instance of these files.

Step 8 Creating the collection XML for WWT:

<?xml version="1.0" encoding="UTF-8"?>

<Folder Name="Montage Test"
        Group="Explorer"
        Searchable="True"
        Type="Sky"
        Thumbnail="http://yourserver.edu/path/Planck/Planck857_AIT_small.png">


  <ImageSet Generic="False"
            DataSetType="Sky"
            BandPass="microwave"
            Name="Planck 857 GHz"
            Url="http://yourserver.edu/path/Planck/png/Planck{Q}.png"
            BaseTileLevel="0"
            TileLevels="5"
            BaseDegreesPerTile="180"
            FileType=".png"
            BottomsUp="False"
            Projection="Toast"
            QuadTreeMap="0123"
            CenterX="0"
            CenterY="0"
            OffsetX="0"
            OffsetY="0"
            Rotation="0"
            Sparse="False"
            ElevationModel="False"
            StockSet="False">

    <ThumbnailUrl>
       http://yourserver.edu/path/Planck/Planck857_AIT_small.png
    </ThumbnailUrl>

    <Credits>
       Montage reverse grayscale example made from Planck HEALPIX 857 GHz data.
    </Credits>

    <CreditsUrl>
       http://yourserver.edu
    </CreditsUrl>

  </ImageSet>

</Folder>

Once you have finished updating it, copy it to the URL space you have already set up.

Step 9 Testing through WWT:

You should now be able to open your copy of the Planck data in WWT. As described above, go to:

      http://www.worldwidetelescope.org/webclient/

Opening the menu item

and enter the URL of your XML file:

      http://yourserver.edu/path/Planck/planck.xml

We maintain a copy of these files on the Montage server, so you can see the results of the above processing but cutting the following URL and pasting it into the WWT interface:

       http://montage.ipac.caltech.edu/workspace/Planck/planck.xml