R/RcppExports.R

In xbioclim: Bioclimatic Variables from Monthly Climate Data

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' Create a new BioclimEngine instance
#'
#' Allocates a new \code{BioclimEngine} C++ object and returns an opaque
#' external pointer to it.  Use the companion \code{engine_*()} functions to
#' configure and run the engine.
#'
#' @return An \code{externalptr} to a new \code{BioclimEngine} object.
#' @seealso \code{\link{engine_open}}, \code{\link{engine_compute}}
engine_create <- function() {
    .Call(`_xbioclim_engine_create`)
}

#' Configure monthly climate input files
#'
#' Associates four sets of raster file paths with the engine.  Each vector
#' must contain either one multi-band file (12 bands) or twelve single-band
#' files (one per calendar month).
#'
#' @param xptr   External pointer returned by \code{\link{engine_create}}.
#' @param tas_files    Character vector (length 1 or 12): mean temperature.
#' @param tasmax_files Character vector (length 1 or 12): maximum temperature.
#' @param tasmin_files Character vector (length 1 or 12): minimum temperature.
#' @param pr_files     Character vector (length 1 or 12): precipitation.
#' @return \code{NULL} invisibly.
#' @seealso \code{\link{engine_create}}, \code{\link{engine_compute}}
engine_open <- function(xptr, tas_files, tasmax_files, tasmin_files, pr_files) {
    invisible(.Call(`_xbioclim_engine_open`, xptr, tas_files, tasmax_files, tasmin_files, pr_files))
}

#' Set the output raster path
#'
#' The engine will create (or overwrite) a multi-band GeoTIFF named
#' \code{bio.tif} inside this directory when \code{\link{engine_compute}} is
#' called.
#'
#' @param xptr External pointer returned by \code{\link{engine_create}}.
#' @param path Character scalar: output directory path.
#' @return \code{NULL} invisibly.
#' @seealso \code{\link{engine_create}}, \code{\link{engine_compute}}
engine_set_output <- function(xptr, path) {
    invisible(.Call(`_xbioclim_engine_set_output`, xptr, path))
}

#' Set an optional mask raster
#'
#' Pixels where the mask band equals 0 or \code{NaN} receive \code{NaN}
#' (no-data) in every output band.  Pass an empty string to disable masking.
#'
#' @param xptr      External pointer returned by \code{\link{engine_create}}.
#' @param mask_path Character scalar: mask raster path, or \code{""} for none.
#' @return \code{NULL} invisibly.
#' @seealso \code{\link{engine_create}}, \code{\link{engine_compute}}
engine_set_mask <- function(xptr, mask_path) {
    invisible(.Call(`_xbioclim_engine_set_mask`, xptr, mask_path))
}

#' Set the number of OpenMP threads
#'
#' Controls the number of threads used in the per-pixel inner loop inside
#' each tile.  Values less than 1 are clamped to 1.
#'
#' @param xptr External pointer returned by \code{\link{engine_create}}.
#' @param n    Integer scalar: number of threads.
#' @return \code{NULL} invisibly.
#' @seealso \code{\link{engine_create}}, \code{\link{engine_compute}}
engine_set_threads <- function(xptr, n) {
    invisible(.Call(`_xbioclim_engine_set_threads`, xptr, n))
}

#' Set the tile size used during tiled processing
#'
#' Width and height of each processing tile in pixels.  Default is 256.
#' Mostly useful for testing with small rasters.  Values less than 1 are
#' clamped to 1.
#'
#' @param xptr      External pointer returned by \code{\link{engine_create}}.
#' @param tile_size Integer scalar: tile width and height in pixels.
#' @return \code{NULL} invisibly.
#' @seealso \code{\link{engine_create}}, \code{\link{engine_compute}}
#' @keywords internal
engine_set_tile_size <- function(xptr, tile_size) {
    invisible(.Call(`_xbioclim_engine_set_tile_size`, xptr, tile_size))
}

