Note: This documentation is preliminary and subject to change.

This document describes the data file formats used by the WorldWide Telescope. The files are XML files, and have the extension .WTML. Also covered are a few URL based controls that enable the sharing of single images without creating data files.

Data files are used to add to the default data and user experience of WorldWide Telescope. Data files are used to add single or multiple images -- either foreground images (typically single images referred to as studies) or background images (typically created from a large number of images, covering all or most of the sky, and referred to as surveys), to add tours (animated slide-shows), to create sign up files for communities (public or private groups that can share data), and to add simple or complex sets of data and links for those communities.

Table of Contents

• Collections Files
• Places
• Studies
• Surveys
• Tours
• Communities
• Including Other WTML Files
• WTML Samples
• Sharing Views
• Goto
• ShowImage
• Command Line
• Appendices
• Classifications
• Constellations
• Taxonomy

See Also

• WorldWide Telescope Authoring
• WorldWide Telescope Data Tools Guide
• WorldWide Telescope Projection Reference
• WorldWide Telescope Web Control Script Reference

Collections Files

A collection is a friendly name given to a WTML file. WTML is the user-editable file format designed specifically for WorldWide Telescope. The Explore menu entry that WorldWide Telescope users will be very familiar with, is essentially a WTML browser.

Fairly simple examples of WTML files are those that contain only one type of object entry, for example a list of tours, or a list of studies. Potentially one of the most complex is a community payload file, which will often contain a hierarchy of folders, each folder containing a collection of sub-folders and objects. Objects can be tours, studies, panoramas, planets, all-sky surveys, and links. Examples of the most common types of WTML file are listed in the samples section.

• Structure of a Collection File
• Places
• Studies
• Surveys
• Tours
• Communities
• Including Other WTML Files
• WTML Samples

See Also

• WorldWide Telescope Data Files Reference

Structure of a Collection File

A collection file is coded in xml, and is a hierarchical collection of Folder entries. The following example can be loaded into WorldWide Telescope and will appear as the image below, even though all the folders are empty. The example is based on a community payload file, though a very similar structure would apply to a hierarchical selection of tours or studies.

Note that the Name entries appear in the upper panel of WorldWide Telescope, and that one unique thumbnail image for each Folder is helpful (though not required, a default thumbnail will be used if none is provided), and more thumbnail images will be helpful for each entry within each Folder. A substantial number of thumbnail images can be necessary if the collection file is large.

Blank Collection.WTML

<?xml version="1.0"?> <Folder      Name="Blank Collection"      Group="Explorer"      Searchable="True"      Type="Earth"     Thumbnail="http://...../Images/T_Earth.jpg">         <Folder          Name="Our Tours"          Group="Tour"          Thumbnail="http://...../Images/T_Tours.jpg">         <!-- Tour entries go in here -->            </Folder>      <Folder          Name="Our Studies"          Group="Explorer"          Searchable="True"          Type="Sky"          Thumbnail="http://...../Images/T_Star.jpg">                <!-- Studies go in here -->      </Folder>      <Folder          Name="Context"          Group="Search"          Searchable="True"          Browseable="False"          Type="Sky">              <!-- Context only entries go in here -->     </Folder>     <Folder          Name="Our Links"          Group="Explorer"          Searchable="True"          Type="Sky"         Thumbnail="http://...../Images/T_Red.jpg">         <!-- Link entries go in here -->     </Folder>     <Folder          Name="Our Downloads"          Thumbnail="http://...../Images/T_Saucer.jpg">         <!-- Catalogs (pdf files, Word documents) go in here -->              </Folder>   <!-- Some top level place entries go in here -->    </Folder>

See Also

• Collections Files
• WorldWide Telescope Data Files Reference
• WTML Samples

Places

A place is simply a location for the view. Place entries are used within Studies to contain imagery, but can be present in a collection file as viewing points without any additional images. Place entries can also be used to hold links to web pages (articles, supporting documents, community website, and so on).

The following shows an example of a Place entry in Sky mode (a view of the southern star Canopus).

The following shows an example of a Place entry in Planet mode (the location of Olympus Mons on Mars).

The following shows an example of a Place entry containing a link (to a high definition image of a gully on Mars):

Thumbnail Images

Thumbnail images are used frequently throughout WorldWide Telescope to provide an image to go along with a link, either in the top pane under Collections or Tours, or in the lower pane as part of a context search. Typically if you prepare your own data you may well create a thumbnail image for it - usually be taking a screen shot then capturing a rectangle of interest to match the fixed sizes of the thumbnails given in this document. Note that URL entries for thumbnails should always reference the full path, and not a relative path.

An alternative is to request a thumbnail image from the thumbnail server. This is done by entering appropriate text at the end of the following query (the example requests a thumbnail where the title contains the word "Mars"):

