Skip to content

R package

R-CMD-check

The geolibre R package embeds the full GeoLibre map in RStudio, Quarto, R Markdown, and Shiny through htmlwidgets. It creates standard .geolibre.json projects, so maps can move between R and the GeoLibre web or desktop application.

View the R package website Open the interactive example Browse the source

Installation

The package is currently available from GitHub while its first CRAN submission is prepared:

install.packages("pak")
pak::pak("opengeos/geolibre-r")

After it is published on CRAN, install the released version with:

install.packages("geolibre")

Quick start

Create an interactive map from GeoJSON and set its initial camera:

library(geolibre)

places <- list(
  type = "FeatureCollection",
  features = list(list(
    type = "Feature",
    properties = list(name = "Washington, DC"),
    geometry = list(
      type = "Point",
      coordinates = c(-77.0369, 38.9072)
    )
  ))
)

geolibre(map_only = TRUE) |>
  add_geojson(
    places,
    name = "Places",
    style = list(fillColor = "#dc2626", circleRadius = 8)
  ) |>
  set_view(center = c(-77.0369, 38.9072), zoom = 10)

The widget is responsive in the RStudio Viewer and rendered HTML documents. Its map loads the hosted GeoLibre application, so viewing it requires an internet connection unless app_url points to a self-hosted deployment.

Spatial data with sf

add_sf() accepts an sf object and transforms it to WGS 84 before passing GeoJSON to the browser:

library(sf)

nc <- st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)

geolibre() |>
  add_sf(nc, name = "North Carolina counties")

The sf package is optional. On Linux, installing it may require system libraries such as GDAL, GEOS, PROJ, and UDUNITS.

Remote rasters

GeoLibre reads remote Cloud Optimized GeoTIFFs directly in the browser. The server hosting the raster must support CORS and HTTP range requests.

geolibre() |>
  add_raster(
    "https://example.org/visual.tif",
    name = "Satellite image",
    bands = c(1, 2, 3)
  )

Project files

Save the widget state as a portable GeoLibre project and restore it later:

map <- geolibre() |> add_geojson(places)
save_project(map, "example.geolibre.json")

restored <- geolibre(load_project("example.geolibre.json"))

The saved project can also be opened in GeoLibre Web or GeoLibre Desktop. In a Shiny application, browser-side changes are available through input$<outputId>_project.

Shiny

Use geolibreOutput() and renderGeolibre() to render a map. A proxy updates the live widget without rebuilding the output:

library(shiny)
library(geolibre)

ui <- fluidPage(
  geolibreOutput("map", height = "80vh"),
  actionButton("reset", "Reset view")
)

server <- function(input, output, session) {
  map <- reactiveVal(geolibre(map_only = TRUE))
  output$map <- renderGeolibre(map())

  observeEvent(input$reset, {
    next_map <- set_view(map(), center = c(0, 20), zoom = 2)
    map(next_map)
    update_geolibre(geolibre_proxy("map"), next_map)
  })
}

shinyApp(ui, server)

Self-hosting

Set a custom GeoLibre application URL for one widget or for the R session:

geolibre(app_url = "https://gis.example.org/")

options(geolibre.app_url = "https://gis.example.org/")

The deployment must expose the GeoLibre web app and its ?embed=1 project bridge. See the package reference for the complete API.