Package 'gdalvector'

Description

Render a gdal_config_opts() or gdal_vsi_opts() object to a named character vector c(NAME = "VALUE"), the form consumed by gdalraster::set_config_option(). Configuration options are ignored by the GDAL algorithm API and must be applied to the process/session this way (or via the CLI --config flag, see as_gdal_args()).

Usage

as_config_option(x, ...)

## S3 method for class 'gdal_config_opts'
as_config_option(x, ...)

## S3 method for class 'gdal_vsi_opts'
as_config_option(x, ...)

## Default S3 method:
as_config_option(x, ...)

Arguments

Value

A named character vector.

Examples

as_config_option(gdal_config_opts(CPL_DEBUG = "ON"))

Description

Render a gdal_opts() object to the form consumed by the GDAL algorithm API (gdalraster::gdal_alg() / gdalraster::gdal_run()).

Usage

as_gdal_args(x, ...)

## S3 method for class 'gdal_opts'
as_gdal_args(x, cli = TRUE, long = FALSE, with_format = FALSE, ...)

## S3 method for class 'character'
as_gdal_args(x, ...)

## S3 method for class 'list'
as_gdal_args(x, ...)

## Default S3 method:
as_gdal_args(x, ...)

Arguments

Details

For repeated options (--oo/--co/--lco), GDAL requires each value to be preceded by its own flag - values are never comma-packed (a packed value would corrupt options such as PRELUDE_STATEMENTS that themselves contain ⁠;⁠/⁠,⁠). Accordingly:

• cli = TRUE (default) emits a flat token vector c("--open-option", "K=V", "--open-option", "K2=V2", ...), suitable as the args to gdalraster::gdal_alg().

• cli = FALSE emits an unnamed c("K=V", ...) vector, suitable for a single ⁠alg$setArg(<flag>, .)⁠ call.

Value

A character vector.

Examples

as_gdal_args(gdal_open_opts(LIST_ALL_TABLES = FALSE, driver = "GPKG"))
as_gdal_args(gdal_open_opts(LIST_ALL_TABLES = FALSE), cli = FALSE)

Description

Coerce a named list, a KEY=VALUE character vector, a driver-metadata tibble, or an existing gdal_config_opts to the gdal_config_opts() class.

Usage

as_gdal_config_opts(x, ..., driver = NULL, call = rlang::caller_env())

## Default S3 method:
as_gdal_config_opts(x, ..., driver = NULL, call = rlang::caller_env())

## S3 method for class 'gdal_config_opts'
as_gdal_config_opts(x, ..., driver = NULL, call = rlang::caller_env())

## S3 method for class 'list'
as_gdal_config_opts(x, ..., driver = NULL, call = rlang::caller_env())

## S3 method for class 'character'
as_gdal_config_opts(x, ..., driver = NULL, call = rlang::caller_env())

## S3 method for class 'tbl_df'
as_gdal_config_opts(x, ..., driver = NULL, call = rlang::caller_env())

Arguments

Value

A gdal_config_opts() object.

Description

Coerce a named list, a KEY=VALUE character vector, a driver-metadata tibble, or an existing gdal_creation_opts to the gdal_creation_opts() class.

Usage

as_gdal_creation_opts(
  x,
  ...,
  driver = NULL,
  level = c("layer", "dataset"),
  call = rlang::caller_env()
)

## Default S3 method:
as_gdal_creation_opts(
  x,
  ...,
  driver = NULL,
  level = c("layer", "dataset"),
  call = rlang::caller_env()
)

## S3 method for class 'gdal_creation_opts'
as_gdal_creation_opts(
  x,
  ...,
  driver = NULL,
  level = c("layer", "dataset"),
  call = rlang::caller_env()
)

## S3 method for class 'list'
as_gdal_creation_opts(
  x,
  ...,
  driver = NULL,
  level = c("layer", "dataset"),
  call = rlang::caller_env()
)

## S3 method for class 'character'
as_gdal_creation_opts(
  x,
  ...,
  driver = NULL,
  level = c("layer", "dataset"),
  call = rlang::caller_env()
)

## S3 method for class 'tbl_df'
as_gdal_creation_opts(
  x,
  ...,
  driver = NULL,
  level = c("layer", "dataset"),
  call = rlang::caller_env()
)

Arguments

Value

A gdal_creation_opts() object.

Description

Coerce a named list, a KEY=VALUE character vector, a driver-metadata tibble, or an existing gdal_open_opts to the gdal_open_opts() class.

Usage

as_gdal_open_opts(x, ..., driver = NULL, call = rlang::caller_env())

## Default S3 method:
as_gdal_open_opts(x, ..., driver = NULL, call = rlang::caller_env())

## S3 method for class 'gdal_open_opts'
as_gdal_open_opts(x, ..., driver = NULL, call = rlang::caller_env())

## S3 method for class 'list'
as_gdal_open_opts(x, ..., driver = NULL, call = rlang::caller_env())

## S3 method for class 'character'
as_gdal_open_opts(x, ..., driver = NULL, call = rlang::caller_env())

## S3 method for class 'tbl_df'
as_gdal_open_opts(x, ..., driver = NULL, call = rlang::caller_env())

Arguments

Value

A gdal_open_opts() object.

Description

Coerce a named list, a KEY=VALUE character vector, or an existing gdal_vsi_opts to the gdal_vsi_opts() class. VSI options are path-scoped, config-like settings applied via gdalraster::vsi_set_path_option().

Usage

as_gdal_vsi_opts(x, ..., vsi_path = NULL, call = rlang::caller_env())

## Default S3 method:
as_gdal_vsi_opts(x, ..., vsi_path = NULL, call = rlang::caller_env())

## S3 method for class 'gdal_vsi_opts'
as_gdal_vsi_opts(x, ..., vsi_path = NULL, call = rlang::caller_env())

## S3 method for class 'list'
as_gdal_vsi_opts(x, ..., vsi_path = NULL, call = rlang::caller_env())

## S3 method for class 'character'
as_gdal_vsi_opts(x, ..., vsi_path = NULL, call = rlang::caller_env())

Arguments

Value

A gdal_vsi_opts() object.

Description

Coerce to GDALG

Usage