#' Set the output data type
#'
#' Controls the on-disk data type of the output \code{bio.tif} file.
#'\describe{
#'   \item{"Float64"}{IEEE 754 double precision (default).}
#'   \item{"Float32"}{IEEE 754 single precision — half the file size with
#'     negligible loss for most climate data.}
#' }
#'
#' @param xptr  External pointer returned by \code{\link{engine_create}}.
#' @param dtype Character scalar: one of \code{"Float64"} or \code{"Float32"}.
#' @return \code{NULL} invisibly.
#' @seealso \code{\link{engine_create}}, \code{\link{engine_compute}}
#' @keywords internal
engine_set_dtype <- function(xptr, dtype) {
    invisible(.Call(`_xbioclim_engine_set_dtype`, xptr, dtype))
}

#' Select which bioclimatic variables to write
#'
#' Restricts the output to a subset of the 19 standard bioclimatic variables.
#' The engine always computes all 19 internally (they share intermediate
#' values).  With the multi-band output file, all 19 bands are written and
#' the \code{\link{bioclim_engine}} R wrapper subsets the returned
#' \code{SpatRaster}.
#'
#' @param xptr      External pointer returned by \code{\link{engine_create}}.
#' @param variables Integer vector with elements in 1..19.
#' @return \code{NULL} invisibly.
#' @seealso \code{\link{engine_create}}, \code{\link{engine_compute}}
#' @export
engine_set_variables <- function(xptr, variables) {
    invisible(.Call(`_xbioclim_engine_set_variables`, xptr, variables))
}

#' Enable or disable the overlapped read/compute/write pipeline
#'
#' This is an internal, opt-in flag.  When \code{TRUE}, the next call to
#' \code{\link{engine_compute}} uses three background threads to overlap
#' the GDAL read, BIOCLIM computation, and GDAL write stages for each tile.
#' When \code{FALSE} (the default) the engine uses the original serial loop.
#'
#' @param xptr External pointer returned by \code{\link{engine_create}}.
#' @param use_pipeline Logical scalar: \code{TRUE} to enable the pipeline.
#' @return \code{NULL} invisibly.
#' @seealso \code{\link{engine_create}}, \code{\link{engine_compute}}
#' @keywords internal
#' @export
engine_set_pipeline <- function(xptr, use_pipeline) {
    invisible(.Call(`_xbioclim_engine_set_pipeline`, xptr, use_pipeline))
}

#' Run the bioclimatic-variable computation pipeline
#'
#' Reads all monthly climate input rasters tile by tile, computes the
#' bioclimatic variables for every pixel, and writes all 19 variables to a
#' single multi-band GeoTIFF named \code{bio.tif} inside the output
#' directory.  Peak memory is proportional to the tile size, not the full
#' raster size.
#'
#' Requires GDAL support.  Stops with an informative error when the package
#' was built without GDAL.
#'
#' @param xptr External pointer returned by \code{\link{engine_create}}.
#' @return Character scalar: the output directory path (same as the value
#'   passed to \code{\link{engine_set_output}}).
#' @seealso \code{\link{engine_create}}, \code{\link{engine_set_output}},
#'   \code{\link{has_gdal}}
engine_compute <- function(xptr) {
    .Call(`_xbioclim_engine_compute`, xptr)
}

#' Compute BIO01 (Mean Annual Temperature) for a raster block
#'
#' @param tas Numeric matrix with 12 columns (one per month); rows are pixels.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio01_cpp <- function(tas) {
    .Call(`_xbioclim_bio01_cpp`, tas)
}

#' Compute BIO02 (Mean Diurnal Range) for a raster block
#'
#' @param tasmax Numeric matrix (pixels x 12): monthly max temperature.
#' @param tasmin Numeric matrix (pixels x 12): monthly min temperature.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio02_cpp <- function(tasmax, tasmin) {
    .Call(`_xbioclim_bio02_cpp`, tasmax, tasmin)
}

#' Compute BIO03 (Isothermality) for a raster block
#'
#' @param tasmax Numeric matrix (pixels x 12): monthly max temperature.
#' @param tasmin Numeric matrix (pixels x 12): monthly min temperature.
#' @return Numeric vector with one value per pixel (NaN where BIO07 == 0).
#' @keywords internal
bio03_cpp <- function(tasmax, tasmin) {
    .Call(`_xbioclim_bio03_cpp`, tasmax, tasmin)
}

