# Dstile howto

(Difference between revisions)
 Revision as of 22:39, 29 September 2006 (edit)Withak (Talk | contribs) (→Level zero tile size)← Previous diff Revision as of 22:41, 29 September 2006 (edit) (undo)Withak (Talk | contribs) (→Level zero tile size)Next diff → Line 47: Line 47: 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 390 km, as seen in [[:Image:Lztsdshot.png|this screenshot]]. You will have to experiment with this parameter to make your layer work the way you want it to. 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 390 km, as seen in [[:Image:Lztsdshot.png|this screenshot]]. You will have to experiment with this parameter to make your layer work the way you want it to. - The level zero tile size ''should'' be 180/(2^n), where n is an integer. For example a lztsd of 0.703125 (180/(2^8)) would work, while the lztsd of 1.0 used in the his example would not satisfy the expression. It is possible to give dstile values that do not satisfy this expression, and the resulting imagery layers will render in WW, but there may be alignment problems with the tiles. The map in this example did not show the alignment problems because of the relatively coarse scale. Detailed orthoimagery will be more likely to show the alignment problems, and thus the 180/(2^n) rule should be followed. + The level zero tile size ''should'' be 180/(2^n), where n is an integer. That is, a lztsd of 1.40625 (180/(2^7)) would have been the ideal value to use for this example. It is possible to give dstile values that do not satisfy this expression, and the resulting imagery layers will render in WW, but there may be alignment problems with the tiles. The map in this example did not show the alignment problems because of the relatively coarse scale. Detailed orthoimagery will be more likely to show the alignment problems, and thus the 180/(2^n) rule should be followed. ==Adding the layer to World Wind== ==Adding the layer to World Wind==

## Revision as of 22:41, 29 September 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.

## Required Software

• FWTools - This is a free 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 in the Making Layers article. Put dstile.exe in the folder where FWTools was installed (C:\Program Files\FWTools1.0.0b2 for me).
• World Wind, 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, but these can be converted to RGB Images using the pct2rgb utility suppiled with FWTools.

I put the image and world file (if the image requires one) in the FWTools directory for simplicity, but these files can be anywhere as long as you give dstile the correct location for them.

Dstile can also tile terrain data using the --dem switch at the command line. The terrain data must be 16bit.

## 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(s)
```

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(s) - the image file itself. A list of multiple image files can be supplied and will be automatically combined into a single set of tiles. Alternately, gdal_merge.py in FWTools can be used to create your own mosaic first if you would like more control over that step of the process.

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 took just a minute or two for my 111MB image file. In another case, dstile running on a single machine took 70 minutes to produce a tile tree of 1.8GB from a 21GB data set. Larger runs are done on the Free Earth Foundation Cluster.

### 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 36 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 390 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.

The level zero tile size should be 180/(2^n), where n is an integer. That is, a lztsd of 1.40625 (180/(2^7)) would have been the ideal value to use for this example. It is possible to give dstile values that do not satisfy this expression, and the resulting imagery layers will render in WW, but there may be alignment problems with the tiles. The map in this example did not show the alignment problems because of the relatively coarse scale. Detailed orthoimagery will be more likely to show the alignment problems, and thus the 180/(2^n) rule should be followed.

## 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">
<Name>N. Delaware</Name>
<DistanceAboveSurface>0</DistanceAboveSurface>
<BoundingBox>
<North>
<Value>40.0</Value>
</North>
<South>
<Value>39.0</Value>
</South>
<West>
<Value>-76.0</Value>
</West>
<East>
<Value>-75.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>
</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 solid black areas inside of your imagery transparent. A few preprocessing steps can be used to fix this, in general a bit of creativity is needed. For example in an image with default null value and assuming no pixels within the actual image are pure white, a quick fix will be to:

• Add an offset (e.g. 32) to all black pixels.
• Convert all white pixels to black
• Tile using dstile and set the transparent colour as above.

Due to compression in JPEG's colour along black edges is not pure black. To get around this use the following tags:

```    <TransparentMinValue>0</TransparentMinValue>
<TransparentMaxValue>20</TransparentMaxValue>
```

## 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 your World Wind directory. I used a temporary directory in this example to make it simpler to follow.

## DSTile Credits

• Adam Nowacki: For writing this amazingly simple piece of GDAL wizardry.
• Frank Warmerda: For maintaining the GDAL library and FWTools.
• Tisham Dhar: For wasting his time in porting to the humble and buggy Windows platform.
• Erik Newman: For writing this HOW-TO.
##### Personal tools
World Wind Central
Knowledge Base
Toolbox