godal

Godal is an idiomatic Go wrapper around the GDAL library designed to minimize the overhead of Cgo calls. It follows these design principles:

1. Idiomatic Error Handling: Function calls return a result and an error. The result is only valid if err == nil. The error message contains the root cause from GDAL.
2. Reduced Cgo Overhead: Instead of exposing every individual GDAL C function, Godal groups frequently used calls into single Cgo functions. This allows you to retrieve complex structures (like dataset dimensions or band information) in a single call rather than multiple individual calls.
3. Option Pattern: Unfrequently used or non-default parameters are passed using an options pattern (e.g., godal.Update()).
4. VSI Support: Godal exposes a VSI handler that allows you to treat an io.ReaderAt as a filename that GDAL can open. This is useful for integrating cloud storage (like gs:// URIs via osio) directly into GDAL workflows.

// Example of the idiomatic grouping pattern
hDS, err := godal.Open(filename)
if err != nil {
    panic(err)
}

// Instead of multiple C calls, use Structure() to get metadata at once
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)
    }
}

The Band type provides methods to interact with individual raster bands in a dataset. Key capabilities include:

• Structure: Use Structure() to get dimensions (SizeX, SizeY), block sizes, scale, offset, and DataType.
• NoData: Use NoData() to retrieve the nodata value, SetNoData() to set it, and ClearNoData() to remove it.
• Scale/Offset: Use SetScaleOffset() and ClearScaleOffset() to manage data scaling.
• Color: Use ColorInterp() and SetColorInterp() to manage color interpretation, and ColorTable()/SetColorTable() to manage color tables.
• Masking: Use MaskFlags() to check mask flags, MaskBand() to get the existing mask band, or CreateMask() to generate a new one.
• I/O: Use Read() and Write() (convenience wrappers for IO()) to move pixel data between the band and a Go buffer.
• Statistics: Use GetStatistics() to retrieve cached values, ComputeStatistics() to calculate them, or SetStatistics() to manually set them.
• Advanced Operations: Use Polygonize() to convert raster data to vector, FillNoData() to fill nodata areas, SieveFilter() to remove small features, and Histogram() to compute pixel distributions.

// Example: Reading data from a band
var buffer []float32 = make([]float32, 100*100)
err := band.Read(0, 0, buffer, 100, 100)

// Example: Getting band structure
struct := band.Structure()
fmt.Printf("Size: %dx%d\n", struct.SizeX, struct.SizeY)

The Dataset type is the primary entry point for interacting with raster datasets. Key capabilities include:

• Bands: Use Bands() to retrieve all raster bands in the dataset.
• Spatial Metadata: Use Bounds() to get the bounding box (optionally reprojected), Projection() for WKT, SpatialRef() for the spatial reference object, and GeoTransform()/SetGeoTransform() for affine transformations.
• Dataset-wide Metadata: Use SetNoData() and SetScaleOffset() to apply settings to the entire dataset.
• Transformations:
  • Translate(): Runs the equivalent of gdal_translate to convert formats or apply switches.
  • Warp(): Runs the equivalent of gdalwarp to reproject or warp a single dataset.
  • WarpInto(): Warps multiple source datasets into the existing dataset.
• Overviews: Use BuildOverviews() to compute pyramid levels and ClearOverviews() to delete them.
• I/O: Use Read(), Write(), and IO() to perform multi-band or single-band pixel operations.

// Example: Getting dataset bounds
bounds, err := ds.Bounds()

// Example: Running gdal_translate via Translate
newDS, err := ds.Translate("output.tif", []string{"-a_srs", "epsg:4326"}, godal.CreationOption("TILED=YES"))

By default, godal treats all GDAL messages with a severity of CE_Warning or higher as errors. You can override this behavior by providing a custom ErrorHandler function as an option to most godal functions.

An ErrorHandler is a function with the following signature: type ErrorHandler func(ec ErrorCategory, code int, msg string) error

Behavior Rules:

• If the ErrorHandler returns nil, the parent godal function will not return an error. It is the responsibility of your handler to log the message if you want it recorded.
• If the ErrorHandler returns an error, that specific error will be returned to the caller of the godal function.

This allows you to filter out specific warnings or transform GDAL messages into custom Go error types.

// Example: A handler that only returns an error if the message contains "critical"
myHandler := func(ec ErrorCategory, code int, msg string) error {
    if strings.Contains(msg, "critical") {
        return fmt.Errorf("GDAL critical error: %s", msg)
    }
    // Return nil to ignore the message and prevent the godal function from failing
    return nil
}

// Use it with a godal function (e.g., Open)
// Note: The exact function call depends on the specific godal API
dataset, err := gdal.Open("path/to/file.tif", myHandler)

To use GDAL drivers, you must register them. You can register all available drivers, a specific subset, or individual drivers.

• RegisterAll(): Registers all available raster and vector drivers.
• RegisterInternalDrivers(): A shorthand for registering essential drivers (VRT, MEM, GTiff for raster; MEM, VRT, GeoJSON for vector). Note: registration order for VRT/GTiff may vary based on GDAL version.
• RegisterRaster(drivers ...DriverName): Registers specific raster drivers.
• RegisterVector(drivers ...DriverName): Registers specific vector drivers.
• RegisterPlugin(name string, opts ...RegisterPluginOption): Registers a GDAL plugin.

If a driver is not explicitly defined in the Go wrapper, you can pass a DriverName that matches the C function name GDALRegister_XXX (for raster) or RegisterOGRXXX (for vector) to attempt registration via the underlying binary.

// Register everything
godal.RegisterAll()

// Or register essential drivers
err := godal.RegisterInternalDrivers()

// Or specific drivers
err := godal.RegisterRaster(godal.GTiff, godal.VRT)