as_gdalg(x, ..., call = rlang::caller_env())

Arguments

Value

An object of class "gdalg".

Description

Checks that the provided value x (in bytes) does not exceed the available system RAM as returned by sys_available_ram(). If the check fails, an error is thrown.

Usage

check_available_ram(x, arg = rlang::caller_arg(x), call = rlang::caller_env())

Arguments

Value

If the check passes, invisibly returns the provided x value. If the check fails, a condition error is thrown indicating that the provided value exceeds available system RAM.

Description

These functions perform checks that assert the underlying class of objects passed to them.

• check_inherits(): checks that object x is of class class using base::inherits()

• check_inherits2(): checks that object x is of class class using base::.class2()

• check_inherits_any(): checks that object x is at least one of the provided classes via rlang::inherits_any()

• check_inherits_all(): checks that object x is all of the provided classes via rlang::inherits_all()

If validation fails for any of these functions, an error is thrown via check_abort() displaying a friendly error message.

Usage

check_inherits(
  x,
  class,
  arg = rlang::caller_arg(x),
  call = rlang::caller_env()
)

check_inherits2(
  x,
  class,
  arg = rlang::caller_arg(x),
  call = rlang::caller_env()
)

check_inherits_any(
  x,
  classes,
  arg = rlang::caller_arg(x),
  call = rlang::caller_env()
)

check_inherits_all(
  x,
  classes,
  arg = rlang::caller_arg(x),
  call = rlang::caller_env()
)

Arguments

Value

If checks pass, invisibly returns the provided x object. If checks fail, a condition error is thrown.

Description

Checks the provided x is not "empty" via rlang::is_empty().

Usage

check_not_empty(x, arg = rlang::caller_arg(x), call = rlang::caller_env())

Arguments

Value

If checks pass, invisibly returns the provided x object. If checks fail, a condition error is thrown.

Description

Checks the provided x is a scalar string via rlang::check_string().

Usage

check_string(x, arg = rlang::caller_arg(x), call = rlang::caller_env())

Arguments

Value

If checks pass, invisibly returns the provided x object. If checks fail, a condition error is thrown.

Description

Collection of various checking functions primarily used for incorporating argument validation checks for package functions.

These check functions act as assertions, and will either return the provided objects invisibly, or throw exceptions.

Description

The FlatGeobuf driver exposes no documented configuration options. This constructor exists for interface symmetry with the other driver option families; it warns and returns an empty gdal_config_opts() object.

Usage

fgb_config_opts(...)

Arguments

Value

An (empty) gdal_config_opts() object for the FlatGeobuf driver.

See Also

fgb_open_opts(), fgb_creation_opts()

Examples

fgb_config_opts()

Description

Construct a layer-level gdal_creation_opts() object for the FlatGeobuf driver. Only options you supply are emitted; values are validated against the driver's registered metadata.

Usage

fgb_creation_opts(
  spatial_index = NULL,
  temporary_dir = NULL,
  title = NULL,
  description = NULL,
  ...,
  .set_defaults = FALSE
)

Arguments

Value

A layer-level gdal_creation_opts() object for the FlatGeobuf driver.

See Also

fgb_open_opts(), gdal_creation_opts()

• FlatGeobuf Home Page

• FlatGeobuf GDAL Driver

  • FlatGeobuf GDAL Open Options

  • FlatGeobuf GDAL Layer Creation Options

Examples

fgb_creation_opts(spatial_index = TRUE, title = "Parcels")

Description

Construct a gdal_open_opts() object for the FlatGeobuf driver. Only options you supply are emitted; values are validated against the driver's registered metadata.

Usage

fgb_open_opts(verify_buffers = NULL, ..., .set_defaults = FALSE)

Arguments

Value

A gdal_open_opts() object for the FlatGeobuf driver.

See Also

fgb_creation_opts(), gdal_open_opts()

• FlatGeobuf Home Page

• FlatGeobuf GDAL Driver

  • FlatGeobuf GDAL Open Options

  • FlatGeobuf GDAL Layer Creation Options

Examples

fgb_open_opts()
fgb_open_opts(verify_buffers = FALSE)
fgb_open_opts(.set_defaults = TRUE)

Description

Validates if the available RAM is sufficient to build a spatial index for a FlatGeobuf file based on the number of features and an estimated RAM requirement of 83 bytes per feature.

Usage

fgb_validate_spatial_index_ram(fgb_dsn, force = FALSE, quiet = FALSE)

Arguments

Value

Returns TRUE if sufficient RAM is available to build the spatial index, and FALSE otherwise. Also provides informative messages about the RAM requirements and availability.

Description

Creates a session-wide, global GDAL Configuration object of class "gdal_config".

Usage

gdal_config(...)

Arguments

Value

gdal_config

Description

Links to the official GDAL Configuration Documentation.

• GDAL Configuration Options

  • Setting Configuration Options

See Also

gdal_config_opts()

Description

Construct a gdal_config_opts() object from NAME = value pairs. Configuration options are global, stateful settings applied to the GDAL process (via gdalraster::set_config_option() / the CLI --config flag), and are not algorithm arguments. When driver is supplied, values for boolean options are validated against the driver metadata.

Usage

gdal_config_opts(..., driver = NULL, .set_defaults = FALSE)

Arguments

Value

A gdal_config_opts() object.

Examples

gdal_config_opts(CPL_DEBUG = "ON", GDAL_NUM_THREADS = "ALL_CPUS")

Description

Construct a gdal_creation_opts() object from NAME = value pairs. The level controls whether these are dataset-creation options (--co) or layer-creation options (--lco, the default).

Usage

gdal_creation_opts(
  ...,
  driver = NULL,
  level = c("layer", "dataset"),
  .set_defaults = FALSE
)

Arguments

Value

A gdal_creation_opts() object.

Examples

gdal_creation_opts(COMPRESSION = "ZSTD", driver = "Parquet")

Description

Query the GDAL drivers registered in the active GDAL build.

• gdal_drivers(): returns a normalized tibble::tibble() of driver metadata (identity, capabilities, supported extensions and SQL dialects), optionally filtered by a name pattern.

• gdal_driver_names(): returns just the short driver names.

The driver table is built once from gdalraster::gdal_formats() and cached for the session.

