View source for WPS with GeoTIFF support

As of {{WRF-Fire-commit|d5746414a0bee94c1a18435cd7be9b2b311e338f|April 6, 2011}}, WRF-Fire's version of WPS supports reading of [http://trac.osgeo.org/geotiff/ geotiff] files directly without [[How to convert data for Geogrid|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=
In order to use this feature, the user must have both the [http://trac.osgeo.org/geotiff/ GeoTIFF] and [http://www.libtiff.org/ TIFF] libraries installed.  For many linux distributions, it is possible to install these libraries using its package manager.  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 [http://www.macports.org/install.php macports] and use the command
 sudo port install libgeotiff
to install all necessary libraries.

==Installing libTIFF from source==

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 [http://download.osgeo.org/libtiff/ 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 <code>~/wpslibs</code>.  Run the configure script telling it where you want the library installed, then build and install.
 ./configure --prefix ~/wpslibs
 make
 make install

==Installing GeoTIFF from source==

In order to make use of GeoTIFF images containing projected data, you must compile GeoTIFF with PROJ.4 support.  Download the source code for PROJ.4 [http://trac.osgeo.org/proj/ here], then extract and install it into your library installation path.
 ./configure --prefix ~/wpslibs
 make
 make install
Now, you can download GeoTIFF from [ftp://ftp.remotesensing.org/pub/geotiff/libgeotiff/ here].  Extract the archive and compile with PROJ.4 support.
 ./configure --with-libtiff=~/wpslibs --with-proj=~/wpslibs --prefix=~/wpslibs
 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 <code>LIBTIFF</code> and <code>GEOTIFF</code> 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 <code>/usr</code>, as follows.
 export LIBTIFF=/usr
 export GEOTIFF=/usr
If you installed GeoTIFF with macports, the prefix is <code>/opt/local</code>.
 export LIBTIFF=/opt/local
 export GEOTIFF=/opt/local
If you installed from source, then the prefix is the path given to the configure script.  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 <code>~/.bash_profile</code>)  file to avoid having to type them in every time you log in or open a new terminal window.

=Using GeoTIFF with WPS=

With the environment properly set up, you can compile [[How to compile WRF-Fire|WRF]] and [[How to run WRF-Fire with real data#Compiling WPS|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 <code>geogrid/GEOGRID.TBL</code>.  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 <code>index</code>, which details the storage format of the data contained in that directory.  The specification of GeoTIFF files follows this convention; however, the <code>index</code> file must (at the least) contain a line such as <code>geotiff=XXXX.tif</code> giving the name of the GeoTIFF file residing in the same directory.  

For example, if you have a GeoTIFF file named <code>topo.tif</code> containing 
topographical data that you want to use for the field <code>ZSF</code>, you would edit the <code>ZSF</code> section of <code>geogrid/GEOGRID.TBL</code> with the line <code>abs_path=./ned_data</code>.  Then create a directory under <code>WPS</code> called <code>ned_data</code>, and copy <code>topo.tif</code> to this directory.  Finally, you would add a text file called <code>index</code> inside <code>ned_data</code> containing the line:
 geotiff=topo.tif
This would tell geogrid that the file <code>ned_data/topo.gif</code> contains a GeoTIFF file that should be used to fill the field <code>ZSF</code>.  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 <code>type</code>, <code>category_min</code>, and <code>category_max</code>.

While for a continuous field such as <code>ZSF</code> 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 <code>geogrid.log</code>; 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