#' Compute BIO04 (Temperature Seasonality) for a raster block
#'
#' @param tas Numeric matrix (pixels x 12): monthly mean temperature.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio04_cpp <- function(tas) {
    .Call(`_xbioclim_bio04_cpp`, tas)
}

#' Compute BIO05 (Max Temperature of Warmest Month) for a raster block
#'
#' @param tasmax Numeric matrix (pixels x 12): monthly max temperature.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio05_cpp <- function(tasmax) {
    .Call(`_xbioclim_bio05_cpp`, tasmax)
}

#' Compute BIO06 (Min Temperature of Coldest Month) for a raster block
#'
#' @param tasmin Numeric matrix (pixels x 12): monthly min temperature.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio06_cpp <- function(tasmin) {
    .Call(`_xbioclim_bio06_cpp`, tasmin)
}

#' Compute BIO07 (Temperature Annual Range) for a raster block
#'
#' @param tasmax Numeric matrix (pixels x 12): monthly max temperature.
#' @param tasmin Numeric matrix (pixels x 12): monthly min temperature.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio07_cpp <- function(tasmax, tasmin) {
    .Call(`_xbioclim_bio07_cpp`, tasmax, tasmin)
}

#' Compute BIO08 (Mean Temperature of Wettest Quarter) for a raster block
#'
#' @param tas Numeric matrix (pixels x 12): monthly mean temperature.
#' @param pr  Numeric matrix (pixels x 12): monthly precipitation.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio08_cpp <- function(tas, pr) {
    .Call(`_xbioclim_bio08_cpp`, tas, pr)
}

#' Compute BIO09 (Mean Temperature of Driest Quarter) for a raster block
#'
#' @param tas Numeric matrix (pixels x 12): monthly mean temperature.
#' @param pr  Numeric matrix (pixels x 12): monthly precipitation.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio09_cpp <- function(tas, pr) {
    .Call(`_xbioclim_bio09_cpp`, tas, pr)
}

#' Compute BIO10 (Mean Temperature of Warmest Quarter) for a raster block
#'
#' @param tas Numeric matrix (pixels x 12): monthly mean temperature.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio10_cpp <- function(tas) {
    .Call(`_xbioclim_bio10_cpp`, tas)
}

#' Compute BIO11 (Mean Temperature of Coldest Quarter) for a raster block
#'
#' @param tas Numeric matrix (pixels x 12): monthly mean temperature.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio11_cpp <- function(tas) {
    .Call(`_xbioclim_bio11_cpp`, tas)
}

#' Compute BIO12 (Annual Precipitation) for a raster block
#'
#' @param pr Numeric matrix (pixels x 12): monthly precipitation.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio12_cpp <- function(pr) {
    .Call(`_xbioclim_bio12_cpp`, pr)
}

#' Compute BIO13 (Precipitation of Wettest Month) for a raster block
#'
#' @param pr Numeric matrix (pixels x 12): monthly precipitation.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio13_cpp <- function(pr) {
    .Call(`_xbioclim_bio13_cpp`, pr)
}

#' Compute BIO14 (Precipitation of Driest Month) for a raster block
#'
#' @param pr Numeric matrix (pixels x 12): monthly precipitation.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio14_cpp <- function(pr) {
    .Call(`_xbioclim_bio14_cpp`, pr)
}

#' Compute BIO15 (Precipitation Seasonality) for a raster block
#'
#' @param pr Numeric matrix (pixels x 12): monthly precipitation.
#' @return Numeric vector with one value per pixel (NaN where mean precip == 0).
#' @keywords internal
bio15_cpp <- function(pr) {
    .Call(`_xbioclim_bio15_cpp`, pr)
}

#' Compute BIO16 (Precipitation of Wettest Quarter) for a raster block
#'
#' @param pr Numeric matrix (pixels x 12): monthly precipitation.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio16_cpp <- function(pr) {
    .Call(`_xbioclim_bio16_cpp`, pr)
}

#' Compute BIO17 (Precipitation of Driest Quarter) for a raster block
#'
#' @param pr Numeric matrix (pixels x 12): monthly precipitation.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio17_cpp <- function(pr) {
    .Call(`_xbioclim_bio17_cpp`, pr)
}