Usage

gdal_drivers(pattern = NULL, ignore_case = TRUE)

gdal_driver_names(pattern = NULL)

Arguments

Value

• gdal_drivers(): a tibble::tibble() with one row per driver.

• gdal_driver_names(): a character vector of short driver names.

See Also

gdal_vector_driver_opts(), gdal_vector_driver_capabilities()

Examples

gdal_drivers()
gdal_drivers(c("parquet", "geojson"))
gdal_driver_names("gpkg")

Description

Construct a gdal_open_opts() object from NAME = value pairs (the GDAL --oo / GDALOpenEx() open-option channel).

Usage

gdal_open_opts(..., driver = NULL, .set_defaults = FALSE)

Arguments

Value

A gdal_open_opts() object.

Examples

gdal_open_opts(LIST_ALL_TABLES = FALSE, driver = "GPKG")

Description

GDAL options control how the GDAL/OGR library reads, writes, and otherwise processes geospatial data. This package models the distinct GDAL option channels as a small family of S3 classes, each backed by a named list of NAME = "VALUE" pairs (values stored as their coerced GDAL strings) plus a driver attribute, so a set of options is an inert, composable value that can be rendered on demand to whichever form a given consumer needs.

In the GDAL CLI, an option is supplied via one of these argument flags:

--config <NAME>=<VALUE>
--open-option / --oo <NAME>=<VALUE>
--creation-option / --co <NAME>=<VALUE>
--layer-creation-option / --lco <NAME>=<VALUE>

Classes

All four classes share the gdal_opts base (a named list) and differ only by channel:

gdal_opts
 |- gdal_config_opts                          --config      CPLSetConfigOption()
 |- gdal_open_opts                            --oo          GDALOpenEx()
 |- gdal_creation_opts  (level = layer)       --lco         GDALDatasetCreateLayer()
 |                      (level = dataset)     --co          GDALCreate()
 |- gdal_vsi_opts       (vsi_path)            --config      VSISetPathSpecificOption()

• gdal_config_opts(): global, stateful configuration options. Applied to the process/session (via gdalraster::set_config_option()), not as an algorithm argument.

• gdal_open_opts(): driver open options.

• gdal_creation_opts(): driver dataset- or layer-creation options, selected by level.

• gdal_vsi_opts(): virtual file system (VSI) path-scoped options (config-like).

Rendering

A gdal_opts value is rendered with as_gdal_args() (CLI token vector for gdalraster::gdal_alg() / gdalraster::gdal_run()), as_config_option() (a NAME = VALUE character vector for gdalraster::set_config_option(), config/VSI only), or gdal_render() (a copy-pasteable shell snippet).

See Also

as_gdal_args(), as_config_option(), gdal_render(); and the typed per-driver builders gpkg_open_opts(), gpq_creation_opts(), shp_open_opts(), fgb_creation_opts(), gdb_open_opts().

Description

Render a gdal_opts() object to a copy-pasteable, multi-line shell snippet with one flag/value pair per line and the appropriate line-continuation for the target shell. Only the option flags (and the leading --input-format/--output-format when the driver is known) are rendered; the base gdal invocation and datasets are not included.

Usage

gdal_render(x, shell = c("bash", "sh", "pwsh", "cmd"))

Arguments

Value

A length-1 character string (embedded newlines), or "" when there are no options.

Examples

gdal_render(gdal_creation_opts(COMPRESSION = "ZSTD", driver = "Parquet"), shell = "bash")

Description

Return a driver's capability flags (the ⁠DCAP_*⁠ metadata items) as a named logical vector.

Usage

gdal_vector_driver_capabilities(driver)

Arguments

Value

A named logical vector, one element per ⁠DCAP_*⁠ capability (name without the DCAP_ prefix retained as given by GDAL), TRUE where the capability is advertised.

See Also

gdal_drivers()

Examples

gdal_vector_driver_capabilities("GPKG")

Description

Accessors for a driver's configuration options (the --config channel). Configuration options are sourced from curated package data, since GDAL does not expose them in driver metadata.

• gdal_vector_driver_config_opts(): the configuration-option table for driver.

• gdal_vector_driver_config_opts_defaults(): name to default (all, or one when opt_name given).

• gdal_vector_driver_config_opts_values(): name to allowed values (only constrained options).

• gdal_vector_driver_config_opts_types(): name to data_type.

Usage

gdal_vector_driver_config_opts(driver)

gdal_vector_driver_config_opts_defaults(driver, opt_name = NULL)

gdal_vector_driver_config_opts_values(driver, opt_name = NULL)

gdal_vector_driver_config_opts_types(driver)

Arguments

Value

A tibble::tibble(), named character vector, or named list (see gdal_vector_driver_opts()).

See Also

gdal_config_opts(), gdal_vector_driver_opts()

Examples

gdal_vector_driver_config_opts("GPKG")
gdal_vector_driver_config_opts_values("GPKG")

Description

Accessors for a driver's creation options, parsed from both the dataset-level (DMD_CREATIONOPTIONLIST, --co) and layer-level (DS_LAYER_CREATIONOPTIONLIST, --lco) metadata. Use sub_type to restrict to one level.

• gdal_vector_driver_creation_opts(): the creation-option table for driver.

• gdal_vector_driver_creation_opts_defaults(): name to default (all, or one when opt_name given).

• gdal_vector_driver_creation_opts_values(): name to allowed values (only constrained options).

• gdal_vector_driver_creation_opts_types(): name to data_type.

Usage

gdal_vector_driver_creation_opts(driver, sub_type = NULL)

gdal_vector_driver_creation_opts_defaults(
  driver,
  opt_name = NULL,
  sub_type = NULL
)

gdal_vector_driver_creation_opts_values(
  driver,
  opt_name = NULL,
  sub_type = NULL
)

gdal_vector_driver_creation_opts_types(driver, sub_type = NULL)

Arguments

Value

A tibble::tibble(), named character vector, or named list (see gdal_vector_driver_opts()).

See Also

gdal_creation_opts(), gdal_vector_driver_opts()

Examples

gdal_vector_driver_creation_opts("Parquet", sub_type = "layer")
gdal_vector_driver_creation_opts_values("GPKG", sub_type = "layer")