If a thumbnail image is not found containing the supplied text, as suitable default is used.

See Also

• Collections Files
• WorldWide Telescope Data Files Reference
• WTML Samples

Studies

Study images are stored in image pyramids. Given an W x H pixel study, it is represented as an N x N pixel image where N is the smallest power of 2 that is at least as big as W and H. In mathematical terms, N = 2^ceiling(log_2(max(W,H))). In simpler terms, if a study image is 958 by 768 pixels, it will be embedded in a 1024 x 1024 square bitmap. The extra area not covered by the W x H photograph is occupied by transparent pixels. This forms the lowest level of the pyramid, with each level up containing a lower-resolution version of the original image with half the height and half the width of the image at the previous level. At each level, the image is further divided up into 256 x 256 tiles.

The process of dividing up an image into this pyramid of tiles can be done using the Study Chopper tool. This tool not only creates the correct tiles, but places them in the required directory structure, and outputs sample WTML files to load them into WorldWide Telescope. The Study Chopper tool is included with the WorldWide Telescope May 2009 ADK.

For example, suppose we had a 1457 x 1201 study image, such as this Spitzer image of Galaxy NGC 4579.

This image should be embedded in a 2048 x 2048 image and stored in a pyramid with four levels 0, 1, 2, 3. At level 3 there would be 64 256 x 256 tiles containing the entire image (no image is shown here for this level). The 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 arc seconds wide.

Level 2

At level 2 there are 16 256x256 tiles representing a down-sampled 1024 x 1024 version of the image. The grey shadows show the transparent regions. Some of the tiles have been labeled with X and Y coordinates between 0 and 3 -- which is how individual tiles of the pyramid are addressed at each level.

Level 1

At level 1 there are 4 256x256 tiles representing a further down-sampled 512 x 512 version of the image.

Level 0

At level 0 there is a single down-sampled 256x256 version of the image.

The following table describes how the Galaxy NGC 4579 image might be entered into a date file. The Place entry should be considered the position of the view, and the ImageSet entry the position of the image itself.

The following images give examples of how the appearance of an image can be changed by varying some of the parameters.

Image Manipulation
The following text shows the starting point, with the resulting image shown below.
Changing the Rotation entry of the ImageSet to 45 will result in a 45 degree left rotation. If the Rotation was set at -45, the rotation would be to the right.
Leaving the ImageSet Rotation at zero, and changing the Place Rotation to -45 degrees, results in the following image. Note the apparent variation in the angle of the image, as the view is not perfectly aligned with the center of the image.
Leaving both rotation values at zero, and doubling the ZoomLevel to 0.246666:
Changing the ZoomLevel to 10 results in a much more distant image:
Changing the Opacity setting for the view to 25 (percent):
Applying an offset to the image (OffsetX = 0.001, OffsetY == 0.002), results in a slight displacement of the image up and to the right.

See Also

• Collections Files
• WorldWide Telescope Data Files Reference
• WTML Samples

Surveys

Surveys typically contain image data for the entire sky. The most popular surveys are inevitably at the visual wavelengths, however there are many other options at non-visible wavelengths -- such as radio, x-ray, gamma, and so on. Comparing the visual appearance of an object with a graphical representation of one of the non-visible wavelengths is an important feature of WorldWide Telescope.

This section describes the WTML file format used to contain survey data.

Survey Data

Preparing a full sky survey involves a huge amount of data collection and preparation, and a comparatively simple WTML collection file to render it. The Toast projection system for survey data is described in the WorldWide Telescope Projection Reference, and the Sphere Toaster tool used to prepare data is described in the WorldWide Telescope Data Tools Guide.

Similar to studies, the source image data is converted into an image pyramid for ease of rendering.

The WTML collection file used to render a survey is simpler than that for a study, as no positional data is needed. The orientation of the survey is determined using the Sphere Toaster tool.

See Also

• Collections Files
• WorldWide Telescope Data Files Reference
• WTML Samples

Tours

The actual content of a tour is stored in a .WTT file. These files include a lot of binary information and are not designed to be human-readable. However, WTML files can contain references to tours. These references can be used in conjunction with a set of images, so that an appropriate tour or range of tours is available for the new image data (the references to the new images are embedded in the WTT file). Alternatively of course tour collections can be put together for existing image data.

All but two of the parameters in a Tour entry are optional, and are identified in the table.

The following example shows the minimal meaningful information necessary to add a Tour entry.

See Also

• Collections Files
• WorldWide Telescope Data Files Reference
• WTML Samples

The default tours used by the Windows version of WorldWide Telescope are held in the tours.WTML file, in the following locations:

Windows Vista: C:\Users\<userid>\AppData\Local\Microsoft\WorldWideTelescope\data\

Windows XP: C:\Documents and Settings\<userid>\Local Settings\Application Data\Microsoft\WorldWideTelescope\

