WPS with GeoTIFF support

Back to the WRF-SFIRE user guide.

As of April 6, 2011, WRF-Fire's version of WPS supports reading of geotiff files directly without converting to geogrid's binary format. This feature has been added to make it easier to incorporate high resolution data for real WRF-Fire simulations. WPS must be linked with GeoTIFF support in order to use this feature. To maintain compatibility, GeoTIFF support is not compiled in unless the necessary libraries are installed.

Prerequisite libraries

Installing by system package manager

In order to use this feature, the user must have the GeoTIFF library and its dependencies installed. For many linux distributions, it is possible to install these libraries and all dependencies using its package manager, which is highly recommended. Using Ubuntu,

sudo apt-get install geotiff-bin

or Fedora,

sudo yum install libgeotiff-devel

will install everything required. For other distributions, search the package manager for geotiff; you will need the development libraries if they are packaged separately. Users of Mac OSX can install macports and use the command

sudo port install libgeotiff

to install all necessary libraries.

Installing libTIFF from sources

GeoTIFF files use the TIFF image format, with geolocation information added. The current stable version of libTIFF is 3.9.4; however, we recommend you use the latest development release of version 4.0. Version 4.0 of libTIFF adds support for what is called BigTIFF, which are images larger than 2^32 bytes. BigTIFF files are often seen in large GeoTIFF datasets that you may want to use with WRF-Fire. To install, get the latest source package from here or directly from here, extract it, and go to the extracted directory in your terminal. You will want to choose a place to install the new libraries, such as ~/wpslibs and create this directory by mkdir ~/wpslibs . Run the configure script telling it where you want the library installed, then build and install.

./configure --prefix ~/wpslibs
make
make install

Installing PROJ.4 from sources

In order to make use of GeoTIFF images containing projected data, you must compile GeoTIFF with PROJ.4 upport. Download the source code for PROJ.4 here or directly from here, then extract and install it into your library installation path.

./autogen.sh  (skip if configure script is already there)
./configure --prefix ~/wpslibs
make
make install

PRPJ.4 depends on SQLite3. Have your sysadmin install it is not on your system already, or see ./README for configuration if you install SQLite3 from sources in a nonstandard location.

Installing GeoTIFF from sources

You can download GeoTIFF from here or directly from here. Extract the archive and compile with PROJ.4 support.

./configure --with-libtiff=~/wpslibs --with-proj=~/wpslibs --prefix=~/wpslibs
make
make install

GeoTIFF may complain about using relative paths, so if that is the case provide the full path to your wpslibs directory. For instance:

 ./configure --with-libtiff=/home/your_user_name/wpslibs --with-proj=/home/your_user_name/wpslibs --prefix=/home/your_user_name/
make
make install

Setting up the environment

Before compiling WPS, you must set environment variables informing the configure script where to find the GeoTIFF libraries. The convention for these environment variables is the same as for the netCDF libraries; you must set LIBTIFF and GEOTIFF to the prefix path of TIFF and GeoTIFF, respectively. If you installed the libraries using the package manager on Linux, the prefix path for each will be /usr, as follows.

export LIBTIFF=/usr
export GEOTIFF=/usr

If you installed GeoTIFF with macports, the prefix is /opt/local.

export LIBTIFF=/opt/local
export GEOTIFF=/opt/local

If you installed from source, then the prefix is the path given to the configure script.

export LIBTIFF=~/wpslibs
export GEOTIFF=~/wpslibs

You may also need to configure the shared library search path, especially if you installed from source. This can be done with the following command.

export LD_LIBRARY_PATH=$GEOTIFF/lib

You may want to add these environment variables to your startup (such as ~/.bash_profile) file to avoid having to type them in every time you log in or open a new terminal window.

After this step you are ready to compile WPS (WRF must be already compiled). If you have an old WPS version compiled before you remeber to clean it firts:

./clean -a

Then configure it again

./configure

and compile

./compile

Using GeoTIFF with WPS

With the environment properly set up, you can compile WRF and WPS in the normal way.

Specifying a GeoTIFF dataset for geogrid

The procedure for using a dataset in geogrid involves adding a field specification to the file geogrid/GEOGRID.TBL. The field specification provides paths to one or more datasets that can be used to initial the field. These paths must each contain a text file named index, which details the storage format of the data contained in that directory. The specification of GeoTIFF files follows this convention; however, the index file must (at the least) contain a line such as geotiff=XXXX.tif giving the name of the GeoTIFF file residing in the same directory.

For example, if you have a GeoTIFF file named topo.tif containing topographical data that you want to use for the field ZSF, you would edit the ZSF section of geogrid/GEOGRID.TBL with the line abs_path=./ned_data. Then create a directory under WPS called ned_data, and copy topo.tif to this directory. Finally, you would add a text file called index inside ned_data containing the line:

geotiff=topo.tif

This would tell geogrid that the file ned_data/topo.gif contains a GeoTIFF file that should be used to fill the field ZSF. The new extension to WPS will provide geogrid with the cartographic projection and storage details that are normally provided in the index. Geogrid requires a bit more information about categorical fields than is actually provided by GeoTIFF. For these fields, you must also specify values for type, category_min, and category_max.

While for a continuous field such as ZSF this is the only line that absolutely must be in the index, you may wish to provide more information that cannot be determined from the GeoTIFF metadata. All parameters supported by standard geogrid index files are allowed in GeoTIFF index files as well. If a setting is present in the index file, it will override anything read from the GeoTIFF metadata. This is useful in case the GeoTIFF extension or the GeoTIFF file itself provides incorrect information; the user can easily fix it by providing the correct value in the index. To assist in debugging, geogrid creates a log file called geogrid.log; this log contains source data parameters that were actually used. Check this file for anything incorrect.

For importing high resolution data from GeoTIFF files for WRF-Fire, we recommend the following index files:

#ned_data/index
geotiff = ned_data.tif
description = "Topography height"
type = continuous
units = "meters"
description = "National Elevation Dataset"
tile_bdr = 3

#landfire_data/index
geotiff = lf_data.tif
type = categorical
category_min = 1
category_max = 14
tile_bdr = 3
units = "category"
missing_value = 14