LibGrid Tutorial

Landsat | | The Viewer

Resampling with LibGrid

The Grid Library (libGrid) is the resampling backend for the libMini terrain rendering engine.

Getting the Package

The latest version of libGrid is available via svn:

svn co grid


The library compiles on a wide variety of platforms, but it requires the following dependencies to be installed on the system:

It is highly recommended to use GDAL versions 1.6 and higher with internal libtiff support.

If you checked out libGrid from svn, libMini and Squish are already contained in the source code and ZLIB is most likely part of the installation (e.g. on Linux/Ubuntu). So the only dependency that needs to be installed to compile the source code is GDAL.

On Unix use the following command line to build GDAL:

./configure —with-libtiff=internal —with-geotiff=internal
sudo make install

The only build system supported so far is CMake. To compile on Windows, specify the libGrid directory as the source and binary directory in the CMake GUI and click the generator button. Then open the generated VC++ project and compile with Visual Studio. On Unix (and MacOS X), simply type the following on the command line:

cmake . && make

If some of the required dependencies cannot be found, because they have not been installed at a standard location like /usr/local, you can specify the installation directory by overriding the variable LIBGRID_THIRDPARTY_DIR in the CMake configuration (via ccmake or the Windows CMake GUI). The path to libMini can be specified separately with the variable LIBMINI_PATH.

Optionally, libGrid allows the generation of S3TC compressed images via the squish library. To disable that feature, turn off the BUILD_GRID_WITH_SQUISH cmake option.


The purpose of libGrid is to resample terrain data and create paged tilesets that can be displayed at real time with the libMini terrain rendering engine, in particularly the libMini QTViewer.

Terrain data usually comes as gridded elevation, bathymetry and satellite imagery at varying spatial resolution, location and geographic coordinate systems. A single piece of data is called a layer. In order to display such a heterogeneous data collection with libMini, the data needs to be transformed into a single consistent coordinate system. Data that does not fit into the graphics card in one piece needs to be broken up into smaller pieces. This process is called resampling and implemented in libGrid.

As opposed to commercial earth viewers like Google Earth, libGrid allows you to import, view and analyze whatever terrain data you like. You are not limited by policies, the limit is just the data itself.

Aside from massaging data for use with libMini, the library also serves as a generic tool for manipulating terrain data.


The whole resampling process can be described as follows:

After specifying a set of input layers and an area of interest, the terrain data is transformed into the respective output coordinate system. Then the area is broken up into evenly spaced tiles yielding the layout of the tileset. The data size of a generated tile depends on the resolution of the overlapping layers. The higher the resolution of the overlapping layers, the larger the size of the tile. The higher the number of tiles, the larger the extent of a tile and the smaller the size of it. libGrid automatically determines the number of tiles such that all the tiles fit into the graphics card in one piece. With those definitions, the resampling process is fully specified and will take some time, as it is a computationally expensive operation.

Once resampling is finished, the generated tileset is ready to be viewed with libMini. To do so, the terrain renderer will only page in all those tiles, which are visible for a specific point of view and viewing distance. This minimizes the amount of terrain data residing in graphics memory and the number of triangles being displayed. To further reduce the graphics memory foot print, libMini will also only page in the level of detail that is appropriate for a specific viewing distance. Thus, a tile in the distance will page in at a lower resolution than a tile that is close by. While the amount of available graphics memory limits the resolution of the visible tiles being rendered, the size and resolution of the entire tileset, however, is principally unlimited.

Resampler Usage

In order to generate a tileset with libGrid, the layers need to be specified in a so called grid file. In that file, one layer per line is given. The first line denotes the name of the tileset. With respect to supported layer file formats, all the available formats of GDAL library are supported. In particular the GeoTIFF format is recommended.

To start the resampling process, simply invoke the “gridder” application with the name of the grid file as single argument.

Simple Resampling Example

In the simplest case, the set of input layers for the gridder just consists of two layers, a single elevation grid (height field) and a single geo-referenced image or satellite photo. For the Island of Oahu the libGrid package contains sample elevation data at 10m resolution and sample imagery at 25m resolution in the data directory. This directory needs to be checked out in addition to the source code we already checked out into our working directory:

svn co data

With that terrain data, a simple grid input file for the gridder could look as follows:

“Sample-Tileset”     # tileset name
path “data/tilesets” # output path

“data/elev/Oahu-10m.tif” # input elevation layer 1
“data/imag/Oahu-25m.tif” # input imagery layer 2

For convenience, the above file is located in the “data/tilesets” directory as sample grid file “Sample.grid”.

Now, if you start the gridder with that file, it will create a tileset in the “data/tilesets/Sample-Tileset” directory. On Linux, this corresponds to the following command line in the working directory:

grid/gridder data/tilesets/Sample.grid

Due to the size of the data this will take several minutes (5min on my Apple MacBook). Please be patient and have a Kona coffee.

Landsat | | The Viewer