This function sets GDAL configuration options that can be used to control the behavior of GDAL operations. These options can be used to optimize performance, control caching, and manage HTTP requests (among other things)
Usage
gdal_config_opts(
VSI_CACHE = "TRUE",
VSI_CACHE_SIZE = "268435456",
GDAL_NUM_THREADS = "ALL_CPUS",
GDAL_DISABLE_READDIR_ON_OPEN = "FALSE",
CPL_VSIL_CURL_CACHE_SIZE = "1342177280",
GDAL_HTTP_MAX_RETRY = "3",
GDAL_HTTP_RETRY_DELAY = "5",
GDAL_HTTP_MULTIPLEX = "YES",
GDAL_HTTP_VERSION = "2",
GDAL_HTTP_MERGE_CONSECUTIVE_RANGES = "YES",
GDAL_HTTP_COOKIEFILE = "~/.cookies.txt",
GDAL_HTTP_COOKIEJAR = GDAL_HTTP_COOKIEFILE,
GDAL_MAX_DATASET_POOL_SIZE = NULL,
GDAL_INGESTED_BYTES_AT_OPEN = NULL,
CPL_VSIL_CURL_ALLOWED_EXTENSIONS = NULL,
CPL_VSIL_CURL_USE_HEAD = NULL,
CPL_VSIL_CURL_CHUNK_SIZE = NULL,
...
)
gdal_creation_options(
output_format = NULL,
COMPRESS = "DEFLATE",
PREDICTOR = "2",
NUM_THREADS =
as.character(ceiling(vrtility::machine_cores()/pmax(vrtility::n_daemons(), 1))),
BIGTIFF = "IF_NEEDED",
TILED = "YES",
BLOCKXSIZE = "128",
BLOCKYSIZE = "128",
COPY_SRC_OVERVIEWS = "YES",
...
)
gdalwarp_options(
multi = FALSE,
warp_memory = "50%",
num_threads =
as.character(ceiling(vrtility::machine_cores()/pmax(vrtility::n_daemons(), 1))),
unified_src_nodata = c("NO", "YES", "PARTIAL")
)
set_gdal_config(x, scope = c("gdalraster", "sys"))
set_gdal_cache_max(mem_fraction = 0.1)Arguments
- VSI_CACHE
Should the Virtual File System (VSI) cache be used?
- VSI_CACHE_SIZE
Size of the VSI cache in bytes.
- GDAL_NUM_THREADS
Number of threads to use for processing. Default is the number of available cores divided by the number of daemons.
- GDAL_DISABLE_READDIR_ON_OPEN
Disable directory listing on open?
- CPL_VSIL_CURL_CACHE_SIZE
Cache size for HTTP requests.
- GDAL_HTTP_MAX_RETRY
Maximum number of retries for HTTP requests.
- GDAL_HTTP_RETRY_DELAY
Delay between retries in seconds.
- GDAL_HTTP_MULTIPLEX
Use HTTP multiplexing?
- GDAL_HTTP_VERSION
HTTP version to use.
- GDAL_HTTP_MERGE_CONSECUTIVE_RANGES
Merge consecutive ranges in HTTP requests?
Path to the cookie file for HTTP requests.
Path to the cookie jar for HTTP requests.
- GDAL_MAX_DATASET_POOL_SIZE
Maximum size of the dataset pool.
- GDAL_INGESTED_BYTES_AT_OPEN
Number of bytes to read at open.
- CPL_VSIL_CURL_ALLOWED_EXTENSIONS
Allowed file extensions for HTTP requests.
- CPL_VSIL_CURL_USE_HEAD
Use HTTP HEAD requests?
- CPL_VSIL_CURL_CHUNK_SIZE
Chunk size for HTTP requests.
- ...
Additional -co options to set
- output_format
Output format equivalent to -of on the CLI. see details
- COMPRESS
Compression method
- PREDICTOR
Prediction method
- NUM_THREADS
Number of threads
- BIGTIFF
Use BigTIFF
- TILED
Use tiling
- BLOCKXSIZE
Block size in X
- BLOCKYSIZE
Block size in Y
- COPY_SRC_OVERVIEWS
Copy source overviews
- multi
Logical indicating whether to use multi-threading, equivalent to -multi on the CLI
- warp_memory
Memory to use for warping equivalent to -wm on the CLI
- num_threads
Number of threads to use for warping equivalent to -wo NUM_THREADS on the CLI. "ALL_CPUS" (the default) will use all available CPUs, alternartively an integer can be supplied - or NULL to use a single threaded process.
- unified_src_nodata
Unified source nodata option equivalent to -wo UNIFIED_SRC_NODATA on the CLI. Can be "NO", "YES" or "PARTIAL". Default is "NO" (as was the deafault for earlier versions of GDAL).
- x
A named character vector of the configuration options
- scope
A character vector of the scope to set the options in. Either "gdalraster" or "sys".
- mem_fraction
Fraction of total RAM to use for GDAL cache, default is 0.1 (10% of total RAM)
Value
Character vector of options
set_gdal_cache_max returns (invisibly), a
memuse object - the value set for GDAL_CACHEMAX
Details
Where a named argument is set to NULL, the default GDAL value will be used.
These arguments are currently included as NULL because they could in theory
improve performance but, from our limited testing they either have no or
a negative impact on performance.
output_format, equaivalent to -of from the gdaltranslate or gdalwarp CLIs.
If NULL, then the output format will be inferred from the file extension.
set_gdal_cache_max is a very thin wrapper around
set_cache_max that allows you to conveniently
set the GDAL_CACHEMAX option as a fraction of the total RAM on your system.
Examples
gdal_config_opts(GDAL_HTTP_USERPWD = "user:password")
#> VSI_CACHE VSI_CACHE_SIZE
#> "TRUE" "268435456"
#> GDAL_NUM_THREADS GDAL_DISABLE_READDIR_ON_OPEN
#> "ALL_CPUS" "FALSE"
#> CPL_VSIL_CURL_CACHE_SIZE GDAL_HTTP_MAX_RETRY
#> "1342177280" "3"
#> GDAL_HTTP_RETRY_DELAY GDAL_HTTP_MULTIPLEX
#> "5" "YES"
#> GDAL_HTTP_VERSION GDAL_HTTP_MERGE_CONSECUTIVE_RANGES
#> "2" "YES"
#> GDAL_HTTP_COOKIEFILE GDAL_HTTP_COOKIEJAR
#> "~/.cookies.txt" "~/.cookies.txt"
#> GDAL_HTTP_USERPWD
#> "user:password"
gdal_creation_options(COMPRESS = "JPEG", JPEG_QUALITY = "90")
#> [1] "COMPRESS=JPEG" "PREDICTOR=2" "NUM_THREADS=4"
#> [4] "BIGTIFF=IF_NEEDED" "TILED=YES" "BLOCKXSIZE=128"
#> [7] "BLOCKYSIZE=128" "COPY_SRC_OVERVIEWS=YES" "JPEG_QUALITY=90"
gdalwarp_options(multi = TRUE, warp_memory = "50%", num_threads = 4)
#> [1] "-multi" "-wm" "50%"
#> [4] "-wo" "NUM_THREADS=4" "-wo"
#> [7] "UNIFIED_SRC_NODATA=NO"
set_gdal_config(gdal_config_opts())
gcm <- set_gdal_cache_max(0.05)
#> ℹ GDAL_CACHEMAX set to 799.779 MiB; to change this use
#> vrtility::set_gdal_cache_max()
print(gcm)
#> 799.779 MiB