#' Compute BIO18 (Precipitation of Warmest Quarter) for a raster block
#'
#' @param tas Numeric matrix (pixels x 12): monthly mean temperature.
#' @param pr  Numeric matrix (pixels x 12): monthly precipitation.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio18_cpp <- function(tas, pr) {
    .Call(`_xbioclim_bio18_cpp`, tas, pr)
}

#' Compute BIO19 (Precipitation of Coldest Quarter) for a raster block
#'
#' @param tas Numeric matrix (pixels x 12): monthly mean temperature.
#' @param pr  Numeric matrix (pixels x 12): monthly precipitation.
#' @return Numeric vector with one value per pixel.
#' @keywords internal
bio19_cpp <- function(tas, pr) {
    .Call(`_xbioclim_bio19_cpp`, tas, pr)
}

#' Compute all 19 bioclimatic variables for a raster block
#'
#' @param tas    Numeric matrix (pixels x 12): monthly mean temperature.
#' @param tasmax Numeric matrix (pixels x 12): monthly max temperature.
#' @param tasmin Numeric matrix (pixels x 12): monthly min temperature.
#' @param pr     Numeric matrix (pixels x 12): monthly precipitation.
#' @param ncores Integer: number of OpenMP threads (default 1).
#' @param na_rm  Logical: if TRUE, treat NA as missing and compute each BIO
#'   from the available months (quarters need >=1 valid month). If FALSE,
#'   a single NA in any input for a pixel gives an all-NA row (default).
#' @return Numeric matrix (pixels x 19) with one column per variable
#'   (bio01..bio19), named accordingly.
#' @keywords internal
bioclim_cpp <- function(tas, tasmax, tasmin, pr, ncores = 1L, na_rm = FALSE) {
    .Call(`_xbioclim_bioclim_cpp`, tas, tasmax, tasmin, pr, ncores, na_rm)
}

#' Compute quarterly/seasonal climate variables for a raster block
#'
#' @param tas    Numeric matrix (pixels x 12): monthly mean temperature.
#' @param tasmax Numeric matrix (pixels x 12): monthly maximum temperature.
#' @param tasmin Numeric matrix (pixels x 12): monthly minimum temperature.
#' @param pr     Numeric matrix (pixels x 12): monthly precipitation.
#' @param months Integer vector of 1-based month indices to include.
#' @param na_rm  Logical: if `TRUE`, skip `NA` months.
#' @return Numeric matrix (pixels x 6) with columns
#'   `tmean_s`, `tmax_max`, `tmin_min`, `trange`, `pr_tot`, `pr_cv`.
#' @keywords internal
quarterly_variables_cpp <- function(tas, tasmax, tasmin, pr, months, na_rm = FALSE) {
    .Call(`_xbioclim_quarterly_variables_cpp`, tas, tasmax, tasmin, pr, months, na_rm)
}

#' Compute bioclimatic variables over an arbitrary window of months
#'
#' @param tas    Numeric matrix (pixels x 12): monthly mean temperature.
#' @param tasmax Numeric matrix (pixels x 12): monthly maximum temperature.
#' @param tasmin Numeric matrix (pixels x 12): monthly minimum temperature.
#' @param pr     Numeric matrix (pixels x 12): monthly precipitation.
#' @param months Integer vector of 1-based month indices in the window.
#' @param window Integer: length (months) of the internal rolling sub-window
#'   used for the BIO08-BIO19 variables.  Must be >= 3 and <= length(months)
#'   for those variables to be non-NA.
#' @param na_rm  Logical: if `TRUE`, skip `NA` months.
#' @return Numeric matrix (pixels x 19) with columns `bio01`..`bio19`.
#' @keywords internal
bioclim_window_cpp <- function(tas, tasmax, tasmin, pr, months, window = 3L, na_rm = FALSE) {
    .Call(`_xbioclim_bioclim_window_cpp`, tas, tasmax, tasmin, pr, months, window, na_rm)
}