Description

Accessors for a driver's open options (the --oo / GDALOpenEx() channel), parsed from the driver's DMD_OPENOPTIONLIST metadata.

• gdal_vector_driver_open_opts(): the open-option table for driver.

• gdal_vector_driver_open_opts_defaults(): name to default (all, or one when opt_name given).

• gdal_vector_driver_open_opts_values(): name to allowed values (only constrained options).

• gdal_vector_driver_open_opts_types(): name to data_type.

Usage

gdal_vector_driver_open_opts(driver)

gdal_vector_driver_open_opts_defaults(driver, opt_name = NULL)

gdal_vector_driver_open_opts_values(driver, opt_name = NULL)

gdal_vector_driver_open_opts_types(driver)

Arguments

Value

A tibble::tibble(), named character vector, or named list (see gdal_vector_driver_opts()).

See Also

gdal_open_opts(), gdal_vector_driver_opts()

Examples

gdal_vector_driver_open_opts("GPKG")
gdal_vector_driver_open_opts_values("GPKG", "LIST_ALL_TABLES")

Description

Look up the documented options for the core supported vector drivers (see GDAL_VECTOR_DRIVERS), drawn from the merged option table assembled at package load (driver-metadata XML for open/creation options plus the curated configuration options).

• gdal_vector_driver_opts(): the full option table, optionally filtered by type, sub_type, and scope.

• gdal_vector_driver_opt_defaults(): a named vector mapping option name to its declared default.

• gdal_vector_driver_opt_values(): a named list mapping option name to its allowed values (booleans expanded to c("YES", "NO")); only options that declare a constrained set appear.

• gdal_vector_driver_opt_types(): a named vector mapping option name to its data_type.

Usage

gdal_vector_driver_opts(
  driver = NULL,
  type = NULL,
  sub_type = NULL,
  scope = NULL
)

gdal_vector_driver_opt_defaults(
  driver,
  type = NULL,
  sub_type = NULL,
  scope = NULL
)

gdal_vector_driver_opt_values(
  driver,
  type = NULL,
  sub_type = NULL,
  scope = NULL
)

gdal_vector_driver_opt_types(
  driver,
  type = NULL,
  sub_type = NULL,
  scope = NULL
)

Arguments

Value

• gdal_vector_driver_opts(): a tibble::tibble() of options.

• gdal_vector_driver_opt_defaults() / gdal_vector_driver_opt_types(): a named character vector.

• gdal_vector_driver_opt_values(): a named list of character vectors.

See Also

gdal_vector_driver_open_opts(), gdal_vector_driver_creation_opts(), gdal_vector_driver_config_opts()

Examples

gdal_vector_driver_opts("GPKG", type = "open")
gdal_vector_driver_opt_defaults("GPKG", type = "open")

Description

Construct a gdal_vsi_opts() object from NAME = value pairs, optionally scoped to a vsi_path. These are config-like options for GDAL virtual file systems (e.g. cloud storage credentials and HTTP tuning) and render as ⁠--config NAME=VALUE⁠.

Usage

gdal_vsi_opts(..., vsi_path = NULL)

Arguments

Value

A gdal_vsi_opts() object.

Examples

gdal_vsi_opts(AWS_REGION = "us-east-1", vsi_path = "/vsis3/my-bucket")

Description

Construct a gdal_config_opts() object for the OpenFileGDB driver. Only options you supply are emitted; boolean values are validated against the driver metadata.

Usage

gdb_config_opts(
  default_string_width = NULL,
  in_memory_spi = NULL,
  ...,
  .set_defaults = FALSE
)

Arguments

Value

A gdal_config_opts() object for the OpenFileGDB driver.

See Also

gdb_open_opts(), gdb_creation_opts(), gdal_config_opts()

• OpenFileGDB GDAL Driver

  • OpenFileGDB GDAL Open Options

  • OpenFileGDB GDAL Layer Creation Options

  • OpenFileGDB GDAL Configuration Options

• ESRI File Geodatabase (.gdb) Format

Examples

gdb_config_opts(default_string_width = 1024L, in_memory_spi = TRUE)

Description

Construct a layer-level gdal_creation_opts() object for the OpenFileGDB driver. Typed arguments cover the common layer options; advanced coordinate-precision grid options (XORIGIN, XYSCALE, XYTOLERANCE, ⁠Z*⁠/⁠M*⁠) may be supplied through ....

Usage

gdb_creation_opts(
  fid = NULL,
  geometry_name = NULL,
  geometry_nullable = NULL,
  configuration_keyword = NULL,
  target_arcgis_version = NULL,
  create_multipatch = NULL,
  create_shape_area_and_length_fields = NULL,
  time_in_utc = NULL,
  column_types = NULL,
  feature_dataset = NULL,
  layer_alias = NULL,
  documentation = NULL,
  ...,
  .set_defaults = FALSE
)

Arguments

Value

A layer-level gdal_creation_opts() object for the OpenFileGDB driver.

See Also

gdb_open_opts(), gdal_creation_opts()

• OpenFileGDB GDAL Driver

  • OpenFileGDB GDAL Open Options

  • OpenFileGDB GDAL Layer Creation Options

  • OpenFileGDB GDAL Configuration Options

• ESRI File Geodatabase (.gdb) Format

Examples

gdb_creation_opts(geometry_name = "SHAPE", target_arcgis_version = "ALL")

Description

Construct a gdal_open_opts() object for the OpenFileGDB driver.

Usage

gdb_open_opts(list_all_tables = NULL, ..., .set_defaults = FALSE)

Arguments

Value

A gdal_open_opts() object for the OpenFileGDB driver.

See Also

gdb_creation_opts(), gdal_open_opts()

• OpenFileGDB GDAL Driver

  • OpenFileGDB GDAL Open Options

  • OpenFileGDB GDAL Layer Creation Options

  • OpenFileGDB GDAL Configuration Options

• ESRI File Geodatabase (.gdb) Format

Examples

gdb_open_opts(list_all_tables = TRUE)

Description

Construct a gdal_config_opts() object for the GPKG driver. These are global configuration options applied to the GDAL process.

Usage

