GDAL FAQ

1. General
2. FAQInstallationAndBuilding
3. FAQRaster
4. FAQVector
5. FAQCoordinateSystemsAndProjections
6. FAQMiscellaneous

Installation and Building

Can I get a MS Visual Studio Project file for GDAL?

The GDAL developers find it more convenient to build with makefiles and the ​Visual Studio NMAKE utility. Maintaining a parallel set of project files for GDAL is too much work, so there are no full project files directly available from the maintainers.

There are very simple project files available since GDAL/OGR 1.4.0 that just invoke the makefiles for building, but make debugging somewhat more convenient. These are the makegdal71.sln and makegdal80.sln files in the GDAL root directory.

Occasionally other users do prepare full project files, and you may be able to get them by asking on the ​gdal-dev list. However, I would strongly suggest you just use the NMAKE based build system. With debugging enabled you can still debug into GDAL with Visual Studio.

Can I build GDAL with MS Visual C++ 2005 Express Edition?

Yes, you can. It's also possible to use GDAL libraries in applications developed using ​Microsoft Visual C++ 2005 Express Edition.

• Download and install ​Visual C++ 2005 Express Edition. Follow instructions presented on this website:

• Download and install ​Microsoft Platform SDK. Also, follow these instructions carefully without omitting any of steps presented there:

• Add following two paths to Include files in the Visual C++ IDE settings. Do it the same way as presented in ​Step 3 from the website above.

C:\\Program Files\\Microsoft Platform SDK\\Include\\atl
C:\\Program Files\\Microsoft Platform SDK\\Include\\mfc

• Since you will build GDAL from command line using nmake tool, you also need to set or update INCLUDE and LIB environment variables manually. You can do it in two ways:
  1. using the System applet available in the Control Panel
  2. by editing vsvars32.bat script located in

     C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat
     

These variables should have following values assigned:

INCLUDE=C:\\Program Files\\Microsoft Visual Studio 8\\VC\\Include;
        C:\\Program Files\\Microsoft Platform SDK\\Include;
        C:\\Program Files\\Microsoft Platform SDK\\Include\\mfc;
        C:\\Program Files\\Microsoft Platform SDK\\Include\\atl;%INCLUDE%

LIB=C:\\Program Files\\Microsoft Visual Studio 8\\VC\\Lib;
    C:\\Program Files\\Microsoft Visual Studio 8\\SDK\\v2.0\\lib;
    C:\\Program Files\\Microsoft Platform SDK\\lib;%LIB%

NOTE: If you have edited system-wide INCLUDE and LIB variables, using System applet, every Console (cmd.exe) will have it properly set. But if you have edited them through vsvars32.bat script, you will need to run this script in the Console before every compilation.

• Patch atlwin.h header

At line 1725 add int i; declaration, so it looks as follows:

