README.md

Golang bindings for GDAL

Goals

Godal aims at providing an idiomatic go wrapper around the GDAL library:

• Function calls return a result and an error. The result will be valid if no error was returned. The error message will contain the root cause of why the error happened.
• Calls between go and native libraries incur some overhead. As such godal does not strictly expose GDAL's API, but groups often-used calls in a single cgo function to reduce this overhead. For example, C code like

    hDS = GDALOpen(filename, GA_Readonly)
    if (hDS == NULL) exit(1);
    int sx = GDALGetRasterXSize(hDS);
    int sy = GDALGetRasterYSize(hDS);
    int nBands = GDALGetRasterCount(hDS);
    printf("dataset size: %dx%dx%d\n",sx,sy,nBands);
    for (int i=1; i<=nBands; i++) {
        hBand = GDALGetRasterBand(hDS,i);
        int ovrCount = GDALGetOverviewCount(hBand)
        for(int o=0; o<=ovrCount; o++) {
            GDALRasterBandH oBand = GDALGetOverview(hBand,o);
            int osx = GDALGetRasterBandXSize(oBand);
            int osy = GDALGetRasterBandYSize(oBand);
            printf("overview %d size: %dx%d\n",o,osx,osy);
        }
    }

will be written as

    hDS,err := godal.Open(filename)
    if err!=nil {
        panic(err)
    }
    structure := hDS.Structure()
    fmt.Printf("dataset size: %dx%dx%d\n", structure.SizeX,structure.SizeY,structure.NBands)
    for _,band := range hDS.Bands() {
        for o,ovr := range band.Overviews() {
            bstruct := ovr.Structure()
            fmt.Printf("overview %d size: %dx%d\n",o,bstruct.SizeX,bstruct.SizeY)
        }
    }

• Unfrequently used or non-default parameters are passed as options:

    ds,err := godal.Open(filename) //read-only
    ds,err := godal.Open(filename, Update()) //read-write

• Godal exposes a VSI handler that can easily allow you to expose an io.ReaderAt as a filename that can be opened by GDAL. A handler for opening gs:// google cloud storage URIs is provided through https://github.com/airbusgeo/osio

Documentation

contains the API reference and example code to get you started. The *_test.go files can also be used as reference.

Status

Godal is not feature complete. The raster side is nearing completion and should remain stable. The vector and spatial-referencing sides are far from complete, meaning that the API might evolve in backwards incompatible ways until essential functionality is covered.

Contributing

Contributions are welcome. Please read the contribution guidelines before submitting fixes or enhancements.

Installation

Godal requires a GDAL version greater than 3.0. Make sure the GDAL headers are installed on the system used for compiling go+godal code. If using a GDAL installation in a non standard location, you can set your PKG_CONFIG_PATH environment variable, e.g. export PKG_CONFIG_PATH=/opt/include/pkgconfig.

Licensing

Godal is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.