ffi-gdal

Ruby wrapper around GDAL, using FFI, along with some helper methods.

• GDAL 2.4 and GDAL 3+ are supported.
• Ruby 3.4+ supported.

Add this line to your application's Gemfile:

gem 'ffi-gdal'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ffi-gdal

Note that this requires you to have libgdal installed on your system and accessible in your PATH.

ffi-gdal provides two interfaces, really: the direct FFI wrapper around GDAL's C API, and a Ruby-fied interface that uses the FFI wrapper to make use more like using an object-oriented library instead of a functional one. Most likely you'll just want to use the Ruby-fied library, but if for some reason that doesn't get you what you want, direct access to the FFI wrapper (which is really just direct access to the C API) is available.

To distinguish this gem from the already-existing gdal gem, you require ffi-gdal to get access to the GDAL module and its children.

Following RubyGem conventions, to get access to the FFI wrapper, you require ffi/gdal.

For classes that are enabled with logging capabilities, you can turn logging on and off like GDAL::RasterBand.logging_enabled = true. If you're using ffi-gdal in Rails, you can GDAL::Logger.logger = Rails.logger.

Additional error logging can be enabled through GDAL's global configuration options.

FFI::CPL::Conv.CPLSetConfigOption('CPL_DEBUG', 'ON')
FFI::CPL::Conv.CPLSetConfigOption('CPL_LOG_ERRORS', 'ON')

CI is run against:

• Ruby 3.4, 4.0 for Ubuntu 24.04 (GDAL 3.8.4, PROJ 9.4.0, GEOS 3.12.1)
• Ruby 3.4, 4.0 for Ubuntu 22.04 (GDAL 3.4.1, PROJ 8.2.1, GEOS 3.10.2)

We intentionally pin CI to specific Ubuntu versions (rather than -latest) so that GDAL/PROJ/GEOS library compatibility is tracked and upgraded deliberately.

GDAL 2.4 compatibility is no longer covered by CI, but a docker-compose.yml with a gdal2 service (see Dockerfile.gdal2) is kept around for local testing against GDAL 2.4.4, e.g. docker compose run --rm gdal2 bundle exec rspec. This is also handy if you're on macOS/Windows and want to run specs against Linux + GDAL locally.

GDAL itself has differences in behaviour between versions. This means that upgrading your project to a newer version of GDAL may introduce some breaking changes to your project due to changes in GDAL internal logic. We document these differences in the specs when possible.

1. Fork it ( https://github.com/telus-agcg/ffi-gdal/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Please consider adhering to Conventional Commits v1.0.0 with your commit messages.

There are a couple Dockerfiles that allow doing development/testing against GDAL 2.4 and 3.x.

...for GDAL2:

docker-compose run gdal2 bundle exec rake spec

...for GDAL3:

docker-compose run gdal3 bundle exec rake spec