gpkg_config_opts(
  sqlite_cache = NULL,
  sqlite_journal = NULL,
  sqlite_synchronous = NULL,
  sqlite_pragma = NULL,
  use_ogr_vfs = NULL,
  num_threads = NULL,
  ...,
  .set_defaults = FALSE
)

Arguments

Value

A gdal_config_opts() object for the GPKG driver.

See Also

gpkg_open_opts(), gpkg_creation_opts(), gdal_config_opts()

• GDAL GPKG (GeoPackage) vector driver

• GPKG open options

• GDAL configuration options

• SQLite PRAGMA statements

• GeoPackage specification

Examples

gpkg_config_opts(sqlite_synchronous = "OFF", use_ogr_vfs = TRUE, num_threads = "ALL_CPUS")

Description

Construct a gdal_creation_opts() object for the GPKG driver. The typed arguments are layer-creation options (level = "layer", the default, --lco); dataset-creation options (VERSION, METADATA_TABLES, ADD_GPKG_OGR_CONTENTS, ...) are supplied through ... together with level = "dataset".

Usage

gpkg_creation_opts(
  fid = NULL,
  geometry_name = NULL,
  geometry_nullable = NULL,
  spatial_index = NULL,
  identifier = NULL,
  description = NULL,
  launder = NULL,
  overwrite = NULL,
  ...,
  level = c("layer", "dataset"),
  .set_defaults = FALSE
)

Arguments

Value

A gdal_creation_opts() object for the GPKG driver.

See Also

gpkg_open_opts(), gdal_creation_opts()

• GDAL GPKG (GeoPackage) vector driver

• GPKG open options

• GDAL configuration options

• SQLite PRAGMA statements

• GeoPackage specification

Examples

gpkg_creation_opts(geometry_name = "geom", spatial_index = TRUE)
gpkg_creation_opts(VERSION = "1.4", level = "dataset")

Description

Construct a gdal_open_opts() object for the GPKG (GeoPackage) driver.

Usage

gpkg_open_opts(
  list_all_tables = NULL,
  prelude_statements = NULL,
  nolock = NULL,
  immutable = NULL,
  ...,
  .set_defaults = FALSE
)

Arguments

Details

Because a GeoPackage is a SQLite database, several open options carry performance and safety implications. Of note is the PRELUDE_STATEMENTS open option, which allows you to specify arbitrary SQL statements that will run before any other queries once connected to the SQLite3 connection is established. This is commonly used to attach another database and issue cross-database requests, but we use it more commonly here to set PRAGMA statements to optimize performance and avoid the global configuration ⁠OGR_SQLITE_*⁠ options.

Each open option is enumerated and described below:

• ⁠LIST_ALL_TABLES=[AUTO/YES/NO]⁠: Defaults to AUTO. Whether all tables, including those not listed in gpkg_contents, should be listed. If AUTO, all tables including those not listed in gpkg_contents will be listed, except if the aspatial extension is found or a table is registered as 'attributes' in gpkg_contents. If YES, all tables including those not listed in gpkg_contents will be listed, in all cases. If NO, only tables registered as 'features', 'attributes' or 'aspatial' will be listed.

• ⁠PRELUDE_STATEMENTS=[SQL]⁠: (GDAL >= 3.2) SQL statement(s) to send on the SQLite3 connection before any other ones. In case of several statements, they must be separated with the semicolon (⁠;⁠) sign. This option may be useful to attach another database to the current one and issue cross-database requests.

• ⁠NOLOCK=[YES/NO]⁠: (GDAL >= 3.4.2) Defaults to NO. Whether the database should be used without doing any file locking. Setting it to YES will only be honored when opening in read-only mode and if the journal mode is not WAL. This corresponds to the nolock=1 query parameter described at https://www.sqlite.org/uri.html.

• ⁠IMMUTABLE=[YES/NO]⁠: (GDAL >= 3.5.3) Whether the database should be opened by assuming that the file cannot be modified by another process. This will skip any checks for change detection. This can be useful for WAL enabled files on read-only storage. GDAL will automatically try to turn it on when not being able to open in read-only mode a WAL enabled file. This corresponds to the immutable=1 query parameter described at https://www.sqlite.org/uri.html.

Value

A gdal_open_opts() object for the GPKG driver.

See Also

gpkg_prelude_pragmas(), gpkg_creation_opts(), gdal_open_opts()

• GDAL GPKG (GeoPackage) vector driver

• GPKG open options

• GDAL configuration options

• SQLite PRAGMA statements

• GeoPackage specification

Examples

gpkg_open_opts(list_all_tables = FALSE, nolock = TRUE)

prelude <- gpkg_prelude_pragmas(cache_size = -4000000, temp_store = "MEMORY")
gpkg_open_opts(list_all_tables = FALSE, prelude_statements = prelude)

Description

Build a PRELUDE_STATEMENTS string of SQLite PRAGMA directives for use as a GPKG/SQLite open option. The result is a single semicolon-separated string. Because it embeds ⁠;⁠ (and possibly ⁠,⁠), it is carried as single --open-option value and rendered as such.

Usage

gpkg_prelude_pragmas(
  cache_size = NULL,
  temp_store = NULL,
  mmap_size = NULL,
  journal_mode = NULL,
  ...
)

Arguments

Value

A length-1 character string of semicolon-separated PRAGMA statements (or "").

See Also

gpkg_open_opts()

Examples

gpkg_prelude_pragmas(cache_size = -4000000, temp_store = "MEMORY", journal_mode = "WAL")

Description

Construct a layer-level gdal_creation_opts() object for the Parquet (GeoParquet) driver. Only options you supply are emitted; enumerated values are validated against the driver metadata.

Usage

gpq_creation_opts(
  compression = NULL,
  compression_level = NULL,
  geometry_encoding = NULL,
  row_group_size = NULL,
  geometry_name = NULL,
  fid = NULL,
  polygon_orientation = NULL,
  edges = NULL,
  creator = NULL,
  write_covering_bbox = NULL,
  covering_bbox_name = NULL,
  use_parquet_geo_types = NULL,
  sort_by_bbox = NULL,
  timestamp_with_offset = NULL,
  coordinate_precision = NULL,
  ...,
  .set_defaults = FALSE
)

