ecmdb 0.7.0

Next: , Up: (dir)


This manual was last updated 12 November 2012 for version 0.7.0 of ecmdb.

Copyright © 2012
Computer Graphics Group, University of Siegen, Germany.
Written by Martin Lambers (
See for contact information.

Copying and distribution of this file and the accompanying media files, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. These files are offered as-is, without any warranty.

Short Contents:

Table of Contents

Next: , Previous: Top, Up: Top

1 Introduction

ecmdb is a tool to create and manage ECM databases.

ECM (Ellipsoidal Cube Map) databases store data for the surface of a planetary object, for example photos and elevation models of Earth, Moon, or Mars. An ECM database can be used by a rendering program to efficiently display huge data sets.

For more information about ECM, see

Building an ECM database can be computationally expensive. To make best use of multi-processor systems and clusters, this task is split into multiple steps:

  1. Create a database.
    Use the command ecmdb create to create a database. This step defines the database category (e.g. elevation or texture data), its maximum resolution, and the ellipsoid for which it provides data.
    See ecmdb create --help for more information. To find the right maximum resolution, see ecmdb resolutions --help.
  2. Add input files to the database.
    Use the command ecmdb add to add input files to your data base. The input files must contain georeference information. They can be in any format that GDAL understands.
    If multiple input files are given, this command will automatically use all processors in a multi-processor system to add them in parallel. Additionally, this command can be run simultaneously on multiple cluster nodes to add many files to the same database in parallel.
    See ecmdb add --help for more information.
  3. Commit all added input files to the database.
    Before added input files can be used, you need to commit them to the database using the command ecmdb commit.
    This command will automatically use all processors in a multi-processor system. Only one commit command can be used on a given database at any given time, but you can still run more add commands in parallel or after the commit command; you just need to rerun commit afterwards to use the new files.
    See ecmdb commit --help for more information.
  4. Finalize a database.
    Once all relevant input files are committed to a database, you can optionally run the command ecmdb finalize to remove all management information from the database and save disk space. Note that you cannot add or commit more input files to a finalized database.
    See ecmdb finalize --help for more information.

Next: , Previous: Introduction, Up: Top

2 Data Sets For Earth

2.1 NASA Blue Marble Next Generation


The BMNG data set consists of 12 Earth surface images for the months of the year 2004, and an elevation model.

To build an ECM database from the image for January, do the following:

To build an ECM database from the elevation model, do the following:

2.2 Natural Earth


Various artificial, low-resolution images of the Earth surface are available from the Natural Earth project.

The files provided by this project can be imported directly. For example:

     ecmdb create   /ecmdb/naturalearth/hyp-hr -E earth-wgs84 -q 512 -l 5 -C texture
     ecmdb add      /ecmdb/naturalearth/hyp-hr HYP_HR/HYP_HR.tif
     ecmdb commit   /ecmdb/naturalearth/hyp-hr
     ecmdb finalize /ecmdb/naturalearth/hyp-hr



The SRTM 90m Digital Elevation Database version 4 is available from It provides elevation data for the land masses of Earth.

First, get all the ZIP files from You don't need to unzip them; instead, you can build a list of special file names that allow GDAL to read the ZIP contents directly:

     for i in *.zip; do echo /vsizip/$i/`basename $i .zip`.tif; done > addlist.txt


     ecmdb create   /ecmdb/srtm4 -E earth-wgs84 -q 512 -l 9 -C elevation
     ecmdb add      /ecmdb/srtm4 `cat addlist.txt`
     ecmdb commit   /ecmdb/srtm4
     ecmdb finalize /ecmdb/srtm4

2.4 Utah GIS portal


The Utah GIS portal provides lots of great high-quality data sets.

2.4.1 HRO 2006 Image Data

This is a high-resolution (ca. 25 cm ground resolution) image data set stored in 3239 TIFF files. Get them all from (you only need the .tif files).

One of the files has corrupt GeoTIFF headers. You can fix it with this command:

     gdal_translate -a_srs "epsg:26912" 12SWJ320760.tif fixed-12SWJ320760.tif
     mv fixed-12SWJ320760.tif 12SWJ320760.tif

Then build the ECM database:

     ecmdb create   /ecmdb/utah-hro2006 -E earth-wgs84 -q 512 -l 18 -C texture
     ecmdb add      /ecmdb/utah-hro2006 *.tif
     ecmdb commit   /ecmdb/utah-hro2006
     ecmdb finalize /ecmdb/utah-hro2006

You may want to run multiple concurrent add commands in a cluster because this will take some time. With lossless compression, all steps took 114 hours and 54 minutes on a single Intel Core i7-930 machine. Now lossy compression is supported and is the default; this should result in better performance and significantly reduced disk usage.

2.4.2 2m and 5m Elevation Models

The Utah GIS portal provides various elevation models, e.g. a 2m model (at and a 5m model (at

To build a database from the 2m model:

     ecmdb create   /ecmdb/utah-2m -E earth-wgs84 -q 512 -l 15 -C elevation
     ecmdb add      /ecmdb/utah-2m --min=-9000 --max=+9000 --srs "+proj=utm +zone=12 +datum=NAD83" *.asc
     ecmdb commit   /ecmdb/utah-2m
     ecmdb finalize /ecmdb/utah-2m

For the 5m model, use -l 14 for the create command due to the lower resolution.

2.5 TerraSAR-X


Several TerraSAR-X demonstration datasets are available from the TerraSAR-X Sample Imagery Site.

The files can be imported directly. Be sure to select a geocoded file in GeoTIFF format.

The example shown above is from the TerraSAR-X StripMap Image of the Strait of Gibraltar (plus a DEM and a little lighting). In StripMap mode, TerraSAR-X achieves a resolution of up to 3 m on ground, which according to ecmdb resolutions corresponds to level 13 (with a quad size of 512). So we need 14 levels (0-13) to store the data without resolution loss.

     ecmdb create   /ecmdb/terrasar-x/gibraltar -E earth-wgs84 -q 512 -l 14 -C sar-amplitude
     ecmdb add      /ecmdb/terrasar-x/gibraltar IMAGE_HH_SRA_strip_008.tif
     ecmdb commit   /ecmdb/terrasar-x/gibraltar
     ecmdb finalize /ecmdb/terrasar-x/gibraltar

Next: , Previous: Data Sets For Earth, Up: Top

3 Data Sets For Moon

3.1 WAC Digital Terrain Model (DTM) 100 meters/pixel


This elevation model is available here: Get the files WAC_GLD100_*_100M.IMG from

Build an ECM database:

     ecmdb create   /ecmdb/moon-wac100m -E moon-nasa -q 512 -l 7 -C elevation
     ecmdb add      /ecmdb/moon-wac100m WAC_GLD100_*_100M.IMG
     ecmdb commit   /ecmdb/moon-wac100m
     ecmdb finalize /ecmdb/moon-wac100m

Previous: Data Sets For Moon, Up: Top

4 Data Sets For Mars

4.1 MOC Graylevel Images


See Get all the data files mcXX-256.img, where XX ranges from 02 to 30. Additionally, get the file number 1, which uses only one digit: mc1-256.img.

Build an ECM database:

     ecmdb create   /ecmdb/mars-moc -E mars-nasa -q 512 -l 7 -C texture -c 1
     ecmdb add      /ecmdb/mars-moc mc*-256.img
     ecmdb commit   /ecmdb/mars-moc
     ecmdb finalize /ecmdb/mars-moc

4.2 MOLA


See You need the files megt*.lbl and megt*.img in the best available resolution. These can be found in the MEG128 and POLAR directories. From the POLAR directory, you only need the megt_?_512_1.* files.

Build an ECM database:

     ecmdb create   /ecmdb/mars-mola -E mars-nasa -q 512 -l 6 -C elevation
     ecmdb add      /ecmdb/mars-mola megt*.lbl
     ecmdb commit   /ecmdb/mars-mola
     ecmdb finalize /ecmdb/mars-mola

4.3 HiRISE


The HiRISE project provides high-resolution images of Mars.

Unfortunately it is not easy to get the correct data files from their website. You have to click your way through. The files you need are high-resolution .JP2 files.

The JPEG2000 format is poorly supported in general. I had to use the proprietary Kakadu software to produce a TIFF file that is readable by all common tools:

     kdu_expand -i PSP_008648_1810_RED.JP2 -o PSP_008648_1810_RED.tiff

Since ECM databases do not yet support color definitions beyond 8 bit per channel, you need to tell GDAL to reduce the original 10 bit color range to 8 bit:

     gdal_translate -of VRT -scale 0 1023 0 255 PSP_008648_1810_RED.tiff hirise.vrt

Now you can import the file:

     ecmdb create   /ecmdb/mars-hirise -E mars-nasa -q 512 -l 16 -C texture -c 1
     ecmdb add      /ecmdb/mars-hirise --min 1 hirise.vrt
     ecmdb commit   /ecmdb/mars-hirise

You can add and commit more HiRISE images to the same database (even if they are from completely different locations) before finalizing it.