#' Compute bioclimatic variables using a rolling window of arbitrary length
#'
#' @param tas    Numeric matrix (pixels x 12): monthly mean temperature.
#' @param tasmax Numeric matrix (pixels x 12): monthly maximum temperature.
#' @param tasmin Numeric matrix (pixels x 12): monthly minimum temperature.
#' @param pr     Numeric matrix (pixels x 12): monthly precipitation.
#' @param window Integer: length (months) of the rolling window (2-11).
#' @param na_rm  Logical: if `TRUE`, skip `NA` months.
#' @return Numeric matrix (pixels x 19) with columns `bio01`..`bio19`.
#'   The base variables (bio01-bio07, bio12-bio15) are computed over the
#'   full 12 months; the rolling-window variables (bio08-bio11, bio16-bio19)
#'   are computed over the best `window`-month period.
#' @keywords internal
bioclim_rolling_cpp <- function(tas, tasmax, tasmin, pr, window = 3L, na_rm = FALSE) {
    .Call(`_xbioclim_bioclim_rolling_cpp`, tas, tasmax, tasmin, pr, window, na_rm)
}

#' Create a new C++ BioclimModel and return an external pointer
#'
#' @param tas    Numeric vector of length 12.
#' @param tasmax Numeric vector of length 12.
#' @param tasmin Numeric vector of length 12.
#' @param pr     Numeric vector of length 12.
#' @return An external pointer wrapping a \code{BioclimModel} C++ object.
#' @keywords internal
bioclim_model_new <- function(tas, tasmax, tasmin, pr) {
    .Call(`_xbioclim_bioclim_model_new`, tas, tasmax, tasmin, pr)
}

#' Test whether the C++ pointer is null
#' @param ptr An external pointer.
#' @return Logical scalar.
#' @keywords internal
bioclim_model_is_null <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_is_null`, ptr)
}

#' @keywords internal
bioclim_model_bio01 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio01`, ptr)
}

#' @keywords internal
bioclim_model_bio02 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio02`, ptr)
}

#' @keywords internal
bioclim_model_bio03 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio03`, ptr)
}

#' @keywords internal
bioclim_model_bio04 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio04`, ptr)
}

#' @keywords internal
bioclim_model_bio05 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio05`, ptr)
}

#' @keywords internal
bioclim_model_bio06 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio06`, ptr)
}

#' @keywords internal
bioclim_model_bio07 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio07`, ptr)
}

#' @keywords internal
bioclim_model_bio08 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio08`, ptr)
}

#' @keywords internal
bioclim_model_bio09 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio09`, ptr)
}

#' @keywords internal
bioclim_model_bio10 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio10`, ptr)
}

#' @keywords internal
bioclim_model_bio11 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio11`, ptr)
}

#' @keywords internal
bioclim_model_bio12 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio12`, ptr)
}

#' @keywords internal
bioclim_model_bio13 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio13`, ptr)
}

#' @keywords internal
bioclim_model_bio14 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio14`, ptr)
}

#' @keywords internal
bioclim_model_bio15 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio15`, ptr)
}

#' @keywords internal
bioclim_model_bio16 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio16`, ptr)
}

#' @keywords internal
bioclim_model_bio17 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio17`, ptr)
}

#' @keywords internal
bioclim_model_bio18 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio18`, ptr)
}

#' @keywords internal
bioclim_model_bio19 <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_bio19`, ptr)
}

#' Compute all 19 bioclimatic variables from the C++ object
#' @param ptr An external pointer to a \code{BioclimModel} C++ object.
#' @return Named numeric vector of length 19.
#' @keywords internal
bioclim_model_compute <- function(ptr) {
    .Call(`_xbioclim_bioclim_model_compute`, ptr)
}

#' Compute all 19 bioclimatic variables (vectorized, zero-copy bridge)
#'
#' A faster alternative to \code{bioclim_cpp()} that uses whole-array
#' vectorized operations and maps R matrix memory directly onto C++ pointers
#' (zero-copy on both input and output).
#'
#' @param tas    Numeric matrix (n_pixels x 12): monthly mean temperature.
#' @param tasmax Numeric matrix (n_pixels x 12): monthly max temperature.
#' @param tasmin Numeric matrix (n_pixels x 12): monthly min temperature.
#' @param pr     Numeric matrix (n_pixels x 12): monthly precipitation.
#' @param ncores Integer: number of OpenMP threads (default 1).
#' @return Numeric matrix (n_pixels x 19) with one column per variable
#'   (bio01..bio19), named accordingly.  Rows with any NA input are returned
#'   as all-NA.
#' @keywords internal
bioclim_xt <- function(tas, tasmax, tasmin, pr, ncores = 1L) {
    .Call(`_xbioclim_bioclim_xt`, tas, tasmax, tasmin, pr, ncores)
}

