Open Source Geometry Engine ('GEOS') C API

Provides the Open Source Geometry Engine ('GEOS') as a C API that can be used to write high-performance C and C++ geometry operations using R as an interface. Headers are provided to make linking to and using these functions from C++ code as easy and as safe as possible. This package contains an internal copy of the 'GEOS' library to guarantee the best possible consistency on multiple platforms.

libgeos

The goal of libgeos is to provide access to the GEOS C API for high-performance geometry operations within the R package framework. This package contains a copy of the GEOS library, modified slightly to eliminate errors on all the platorms checked by CRAN and GitHub actions. This means you don’t have to install anything (other than the package) to take advantage of GEOS functions in R. It also means you don’t need a configure script if you’re writing a package that needs GEOS functionality (just LinkingTo: libgeos). Because GEOS is license under the LGPL, dynamically linking to GEOS (e.g., through the C API exposed in this package) is generally allowed from a package with any license. See the geos R package for an R API to GEOS.

Installation

You can install the released version of libgeos from CRAN with:

install.packages("libgeos")

To install a binary on supported Linux platforms, you can use RStudio Package Manager’s public instance (see here for how to configure on your platform).

You can install the development version from RUniverse with:

install.packages("libgeos", repos = "https://paleolimbot.r-universe.dev")

Example

This package only exists for its exported C API. You can link to libgeos from a package by specifying LinkingTo: libgeos and Imports: libgeos in your DESCRIPTION. You can link to libgeos interactively from Rcpp using // [[Rcpp::depends(libgeos)]]:

#include <Rcpp.h>

// Packages will also need LinkingTo: libgeos
// [[Rcpp::depends(libgeos)]]

// needed in every file that uses GEOS functions
#include "libgeos.h"

// needed exactly once in your package or Rcpp script
// contains all the function pointers and the
// implementation of the function to initialize them
// (`libgeos_init_api()`)
#include "libgeos.c"

// this function needs to be called once before any GEOS functions
// are called (e.g., in .onLoad() for your package)
// [[Rcpp::export]]
void cpp_libgeos_init_api() {
  libgeos_init_api();
}

// regular C or C++ code that uses GEOS functions!
// [[Rcpp::export]]
std::string version() {
  return GEOSversion();
}

cpp_libgeos_init_api()
version()
#> [1] "3.11.1-CAPI-1.17.1"

You can link to libegeos interactively from cpp11 using [[cpp11::linking_to(libgeos)]]:

#include <cpp11.hpp>

// needed in every file that uses GEOS functions
#include "libgeos.h"

// needed exactly once in your package or Rcpp script
// contains all the function pointers and the
// implementation of the function to initialize them
// (`libgeos_init_api()`)
#include "libgeos.c"

// this function needs to be called once before any GEOS functions
// are called (e.g., in .onLoad() for your package)
[[cpp11::linking_to(libgeos)]]
[[cpp11::register]]
void cpp_libgeos_init_api() {
  libgeos_init_api();
}

// regular C or C++ code that uses GEOS functions!
[[cpp11::register]]
std::string version() {
  return GEOSversion();
}

cpp_libgeos_init_api()
version()
#> [1] "3.11.1-CAPI-1.17.1"