Currently there is not a supported process to add your own tours to this file.

See Also

• Collections Files
• WorldWide Telescope Data Files Reference

Communities

Communities are the primary way in which WorldWide Telescope users can share data and tours with each other. Communities can be made by any user, but typically are individuals or organizations, such as planetariums, science centers, astronomy clubs, magazines, bloggers, schools, classes, and for class projects. There is no limit to the number of communities that can be set up.

• Setting up a Community

See Also

• Collections Files
• WorldWide Telescope Data Files Reference
• WTML Samples

Setting up a Community

You can set up your own community using your own servers and without any contact with Microsoft. However, you may prefer to have your community listed it on the WorldWide Telescope Community Directory (a subset of which is shown on the WWT Support page). To do this, send an email to WWTCommunity@microsoft.com, requesting that your community be listed. To be considered for inclusion in the community directory, community sites must maintain standards in terms of quality, scalability, and content appropriateness. These standards include:

• Sign-up membership can be required by your community, but community access must remain free for all users.
• Community content must be well moderated, free of hate speech, and reflect currently accepted astronomical information/theory. The installation must have sufficient capacity for handling projected traffic.
• The community must make use of integrated WorldWide Telescope features such as tours, sky-aligned images, and so on. Not just simple HTML links to existing web content.

To set up a community go through the following steps:

• Step 1: Set the Mime Types
• Step 2: Create a Thumbnail Image
• Step 3: Create a Payload File
• Step 4: Create a Signup File
• Step 5: Accessing the Community

See Also

• Collections Files
• WorldWide Telescope Data Files Reference

Step 1: Set the Mime Types

To set up a community, you should first add the WorldWide Telescope file extensions to the mime types on your server.

See Also

• Setting up a Community

Step 2: Create a Thumbnail Image

Create a thumbnail image for the community. This should be 176 wide by 45 pixels in height.

Sample community thumbnail.

See Also

• Setting up a Community

Step 3: Create a Payload File

The payload file contains the main content for a community. This file determines the folder structure, images, tours, community metadata, and so on. In its simplest form, a payload file can be a static WTML file that is hand-edited on the server side. Alternatively it can be generated from a database, and so might be much easier to update regularly.

Typically payload files contain the following:

• Tours
• Study Images
• Surveys
• Panoramas
• Places: lists of locations (Place entries without an ImageSet)
• Catalogs
• Constellation figures (files with the WWTFIG extension)
• Links to articles or the organization’s website
• Links to Blog entries, forums, conversation threads, discussion boards

A sample community payload file is Community Payload.html.

See Also

• Setting up a Community

Step 4: Create a Signup File

A signup file is a short WTML file that points to the thumbnail and payload files, and gives the title of the community. The following table shows a sample signup file, based on the signup file for the WWT Data Community.

A sample community signup file is also listed at Join Our Community.html.

See Also

• Setting up a Community

Step 5: Accessing the Community

The signup file should be placed in a web-accessible location, and appropriately linked to from your institution/organization/club website.

See Also

• Collections Files
• Setting up a Community
• WorldWide Telescope Data Files Reference
• WTML Samples

Including Other WTML Files

A WTML file can include references to other WTML files, which can then be used to build up collections of collections, or add studies and surveys to a community payload file, for example. To include another WTML file in a collection, add the following entry:

See Also

• Collections Files
• WorldWide Telescope Data Files Reference
• WTML Samples

WTML Samples

The following table lists the samples that can be used as a starting point for WorldWide Telescope WTML file development.

Click on the Sample Name to view the source. Note that paths may need to be changed for the samples to work, these paths are highlighted by comments in the sample code.

See Also

• Collections Files
• WorldWide Telescope Data Files Reference

Sharing Views

There are two single URL based controls, Goto and ShowImage that enable the sharing of views by simply providing recipients with the URL. Goto is the simpler of the two, and enables a link to a particular point in space (RA, Dec and Zoom) to be captured, and then sent, for example, by email. ShowImage is similar, but includes more information (including a link to an image) that enables the sharing of that single image, without the need to write a WTML data file or create a community. If a valid data file does exist, a command line parameter can be used to initiate the Windows Client version.

• Goto
• ShowImage
• Command Line

See Also

• WorldWide Telescope Data Files Reference

Goto

To capture a link from WorldWide Telescope, right click to bring up the Finder Scope, select Research then Copy Shortcut from the menu. This will encode the current view into a URL.

The base of the URL is as follows:

Following this there are four required parameters, separated by the ampersand (&) symbol:

For example:

• http://www.worldwidetelescope.org/wwtweb/goto.aspx?object=NGC117&ra=0.453&dec=1.333888889&zoom=0.157005192359341

If the receiver of the email clicks on this link, it should open up the Web client version of WorldWide Telescope, and provide a thumbnail that can be selected for the specified view to be rendered:

