Installing and Configuring OGR WCTS

The OGR WCTS server is currently implemented as a C++ cgi-bin style web service. It should be useable with any web server that supports passing on arguments via QUERY_STRING and posted input via stdin.

Build and Install PROJ.4

The OGR WCTS server depends on PROJ.4 for doing the actual transformations. It is therefore necessary to build and install PROJ.4, preferrably before building and installing GDAL. Download the latest source release from http://www.remotesensing.org/proj . Ensure you get PROJ 4.4.7 or later if NTv2 datum shifting support is required.

If US grid based NAD27 datum shifting is required for North America, it is imperative to unpack the the datum shift files "on" the PROJ.4 source tree before configuring, building and installing.

% tar xzvf proj-4.4.7.tar.gz
% cd proj-4.4.7/nad
% tar xzvf ../../proj-nad27-1.1.tar.gz
% cd ..
% ./configure
% make
% su
Password: *******
$ make install
$ exit

If NTv2 support is desired, download the NTv2 data file from the Natural Resources Canada web site, and copy it to /usr/local/share/proj. This can be safely done after PROJ.4 is installed. The file is platform independent (unlike the binary files built for the US grid shift files). Please ensure the file is installed with the filename in lower case.

$ cp NTV2_0.GSB /usr/local/share/proj/ntv2_0.gsb

Build and Install GDAL

Currently a build mechanism only exists for Unix, and the WCTS server is not built and installed as a standard part of GDAL/OGR. However it does live in the GDAL/OGR source tree in the ogr/wcts directory. The source (such as a nightly CVS snapshot) can be downloaded from the GDAL/OGR web site.

Once unpacked, build GDAL/OGR according to the provided instructions, and then install.

% cd gdal
% ./configure
...
% make
% su 
Password: ********
$ make install
$ exit

Build and Install OGR WCTS Server

Next, build the WCTS server itself. It is found in ogr/wcts. If you wish the ability to fetch remote GML files, ensure that libcurl is installed, and uncomment the CURL_LIB and CURL_DEF lines in the GNUmakefile. Ensure that the CURL_LIB is defined appropriately to find libcurl on your system.

Then build the server.

% cd ogr/wcts
% make

The server (ogrwcts) is a simple executable that depends on libgdal.1.1, and potentially on libcurl. It would normally be copied directly into your web server cgi-bin directory.

% cp ogrwcts /u/apache/cgi-bin

If you want the HTML form based WCTS client (demonstrated at http://maps.gdal.org/wcts/client.html to have a local cgi-bin server, you should also build the wctsclient application.

% make all
% cp wctsclient /u/apache/cgi-bin

GetCapabilities

The server needs to be able to respond to a GetCapabilities request. The response document is actually created statically ahead of time. There is a provided sample in the ogr/wcts directory called wcts_capabilities.xml.0.1.0. It should generally be updated depending on the nature of the service being setup. In particular, the ContactInformation should be updated to refer to whoever is setting up the service. Also, all the service URLs all need to be updated to reflect the url for the service as it is being installed. Change each occurance of "http://maps.gdal.org/cgi-bin/ogrwcts?to the appropriate value.

% vi wcts_capabilities.xml.0.1.0
% cp wcts_capabilities.xml.0.1.0 /usr/local/share/gdal

Next this modified document (with the name unchanged) needs to be placed some where it can be found by the server. The ideal location is the /usr/local/share/gdal directory since it is already in the "data file search path". If it is placed elsewhere, the -data switch to ogrwcts will need to be used to point to the directory. Note, all aspects of the server other than the GetCapabilities request will work fine even without the capabilities document.

Commandline Testing of Server

Before trying under the web server, it may be helpful to test the WCTS server as a commandline program. Some sample requests are available in the wcts build directory, and can be used like this:

% cd ogr/wcts
% ./ogrwcts -put < req_getcap.xml
% ./ogrwcts -put < req_istransformable.xml
% ./ogrwcts -put < req_transform.xml

Web Server Setup

It is assumed that the web server is already setup to allow cgi-bin programs to be executed in the directory you installed the ogrwcts executable. If not, correct this.

It is also necessary for the ogrwcts program to be able to load the shared libraries it depends on. In a default install under /usr/local, this might involved adding the directive "SetEnv LD_LIBRARY_PATH /usr/local/lib" in an Apache configuration file, or utilizing ldconfig to ensure that libgdal.1.1.so, and libproj.so will be found when ogrwcts is started.

It is also necessary that directories with the supporting data files used by ogrwcts be readable by the user that cgi-bin programs run as (often "nobody"). In a default install the directories in question are /usr/local/share/gdal and /usr/local/share/proj. Usually these locations will be world readable by default.

Debugging

If the server isn't working there are a few strategies to debugging problems.

Most errors will result in an XML exception document being returned. If so, it should contain some indication of what went wrong.
Ensure that ogrwcts works standalone (see Commandline Testing of Server above).
Check the error log for the web server and check for messages there. Common problems would be web server permissions problems for the cgi-bin or failure to load the shared libraries.
Run the server with full debugging turned on. This can be accomplished by passing the -debug commandline switch. This will various debugging information from GDAL/OGR, and PROJ.4 to be logged in the error file, including details of what grids are being used for datum shifting.

If all the above have been exausted, bugs with OGR WCTS may be reported via the GDAL/OGR Bugzilla.

Installing in Non-Default Locations

It is often desirable to install GDAL, and PROJ.4 in a non-default location in order to better control software configurations. This can be accomplished by using the --prefix flag when configuring them. For example:

% ./configure --prefix=/opt

This mechanism can be used while configuring both GDAL and PROJ.4 (and presumably libcurl). Appropriate adjustements to the LD_LIBRARY_PATH or ldconfig settings would be required to find support libraries in ${prefix}/lib. Default path to files supporting GDAL, and PROJ.4 are established during their builds (based on the configure --prefix setting), so these components should be able to find their supporting data files as long as everything is built and installed consistently.

Sometimes it is also desirable to force the ogrwcts cgi-bin to use particular versions of local files. This is normally accomplished by using a shell script as the target cgi-bin, and having that script run ogrwcts with appropriate override commandline switches and environment variables.

The PROJ_LIB environment variable can be set to point to an alternate location to find supporting datum shift files for PROJ.4. They are normally kept in /usr/local/share/proj.

The GDAL_DATA environment variable may be used to set an alternate source for the .csv files used to translate EPSG CRS numbers into detailed definitions. They are normally kept in /usr/local/share/gdal.

The -data directory commandline switch to ogrwcts may be used to designate an alternate search directory for GDAL .csv files, and the capabilities document.

This is an example of a script that might be to override selected environment variables before running the real ogrwcts binary.

#! /bin/sh

LD_LIBRARY_PATH=/home/warmerda/gdal:/usr/local/lib
export LD_LIBRARY_PATH
PROJ_LIB=/usr2/cgi-bin/wcts-proj-lib
export PROJ_LIB
/home/warmerda/gdal/ogr/wcts/ogrwcts $*
exit 0