gdalcli: An R Frontend for the GDAL (>=3.11) Unified CLI
An R interface to GDAL's unified command-line interface (GDAL >=3.11). Provides a lazy evaluation framework for building and executing GDAL commands with composable, pipe-aware functions. Supports native GDAL pipelines, gdalcli pipeline format persistence, and pipeline composition.
Installation
Version-Specific Releases
gdalcli is released as version-specific builds tied to particular GDAL
releases. Using a package version matching your GDAL version is
recommended. Newer package versions introduce features that require
newer GDAL versions. Existing functionality should generally remain
compatible with older GDAL installations, though this cannot be
guaranteed until the GDAL CLI is stabilized.
See GitHub Releases for the latest version-specific builds.
Each release is tagged with both the package version and the GDAL version it targets:
v0.5.0-3.11.4- Compatible with GDAL 3.11.4v0.5.0-3.12.0- Compatible with GDAL 3.12.0- etc.
Finding Your GDAL Version
# Check your system GDAL installation
system2("gdalinfo", "--version")
system2("gdalinfo", "--version")
Installation from Release Branch
Install the version compatible with your GDAL installation:
# For GDAL 3.12.x
remotes::install_github("brownag/gdalcli", ref = "release/gdal-3.12")
# For GDAL 3.11.x
remotes::install_github("brownag/gdalcli", ref = "release/gdal-3.11")
remotes::install_github("brownag/gdalcli", ref = "release/gdal-3.12")
# For GDAL 3.11.x
remotes::install_github("brownag/gdalcli", ref = "release/gdal-3.11")
Docker: Pre-built images available at
ghcr.io/brownag/gdalcli:gdal-X.Y.Z-latest
Requirements
- R >= 4.1
- GDAL >= 3.11 (CLI must be available in system PATH for processx backend)
- gdalraster (optional; enables gdalraster backend)
- reticulate (optional; enables reticulate backend)
Examples
Basic Usage
library(gdalcli)
# Create a job (lazy evaluation - nothing executes yet)
job <- gdal_raster_convert(
input = system.file("extdata/sample_clay_content.tif", package = "gdalcli"),
output = tempfile(fileext = ".tif"),
output_format = "COG"
)
# Execute the job
gdal_job_run(job)
#> 0...10...20...30...40...50...60...70...80...90...100 - done.
# Create a job (lazy evaluation - nothing executes yet)
job <- gdal_raster_convert(
input = system.file("extdata/sample_clay_content.tif", package = "gdalcli"),
output = tempfile(fileext = ".tif"),
output_format = "COG"
)
# Execute the job
gdal_job_run(job)
#> 0...10...20...30...40...50...60...70...80...90...100 - done.
Adding Options
job <- gdal_raster_convert(
input = system.file("extdata/sample_clay_content.tif", package = "gdalcli"),
output = tempfile(fileext = ".tif"),
output_format = "COG"
) |>
gdal_with_co("COMPRESS=LZW", "PREDICTOR=2") |>
gdal_with_config("GDAL_CACHEMAX=512")
gdal_job_run(job)
input = system.file("extdata/sample_clay_content.tif", package = "gdalcli"),
output = tempfile(fileext = ".tif"),
output_format = "COG"
) |>
gdal_with_co("COMPRESS=LZW", "PREDICTOR=2") |>
gdal_with_config("GDAL_CACHEMAX=512")
gdal_job_run(job)
Multi-Step Pipelines
pipeline <- gdal_raster_reproject(
input = system.file("extdata/sample_clay_content.tif", package = "gdalcli"),
dst_crs = "EPSG:32632"
) |>
gdal_raster_scale(src_min = 0, src_max = 100, dst_min = 0, dst_max = 255) |>
gdal_raster_convert(output = tempfile(fileext = ".tif"), output_format = "COG")
gdal_job_run(pipeline)
#> 0...10...20...30...40...50...60...70...80...90...100 - done.
#> 0...10...20...30...40...50...60...70...80...90...100 - done.
input = system.file("extdata/sample_clay_content.tif", package = "gdalcli"),
dst_crs = "EPSG:32632"
) |>
gdal_raster_scale(src_min = 0, src_max = 100, dst_min = 0, dst_max = 255) |>
gdal_raster_convert(output = tempfile(fileext = ".tif"), output_format = "COG")
gdal_job_run(pipeline)
#> 0...10...20...30...40...50...60...70...80...90...100 - done.
#> 0...10...20...30...40...50...60...70...80...90...100 - done.
Pipeline Persistence
# Save pipeline to gdalcli pipeline format
workflow_file <- tempfile(fileext = ".gdalcli.json")
gdal_save_pipeline(pipeline, workflow_file, name = "Example Pipeline")
# Load pipeline for later use
loaded <- gdal_load_pipeline(workflow_file)
workflow_file <- tempfile(fileext = ".gdalcli.json")
gdal_save_pipeline(pipeline, workflow_file, name = "Example Pipeline")
# Load pipeline for later use
loaded <- gdal_load_pipeline(workflow_file)
Cloud Storage
# Set AWS credentials (from environment variables)
auth <- gdal_auth_s3()
job <- gdal_raster_convert(
input = "/vsis3/my-bucket/input.tif",
output = "/vsis3/my-bucket/output.tif",
output_format = "COG"
) |>
gdal_with_env(auth)
gdal_job_run(job)
auth <- gdal_auth_s3()
job <- gdal_raster_convert(
input = "/vsis3/my-bucket/input.tif",
output = "/vsis3/my-bucket/output.tif",
output_format = "COG"
) |>
gdal_with_env(auth)
gdal_job_run(job)
Raster Information
# Get detailed information about a raster file
info_job <- gdal_raster_info(
input = system.file("extdata/sample_clay_content.tif", package = "gdalcli")
)
gdal_job_run(info_job)
info_job <- gdal_raster_info(
input = system.file("extdata/sample_clay_content.tif", package = "gdalcli")
)
gdal_job_run(info_job)
Vector Operations
# Convert vector format
vector_job <- gdal_vector_convert(
input = system.file("extdata/sample_mapunit_polygons.gpkg", package = "gdalcli"),
output = tempfile(fileext = ".geojson"),
output_format = "GeoJSON"
)
gdal_job_run(vector_job, backend = "processx")
vector_job <- gdal_vector_convert(
input = system.file("extdata/sample_mapunit_polygons.gpkg", package = "gdalcli"),
output = tempfile(fileext = ".geojson"),
output_format = "GeoJSON"
)
gdal_job_run(vector_job, backend = "processx")
Raster Processing Pipeline
# Simple processing pipeline: reproject and convert
processing_pipeline <- gdal_raster_reproject(
input = system.file("extdata/sample_clay_content.tif", package = "gdalcli"),
dst_crs = "EPSG:32632"
) |>
gdal_raster_convert(output = tempfile(fileext = ".tif"))
gdal_job_run(processing_pipeline, backend = "processx")
processing_pipeline <- gdal_raster_reproject(
input = system.file("extdata/sample_clay_content.tif", package = "gdalcli"),
dst_crs = "EPSG:32632"
) |>
gdal_raster_convert(output = tempfile(fileext = ".tif"))
gdal_job_run(processing_pipeline, backend = "processx")
Backends
gdalcli supports multiple execution backends:
- processx (default): Executes GDAL CLI commands as subprocesses
- gdalraster (optional): Uses C++ GDAL bindings via gdalraster package
- reticulate (optional): Uses Python GDAL bindings via reticulate
Set your preferred backend globally:
# Using gdalcli_options()
gdalcli_options(backend = "gdalraster")
# Or using base R options() directly
options(gdalcli.backend = "gdalraster") # or "processx", "reticulate"
gdalcli_options(backend = "gdalraster")
# Or using base R options() directly
options(gdalcli.backend = "gdalraster") # or "processx", "reticulate"
Package Options
Manage package behavior with gdalcli_options():
# View current options
gdalcli_options()
# Set options
gdalcli_options(
backend = "auto", # "auto", "gdalraster", or "processx"
verbose = TRUE, # Enable verbose output
stream_out_format = "text", # NULL, "text", or "binary"
audit_logging = FALSE # Enable audit logging
)
# Set individual options
gdalcli_options(verbose = TRUE)
gdalcli_options(backend = "processx")
gdalcli_options()
# Set options
gdalcli_options(
backend = "auto", # "auto", "gdalraster", or "processx"
verbose = TRUE, # Enable verbose output
stream_out_format = "text", # NULL, "text", or "binary"
audit_logging = FALSE # Enable audit logging
)
# Set individual options
gdalcli_options(verbose = TRUE)
gdalcli_options(backend = "processx")
Pipeline Features
Native GDAL Pipeline Execution
Execute multi-step workflows as a single GDAL pipeline:
pipeline <- gdal_raster_reproject(
input = system.file("extdata/sample_clay_content.tif", package = "gdalcli"),
dst_crs = "EPSG:32632"
) |>
gdal_raster_convert(output = tempfile(fileext = ".tif"))
gdal_job_run(pipeline, backend = "processx")
input = system.file("extdata/sample_clay_content.tif", package = "gdalcli"),
dst_crs = "EPSG:32632"
) |>
gdal_raster_convert(output = tempfile(fileext = ".tif"))
gdal_job_run(pipeline, backend = "processx")
gdalcli Pipeline Format: Save and Load Pipelines
Persist pipelines as JSON for sharing and version control. gdalcli supports three formats:
- Hybrid Format (.gdalcli.json): Combines GDAL command with R metadata for lossless round-trip serialization
- Pure GDALG Format (.gdalg.json): RFC 104 compliant GDAL specification for compatibility with other GDAL tools
- Legacy Format: Deprecated (pre-v0.5.0) - no longer recommended
# Save pipeline to gdalcli hybrid format (recommended)
workflow_file <- tempfile(fileext = ".gdalcli.json")
gdal_save_pipeline(
pipeline,
workflow_file,
name = "Reproject and Scale",
description = "Reproject to UTM Zone 32N and scale to 0-255"
)
# Load pipeline for later use (auto-detects format)
loaded <- gdal_load_pipeline(workflow_file)
# Export as pure GDALG for use with other GDAL tools
gdalg <- as_gdalg(loaded)
gdalg_write(gdalg, "workflow.gdalg.json")
workflow_file <- tempfile(fileext = ".gdalcli.json")
gdal_save_pipeline(
pipeline,
workflow_file,
name = "Reproject and Scale",
description = "Reproject to UTM Zone 32N and scale to 0-255"
)
# Load pipeline for later use (auto-detects format)
loaded <- gdal_load_pipeline(workflow_file)
# Export as pure GDALG for use with other GDAL tools
gdalg <- as_gdalg(loaded)
gdalg_write(gdalg, "workflow.gdalg.json")
Shell Script Generation
Generate executable shell scripts from pipelines:
# Generate bash script
script <- render_shell_script(pipeline, format = "native", shell = "bash")
cat(script)
#> #!/bin/bash
#>
#> set -e
#>
#> # Native GDAL pipeline execution
#> gdal raster pipeline ! read /home/andrew/R/x86_64-pc-linux-gnu-library/4.5/gdalcli/extda ta/sample_clay_content.tif ! reproject --dst-crs EPSG:32632 --output /vsimem/gdalcli_9860c6c83523c.tif ! scale --src-min 0 --src-max 100 --dst-min 0 --dst-max 255 ! write /tmp/Rtmpw8bD5X/file9860c5ba69099.tif --input /vsimem/gdalcli_9860c372bd35c.tif
script <- render_shell_script(pipeline, format = "native", shell = "bash")
cat(script)
#> #!/bin/bash
#>
#> set -e
#>
#> # Native GDAL pipeline execution
#> gdal raster pipeline ! read /home/andrew/R/x86_64-pc-linux-gnu-library/4.5/gdalcli/extda ta/sample_clay_content.tif ! reproject --dst-crs EPSG:32632 --output /vsimem/gdalcli_9860c6c83523c.tif ! scale --src-min 0 --src-max 100 --dst-min 0 --dst-max 255 ! write /tmp/Rtmpw8bD5X/file9860c5ba69099.tif --input /vsimem/gdalcli_9860c372bd35c.tif
Architecture
gdalcli uses a three-layer architecture:
- Frontend Layer: Auto-generated R functions with composable modifiers
- Pipeline Layer: Automatic pipeline building and gdalcli pipeline format serialization
- Engine Layer: Command execution with multiple backend options
Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
License
MIT License - see LICENSE file for details