Arguments

Value

A layer-level gdal_creation_opts() object for the Parquet driver.

Distributing GeoParquet

Following the OGC Best Practices for Distributing GeoParquet, good defaults for distribution are ZSTD compression at a moderate level, a row-group size around 50000-150000, the per-row bounding-box covering columns enabled, and spatially ordered features:

gpq_creation_opts(
  compression = "ZSTD",
  compression_level = 15,
  row_group_size = 100000,
  write_covering_bbox = TRUE,
  sort_by_bbox = TRUE
)

See Also

gpq_open_opts(), gdal_creation_opts()

• GeoParquet Home Page

• (Geo)Parquet GDAL Driver

  • (Geo)Parquet GDAL Layer Creation Options

  • (Geo)Parquet GDAL Open Options

• Best Practices for Distributing GeoParquet

Examples

gpq_creation_opts(compression = "ZSTD", geometry_encoding = "WKB")

Description

Construct a gdal_open_opts() object for the Parquet (GeoParquet) driver.

Usage

gpq_open_opts(
  geom_possible_names = NULL,
  crs = NULL,
  lists_as_string_json = NULL,
  ...,
  .set_defaults = FALSE
)

Arguments

Value

A gdal_open_opts() object for the Parquet driver.

See Also

gpq_creation_opts(), gdal_open_opts()

• GeoParquet Home Page

• (Geo)Parquet GDAL Driver

  • (Geo)Parquet GDAL Layer Creation Options

  • (Geo)Parquet GDAL Open Options

• Best Practices for Distributing GeoParquet

Examples

gpq_open_opts(crs = "EPSG:4326")

Description

Check if a Path is a GDAL Virtual File System (VSI) Path or URL.

Usage

is_vsi_path(x)

Arguments

Value

Logical indicating if the path starts with a valid VSI prefix (i.e. ⁠/vsicurl/⁠ or ⁠/vsizip/⁠).

Examples

is_vsi_path("/vsizip/data.zip")      # TRUE
is_vsi_path("/vsicurl/data.geojson") # TRUE
is_vsi_path("data.geojson")          # FALSE

Description

Retrieves the hash of a local file from its path.

Usage

local_hash(path, algo = "md5")

Arguments

Value

A character string representing the hash of the local file.

Examples

## Not run: 
path <- "data-raw/cache/tiger/GENZ2024/shp/cb_2024_us_state_20m.zip"
local_hash(path)

## End(Not run)

Description

Pings a remote URL.

Usage

ping(url, timeout = 5L)

Arguments

Value

TRUE if successfully pinged, FALSE otherwise.

Description

Downloads a remote file only if it has changed since the cached version. Uses HTTP Last-Modified header when available (fast), falls back to hash comparison for legacy servers.

Usage

remote_download(
  url,
  destfile,
  extract = FALSE,
  timeout = 600L,
  max_tries = 3L,
  force = FALSE,
  algo = "md5"
)

Arguments

Value

Invisibly returns the path to the downloaded file.

Description

Determines whether a remote file exists by sending a HEAD request to the specified URL and checking the HTTP status code.

Usage

remote_exists(url)

Arguments

Value

A logical value: TRUE if the remote file exists (HTTP status 200), FALSE otherwise.

Examples

## Not run: 
url <- "https://www2.census.gov/geo/tiger/GENZ2024/shp/cb_2024_us_state_20m.zip"
remote_exists(url)

## End(Not run)

Description

Retrieves the hash of a remote file from its URL.

Usage

remote_hash(url, algo = "md5")

Arguments

Value

A character string representing the hash of the remote file.

Examples

## Not run: 
url <- "https://www2.census.gov/geo/tiger/GENZ2024/shp/cb_2024_us_state_20m.zip"
remote_hash(url)

## End(Not run)

Description

Sends a HEAD request to the specified URL and retrieves the response headers.

This function is useful for checking the existence of a resource or retrieving metadata without downloading the entire content.

Usage

remote_head(url)

Arguments

Value

A list containing:

• request: The httr2::request()

• response: The httr2::response()

• headers: The httr2::resp_headers() from the response

Examples

## Not run: 
url <- "https://www2.census.gov/geo/tiger/GENZ2024/shp/cb_2024_us_state_20m.zip"
head_info <- remote_head(url)
print(head_info$headers)

## End(Not run)

Description

These functions derive timestamps for local and remote resources.

• remote_last_modified(): Parses the Last-Modified HTTP response header as the timestamp. Returns NA if the header is not available.

• local_last_modified(): Local file last modified timestamp.

Usage

remote_last_modified(url)

local_last_modified(path)

Arguments

Value

• remote_last_modified(): POSIXct datetime representing the Last-Modified header timestamp, or NA if not provided by the server.

• local_last_modified(): POSIXct datetime of the file's last modification.

Examples

## Not run: 
url <- "https://www2.census.gov/geo/tiger/GENZ2024/shp/cb_2024_us_state_20m.zip"
remote_last_modified(url)

path <- "data-raw/cache/tiger/GENZ2024/shp/cb_2024_us_state_20m.zip"
local_last_modified(path)

## End(Not run)

Description

Performs a GET request against an Apache-style autoindex URL and returns the relative file/directory hrefs listed on the page. Works with Census Bureau TIGER and GENZ directory listings.

Usage

remote_list(url, pattern = NULL, full_url = FALSE)

Arguments

Value

A character vector of relative (or absolute, if full_url = TRUE) file/directory hrefs, NAs and navigation links excluded.

Description

Retrieves the size of a remote file by sending a HEAD request to the specified URL and extracting the Content-Length header.

Usage

remote_size(url)

Arguments

Value

A numeric value representing the size of the remote file in bytes.

Examples

## Not run: 
url <- "https://www2.census.gov/geo/tiger/GENZ2024/shp/cb_2024_us_state_20m.zip"
remote_size(url)

## End(Not run)

Description

Construct a gdal_config_opts() object for the ⁠ESRI Shapefile⁠ driver. These are global GDAL configuration options applied to the process (via gdalraster::set_config_option() / --config). Only options you supply are emitted.

Usage