#' Count available CUDA GPU devices
#'
#' Returns the number of CUDA-capable GPUs available on this machine.
#' Returns \code{0} when the package was built without CUDA support or when
#' no CUDA-capable device is found.
#'
#' @return Non-negative integer: number of CUDA devices detected.
#' @seealso \code{\link{has_cuda}}, \code{\link{cuda_device_info}}
#' @export
cuda_device_count <- function() {
    .Call(`_xbioclim_cuda_device_count`)
}

#' Query properties of the first CUDA GPU device
#'
#' Returns a named list with hardware information about the first
#' CUDA-capable GPU.  Returns an empty list when no CUDA device is
#' available or when the package was built without CUDA.
#'
#' @return Named list with:
#'   \describe{
#'     \item{name}{Character: GPU model name.}
#'     \item{memory_gb}{Numeric: total global memory in gigabytes.}
#'     \item{compute_capability}{Character: e.g. \code{"8.0"} for A100.}
#'   }
#'   An empty list when no CUDA device is detected.
#' @seealso \code{\link{has_cuda}}, \code{\link{cuda_device_count}}
#' @export
cuda_device_info <- function() {
    .Call(`_xbioclim_cuda_device_info`)
}

#' Set the compute device for a BioclimEngine instance
#'
#' Controls whether the computation runs on a CUDA GPU or the CPU.
#' When \code{"auto"} is selected the engine uses the GPU if at least one
#' CUDA device is present, otherwise it falls back to the CPU.  GPU
#' requests on systems without a CUDA device silently fall back to the CPU.
#'
#' @param xptr External pointer returned by \code{\link{engine_create}}.
#' @param device Character scalar: one of \code{"auto"}, \code{"cpu"},
#'   or \code{"gpu"}.
#' @return \code{NULL} invisibly.
#' @seealso \code{\link{engine_create}}, \code{\link{has_cuda}},
#'   \code{\link{bioclim_engine}}
#' @export
engine_set_device <- function(xptr, device) {
    invisible(.Call(`_xbioclim_engine_set_device`, xptr, device))
}

#' Aggregate ERA5-Land hourly 2-m temperature to monthly statistics
#'
#' Converts an hourly temperature matrix to monthly mean temperature (tas),
#' monthly mean of daily maxima (tasmax), and monthly mean of daily minima
#' (tasmin), following the CHELSA variable convention.
#'
#' @param hourly Numeric matrix (n_pixels x n_hours): hourly 2-m temperature.
#'   Column-major layout.  n_hours must equal 24 * n_days.
#' @param n_days Integer: number of days in the month.
#' @param to_celsius Logical: if TRUE, convert Kelvin to Celsius (default
#'   FALSE, output in Kelvin matching CHELSA convention).
#' @param ncores Integer: number of OpenMP threads (default 1).
#' @return A named list with three numeric vectors of length n_pixels:
#'   \code{tas}, \code{tasmax}, \code{tasmin}.
#' @keywords internal
era5_t2m_to_monthly_cpp <- function(hourly, n_days, to_celsius = FALSE, ncores = 1L) {
    .Call(`_xbioclim_era5_t2m_to_monthly_cpp`, hourly, n_days, to_celsius, ncores)
}

#' Aggregate ERA5-Land hourly total precipitation to monthly total
#'
#' Sums hourly precipitation accumulations and converts from metres of water
#' to kg m-2 month-1 (equivalent to mm/month), matching the CHELSA \code{pr}
#' variable convention.
#'
#' @param hourly Numeric matrix (n_pixels x n_hours): hourly total
#'   precipitation in metres.
#' @param ncores Integer: number of OpenMP threads (default 1).
#' @return Numeric vector of length n_pixels: monthly total precipitation
#'   in kg m-2 (mm).
#' @keywords internal
era5_tp_to_monthly_cpp <- function(hourly, ncores = 1L) {
    .Call(`_xbioclim_era5_tp_to_monthly_cpp`, hourly, ncores)
}

