WWT StudyChopper takes as input a study image, and generates the tiled multi-resolution image pyramid, in the correct
folder structure and with the correct names, that WorldWide Telescope can accept as foreground image data. In addition to
the image pyramid for each study, an appropriate thumbnail image (96 pixels wide, by 45 in height) and two
WTML files are
also output. One of these WTML files references the location of the thumbnail and pyramid at a local address -- useful for
immediate testing purposes -- and the second references the intended public location when the work is ready for release.
The content of these WTML files can be used as standalone files, or can be cut
and pasted into a larger document such as a community payload file, or perhaps a
collection of similar studies.

See Also

The StudyChopper tool is very useful for data preparation, but its user
interface is somewhat functional and navigating it is not intuitive. For the
most part using the tool is simply a case of entering information in the correct
order, which is described in the following steps. Running the tool will reveal the single dialog:

See Also

Creating Image Pyramids and Thumbnails

Before using the tool, place all the images for the study in a single folder. Preferred image formats are the lossless
and transparency supporting formats such as .tiff and .png, rather than .jpg. Then go through the following steps:

Enter the folder name in the Input Folder text box.

Enter the name of a particular file, or file type using wildcard characters
as required, in the Input File(s) box.

Select the Load button. This will populate the Loaded Studies list box with the image filenames. The tool
will automatically remove images from the Loaded Studies list that cannot be loaded. The tool also
cannot load very large images. In the latter case consider dividing the study into several smaller studies.

If necessary, use the Clear All Entries and Remove Entry buttons, and Display Folder Names
and Display File Size checkboxes, to edit the list of images.

Enter the desired folder for the output to be written to, in the Output Folder text box.

The
Max Level entry is calculated by the tool from the size of
the source image. There is no reason to increase it, but it could be
decreased for a large image during testing, but for the most part need not
be changed.

Click the Tile Images button. This starts tiling as a background process.
A progress bar will display underneath the Tile Images button. This
process will
also create the thumbnail images. If only thumbnail images are required, then click the Save Thumbnail button instead.
Also, set the Overwrite Existing Tiles checkbox appropriately.

When the tiling process has completed (a line will appear in the
Messages text box to indicate this), and without closing the tool, check the contents of the output folder --
it should contain a complete image pyramid. In the example below a 780 x 480 image of Saturn was tiled. Note that there are three
tiling levels (0, 1 and 2), and note also that there are only two entries, and not the full complement of four, at level 2.
This is because the height of the image is such that the top row (0) and bottom row (3) would have entirely empty tiles.

The number 639246517 is the ID number generated by the tool, and is a unique
number used as the
top level folder name. The <ID> text box of the tool is read-only.

If the image pyramid has been created correctly, go on to the next step of creating the
WTML files. If not, go back to
the data and make the necessary adjustments.

See Also

Creating Local and Final WTML Files

Creating WTML files for the newly tiled study will make testing it, and including it in larger collections, straightforward.
To create the two WTML files, go through the following steps:

Click the name in the Loaded Studies list to select the
required study. Note that a number of fields such as Name,
Tile Url, and Thumbnail Url are automatically
populated, and these can be edited now by clicking on the list boxes or changing
the text, or can be edited later (outside of the tool) by hand if needed. For
example, the Name field can take a semi-colon separated list of
names. The first name will be used along with the thumbnail to identify the
study, and if a name is not entered, then the filename will be used as the name.
Note the image thumbnail will appear to the right of the Loaded Studies text box.

Optionally, enter appropriate text into the Credits
text box, and enter a valid link into the Credits Url text
box. The link is provided to help users locate more information on the
study.

If known, enter an appropriate RA and Dec
for the image. An approximation might work well enough as the image can be
finely aligned and scaled within WorldWide Telescope (refer to the section Image Alignment within WorldWide Telescope).
Similarly for the Height of the image the default
approximation of 6 arc minutes (or 0.1 degree) can work well enough until
the image is finely scaled.

If known, enter the Classification,
Constellation and Band. These are not critical for
the image to appear in WorldWide Telescope.

Enter the name of the final WTML file in the Output WTML file text box.

Enter a title in the Output WTML title text box to be used as the
highest level Folder Name entry in the WTML file.

If the final location for the study is known, enter it into the Output Webpage text box.
The final "/" in the URL is optional.

Click the Save Wtml button. This will create both local and final
WTML files. These will be placed in the
output folder specified for the creation of the pyramid. For the example Saturn
study, the local file would look similar to this:

To test the output, click on the LOCAL version of the WTML file, or alternatively load this file from within WorldWide
Telescope. This will display the study and the thumbnails in WorldWide Telescope.
Check not only the images, but also the metadata such as the Name, Credits, CreditsUrl, and so on.

If the Make .plate File checkbox is checked, then in
addition to building the tile pyramid, a single .plate file will be output to
the specified location. A plate file contains every tile of the pyramid, and a
header section encoding the format of the pyramid. The purpose of this single
file is that it is then much easier to transmit the pyramid to colleagues, copy
to a backup file, or send it for some other purpose.