shp_config_opts(
  shape_rewind_on_write = NULL,
  shape_restore_shx = NULL,
  shape_2gb_limit = NULL,
  shape_encoding = NULL,
  ...,
  .set_defaults = FALSE
)

Arguments

Value

A gdal_config_opts() object for the ⁠ESRI Shapefile⁠ driver.

See Also

shp_open_opts(), shp_creation_opts(), gdal_config_opts()

• Shapefile Home Page

• Shapefile GDAL Driver

  • Shapefile GDAL Capabilities

  • Shapefile GDAL Open Options

  • Shapefile GDAL Layer Creation Options

  • Shapefile GDAL Configuration Options

• Shapefile C Library

• ESRI Shapefile Technical Description (PDF)

• Shapefile .SHP File API

• Attribute .DBF File API

• Xbase File Format Description

• Shapelib Code Page

Examples

shp_config_opts(shape_restore_shx = TRUE)

Description

Construct a layer-level gdal_creation_opts() object for the ⁠ESRI Shapefile⁠ driver.

Usage

shp_creation_opts(
  spatial_index = NULL,
  encoding = NULL,
  resize = NULL,
  shpt = NULL,
  two_gb_limit = NULL,
  auto_repack = NULL,
  dbf_date_last_update = NULL,
  dbf_eof_char = NULL,
  ...,
  .set_defaults = FALSE
)

Arguments

Value

A layer-level gdal_creation_opts() object for the ⁠ESRI Shapefile⁠ driver.

See Also

shp_open_opts(), gdal_creation_opts()

• Shapefile Home Page

• Shapefile GDAL Driver

  • Shapefile GDAL Capabilities

  • Shapefile GDAL Open Options

  • Shapefile GDAL Layer Creation Options

  • Shapefile GDAL Configuration Options

• Shapefile C Library

• ESRI Shapefile Technical Description (PDF)

• Shapefile .SHP File API

• Attribute .DBF File API

• Xbase File Format Description

• Shapelib Code Page

Examples

shp_creation_opts(spatial_index = TRUE, encoding = "UTF-8")

Description

Construct a gdal_open_opts() object for the ⁠ESRI Shapefile⁠ driver.

Usage

shp_open_opts(
  encoding = NULL,
  dbf_date_last_update = NULL,
  adjust_type = NULL,
  adjust_geom_type = NULL,
  auto_repack = NULL,
  dbf_eof_char = NULL,
  ...,
  .set_defaults = FALSE
)

Arguments

Value

A gdal_open_opts() object for the ⁠ESRI Shapefile⁠ driver.

See Also

shp_config_opts(), shp_creation_opts(), gdal_open_opts()

• Shapefile Home Page

• Shapefile GDAL Driver

  • Shapefile GDAL Capabilities

  • Shapefile GDAL Open Options

  • Shapefile GDAL Layer Creation Options

  • Shapefile GDAL Configuration Options

• Shapefile C Library

• ESRI Shapefile Technical Description (PDF)

• Shapefile .SHP File API

• Attribute .DBF File API

• Xbase File Format Description

• Shapelib Code Page

Examples

shp_open_opts(encoding = "UTF-8", auto_repack = TRUE)

Description

Constructs a SQL ST_IsValid() expression for filtering geometries.

Usage

sql_where_valid_geom(geom_col, negate = FALSE)

Arguments

Value

A character string containing the SQL expression.

Examples

sql_where_valid_geom("geom")
sql_where_valid_geom("geom", negate = TRUE)

Description

Get the amount of usable physical RAM available to the R session using gdalraster::get_usable_physical_ram(), which calls the CPLGetUsablePhysicalRAM() C++ function from GDAL's Common Portable Library (CPL).

Usage

sys_available_ram()

Details

This function returns the total physical RAM usable by a process, in bytes.

It will be limited to 2GB for 32-bit processes.

It takes into account resource limits (virtual memory) of POSIX systems. It additionally will take into account RLIMIT_RSS on Linux.

On Windows, it will return the total physical RAM minus the memory used by the system and other processes, as reported by the Windows API, in bytes.

Value

A numeric scalar representing the number of bytes as a bit64::integer64() type (or zero 0 in case of failure).

FlatGeobuf Spatial Index RAM Check

This memory may already be partly accounted for by other processes, but is still useful for estimating how much RAM is available for processing large vector data without causing out-of-memory errors.

It is used by the check_available_ram() check utility which is used in fgb_validate_spatial_index_ram() to ensure that there is sufficient RAM to build a spatial index for a given dataset:

"The creation of the packet Hilbert R-Tree requires an amount of RAM which is at least the number of features times 83 bytes."

Examples

## Not run: 
sys_available_ram()

## End(Not run)

Description

Get system error codes and their descriptions. If a specific code is provided, returns the name, value, and description for that code. If no code is provided, returns a tibble of all system error codes.

Usage

sys_error_code(code = NULL)

Arguments

Value

A tibble::tibble() with the name, value, and description of the system error code(s). If one or more codes are provided, returns only the matching code(s). If no codes are found, returns NULL invisibly.

See Also

ps::errno() for the underlying system error codes data.

Examples

## Not run: 
# Get all system error codes
sys_error_code()

# Get specific error code information
sys_error_code(2)  # Example: ENOENT (No such file or directory)

## End(Not run)

Description

Get the number of CPU cores available on the current machine using gdalraster::get_num_cpus(), which calls the internal GDAL C++ library function GDALGetCPUs().

Usage

sys_num_cpus()

Details

This method is more robust than parallel::detectCores() because it accounts for CPU affinity, container limits, and other environmental restrictions that may cap the processing pools actually available to the R session.

However, on a standard unconstrained desktop machine, it will return the same value as parallel::detectCores(logical = TRUE) because both report the total logical processing channels.

• Number of CPUs (GDAL): gdalraster::get_num_cpus() queries the C++ backend to see how many logical execution slots (hardware threads) are exposed by the operating system.

• Number of Cores (parallel): parallel::detectCores(logical = TRUE) targets the virtual threads generated by Hyper-Threading (Intel) or SMT (AMD). Conversely, running parallel::detectCores(logical = FALSE) attempts to return only the count of independent physical cores on the processor.

Value

Integer representing the number of CPU cores available to the R session.

Examples

