96 lines
4.0 KiB
Markdown
96 lines
4.0 KiB
Markdown
# Golang bindings for GDAL
|
|
[](https://pkg.go.dev/github.com/airbusgeo/godal)
|
|
[](https://github.com/airbusgeo/godal/blob/main/LICENSE)
|
|
[](https://github.com/airbusgeo/godal/actions?query=workflow%3Agodal+event%3Apush+branch%3Amain)
|
|
[](https://coveralls.io/github/airbusgeo/godal?branch=main)
|
|
[](https://goreportcard.com/report/github.com/airbusgeo/godal)
|
|
|
|
|
|
|
|
### Goals
|
|
|
|
Godal aims at providing an idiomatic go wrapper around the <img src="https://gdal.org/_static/gdalicon.png" width="25" height="25">
|
|
[GDAL](https://gdal.org) 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
|
|
```c++
|
|
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
|
|
```go
|
|
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:
|
|
```go
|
|
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](https://golang.org/pkg/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
|
|
|
|
[](https://pkg.go.dev/github.com/airbusgeo/godal)
|
|
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](CONTRIBUTING.md)
|
|
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](https://github.com/airbusgeo/godal/blob/main/LICENSE) for the full
|
|
license text.
|
|
|
|
|