#' Unified ERA5-Land hourly-to-monthly aggregation
#'
#' Converts hourly 2-m temperature and total precipitation to the four
#' CHELSA-compatible monthly climate variables in a single parallel pass.
#'
#' @param hourly_t2m Numeric matrix (n_pixels x n_hours_t2m): hourly 2-m
#'   temperature in Kelvin.  n_hours_t2m must equal 24 * n_days.
#' @param hourly_tp Numeric matrix (n_pixels x n_hours_tp): hourly total
#'   precipitation in metres.  n_pixels must match \code{hourly_t2m}.
#' @param n_days Integer: number of days in the month.
#' @param to_celsius Logical: convert temperatures from Kelvin to Celsius?
#'   Default FALSE.
#' @param ncores Integer: number of OpenMP threads (default 1).
#' @return A named list with four numeric vectors of length n_pixels:
#'   \code{tas}, \code{tasmax}, \code{tasmin}, \code{pr}.
#' @keywords internal
era5_to_monthly_cpp <- function(hourly_t2m, hourly_tp, n_days, to_celsius = FALSE, ncores = 1L) {
    .Call(`_xbioclim_era5_to_monthly_cpp`, hourly_t2m, hourly_tp, n_days, to_celsius, ncores)
}

#' Check whether GDAL can open a raster file
#'
#' A lightweight diagnostic that tries to open the specified path via GDAL
#' and returns \code{TRUE} if successful, \code{FALSE} if GDAL cannot open
#' it.  Stops with an informative error if the package was built without
#' GDAL support.
#'
#' @param path Character string: path to the raster file.
#' @return Logical \code{TRUE} if GDAL can open the file, \code{FALSE}
#'   otherwise.
#' @examples
#' \donttest{
#' if (has_gdal()) {
#'   gdal_can_open(system.file("extdata", "tiny.tif", package = "xbioclim"))
#' }
#' }
#' @export
gdal_can_open <- function(path) {
    .Call(`_xbioclim_gdal_can_open`, path)
}

#' Return metadata about a GDAL-readable raster
#'
#' Opens the raster at \code{path} and returns a named list with dimensions,
#' geotransform, coordinate reference system, and per-band scale/offset
#' values.
#'
#' Data values are always returned as \code{double} (\code{float64}) in
#' memory.  If the raster bands carry GDAL scale/offset metadata (e.g. packed
#' integers), those are reported here and applied automatically by
#' \code{GdalReader::read_window()}.
#'
#' Stops with an informative error if the package was built without GDAL
#' support.
#'
#' @param path Character string: path to the raster file.
#' @return Named list with the following elements:
#'   \describe{
#'     \item{\code{path}}{Character: the path as supplied.}
#'     \item{\code{nrows}}{Integer: number of rows (Y pixels).}
#'     \item{\code{ncols}}{Integer: number of columns (X pixels).}
#'     \item{\code{nbands}}{Integer: number of raster bands.}
#'     \item{\code{geotransform}}{Numeric vector of length 6 (GDAL
#'       convention): \code{[x_origin, pixel_width, rotation_x,
#'       y_origin, rotation_y, pixel_height]}.}
#'     \item{\code{crs}}{Character: WKT coordinate reference system string,
#'       or an empty string if not defined.}
#'     \item{\code{scale}}{Numeric vector (one per band): GDAL scale factor
#'       (\code{1.0} if not set).}
#'     \item{\code{offset}}{Numeric vector (one per band): GDAL offset
#'       (\code{0.0} if not set).}
#'   }
#' @examples
#' \donttest{
#' if (has_gdal()) {
#'   info <- gdal_info(
#'     system.file("extdata", "tiny.tif", package = "xbioclim")
#'   )
#'   str(info)
#' }
#' }
#' @export
gdal_info <- function(path) {
    .Call(`_xbioclim_gdal_info`, path)
}