If the input image has AVM-tags, then the appropriate fields will be filled automatically with their values. For more
details on AVM tags, refer to Virtual Astronomy.org. AVM tagging is a standard proposed
by members of the professional astronomy outreach/educators community to tag astronomical photographs with useful metadata
that contain details of what the photograph contains, how it was taken, copyrights, credits, and so on.

Images (currently,
only TIFF images) can be tagged with AVM tags from FITS files using Adobe Photoshop and FITS liberator, or
by using the online
tagging tool available on the Virtual Astronomy site.

See Also

It is possible to adjust the position of an image within WorldWide Telescope.
The image to be aligned should be referenced from
a collection file. For ease of navigation collection files should be located in the My Documents\WWT Collections folder. Collections in this folder will
appear under the My Collections folder when WorldWide Telescope is run. So in order to enable
easy editing, move the WTML file containing the images
you wish to align to the My Documents\WWT Collections folder.

Open up WorldWide Telescope, navigate to the correct collections file, open it, and select the image to be aligned by
clicking on the thumbnail. Click on the image itself when it appears in the main view, then press Ctrl-E. This brings up the
Image Alignment dialog:

Use the controls in this dialog to finely align an image.

Note that
there is currently no save or cancel options. If the data is in the correct
folder, noted above, then the changes will be saved off to the Place
entry in the WTML file.

Pivot Mode can be one of the
easiest ways to align an image. Right-click on a point on the image that is
in the correct location (typically a star), a white circle will appear to
confirm this, then rotate, scale, and invert the image simply by moving the
mouse. Right-click again to de-select Pivot Mode. Typically
aim to align two significant stars that are as far apart as possible on the
image to get the best alignment between foreground and background.

This feature is not currently fully implemented.

See Also

Initializing Study Chopper

StudyChopper reads in default settings from the configStudyChopper.txt
file when the tool is first run. Edit this file
appropriately to make use of the tool efficient. This can either be done by hand, or by use of the
Save Settings in config.txt button. This configuration file should reside
in the same folder as the tool. The default contents of this file are shown in the following table:

See Also

WWT Sphere Toaster takes as input an equirectangular image, and produces as
output a tile pyramid of images suitable either for background images (such as a
complete sky survey), or for spherical object surfaces (such as stars, planets
and moons). Suitable WTML files encapsulating the tile pyramid, and a thumbnail
image, are also output. The tile pyramid is produced using the
TOAST project system. For a description of this projection system, refer to the
WorldWide Telescope Projection Reference document.

See Also

To convert a single equirectangular image of an entire object (sky survey,
planet or moon surface, for example), go through the following procedure. Note
that the entire image is loaded into memory by this tool, so there are limits on
the size of image that the tool can currently process. This limit is increased
if the tool is run on a 64-bit operating system.

When the tool is run the Input tab appears. Use the Open button to select the
equirectangular image.
The equator will appear as a red line across the center of the image.

This image shows the default settings
when a 1000 x 500 image is loaded.

Next, select the WTML tab.

Enter appropriate text for Title, Credits, and
CreditsURL. Credits
should be kept to a maximum of 240 characters.

The
StorageURL entry is the web accessible location where the final output
should be stored.

The MakeWtml button can be used if only
WTML files are required. Otherwise they are generated from the Output tab.

Now select the Output tab.

Ensure to select one of Panorama, Sky or
Planet. These will affect the
inside or outside orientations of the sphere.

The maximum levels
of a pyramid should not be increased, but can be decreased during
testing - to improve performance.

The Test tab can be selected after the input file is
selected and with the Panorama, Sky or Planet
orientation set in the Output tab. It is not necessary to
generate any output to run the test.

The default test is for level 0, and X and Y at 0.

This image shows level has been set to 1 to examine one of the four tiles at this
level.

That completes the process in the simplest of cases - one image covering the
complete sphere. Note that a very large number of tiles can be produced. For
example, if the original image is 8192 x 4096 pixels, then 1365 tiles are
generated in a full pyramid with five levels (and this can take 10 to 20 minutes
of computing time). If the original image is 20000 x 10000 pixels, then over
21500 tiles are created at the required 7 levels (and this can take 24
hours of computing time). Blank tiles are not created. By default, all tiles are
png images, though this can be changed to jpeg, though the jpeg format does not store transparency and can have undesirable
artifacts.

See Also

The single example will cover the great majority of cases
of the use of this tool. However there are
a few other options that might be of value.

If the RA/Longitude increases Left to Right box is
unchecked, then the RA/longitude is assumed to increase right to left, and the layout of the output is changed from the image on the left
to the image on the right:

If the Galactic Coordinates checkbox is selected, then the coordinate system is changed from J2000 to galactic
coordinates.

Change the value of RA/Longitude of left of EQ if the left hand side of
the image is not at Longitude 0. For example, a map of the Earth will often have
Longitude -180 for its left edge, so enter -180 in this field. A value of 45 was entered to give the
image below.

For Panoramas it can be helpful to use the Offset settings to center the image around the "equator".

There are additional options on the Output tab if Panorama is selected, giving a range of
choices on how to fill the empty void above the panorama image.