Dstile howto

From World Wind Wiki

(Difference between revisions)

Revision as of 15:59, 11 August 2006

This is a step-by-step tutorial on how to get your own georeferenced imagery into World Wind. This tutorial will show you how to create tiles from a georeferenced image then create a layer for the tiles in World Wind. From there you can package up the layer as an add-on to distribute. This layer will be stored entirely on your computer. If you want to serve the tiles to others then this tutorial may not be helpful.

The organization of World Wind's tile system is summarized here. This tutorial assumes that you already understand how the tile system works and how World Wind's xml files work.

I will be walking you through an example layer that I will create. The steps can be easily modified for your own data.

1 Required Software
2 Preparation
3 Creating tiles
- 3.1 Level zero tile size
4 Adding the layer to World Wind
5 Tips

Required Software

FWTools - This is a package of tools for manipulating georeferenced imagery. It is required for dstile to work. The entire package is an 18MB download and 84.5MB installed. Perhaps in the future someone can package up only what is required for dstile to work. You can save some space by not installing the developer files using the options in the installer.
The dstile executable itself - This link is the most recent version at the time of this writing. The general procedure that this program follows is summarized here. Put dstile.exe in the folder where FWTools was installed (C:\Program Files\FWTools1.0.0b2 for me).
World Wind itself, obviously

Preparation

In addition to the software you will need a georeferenced image. For this tutorial, I will be using a geology map of northern Delaware from here. The format of the imagery can be anything supported by FWTools (complete list here). Dstile can not handle indexed images at the moment, though there may be a way to convert them to something it can handle (more info necessary here). Put the image and world file (if the image requires one) in the FWTools directory.

Dstile can also handle terrain data (more info is necessary on this).

Creating tiles

Dstile is a command line program (though a gui is on the way). Run the "FWTools shell" shortcut from your start menu. This will give you a command prompt window in the FWTools directory. Alternately you can start your own command prompt, navigate to the FWTools directory, and run the "setfw.bat" script.

The general command line to create local tiles is as follows:

dstile.exe tile --lztsd tile_size --wwcache --overviews output_directory georeferenced_image_file

The variables are as follows:

tile_size - the size of the coarsest level of tiles, in degrees (more on this below)
output_directory - the directory where the tile system will be placed as it is created
georeferenced_image_file - the image file itself

The command line switches:

tile tells dstile that you want to create tiles.
--wwcache tells dstile to organize and name the tiles in the way that World Wind expects them to appear.
--overviews tells dstile to create all of the tile levels necessary. Leaving out this option will result in only the most detailed level of tiles being created.

For my example geology map, the command line I will use to generate the tiles is as follows:

dstile.exe tile --lztsd 1.0 --wwcache --overviews output_tiles geomap10.tif

This will create a new directory (in my FWTools directory) called "output_tiles" where it will put the tile system. The georeferenced input file is "geomap10.tif". Note that this input file needs to be the image itself, not the world file (geomap10.tfw in this case), though the world file does need to exist in the same folder as the image. In my example it created six levels of tiles (folders name 0 through 5) in the output_tiles directory.

When dstile runs, it will restate some of the input parameters and then show a progress indicator. The processing may take anywhere from a minute or two for my 111MB image file to several hours if you have a larger image file and a slower computer.

Level zero tile size

This parameter controls at what zoom level or camera altitude your imagery layer will appear. A larger level zero tile size means it will appear sooner as you zoom in, a smaller size means it will appear later as you zoom in. For reference, the blue marble uses a level zero tile size of 45 degrees, World Wind's default landsat layer uses a level zero tile size of 2.25 degrees, and the high resolution imagery in the Zoomit! add-on uses level zero tile sizes as small as 0.1 to 0.2 degrees.

For my example layer with the geologic map, I used a level zero tile size of 1.0 degrees. This causes the layer to appear at an altitude of around 340 km, as seen in this screenshot. You will have to experiment with this parameter to make your layer work the way you want it to.

Adding the layer to World Wind

To make the layer appear in World Wind you need to put the tiles somewhere in your World Wind directory and then create an xml file for the new layer.

For this example, I put the tiles in my \Data\Earth\ directory. Alternately, they could go somewhere in the /Add-ons/ directory. I don't like putting my own data into the \Cache\ directory because I occasionally delete everything in \Cache\ if I get low on disk space. I like to reserve \Cache\ for data that can be re-downloaded if necessary. Thus I moved the contents of the "output_tile" directory (the contents should only consist of the numbered folders for each level) that dstile created into "\Data\Earth\N. Delaware geology map\" in my World Wind directory.

The organization of these files in the World Wind directory is up to you. If I were going to be putting a lot of geology maps into World Wind then I might want to add another folder and put the tiles into it (\Data\Earth\Geology maps\N. Delaware\ for example). As long as you tell World Wind where to find them you can organize them however you want.

Once the tiles are in the right location, we need an xml file to create the layer in World Wind. The xml files goes in \Config\Earth\ in the World Wind directory. It is helpful to name the xml file to match the name of the layer it is creating ("geology maps.xml" in this case). The xml I used is below:

<?xml version="1.0" encoding="UTF-8"?>
<LayerSet Name="Geology maps" ShowOnlyOneLayer="false" ShowAtStartup="false" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="LayerSet.xsd">
	<QuadTileSet ShowAtStartup="true">
		<Name>N. Delaware</Name>
		<DistanceAboveSurface>0</DistanceAboveSurface>
		<BoundingBox>
			<North>
				<Value>90.0</Value>
			</North>
			<South>
				<Value>-90.0</Value>
			</South>
			<West>
				<Value>-180.0</Value>
			</West>
			<East>
				<Value>180.0</Value>
			</East>
		</BoundingBox>
		<TerrainMapped>true</TerrainMapped>
		<ImageAccessor>
			<LevelZeroTileSizeDegrees>1.0</LevelZeroTileSizeDegrees>
			<NumberLevels>6</NumberLevels>
			<TextureSizePixels>512</TextureSizePixels>
			<ImageFileExtension>jpg</ImageFileExtension>
			<PermanentDirectory>Data\Earth\N. Delaware geology map</PermanentDirectory>
		</ImageAccessor>
		<TransparentColor><Red>0</Red><Green>0</Green><Blue>0</Blue></TransparentColor>

	</QuadTileSet>
</LayerSet>

The "LevelZeroTileSizeDegrees" field needs to be the size that was used in dstile and the "PermanentDirectory" field needs to be the directory where you put the tiles. This will create an entry in the layer manager called "Geology maps" and inside of it there will be a sublayer called "N. Delaware".

Dstile fills in the empty parts of the tiles outside of your imagery with black, so the "TransparentColor" line in the xml makes this area transparent. Note that this will also make black areas inside of your imagery transparent. More info is needed on fixing this.

Tips

When experimenting with the level zero tile size, it may be a good idea to erase the contents of the output folder before rerunning dstile. Dstile will merge new tiles with existing ones where they overlap, but will not erase any old tiles left over that aren't used.
It may be more useful to have dstile output the tiles directly where you want them in you World Wind directory. I used a temporary directory in this example to make it simpler to follow.

Retrieved from "https://worldwindcentral.com/wiki/Dstile_howto"