GDAL/OGR CSharp interface versions

The GDAL/OGR CSharp interface is fairly new and the first official version was published along with the GDAL 1.4.0 release. As of the 1.4.0 release there was a substantial evolution in the interface based on the various user requests. Some of these changes in the current version (1.5.0) were backward incompatible with 1.4.0 and the transition to the current development version is suggested for the interface users and 1.4.0 will be considered as deprecated soon.

The main differences between 1.4.0 and 1.5.0, and the migration steps for the existing code

This chapter describes the fundamental differences between the 1.4.0 and 1.5.0 versions. Although the 1.5.0 version is not yet released the CSharp interface users are encouraged to make this transition as soon as possible since it will be more difficult to make these steps later.

Support for the enumerated types of the C# interface (#1559)

The 1.4.0 version treats the enumerated types as integers. Handling integers instead of enums is quite uncomfortable for the .NET developers since they don't enjoy the benefit of the autocompletion support of the IDE and it's quite an uncomfortable to find out the possible values of a particular type. The 1.5.0 version exposes the enumerated types to the interface and therefore the programmer should use the proper values instead of using integer constants of the module class or using the constants from the gdalconst assembly. Every CSharp sample application has also been modified to reflect this behaviour.

As an example in GDALColorTable.cs we use:

ds = Gdal.Open(file, Access.GA_ReadOnly)

instead of

ds = Gdal.Open(file, gdalconst.GA_ReadOnly)

C# namespace names and module names follows the .NET framework naming guidelines (#1560)

The C# namespace names and the module names were changed according to the ​Microsoft.NET naming guidelines.

The general rule for naming namespaces is to use the company name followed by the technology name and optionally the feature and design as follows.

CompanyName.TechnologyName[.Feature][.Design]

For example:

Microsoft.Media
Microsoft.Media.Design

We should use PascalCase for namespaces, and separate logical components with periods, and avoid using the same name for a namespace and a class.

As far as we can we use PascalCase for the acronyms and UpperCase for the abbreviations.

The following GDAL/OGR namespace names were used:

• OSGeo.GDAL
• OSGeo.OGR
• OSGeo.OSR

The programmer should import these OSGeo prefixed namespaces instead of the old ones like:

import OSGeo.OGR

instead of

import OGR

The following module names were used:

• Gdal
• Ogr
• Osr
• GdalConst

These module classes contain the static functions related to a particular project so the invocation of these function is changed accordingly. For example we should use :

Driver drv = Ogr.GetDriverByName("ESRI Shapefile");

instead of:

Driver drv = ogr.GetDriverByName("ESRI Shapefile");

Many of the functions use the CPLErr enum as the return value but some of them still use integers though. This behaviour itself falls outside the scope of the C# bindings, so the developes may use type casts whenever needed like:

if (ds.BuildOverviews(args[1], levels) != (int)CPLErr.CE_None)
{
   Console.WriteLine("The BuildOverviews operation doesn't work");
}

Changed the names of the Windows builds for a better match with the GNU/Linux/OSX builds

The 1.4.0 version uses different filenames for the Windows and the GNU/Linux/OSX builds. This behaviour makes difficult to include the SWIG generated interface files into the daily shapshot because the wrappers are genereted on Linux but should be usable also on Windows. Since the Windows builds have been affected by this change the programmers should be aware making references to the proper assembles in this case like:

csc /r gdal_csharp.dll /out:MyEXE.exe MySource.cs

instead of:

csc /r gdal_gdal_csharp.dll /out:MyEXE.exe MySource.cs

The gdalconst assembly is now deprecated

The constans related to the GDAL and OGR projects are now included in the corresponding assemblies. There's no need to reference a separate assembly any more. In addition many of the existing constants might have to be changed, like:

ColorTable ct = new ColorTable(PaletteInterp.GPI_RGB);

instead of using

ColorTable ct = new ColorTable(gdalconst.GPI_RGB);

GDAL C# libtool build support (#1558)

The 1.4.0 version required to use the --without-libtool parameter at the configuration of the GNU/Linux/OSX builds. This problem have been corrected with the latest development version and will not be backported to 1.4.0.

CreateFromWkb support (#1565)

The inverse operation of Geometry.ExportToWkb is now supported with the development version. At this point the default behaviour of the SWIG bindings have been altered for the C# interface because the proper marshaling code could not be supported at the constructor overloads. Now the Geometry objects can be constructed using the following signatures:

public Geometry(wkbGeometryType type);
public static Geometry CreateFromWkt(string wkt);
public static Geometry CreateFromGML(string gml);
public static Geometry CreateFromWkb(byte[] wkb);
public Geometry(wkbGeometryType type, string wkt, int wkb, IntPtr wkb_buf, string gml);

The latter is the generic constructor which requires to write the marshaling code for IntPtr wkb_buf outside of the function.

Dataset.ReadRaster, Dataset.WriteRaster support

Similarly to the Band.ReadRaster band Band.WriteRaster implementation the Dataset.ReadRaster, Dataset.WriteRaster is also supported for now. This implementation uses the same approach as described in GDAL/OGR CSharp Raster Operations

Added support for Dataset.BuildOverviews (#1552)

The C# interface now supports the Dataset.BuildOverviews function by creating typemaps for the integer array parameter. Currently the following signature should be used:

public int BuildOverviews( string resampling, int[] overviewlist)

The GDALOverviews.cs sample demonstrates the usage of this function. The function uses the following commandline options:

gdaloverviews {GDAL dataset name} {resamplealg} {level1} {level2} .... 

The created overview images can be extracted using the GDALRead.cs or the GDALReadDirect.cs examples using the following commandline options:

gdalread {GDAL dataset name} {output file name} {overview_level}

Examples added

Along with the aforementioned GDALOverviews.cs sample the GDALInfo.cs sample has also been added for demonstrating the various operations of the GDAL related functions.