“Studies”: Tiling high-resolution images¶
In the AAS WorldWide Telescope framework, “studies” are high-resolution sky images projected on the sky in a tangential (gnomonic) projection. Due to the properties of this projection, the “study” format is best suited for images that are large in terms of pixels, but not necessarily large in terms of angular area. Examples of this kind of imagery include nearly all astrophotography images and typical scientific observations. Mosaics that cover extremely large regions of the sky (multiple steradians) are better represented in the all-sky TOAST format.
The intent of the toasty package is to make it so that most tiling workflows can
be executed on the command line using the
toasty program. This section will
demonstrate this way of using the software.
Tiling study images should generally be easy, and in many circumstances the process can be completely automatic. If there’s one part of the process most likely to cause problems, it is generating the “astrometric” information that specifies where the image should be placed on the sky.
When creating a new WWT study dataset, you need to determine how or where the necessary astrometric information will come from. Your options are:
AVM tags in the source image. Except we haven’t wired this up for basic study processing! Fix this!!!
Pre-positioning in the WWT Windows client and exporting as a WWTL file. If you have a large image that you can load in the WWT Windows client, you can use its interactive placement feature to set its position, and then save the image with that placement as an “image layer” in a WWTL “layers file”, then can load the image and its astrometry using the toasty tile-wwtl command.
If all else fails, the toasty tile-study command will insert default astrometric information and place your image at RA = Dec = 0 and make it 1° across. You can then manually edit the WTML to properly place the image against a reference. This can be less horrible than it sounds, but it’s definitely not good.
Standard workflow 1: manual positioning in the Windows client¶
In the typical study workflow, you have a single source image, potentially very large, that needs to be broken into tiles and described in a WTML file. If you have access to the Windows client and can position the image manually, the standard workflow proceeds as follows:
Choose and/or create a directory on your computer in which you’ll be working.
Download the source image to your work directory. For concreteness, we’ll call it
fullsize.tifhere, but multiple image formats are supported.
Open the image in the WWT Windows client, position it interactively, and export the positioned image layer as a WWTL layer file. We’ll call that
Do the initial tiling and astrometry extraction with:
$ toasty tile-wwtl --outdir=tiled fullsize.wwtl
Here it might make sense to use some of the Standard image-loading options to control how the source image is processed. Along with the tiles, this command will generate a file
tiled/index_rel.wtmlthat describes the image data, including their astrometry.
Generate the higher-level tiles with:
$ toasty cascade --start=5 tiled
where the number passed to the
--startargument will change depending on the characteristics of your image. The
tile-wwtlcommand will tell you what value to use.
Examine the image
tiled/0/0/0_0.pngto see if it looks like a reasonable reduction of your large source image.
Review the appearance of your image in WWT. Use the
wwtdatatoolcommand provided by the wwt_data_formats Python package to start up an HTTP server that will make your WTML and tile data accessible to WWT (either Windows or web clients):
$ wwtdatatool serve tiled
This command will print a URL to a synthetic
index.wtmlfile that you can open up in WWT to view your tiled image. Hopefully everything will be fine, but at this point you can tune and/or fix the tiling procedure if something isn’t right.
Fill in proper metadata in the
index_rel.wtmlfile. Items to consider are:
<Credits>XML element with proper credit text.
<CreditsUrl>XML element with a link to the image source and/or more information about it.
<Description>XML element with text describing the image. If editing the XML manually, make sure to properly escape the magic XML characters
Nameattributes of the
<Folder>elements. These should generally all be the same.
ZoomLevelattribute of the
<Place>element, specifying the zoom level that the client should seek to when viewing the image. It can be a bit subjective as to what zoom level is best, and the numbers are measured oddly so choosing the right value is generally a matter of trial and error.
Other metadata like the
index_rel.wtmlfile is all finalized, it needs to be transformed to have absolute rather than relative URLs. To do this transformation, you need to know the URL from which users will be accessing your data. When you know that base URL, the command to use is of this form:
$ wwtdatatool wtml rewrite-urls \ tiled/index_rel.wtml \ http://data1.wwtassets.org/packages/2020/07_phat_m31/ \ tiled/index.wtml
(Here, the backslashes are used because the command spans multiple lines of the shell prompt. If you type it all on one line, no backslashes should be used.)
Finally, upload the complete contents of your
tiledsubdirectory to your web server. In this case, the upload location should be such that the url http://data1.wwtassets.org/packages/2020/07_phat_m31/index.wtml will yield the
index.wtmlfile created in the previous step.
And that’s it, your image has been tiled and published!