## Not run: 
sys_num_cpus()

## End(Not run)

Description

Get the current machine's operating system name.

Usage

sys_os()

Value

Character string resulting from Sys.info()[["sysname"]], which will be one of c("windows", "linux", "darwin", etc.) depending on the system.

Examples

## Not run: 
sys_os()

## End(Not run)

Description

Get the Current Machine's PATH Environment Variable as a Character Vector

Usage

sys_path(filter = NULL)

Arguments

Value

Character vector of paths from the system's PATH environment variable, split by the appropriate path separator for the operating system. If filter is provided, only paths containing the filter string are included in the returned vector. If no paths match the filter, an empty character vector is returned: character(0).

If filter is provided, only paths containing the filter string are returned.

Examples

## Not run: 
sys_path()

## End(Not run)

Description

Get the current process ID of the R session.

Usage

sys_pid()

Value

Integer representing the current process ID.

Examples

## Not run: 
sys_pid()

## End(Not run)

Description

Get the current machine's platform (operating system "family")

Usage

sys_platform()

Value

Character string resulting from .Platform$OS.type

Examples

## Not run: 
sys_platform()

## End(Not run)

Description

Lightweight, convenience wrapper around base::Sys.which() and base::normalizePath().

Usage

sys_which(x, winslash = "/", ...)

Arguments

Value

Character vector of paths, if found. If not found returns NULL instead of "".

Examples

## Not run: 
sys_which("gdal")

## End(Not run)

Description

Check a gdal_opts() object against its driver's registered metadata: unknown option names, invalid enumerated (string-select) values, and invalid boolean values. Validation is advisory and non-blocking - it warns (with classed conditions) and returns a logical, leaving the decision to act at the call site.

Usage

validate_gdal_opts(x, driver = attr(x, "driver"), call = rlang::caller_env())

Arguments

Value

Invisibly, TRUE if valid, FALSE if any problems were found, or NA if validation could not be performed (no driver).

Examples

validate_gdal_opts(gdal_open_opts(LIST_ALL_TABLES = "NO", driver = "GPKG"))

Description

Build a ⁠/vsiaz/⁠ Path

Usage

vsi_azure(container, blob)

Arguments

Value

Character scalar.

Description

Wrap a URL with ⁠/vsicurl/⁠

Usage

vsi_curl(url)

Arguments

Value

Character vector of ⁠/vsicurl/⁠ paths.

Description

Test Whether a VSI Path Exists

Usage

vsi_exists(path)

Arguments

Value

Logical vector.

Description

Convert a URI to a GDAL VSI Path

Usage

vsi_from_uri(uri)

Arguments

Value

Character vector of VSI paths.

Description

List VSI Handlers Used by a Path

Usage

vsi_handlers(path)

Arguments

Value

Character vector of handler names.

Description

Get VSI File Metadata

Usage

vsi_meta(path, domain = "HEADERS")

Arguments

Value

Named character vector of metadata entries.

Description

Convert a Path to a GDAL VSI Path

Usage

vsi_path(path, ...)

Arguments

Value

Character vector of VSI paths.

Description

Get the Size of a VSI Path

Usage

vsi_size(path)

Arguments

Value

The size of the file/object in bytes, formatted using rlang::as_bytes().

Description

Strip the Outermost VSI Handler

Usage

vsi_strip(path, recurse = TRUE)

Arguments

Value

Character vector with the outermost VSI handler removed.

Description

Sync Between VSI Paths

Usage

vsi_sync(src, dst, ...)

Arguments

Value

Invisibly returns the sync result from GDAL.

Description

Get the Type of a VSI Path

Usage

vsi_type(path)

Arguments

Value

Character vector of path types.

Description

Wrap a Path with ⁠/vsizip/⁠

Usage

vsi_zip(path)

Arguments

Value

Character vector of ⁠/vsizip/⁠ paths.

Description

Build a ⁠/vsizip//vsicurl/⁠ Path

Usage

vsi_zip_curl(url, inner = NULL)

Arguments

Value

Character scalar.

Description

Parses the configuration options for a GDAL driver from the provided XML document. This function is specifically designed to extract the configuration options listed in the "Configuration Options" section of a GDAL driver's documentation page, which is typically structured as an unordered list (⁠<ul>⁠) with list items (⁠<li>⁠) containing the option details.

The function looks for the first ⁠<ul>⁠ element within the section with id="configuration-options" and extracts the option name, description, default value, and possible values (if specified in brackets). The resulting data is returned as a tibble with columns for name, description, scope, default, and values (a list-column containing character vectors of possible values).

Usage

xml_parse_gdal_driver_config_opts(
  xml,
  scope = "all",
  driver = NULL,
  type = "config",
  call = rlang::caller_env()
)

Arguments

Value

A tibble with columns for name, description, scope, default, and values

Description

Parses the XML from GDAL driver metadata into structured tbl_df tibbles.

The function is meant to be flexible enough to be able to parse any of the possible XML metadata structures from GDAL's registered (vector) driver's metadata: DMD_OPENOPTIONLIST, DMD_CREATIONOPTIONLIST, and DS_LAYER_CREATIONOPTIONLIST.

Usage

xml_parse_gdal_options(
  xml,
  driver = NA_character_,
  type = c("config", "open", "creation"),
  sub_type = NA_character_,
  scope = c("vector", "raster", "all"),
  call = rlang::caller_env()
)

Arguments

Value

tibble::tibble() with fields for name, description, scope, type, default, and values (a list-column with a character vector for the possible values).

Additional fields for driver and opt_type may be included if those parameters are provided.

Examples

# parse DS_LAYER_CREATIONOPTIONLIST
gdalraster::gdal_get_driver_md("GPKG", mdi_name = "DS_LAYER_CREATIONOPTIONLIST") |>
  xml_parse_gdal_options()

# parse DMD_CREATIONOPTIONLIST
gdalraster::gdal_get_driver_md("GPKG", mdi_name = "DMD_CREATIONOPTIONLIST") |>
  xml_parse_gdal_options()

# parse DMD_OPENOPTIONLIST
gdalraster::gdal_get_driver_md("GPKG", mdi_name = "DMD_OPENOPTIONLIST") |>
  xml_parse_gdal_options()