Dstile howto

From World Wind Wiki

(Difference between revisions)
Jump to: navigation, search
Revision as of 22:20, 13 August 2006 (edit)
Withak (Talk | contribs)
m (Preparation - - minor fixes)
← Previous diff
Revision as of 22:21, 13 August 2006 (edit) (undo)
Withak (Talk | contribs)
m (Required Software)
Next diff →
Line 7: Line 7:
==Required Software== ==Required Software==
-* [http://fwtools.maptools.org/ 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.+* [http://fwtools.maptools.org/ 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.
* [http://www.twobeds.com/upload/userfiles/tisham/dstile-02whatnickpatches.zip 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). * [http://www.twobeds.com/upload/userfiles/tisham/dstile-02whatnickpatches.zip 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).
* [http://worldwind.arc.nasa.gov World Wind, obviously] * [http://worldwind.arc.nasa.gov World Wind, obviously]

Revision as of 22:21, 13 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.


Contents

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 - the image file itself (Multiple files can be supplied for automatic mosaicking)

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. The larger runs are done on the Free Earth Foundation Cluster. On a single machine the largest dataset processed was 21GB, this took 70min to produce a tile tree of 1.8GB.

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 has to be an integer fraction of 180. That is, lzts*n has to equal 180 where n is an integer. For example, 1.0 would work while 0.7 or 1.1 would not.

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 solid 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 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