#' Rasterize a vector polygon layer to a binary mask raster
#'
#' Burns all polygon features from a vector source into a new single-band
#' GeoTIFF raster that is spatially aligned to a reference raster.  Pixels
#' that fall inside at least one polygon are set to \code{1}; all other
#' pixels are set to \code{0}.
#'
#' This function is the low-level C++ entry point.  Most users should call
#' the higher-level \code{\link{create_mask}} wrapper instead.
#'
#' Stops with an informative error if the package was built without GDAL
#' support.
#'
#' @param vector_path Character string: path to any OGR-readable vector
#'   source (shapefile, GeoJSON, GeoPackage, etc.).
#' @param ref_raster_path Character string: path to a GDAL-readable raster
#'   used as the spatial reference (extent, resolution, CRS).
#' @param output_mask_path Character string: file path where the output
#'   \code{GDT_Byte} GeoTIFF will be written (created or overwritten).
#' @return Invisibly returns \code{NULL}.  The side effect is the creation
#'   of the output mask raster at \code{output_mask_path}.
#' @seealso \code{\link{create_mask}}, \code{\link{apply_mask_cpp}}
#' @examples
#' \donttest{
#' if (has_gdal()) {
#'   # Requires GDAL support at build time.
#'   ref  <- system.file("extdata", "tiny.tif", package = "xbioclim")
#'   poly <- tempfile(fileext = ".geojson")
#'   mask <- tempfile(fileext = ".tif")
#' writeLines(
#'   '{"type":"FeatureCollection","features":[{"type":"Feature",
#'     "geometry":{"type":"Polygon","coordinates":[[[0,0],[1,0],[1,1],[0,1],[0,0]]]},
#'     "properties":{}}]}',
#'   poly)
#'   rasterize_mask_cpp(poly, ref, mask)
#' }
#' }
#' @export
rasterize_mask_cpp <- function(vector_path, ref_raster_path, output_mask_path) {
    .Call(`_xbioclim_rasterize_mask_cpp`, vector_path, ref_raster_path, output_mask_path)
}

#' Apply a binary mask raster to an input raster
#'
#' Reads \code{input_path} and \code{mask_path} tile-by-tile (one row at a
#' time) and writes the result to \code{output_path}.  Pixels where the mask
#' equals \code{0} are replaced with \code{NaN} in the output; all other
#' pixels retain their original values (with any GDAL scale/offset applied).
#'
#' This function is the low-level C++ entry point.  Most users should call
#' the higher-level \code{\link{create_mask}} wrapper instead.
#'
#' Stops with an informative error if the package was built without GDAL
#' support or if the mask and input dimensions differ.
#'
#' @param input_path Character string: path to a GDAL-readable raster
#'   (any number of bands).
#' @param mask_path Character string: path to a single-band \code{GDT_Byte}
#'   mask raster (e.g., produced by \code{\link{rasterize_mask_cpp}}).
#' @param output_path Character string: file path where the output
#'   \code{Float64} GeoTIFF will be written (created or overwritten).
#' @return Invisibly returns \code{NULL}.  The side effect is the creation
#'   of the masked raster at \code{output_path}.
#' @seealso \code{\link{create_mask}}, \code{\link{rasterize_mask_cpp}}
#' @examples
#' \donttest{
#' if (has_gdal()) {
#'   # Requires GDAL support at build time.
#'   ref    <- system.file("extdata", "tiny.tif", package = "xbioclim")
#'   poly   <- tempfile(fileext = ".geojson")
#'   mask   <- tempfile(fileext = ".tif")
#'   output <- tempfile(fileext = ".tif")
#' writeLines(
#'   '{"type":"FeatureCollection","features":[{"type":"Feature",
#'     "geometry":{"type":"Polygon","coordinates":[[[0,0],[1,0],[1,1],[0,1],[0,0]]]},
#'     "properties":{}}]}',
#'   poly)
#'   rasterize_mask_cpp(poly, ref, mask)
#'   apply_mask_cpp(ref, mask, output)
#' }
#' }
#' @export
apply_mask_cpp <- function(input_path, mask_path, output_path) {
    .Call(`_xbioclim_apply_mask_cpp`, input_path, mask_path, output_path)
}