commit 6be873b5d0697ebaba3d9e7e3aacdf7acdd90b44 Author: Phil Rosenfield Date: Sat Jul 29 13:57:46 2017 -0400 initial Commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..0590b3c --- /dev/null +++ b/README.md @@ -0,0 +1,9 @@ +# WorldWide Telescope Data Tools Guide + +This document describes the use of a number of tools that can be used to help prepare data for the WorldWide Telescope. + +To install the tools, follow the instructions for installing the [WorldWide Telescope May 2009 ADK](http://research.microsoft.com/en-us/collaboration/wwt-ap/resources.aspx). To run the tools select **All Programs** and navigate to the following location: + +![](images/AcademicKit.jpg) + +Ensure that you are using the latest versions of the tools: currently versions 0.23. diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..c06e193 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,16 @@ +# Summary + +* [WWT Study Chopper](studychopper.md) + * [The Study Chopper Dialog](studychopper.md#the-study-chopper-dialog) + * [Creating Image Pyramids and Thumbnails](studychopper.md#creating-image-pyramids-and-thumbnails) + * [Creating Local and Final WTML Files](studychopper.md#creating-local-and-final-wtml-files) + * [Plate Files](studychopper.md#plate-files) + * [AVM Tags](studychopper.md#avm-tags) + * [Image Alignment within WorldWide Telescope](studychopper.md#image-alignment-within-worldwide-telescope) + * [Initializing Study Chopper](studychopper.md#initializing-study-chopper) + * [Command Line Input to Study Chopper](studychopper.md#command-line-input-to-study-chopper) +* [WWT Sphere Toaster](spheretoaster.md) + * [Preparing a Single Image](spheretoaster.md#preparing-a-single-image) + * [Special Cases](spheretoaster.md#special-cases) + * [Initializing Sphere Toaster](spheretoaster.md#initializing-sphere-toaster) + * [Command Line Input to Sphere Toaster](spheretoaster.md#command-line-input-to-sphere-toaster) diff --git a/images/AcademicKit.jpg b/images/AcademicKit.jpg new file mode 100644 index 0000000..d0d15e7 Binary files /dev/null and b/images/AcademicKit.jpg differ diff --git a/images/FillOption.png b/images/FillOption.png new file mode 100644 index 0000000..e0d93a5 Binary files /dev/null and b/images/FillOption.png differ diff --git a/images/ImageAlignment.jpg b/images/ImageAlignment.jpg new file mode 100644 index 0000000..c1437e3 Binary files /dev/null and b/images/ImageAlignment.jpg differ diff --git a/images/PanoramaAverageOfTopRow.png b/images/PanoramaAverageOfTopRow.png new file mode 100644 index 0000000..2da6348 Binary files /dev/null and b/images/PanoramaAverageOfTopRow.png differ diff --git a/images/PanoramaExtendTopRow.png b/images/PanoramaExtendTopRow.png new file mode 100644 index 0000000..b806f04 Binary files /dev/null and b/images/PanoramaExtendTopRow.png differ diff --git a/images/PanoramaInput.png b/images/PanoramaInput.png new file mode 100644 index 0000000..4fc0e3a Binary files /dev/null and b/images/PanoramaInput.png differ diff --git a/images/PanoramaNoFill.png b/images/PanoramaNoFill.png new file mode 100644 index 0000000..2ea4bb8 Binary files /dev/null and b/images/PanoramaNoFill.png differ diff --git a/images/PanoramaZoneGrey.png b/images/PanoramaZoneGrey.png new file mode 100644 index 0000000..a9954a7 Binary files /dev/null and b/images/PanoramaZoneGrey.png differ diff --git a/images/Saturn.png b/images/Saturn.png new file mode 100644 index 0000000..7224bf0 Binary files /dev/null and b/images/Saturn.png differ diff --git a/images/SaturnChopped.jpg b/images/SaturnChopped.jpg new file mode 100644 index 0000000..88d8b02 Binary files /dev/null and b/images/SaturnChopped.jpg differ diff --git a/images/StudyChoppedDialog.jpg b/images/StudyChoppedDialog.jpg new file mode 100644 index 0000000..2f3ad74 Binary files /dev/null and b/images/StudyChoppedDialog.jpg differ diff --git a/images/Toast45.png b/images/Toast45.png new file mode 100644 index 0000000..6b3fadd Binary files /dev/null and b/images/Toast45.png differ diff --git a/images/ToastGalactic.png b/images/ToastGalactic.png new file mode 100644 index 0000000..e641ff8 Binary files /dev/null and b/images/ToastGalactic.png differ diff --git a/images/ToastInput1.png b/images/ToastInput1.png new file mode 100644 index 0000000..fd6d7fb Binary files /dev/null and b/images/ToastInput1.png differ diff --git a/images/ToastLR.png b/images/ToastLR.png new file mode 100644 index 0000000..22854a6 Binary files /dev/null and b/images/ToastLR.png differ diff --git a/images/ToastOutput1.png b/images/ToastOutput1.png new file mode 100644 index 0000000..4447bda Binary files /dev/null and b/images/ToastOutput1.png differ diff --git a/images/ToastPanorama.png b/images/ToastPanorama.png new file mode 100644 index 0000000..1d9f65b Binary files /dev/null and b/images/ToastPanorama.png differ diff --git a/images/ToastPanorama2.png b/images/ToastPanorama2.png new file mode 100644 index 0000000..4554ff5 Binary files /dev/null and b/images/ToastPanorama2.png differ diff --git a/images/ToastRL.png b/images/ToastRL.png new file mode 100644 index 0000000..0a4321e Binary files /dev/null and b/images/ToastRL.png differ diff --git a/images/ToastTest.png b/images/ToastTest.png new file mode 100644 index 0000000..aaab123 Binary files /dev/null and b/images/ToastTest.png differ diff --git a/images/ToastWtml.jpg b/images/ToastWtml.jpg new file mode 100644 index 0000000..d91a492 Binary files /dev/null and b/images/ToastWtml.jpg differ diff --git a/images/images.sh b/images/images.sh new file mode 100644 index 0000000..e4a1a68 --- /dev/null +++ b/images/images.sh @@ -0,0 +1,21 @@ +wget wwtweb.blob.core.windows.net/docs/images/AcademicKit.jpg +wget wwtweb.blob.core.windows.net/docs/images/StudyChoppedDialog.jpg +wget wwtweb.blob.core.windows.net/docs/images/Saturn.png +wget wwtweb.blob.core.windows.net/docs/images/SaturnChopped.jpg +wget wwtweb.blob.core.windows.net/docs/uiimages/ImageAlignment.jpg +wget wwtweb.blob.core.windows.net/docs/images/ToastInput1.bmp +wget wwtweb.blob.core.windows.net/docs/images/ToastWtml.jpg +wget wwtweb.blob.core.windows.net/docs/images/ToastOutput1.bmp +wget wwtweb.blob.core.windows.net/docs/images/ToastTest.bmp +wget wwtweb.blob.core.windows.net/docs/images/ToastLR.bmp +wget wwtweb.blob.core.windows.net/docs/images/ToastRL.bmp +wget wwtweb.blob.core.windows.net/docs/images/ToastGalactic.bmp +wget wwtweb.blob.core.windows.net/docs/images/Toast45.bmp +wget wwtweb.blob.core.windows.net/docs/images/ToastPanorama.bmp +wget wwtweb.blob.core.windows.net/docs/images/ToastPanorama2.bmp +wget wwtweb.blob.core.windows.net/docs/images/PanoramaInput.bmp +wget wwtweb.blob.core.windows.net/docs/images/FillOption.bmp +wget wwtweb.blob.core.windows.net/docs/images/PanoramaNoFill.bmp +wget wwtweb.blob.core.windows.net/docs/images/PanoramaExtendTopRow.bmp +wget wwtweb.blob.core.windows.net/docs/images/PanoramaAverageOfTopRow.bmp +wget wwtweb.blob.core.windows.net/docs/images/PanoramaZoneGrey.bmp diff --git a/spheretoaster.md b/spheretoaster.md new file mode 100644 index 0000000..c5e36b4 --- /dev/null +++ b/spheretoaster.md @@ -0,0 +1,154 @@ +## WWT Sphere Toaster + +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](WorldWideTelescopeProjectionReference.html) document. + +The following examples use a test image for clarity. + + +### Preparing a Single Image + +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. + +1. 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. + + ![](images/ToastInput1.png) + + This image shows the default settings when a 1000 x 500 image is loaded. + +2. Next, select the **WTML** tab. + ![](images/ToastWtml.jpg) Enter appropriate text for **Title**, **Credits**, and **Credits** **URL**. **Credits** should be kept to a maximum of 240 characters. + + The **Storage** **URL** entry is the web accessible location where the final output should be stored. + + The **Make** **Wtml** button can be used if only WTML +  files are required. Otherwise they are generated from the **Output** tab. + +3. Now select the **Output** tab. + + ![](images/ToastOutput1.png) 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. + + Refer to the note on [Plate Files](#plate-files). + + Selecting **Generate Pyramid + WTML** will create the image pyramid, WTML +  files, and thumbnail. + +4. 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. + + ![](images/ToastTest.png) 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. + + +### Special Cases + +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: + + ![](images/ToastLR.png) + ![](images/ToastRL.png) +* If the **Galactic Coordinates** checkbox is selected, then the coordinate system is changed from J2000 to galactic coordinates. + + ![](images/ToastGalactic.png) +* 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. + + ![](images/Toast45.png) +* For Panoramas it can be helpful to use the **Offset** settings to center the image around the "equator". + + ![](images/ToastPanorama.png) + ![](images/ToastPanorama2.png) + +* 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. + + The panorama source image + ![](images/PanoramaInput.png) + + The output options + ![](images/FillOption.png) + + **No Fill** + ![](images/PanoramaNoFill.png) + + **Extend top row** + ![](images/PanoramaExtendTopRow.png) + + **Average of top row** + ![](images/PanoramaAverageOfTopRow.png) + + **Zone V Grey** + ![](images/PanoramaZoneGrey.png) + +### Initializing Sphere Toaster + +Sphere Toaster requires the following dll files to work: WwtDataUtils.dll, OctMap.dll, BigPic.dll, PlateTools.dll. These should be in their correct location on installation. + +The configSphereToaster.txt file, in the same location as the program, can be edited to change the default output directory. + +```OUTDIR=C:\Users\Public\Public Documents\example\``` + +### Command Line Input to Sphere Toaster + +The Sphere Toaster tool can be run from a Command Prompt window, taking a single parameter - the name of an XML file, where the content of that file determines the required input and output. + +To run the tool from the Command Prompt window: + +1. Navigate to the location of SphereToaster.exe. By default this is: + ``` + C:\Program Files (x86)\Microsoft\WWT ADK May 2009\ + ``` +2. Create an XML file to define the inputs and outputs. The contents of the XML file should be as follows: + + +##### FileToaster.xml + +```xml + + +   +   +   +   + + +   +   +   + +  C:\Users\....\Pictures\Rowers.png +  Planet +  C:\Users\....\Pictures\Toaster + +   +   +   + +  True +  0 +  False +  0 +  0 + +  True +  False +  False + +  Test Toaster Settings +  MSR +  www.research.microsoft.com +   + + +``` + +4. In the Command Prompt window type: + ``` + SphereToaster _path_\FileToaster.xml + ``` + where _path_ is the full path to the XML file. +5. If this method of running the tool is used, and there are no errors, the tool will be opened, run, then closed. If there are errors the tool will be left open, in order to help identify the issue. + diff --git a/studychopper.md b/studychopper.md new file mode 100644 index 0000000..f463545 --- /dev/null +++ b/studychopper.md @@ -0,0 +1,172 @@ +## WWT Study Chopper + +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. + +The tile pyramid structure, and WTML + files, are explained in detail in the [WorldWide Telescope Data Files Reference](WorldWideTelescopeDataFilesReference.html) document. + +### The Study Chopper Dialog + +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: + +![](images/StudyChoppedDialog.jpg) + +### 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: + +1. Enter the folder name in the **Input Folder** text box. +2. Enter the name of a particular file, or file type using wildcard characters as required, in the **Input File(s)** box. +3. 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. +4. 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. +5. Enter the desired folder for the output to be written to, in the **Output Folder** text box. +6. 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. +7. 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. +8. 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 **** text box of the tool is read-only. + +![Saturn](images/Saturn.png) +![Tiled Saturn](images/SaturnChopped.jpg) + +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. + +### 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: + +1. 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. +2. 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. +3. 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](#ImageAlignmentwithinWorldWideTelescope)). 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. +4. If known, enter the **Classification**, **Constellation** and **Band**. These are not critical for the image to appear in WorldWide Telescope. +5. Enter the name of the final WTML file in the **Output WTML file** text box. +6. Enter a title in the **Output WTML title** text box to be used as the highest level Folder Name entry in the WTML file. +7. If the final location for the study is known, enter it into the **Output Webpage** text box. The final "/" in the URL is optional. +8. 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: + +```xml + + +  +    +      +          +          +          C:\Users\.......\Pictures\Output\639246517.jpg +          +      +    +  + +``` + +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. + +#### Plate Files + +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. + +#### AVM Tags + +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](http://virtualastronomy.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. + + +### Image Alignment within WorldWide Telescope + +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: + +![](images/ImageAlignment.jpg) + +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. + + +### 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: + +``` +INDIR=C:\Users\Public\Pictures +INFILE=*.tif +OUTDIR=C:\Users\Public\Pictures\tiles +OUTWTMLFILE=egstudies.wtml +OUTWTMLTITLE=Example Studies +OUTWEBDIR=http://research.microsoft.com/wwtimages +STOREONWWTSERVERS=False +MAKEPLATE=False +OVERWRITEEXISTINGTILES=True +CREATEJPEG=False +DISPLAYFOLDERNAMES=False +DISPLAYFILESIZE=True +``` + +Note - security issues may prevent the button/edited file from working as expected. + + +### Command Line Input to Study Chopper + +The Study Chopper tool can be run from a Command Prompt window, taking a single parameter - the name of an XML file, where the content of that file determines the required input and output. + +To run the tool from the Command Prompt window: + +1. Navigate to the location of StudyChopper.exe. By default this is: + ``` + C:\Program Files (x86)\Microsoft\WWT ADK May 2009\ + ``` +2. Create an XML file to define the inputs and outputs. The contents of the XML file should be as follows: + +##### FileChopper.xml + +```xml + +   +   +   +   + + +   +   +   + +  C:\Users\....\Documents\OneImage +  *.jpg +  C:\Users\....\Documents\Test web + +   +   +   +  Chopper test.wtml +  Chopper title +  Output web URL +  True +  False +  False + + + +``` + +4. In the Command Prompt window type: + ``` + StudyChopper _path_\FileChopper.xml + ``` + where _path_ is the full path to the XML file. +5. If this method of running the tool is used, and there are no errors, the tool will be opened, run, then closed. If there are errors the tool will be left open, in order to help identify the issue.