Thursday 9 July 2015

Geospatial Data Abstraction Library: Building GDAL from source, and using it within MS Visual Studio

The GeoData Abstraction Library is a very popular library for converting and processing raster and vector data. It is used by popular GIS software such as the open source QGis, and can be used in proprietary software such as Esri's ArcGis. It can also be used within your own application to import and work with vector and raster data in different formats.

GDAL supports over 200 raster and vector formats, as well as provides tools and utilities for processing the data being imported, by reading / writing, transforming, converting, and so on. This makes it a very powerful and flexible tool for manipulating such data in one's application. One such example, specific to a crowd simulation software, is the ability to import geo-referenced real-world maps as raster (eg, geotiff files) and vectors (eg, shape files) in order to map the crowd based on real-world urban maps in the application. In the case of a grid based crowd model, the cell values in the raster data can be used to define the walkable areas for the agents. On the other hand, vector data can be used to provide the location of walls for an Agent Based Model.

That is an aside, coming back to GDAL, it is a library that can be used from a stand-alone command-line terminal, or it can be incorporated into one's own software for handling and manipulating georeferenced data by the software itself. In order to use GDAL into one's own software application, it's web page provides many tutorials on importing GDAL, however, the tutorials and files are split into several different parts, and it can be difficult to get to grips with obtaining the correct compiled libraries for use within your application. Alternatively, we can also build the library directly from the source files. For those who want to obtain the correct files and use it in your application, I thought it may come in handy to use obtain and use it using an example, so here are the steps for building GDAL as well as obtaining the compiled source files directly, and including the correct header and library files in an application.

Option 1: Building the files from source - latest version 2.0.0

This option requires you to build the files yourself, but thankfully it's a fairly easy process. You can download the latest source files as a zip file from the GDAL website by going to the 'Building GDAL from Source' link, and clicking on 'Download from source', alternatively, by clicking here. I downloaded version 2.0.0's zip file. Now in order to build from source, we follow the steps below:

  1. Extract the downloaded source zip files to a convenient location, as a working example, I'll use 'C:\gdal200'.
  2. Open your Visual Studio Developer command prompt. For Visual 2013, it's called 'Developer Command Prompt for VS2013', and will be of a similar name for previous versions of VS Studio.
  3. Type 'vcvars32.bat' and press Enter, in order to set up the appropriate environment variables. Note: for 64-bit builds, the instructions are slightly different. Refer the 'Building from Source' section here.
  4.  Change the directory to the GDAL folder, eg by typing 'cd C:\gdal200\gdal-2.0.0' and enter. You can copy the folder location by opening it in Windows Explorer and copying the text in the location bar if you don't want to type it all.
  5. To set the location of the resulting library and header files, you can optionally edit 'nmake.opt' in the gdal folder, and set 'GDAL_HOME' to an appropriate location, eg 'C:\gdal200\gdal-2.0.0\bld', or leave it as default at "C:\warmerda\bld"
  6. Type 'nmake /f' and press Enter. Wait around 5 to 10 mins for it to finish building. 
  7. Type 'nmake /f devinstall' and press Enter. Wait for it to finish.
We are all done, we've built from source and have obtained the lib and dll files for GDAL i.e . 'gdal_i.lib' and 'gdal200.dll' in the 'C:\gdal200\gdal-2.0.0' folder. Note: The dll version name willl defer depending on the version you are compiling.

The include and lib folders will be in the GDAL_HOME location, eg in 'C:gdal200\gdal-2.0.0\bld'.

Now, we have our library and header files, we can skip to the section on using GDAL in Visual Studio.

Option 2: Obtaining the compiled header and library files - version 1.11.1

Alternatively, GISInternals maintain compiled header and library files for use in your application. We can download compiled header and library files from the GISInternals website. We need to be aware of two things:

  1. Deciding what type of build we want, i.e. development, stable or release. These are basically different branches in the repository. In my opinion, it would be best to choose the release version, as it is the most stable of the three branches and can be used in production code. Heading to the 'Stable Releases' link, we find several more options, as I'm building a 32 bit version, I head to the 'release-1800-gdal-1-11-1-mapserver-6-4-1' in order to download the appropriate files. Here, we download the 'Compiled binaries in a single .zip package' ( and 'Compiled libraries and headers' ( in order to include GDAL in Visual Studio.
  2. In terms of selecting the appropriate Visual Studio Version that you are using, it also depends on  the type of application you are building i.e a 32-bit or 64-bit one (this doesn't depend on the bit version of your Visual Studio IDE). 
Now that we have downloaded the binaries, libraries and headers:
  1. Extract the compiled binary files to an appropriate location, as a working example, I'll use 'C:\release-1800-gdal-1-11-1-mapserver-6-4-1'
  2. Extract the compiled library files to the root folder of the binary files, i.e. the folder above.

Now, we have the 'gdal_i.lib' in ''C:\release-1800-gdal-1-11-1-mapserver-6-4-1\lib' folder, and 'gdal111.dll' in ''C:\release-1800-gdal-1-11-1-mapserver-6-4-1\bin' folder

First of all, lets look at the final folder structure for the above two options, they're quite different

               Option 1: The library built from source - version 2.0.0.

Folder structure for gdal built from source

Option 2: The library downloaded from GISInternals - version 1.11.1

Folder structure for gdal obtained from GISInternals

Using the GDAL library within Visual Studio

For completeness, to use the GDAL library within Visual Studio, we need to follow these steps:

1. Include GDAL's 'include' and 'lib' directories that we extracted above in the Project - Properties - VC++ Directories, i.e. Add GDAL's 'include' folder, in the 'Include Directories' path, and the 'libs' folder in the 'Library Directories' path.

Option 1: The library built from source - version 2.0.0.

Include and Library paths for gdal built from source

Option 2: The library downloaded from GISInternals - version 1.11.1

Include and Library paths for gdal obtained form GISInternals

2. Go to Project - Properties - Linker - Input - Additional Dependencies. Add the full path of the 'gdal_i.lib' file here, eg: 'C:\release-1800-dev\gdal\gdal_i.lib'

Option 1: The library built from source - version 2.0.0.

Adding gdal_i.lib file in the linker

Option 2: The library downloaded from GISInternals - version 1.11.1

Adding gdal_i.lib file in the linker

3. Copy the 'gdal200.dll' or 'gdal111.dll' file (depending on the version obtained) to the root of your Visual Studio solution folder, where the 'dll's' of other libraries are normally copied to.

You should now be up and running with GDAL in your application, and be free to start with the GDAL API tutorials within your application, as found here.