WTML stands for Worldwide Telescope Markup Language. It is one of three file formats native to WWT, the others being WTT files to store tours and WWTFIG to store constellation figures. If you want to host any such files on your servers, you will need to add them to the list of mime types supported by the servers. The entries for those are :
| | File Extension | Mime Type |
| WWT Collections (and Communities) | .wtml | application/x-wtml |
| WWT Tours | .wtt | application/x-wtt |
| WWT Constellation Figures | .wwtfig | application/x-wwtfig |
WWT also uses the astronomy standard VOTable format from the IVOA (International Virtual Observatory Alliance) to transfer data, but that is another blog post.
WTML files can be used for the following purposes
- Storing collections. A collection can be thought of as a hierarchy/tree of folders, each folder contain a mixture of folders and objects (in the same way that a file folder contains a mixture of file folders and files). Objects can be
- tours
- studies. A study is a photograph of a small part of the sky e.g. a Hubble image of the Crab Nebula. The WTML entry for a study does not contain the image itself, but instead
- the location on the internet (or on your hard disk) where the study is stored
- Coordinates – how to show the study on the sky
- Metadata - title, alternative names, credits, etc for the study
- panoramas
- planets
- all-sky surveys
- locations on the sky
- The ‘sign up’ file for a community. This points to the collection that defines the holding the data for the community.
Here is an example of a WTML file that defines a collection called ‘Samples’.
The Samples collection has two folders, called ‘Some Tours’ and ‘Some Studies’.
The Some Tours folder has two tours, while the Some Studies folder has two studies.
The structure of the WTML file looks something like this:
<?xml version='1.0' encoding='UTF-8'?>
<Folder Name = "Samples">
<Folder Name="Some Tours" Group="Tour">
<Tour Title="Over Mars" . . . />
<Tour Title="Apollo Missions" . . . />
</Folder>
<Folder Name="Some Studies" Group="Explorer" Searchable="True" Type="Sky" Thumbnail="">
<Place Name="Hubble Scores a Perfect Ten" . . . > . . . </Place>
<Place Name="Hubble Directly Observes Planet Orbiting Fomalhaut" . . .> . . .</Place>
</Folder>
</Folder>
The Folder tags determine the structure of the hierarchy. The tag can have several attributes. Group is usually set to “Explorer”; it is set to “Tour” for a folder of tours. It can also have a thumbnail by setting the Thumbnail attribute to the location of a 96 x 45 image on the web. If no thumbnail is provided, the standard folder thumbnail is used. Searchable should be set to “True” (not “true" since case is important) for folders with studies so that they can be found using WWT’s search mechanism. Type is set to “Sky” for studies – its other possible values are “Planet”, “Panorama” and “Survey” (covered in future examples).
The Tour tags contain entries for tours.
The Place tags contain entries for studies (‘places on the sky’).
Now, here is the full file. You can also get to it from here: wtml , txt .
<?xml version='1.0' encoding='UTF-8'?>
<Folder Name ="Samples">
<Folder Name="SomeTours" Group="Tour">
<Tour Title="Over Mars"
ID=""
Description="A trip to Mars"
Author="Dinoj Surendran"
OrganizationName="Microsoft Research"
AuthorImageUrl="http://research.microsoft.com/~dinos/live2eat_tn.jpg"
ThumbnailUrl="http://research.microsoft.com/~dinos/wwtexp/overmars_tn.jpg"
TourUrl="http://research.microsoft.com/~dinos/wwtexp/marsTake11.wtt"
LengthInSecs=”258” />
<Tour Title="Apollo Missions"
ID=""
Description="Brief history of Apollo missions"
Author="Dinoj Surendran"
OrganizationName="Microsoft Research"
AuthorImageUrl="http://research.microsoft.com/~dinos/live2eat_tn.jpg"
ThumbnailUrl=”http://research.microsoft.com/~dinos/moony.jpg”
TourUrl="http://research.microsoft.com/~dinos/moony.wtt"
LengthInSecs=”243”
OrganizationUrl=”http://research.microsoft.com”
AuthorEmail=”dinos@microsoft.com”
AuthorUrl=”http://research.microsoft.com/~dinos”
Keywords=”Apollo;Moon” />
</Folder>
<Folder Name="Some Studies" Group="Explorer" Searchable="True" Type="Sky" Thumbnail="">
<Place Name="Hubble Scores a Perfect Ten"
DataSetType="Sky"
RA="3.18858333333333"
Dec="1.31471944444444"
ZoomLevel="0.2"
Opacity="100"
Constellation="CET">
<ForegroundImageSet>
<ImageSet DataSetType="Sky"
BandPass="Visible"
TileLevels="3"
Url=http://research.microsoft.com/~dinos/wwtexp/530919080/{1}/{3}/{3}_{2}.png
CenterX="47.828862896748753"
CenterY="1.3146065774006597"
Rotation="-5.0799999999999867"
BaseDegreesPerTile="0.02842076047738"
FileType=".png"
WidthFactor="2"
Projection="Tangent">
<Credits>NASA, ESA, and M. Livio (STScI)</Credits>
<CreditsUrl>http://hubblesite.org/newscenter/archive/releases/2008/37/</CreditsUrl>
<ThumbnailUrl>http://research.microsoft.com/~dinos/wwtexp/530919080.jpg</ThumbnailUrl>
</ImageSet>
</ForegroundImageSet>
</Place>
<Place Name="Hubble Directly Observes Planet Orbiting Fomalhaut"
DataSetType="Sky"
RA="22.9608472222222"
Dec="-29.6222361111111"
ZoomLevel="0.123333333333333"
Opacity="100"
Constellation="PSA"
Classification="Unfiltered"
Magnitude="0"
Distance="0"
Rotation="0"
Angle="0"
AngularSize="1">
<ForegroundImageSet>
<ImageSet DataSetType="Sky"
BandPass="Visible"
TileLevels="4"
Url=http://research.microsoft.com/~dinos/wwtexp/934203617/{1}/{3}/{3}_{2}.png
CenterX="344.412708333333"
CenterY="-29.6222361111111"
Rotation="0"
BaseDegreesPerTile="0.0220985710119568"
BaseTileLevel="0"
FileType=".png"
WidthFactor="2"
Sparse="True"
QuadTreeMap=""
Projection="Tangent"
Name=""
BottomsUp="False"
OffsetX="0"
OffsetY="0">
<Credits>NASA, ESA, P. Kalas (UC Berkeley) et. al.</Credits>
<CreditsUrl>http://hubblesite.org/newscenter/archive/releases/2008/39</CreditsUrl>
<ThumbnailUrl>http://research.microsoft.com/~dinos/wwtexp/934203617.jpg</ThumbnailUrl>
</ImageSet>
</ForegroundImageSet>
</Place>
</Folder>
</Folder>
Let’s now have a look at the individual entries in closer detail. First, tours.
<Tour Title="Over Mars"
ID=""
Description="A trip to Mars"
Author="Dinoj Surendran"
OrganizationName="Microsoft Research"
AuthorImageUrl="http://research.microsoft.com/~dinos/live2eat_tn.jpg"
ThumbnailUrl="http://research.microsoft.com/~dinos/wwtexp/overmars_tn.jpg"
TourUrl="http://research.microsoft.com/~dinos/wwtexp/marsTake11.wtt"
LengthInSecs=”258” />
There are other attributes that the Tour element can have, some of which are shown in the entry for the Apollo tour, but these are the ones that control how the tour is displayed. (See picture below.) Most of this information would have been entered in the Tour Properties panel when you made the tour, so you might be wondering why you are being asked to enter it again. That is because your tour may not have been downloaded by the WWT user by the time she sees the information in the panel about the tour. So this entry is not just an entry for your tour, but an advertisement for it. Therefore, make your Description of it much more appetizing than the one used in this example!
Title is the name of the tour.
Author is the name of the tour creator.
OrganizationName is the name of the institution, if any, that the author is making the tour for. Set to “” if it is not applicable.
ID must be supplied… as an empty string “” for now.
Description is a description of the tour. It can also include credits e.g. whose music or narration or images were used.
TourUrl points to the location on the web where the wtt file containing the tour.
ThumbnailUrl points to a 96 x 45 thumbnail for the tour. The white ‘T’ in the top right is added automatically by WWT; you do not need to put it in.
AuthorImageUrl points to a 72 x 96 thumbnail of the author, a picture that is typically more recent than the one used in the example here.
LengthInSecs is the duration of the tour in seconds. The world will not explode if it is incorrect.
Now that you know enough about WTML entries for tours, let’s consider WTML entries for studies.
Study images are stored in image pyramids. Given a H x W pixel study, we represent it as a N x N pixel image where N is the smallest power of 2 that is at least as big as H and W. In other words, N = 2^ceiling(log_2(max(H,W))). The extra area not covered by the H x W photograph is occupied by transparent pixels. This forms the lowest level of the pyramid, with each next level contains a lower-resolution version of the original image with each level’s image having half the height and half the width as (i.e. four times smaller than) the image in the previous level. At each level, the image there is chopped up
For example, suppose we had a 1457 x 1201 study image, such as this Spitzer image to the right. We embed it in a 2048 x 2048 image and store it in a pyramid with four levels 0, 1, 2, 3. (Note: Number of Levels = 1 + Maximum Level)
At level 3 are 64 (=8 x 8) 256x256 tiles that partition the 2048 x 2048 image.
At level 2 are 16 (=4 x 4) 256x256 tiles representing a downsampled 1024 x 1024 version of the image. Here they are, with the grey shadows showing the transparent regions. Some of the tiles have been labelled with X and Y coordinates between 0 and 3 inclusive as well. That is how we access individual tiles of the pyramid, specifying its (X,Y) coordinates within the 2^L x 2^L grid of tiles at level L.
At level 1 are 4 (=2 x 2) 256x256 tiles representing a further downsampled 512 x 512 version of the image.
At level 0 is a downsampled 256x256 version of the image, as shown below.
The WTML entry for this study is below. Its location is about Right Ascension = 47.83 degrees (3h 11m 19s) and Declination 1.32 degrees (1d 18m 53s) in J2000 coordinates, and it is about 20 arcseconds wide.
<Place Name="Hubble Scores a Perfect Ten"
DataSetType="Sky"
RA="3.18858333333333"
Dec="1.31471944444444"
ZoomLevel="0.2"
Opacity="100"
Constellation="CET">
<ForegroundImageSet>
<ImageSet DataSetType="Sky"
BandPass="Visible"
TileLevels="3"
Url=”http://research.microsoft.com/~dinos/wwtexp/530919080/{1}/{3}/{3}_{2}.png”
CenterX="47.828862896748753"
CenterY="1.3146065774006597"
Rotation="-5.0799999999999867"
BaseDegreesPerTile="0.02842076047738"
FileType=".png"
WidthFactor="2"
Projection="Tangent">
<Credits>NASA, ESA, and M. Livio (STScI)</Credits>
<CreditsUrl>http://hubblesite.org/newscenter/archive/releases/2008/37/</CreditsUrl>
<ThumbnailUrl>http://research.microsoft.com/~dinos/wwtexp/530919080.jpg</ThumbnailUrl>
</ImageSet>
</ForegroundImageSet>
</Place>
Let’s start with the ImageSet tag first.
DataSetType should be set to “Sky” since this is a study.
BandPass refers to the primary wavelength in which the image was taken. This is not used much by WWT, and only allows one wavelength to be stored (even for composite images). The possible values are (case-sensitive) Gamma, XRay, Ultraviolet, Visible, HydrogenAlpha, IR, Microwave, and Radio.
TileLevels is the maximum level of the image pyramid used to store the study. This study uses 4 levels numbered d 0 to 3, so TileLevels is 3.
Url is a url that returns a 256 x 256 tile of a specific part of the image pyramid. In this case, it is a path to an image on the web, but it can be any url (e.g. a SQL query) that contains {1}, {2}, {3} in it for L (level), X, and Y respectively. For example, if L is 2, X is 0 and Y=3, this would be http://research.microsoft.com/~dinos/wwtexp/530919080/2/3/3_0.png
FileType is the extension of the files – either .jpg or .png . Remember to include the period. (And if you must use JPEG, please use 100% quality for everyone’s sake!)
CenterX : Right Ascension of the center of the image
CenterY : Declination of the center of the image
Rotation: Angle at which image is inclined
BaseDegreesPerTile : Right, now this is not intuitive… though it is well defined. This is the number of degrees of declination that the top tile of the pyramid occupies on the sky. Alternatively, remember how we embedded each study in a larger 2^n x 2^n image? This is also the number of degrees of declination that that larger image occupies on the sky. In this case, our 1457 x 1201 study is about 1 arc minute high. Multiply that by 2048 / 1201 and you get 0.0284… degrees
Project : Always set this to Tangent for studies since studies are tangentially projected.
WidthFactor : Ignore what this actually means and just set it to 2. It’s some technical detail, some WWT historical tidbit that is more gory than glory.
Credits: Brief description of where the image came from, who made it, etc.
CreditsUrl: Where you can get more information on the image
ThumbnailUrl: A link to a 96 x 45 image with a thumbnail for the study.
Right, so that defines how the image is set on the sky. The rest of the Place tag looks like this:
<Place Name="Hubble Scores a Perfect Ten"
DataSetType="Sky"
RA="3.18858333333333"
Dec="1.31471944444444"
ZoomLevel="0.2"
Opacity="100"
Constellation="CET">
<ForegroundImageSet>
<ImageSet . . .> . . . </ImageSet>
</ForegroundImageSet>
</Place>
This defines how the image is viewed on the sky. You know how in WWT when you double/click on a study thumbnail it takes you there? The RA, Dec, and ZoomLevel entries determine the viewpoint where you zoom to.
Name : The title of the study. Alternate names can be included; just separate them using semicolons.
RA : Right Ascension, in hours, of the center of the viewpoint for the study. You usually want this to be the center of the image. For historical reasons, this is between 0 and 24 hours, so we divided the RA of the image (CenterX) in the ImageSet tag (which is between 0 and 360 degrees) by 15.0.
Dec : Declination, in degrees, of the viewpoint for the study. Here it equals CenterY.
ZoomLevel : Height of the viewpoint in degrees.
DataSetType : Set to Sky.
Opacity : Set to 100.
Constellation : Determines constellation shown in the Study Properties panel. Set to the three-letter code (see here for list) of the region of sky where the study is. No kittens will die if you set it to an arbitrary value such as “AND” for Andromeda initially and correct it later.
There are other details we have not mentioned, such as how (CenterX,CenterY) are really the coordinates of the reference pixel of the image that is defined by fields called OffsetX and OffsetY. Their default settings of OffsetX=OffsetY=0 cause the reference pixel of the image to be its center. Another one is Classification, which defines what kind of study it is (case-sensitive choices are listed here), the default being Unfiltered, which means it has not been filtered into a category yet.
But this should be enough to get you started.