Note that the shortcut can be captured from either the Windows Client or Web Client versions of WorldWide Telescope. Clicking on the link will open up the Web Client version unless the wtml=true parameter is set.

See Also

• Sharing Views

Show Image

The ShowImage control enables an image to be shared, by embedding information about the image in a URL. The URL could then, for example, be emailed to colleagues who could then view the image in WorldWide Telescope simply by clicking on the link. Unlike Goto, there is no automated way of creating the URL from within WorldWide Telescope.

Of course the image, and optionally a thumbnail of it, must be web accessible for this to work. The image should also have a maximum size of 2048 x 2048 pixels. If larger sized images are required, then WTML data files should be set up to tile the image correctly (refer to the WorldWide Telescope Data Tools Guide).

The base of the URL is as follows:

Add to this base the following parameters, with an ampersand (&) between each parameter.

Examples

The example URL shown below will only result in a default thumbnail and the name being added to the Open Collections. For the user receiving the URL to view the image, they will need to click on the thumbnail.

http://www.worldwidetelescope.org/wwtweb/ShowImage.aspx?name=Horsehead+APOD%20&ra=85.2983&dec=-2.42589&x=450&y=300&scale=1.69&rotation=90.21&imageurl=http://antwrp.gsfc.nasa.gov/apod/image/0811/horsehead_caelum.jpg

In this second example the optional parameters thumb= and credits= and creditsUrl= have been added, to improve the experience for the user receiving the URL. When the image appears, note the better looking thumbnail image, and the credits text and link in the Properties panel.

http://www.worldwidetelescope.org/wwtweb/ShowImage.aspx?name=Horsehead+APOD%20&ra=85.2983&dec=-2.42589&x=450&y=300&scale=1.69&rotation=90.21&imageurl=http://antwrp.gsfc.nasa.gov/apod/image/0811/horsehead_caelum.jpg&thumb=http://research.microsoft.com/~dinos/wwtimages/tn_horsehead_caelum.jpg&credits=Adam+Block+Mt.+Lemmon+SkyCenter+U.+Arizona&creditsUrl=http://antwrp.gsfc.nasa.gov/apod/ap081126.html

In this third example, the collection file is opened in the Windows Client, rather then Web Client, version:

http://www.worldwidetelescope.org/wwtweb/ShowImage.aspx?name=Horsehead+APOD%20&ra=85.2983&dec=-2.42589&x=450&y=300&scale=1.69&rotation=90.21&imageurl=http://antwrp.gsfc.nasa.gov/apod/image/0811/horsehead_caelum.jpg&thumb=http://research.microsoft.com/~dinos/wwtimages/tn_horsehead_caelum.jpg&wtml=true

See Also

• Sharing Views

Command Line

To initiate the Windows Client version of WorldWide Telescope, with either a WTML data file, or WTT tour file, go through the following steps:

1. Open up a Command Prompt window.
2. Navigate to the folder containing the WWTExplorer.exe file. By default this is:
   
C:\Program Files (x86)\Microsoft Research\Microsoft WorldWide Telescope\

3. Type a command such as:
   
wwtexplorer path\datafile.wtml
or
wwtexplorer path\tourfile.wtt

   ensuring of course that the full path and filenames are correct.
4. This should open up WorldWide Telescope with either the collection thumbnail from a wtml file displayed under Collections > Open Collections, or will startup a tour if a valid tour file is used as the command line parameter.

See Also

• Sharing Views
• WorldWide Telescope Data Files Reference

Appendices

• Classifications
• Constellations
• Taxonomy

See Also

• WorldWide Telescope Data Files Reference

Classifications

Classification entries in WTML files can take one of the following values. The default classification is Unfiltered.

See Also

• Appendices
• Places
• Studies
• WorldWide Telescope Data Files Reference

Constellations

The following table lists the constellation codes and the center of each constellation. If a correct code is entered in a WTML file, such as Constellation="CET", then there can be an improvement in the systems performance. If Constellation is left blank, or is wrong, then the RA and Dec entries are used. There are 89 entries in the table, as the discontiguous Serpens constellation is treated as two.

See Also

• Appendices
• Places
• Studies
• WorldWide Telescope Data Files Reference

The following table lists the taxonomy codes that can be used to classify images. WorldWide Telescope has adopted the image hierarchy taxonomy proposed by the International Virtual Observatory Alliance and the Virtual Astronomy Multimedia Project's (VAMP) Astronomy Visualization Metadata (AVM) Standard. Refer to the International Virtual Observatory Alliance (IVOA) and Virtual Astronomy Multimedia Project (VAMP) websites.

As an example, a tour of the Sea of Tranquility on the Moon could be classified as Planet>Feature>Surface>Impact.

See Also

• Appendices
• WorldWide Telescope Data Files Reference