BOOL SetChainEntry(DWORD dwChainID, CMessageMap* pObject, DWORD dwMsgMapID = 0)
{
    int i;
    // first search for an existing entry

    for(i = 0; i < m_aChainEntry.GetSize(); i++)

• Patch atlbase.h header

At line 287, comment AllocStdCallThunk and FreeStdCallThunk functions and add macros replacements:

/***************************************************
PVOID __stdcall __AllocStdCallThunk(VOID);
VOID __stdcall __FreeStdCallThunk(PVOID);

#define AllocStdCallThunk() __AllocStdCallThunk()
#define FreeStdCallThunk(p) __FreeStdCallThunk(p)

#pragma comment(lib, "atlthunk.lib")
***************************************************/

/* NEW MACROS */
#define AllocStdCallThunk() HeapAlloc(GetProcessHeap(),0,sizeof(_stdcallthunk))
#define FreeStdCallThunk(p) HeapFree(GetProcessHeap(), 0, p)

• Building GDAL
  • Open console windows (Start -> Run -> cmd.exe -> OK)
  • If you have edited vsvars32.bat script, you need to run it using full path:

    C:\> "C:\\Program Files\\Microsoft Visual Studio 8\\Common7\\Tools\\vsvars32.bat"
    Setting environment for using Microsoft Visual Studio 2005 x86 tools
    

  • Go do GDAL sources root directory, for example:

    C:\> cd work\gdal
    

  • Run nmake to compile

    C:\work\gdal> nmake /f makefile.vc
    

  • If no errors occur, after a few minutes you should see GDAL libraries in C:\work\gdal.

Now, you can use these libraries in your applications developed using Visual C++ 2005 Express Edition.

Can I build GDAL with Cygwin or MinGW?

GDAL should build with ​Cygwin using the Unix-like style build methodology. It is also possible to build with ​MinGW though there are some complications. The following might work:

./configure --prefix=$PATH_TO_MINGW_ROOT --host=mingw32 \
	--without-libtool --without-python $YOUR_CONFIG_OPTIONS

Using external win32 libraries will often be problematic with either of these environments - at the least requiring some manual hacking of the GDALmake.opt file.

Can I build GDAL with Borland C or other C compilers?

These are not supported compilers for GDAL; however, GDAL is mostly pretty generic, so if you are willing to take on the onerous task of building an appropriate makefile / project file it should be possible. You will find most portability issues in the ​gdal/port/cpl_port.h file and you will need to prepare a ​gdal/port/cpl_config.h file appropriate to your platform. Using cpl_config.h.vc as a guide may be useful.

Raster Support

Why won't gdalwarp or gdal_merge write to most formats?

GDAL supports many raster formats for reading, but significantly less formats for writing. Of the ones supported for writing most are only supported in create copy mode. Essentially this means they have to be written sequentially from a provided input copy of the image to be written. Programs like gdal_merge.py or gdalwarp that write chunks of imagery non-sequentially cannot easily write to these sequential write formats. Generally speaking formats that are compressed, such as PNG, JPEG and GIF are sequential write. Also some formats require information such as the coordinate system and color table to be known at creation time and so these are also sequential write formats.

When you encounter this problem it is generally a good idea to first write the result to GeoTIFF format, and then translate to the desired target format.

To determine which formats support which capabilities, use the --formats switch with pretty much any GDAL utility. Each driver will include either r (read-only), rw (read or sequential write) or rw+ (read, sequential write or random write).

How to convert a raster to a layer of polygons?

TBD

Vector Support

TBD

Coordinate Systems and Projections

What are Well Known Text projections, and how do I use them?

OpenGIS Well Known Text is a textual format for defining coordinate systems. It is loosely based on the ​EPSG coordinate systems model. While GDAL itself just passes these definitions around as text strings, there is also an ​OGRSpatialReference class in gdal/ogr for manipulating them and a linkage to ​PROJ.4 for transforming between coordinate systems. The OGRSpatialReference, and PROJ.4 linkaged (but not PROJ.4 itself) is linked into the GDAL shared library by default. More documentation on WKT and OGRSpatialReference can be found in the ​OGR Projections Tutorial.

Can I reproject rasters with GDAL?

Yes, you can use the gdalwarp utility program or programmatically use the ​GDALWarpOperation class described in the ​GDAL Warp API Tutorial.

Miscellaneous

Is the GDAL library thread-safe?

No. GDAL is not completely thread safe.

However for GDAL 1.3.0 much work has been done on making some common scenarios thread safe. In particular for the situation where many threads are reading from GDAL datasets at once should work as long as no two threads access the same ​GDALDataset object at the same time. However, in this scenario, no threads can be writing to GDAL while others are reading or chaos may ensue.

Also, while the GDAL core infrastructure is now thread-safe for this specific case, only a few drivers have been vetted to be thread safe.

It is intended that work will continue on improving GDAL's thread safety in future versions.

Does GDAL work in different international numeric locales?

No. GDAL makes extensive use of sprintf() and atof() internally to translate numeric values. If a locale is in effect that modifies formatting of numbers, altering the role of commas and periods in numbers, then PROJ.4 will not work. This problem is common in some European locales.

On Unix-like platforms, this problem can be avoided by forcing the use of the default numeric locale by setting the LC_NUMERIC environment variable to C, e.g.

$ export LC_NUMERIC=C
$ gdalinfo abc.tif

How do I debug GDAL?

Various helpful debugging information will be produced by GDAL and OGR if the CPL_DEBUG environment variable is set to the value ON. Review the documentation for the ​CPLDebug() function for more information on built-in debugging messages.

On Unix operating systems GDAL can be built with the CFG environment variable set to debug to enable debugger support with the -g compiler switch.

On Windows edit the nmake.opt and ensure /Zi appears in the OPTFLAGS variable.

How should I deallocate resources acquainted from GDAL on Windows?

The safest way to release resources allocated and returned (with ownership transfered to caller) from GDAL library is to use dedicated deallocator function. Deallocators promise to release resources on the right module side, without crossing modules boundaries what usually causes memory access violation errors.

• Example of correct resource deallocation:

OGRDataSource* poDS = NULL;

// OGRDataSource aquisition made on side of the GDAL module
poDS = OGRSFDriverRegistrar::Open( "point.shp", FALSE );

// ...

// Properly resource release using deallocator function
OGRDataSource::DestroyDataSource( poDS );

• Example of incorrect resource deallocation:

OGRDataSource* poDS = NULL;

// OGRDataSource aquisition made on side of the GDAL module
poDS = OGRSFDriverRegistrar::Open( "point.shp", FALSE );

// ...

// Deallocation across modules boundaries.
// Here, the deallocation crosses GDAL DLL library and client's module (ie. executable module)
delete poDS;

More detailed explanation of the problem can be found in the ​Allocating and freeing memory across module boundaries article.