Getting the prerequisites
This program requires GeoTIFF and LibTIFF development libraries. These should be available in most if not all package managers. To install in Ubuntu, you just need to install the package libgeotiff-dev like this
sudo apt-get install libgeotiff-dev
Using Homebrew on Mac OSX,
brew install libgeotiff
It is also possible to install the dependencies from source, but you may need to help the configure script below to find the libraries by setting configuration variables CFLAGS="-I$PREFIX/include" and LDFLAGS="-L$PREFIX/lib".
Compiling the source
Download the latest release tarball from here and extract it. In the extracted directory, run ./configure && make. If everything built correctly, you should now have convert_geotiff in the current directly. You can either move this file into your PATH or type sudo make install to install it.
Running convert_geotiff with no arguments will produce a usage description as follows.
Usage: convert_geotiff [OPTIONS] FileName Converts geotiff file `FileName' into geogrid binary format into the current directory. Options: -h : Show this help message and exit -c NUM : Indicates categorical data (NUM = number of categories) -b NUM : Tile border width (default 3) -w [1,2,4] : Word size in output in bytes (default 2) -z : Indicates unsigned data (default FALSE) -t NUM : Output tile size (default 100) -s SCALE : Scale factor in output (default 1.) -m MISSING : Missing value in output (default 0., ignored for categorical data) -u UNITS : Units of the data (default "NO UNITS") -d DESC : Description of data set (default "NO DESCRIPTION")
All of the files will be created in the current directory, so it is best to run the program from an empty directory.
A more detailed description of the arguments to this program follows.
The data tiles in the geogrid binary format are allowed to overlap by a fixed number of grid points. The extra border around the tile is called the halo, and this argument sets the width of the halo. For instance with a halo of size three, the file named 00101-00200.00051-00100 would actually contain columns 98-203 and rows 48-103 of the full dataset. This halo is necessary for the interpolation scheme inside of WPS. The default should be acceptable for most situations.
The number of bytes to represent each data point as an integer. These integers are scaled by the scaling parameter before being truncated to an integer. scaledA lower value will make the output data smaller, at the cost of accuracy or the dynamic range of the input.
Any grid point that is missing data, such as the outer border of the edge tiles, or grid points that the GeoTIFF file indicates as missing will be set to this value. This argument is currently ignored when the categorical flag is set, instead missing data will be set to the maximum category + 1.*-s :
Because the data is always stored as an integer, a scaling parameter is needed to represent fractional numbers or large values. The data set will be divided by this number prior to being truncated to an integer. If the data set has an accuracy of 2 decimal places, a reasonable scale to use would be 0.01.*-u, -d :
The units and a small description of the data set should be included as arguments. Multi-word arguments should be quoted as follows.
-u meters -d "elevation above sea level"
The final argument must always be present. This is the (absolute or relative) path to the GeoTIFF file to be converted.
If you get an error that says something like "error while loading shared libraries: libgeotiff.so...", this means that GeoTIFF was compiled in as a shared library. You just need to tell the system where to find this library. This can be done by adding the path to the GeoTIFF library to the environment variable LD_LIBRARY_PATH. For example,
where $PREFIX is the location where you installed GeoTIFF.
The current code has some limitations which are listed here.
- Datasets must not contain more than 99,999 grid points in each axis. This is a limitation of the geogrid format itself, due to the naming convention of the tiles. However, it is possible (but inefficient) to split a single dataset into multiple directories for this purpose. A better solution would be to resample the data to a lower spatial resolution prior to converting.
- This program cannot convert between geographic projections, so the input data must be in a projection supported by WPS. All of the projections supported by WPS should work for this conversion program; however, only UTM, Albers equal area, and lat-lon have been tested. In addition, data sources may not conform to EPSG standards in their projection tags; the output should always be checked before use.