gdalraster 2.0.0

[ctoney]

Summary of main changes

• add bindings to the GDAL Vector API, implemented in the exposed C++ class GDALVector along with several additions and enhancements to ogr_*() stand-alone functions
• enhance and expand existing bindings to the Geometry API, now operating on raw vectors of WKB or WKT strings
• enhance and expand existing bindings to the Spatial Reference Systems API
• add several new features and improvements to the Raster API, Virtual Systems Interface (VSI) API, and coordinate transformation functions
• add helper functions for working with GDAL raster data types (see ?data_type_helpers)
• add an S4 show() method for all Rcpp exposed classes
• bug fixes, code linting and other internal improvements

Dependencies

• package nanoarrow has been added to Imports and LinkingTo
• package wk has been added to Imports
• C++17 is now a System Requirement
• PROJ is removed as a stand-alone external System Requirement since:
  • gdalraster as of 1.12 requires GDAL >= 3.1
  • PROJ has been a GDAL build requirement since GDAL 3.0
  • gdalraster only uses PROJ via GDAL headers (i.e., there is no longer a requirement for linking to external libproj in this case)

Vector API bindings

• add class GDALVector: encapsulates an OGRLayer object and the GDALDataset that contains it, exposing 48 class methods for obtaining vector layer information, attribute and spatial filtering, and reading/writing feature data
• wrap GDAL's Arrow C Stream interface for reading vector data by exposing an ArrowArrayStream on a layer as a nanoarrow_array_stream object (GDAL >= 3.6) (Add GDALVector::getArrowStream(): expose an Arrow C stream on a layer via nanoarrow_array_stream object #591)
• add ogr_reproject(): reproject a vector layer (purpose-built wrapper of GDALVectorTranslate())
• add ogr_proc(): interface to GDAL OGR facilities for vector geoprocessing
• add ogr_layer_rename(): rename an existing layer in a vector dataset (GDAL >= 3.5)
• ogr_execute_sql() now returns an object of class GDALVector for SQL SELECT statements
• add argument return_obj in ogr_ds_create() and ogr_layer_create(), TRUE to return a GDALVector object for write access on the created layer
• the layer argument in certain ogr_manage functions now supports NULL or empty string, which will default to the first layer by index (mainly as a convenience for single-layer formats)
• remove element $is_ignored from the list object for a feature class definition (affects certain ogr_define and ogr_manage functions): potentially breaking change but assumed to be unused in layer / field creation (Remove is_ignored from feature class definition #513)

Geometry API

• update the geometry interface to support the vector API in gdalraster 2.0, with changes to existing functions, and add g_wk2wk() (WKB <--> WKT conversion), g_create() (create geometries from input points), g_add_geom() (build container geometry types from sub-geometries) (Updated geometry interface to support the vector API in gdalraster 2.0 #572)
• the geometry wrapper functions now operate on input of either WKB raw vector, list of WKB, or character vector of WKT strings, with returned geometries as either WKB raw vector (or list of) or WKT character string (vector of)
• breaking changes: breaks some existing functions by renaming argument wkt to geom, and by returning raw vectors of WKB by default from functions that return geometries (as_wkb = TRUE by default)
• update g_is_valid(), g_is_empty(), g_name() and g_buffer() to the new style Geometry API
• add g_make_valid(): attempt to make invalid geometries valid
• add g_summary(): obtain text summaries of WKB/WKT geometries (GDAL >= 3.7)
• add g_simplify(): simplify WKB/WKT geometries, optionally preserving topology
• add g_swap_xy(): swap x and y coordinates of the input geometry
• add g_geodesic_area() and g_geodesic_length() (Geom API: add g_geodesic_area() and g_geodesic_length() #671)
• add g_is_3D() and g_is_measured() (Geom: add g_is_3D() and g_is_measured() #650)
• add g_envelope(): computes and returns the bounding envelope(s) for input geometries
• add g_coords(): extract coordinate values from geometries
• g_transform(): add argument traditional_gis_order with default TRUE, to support authority compliant order for geometries using geographic coordinates
• bbox_transform(): add argument use_transform_bounds (TRUE by default but requires GDAL >= 3.4)

Spatial Reference Systems API

• improve and expand bindings to a subset of the GDAL Spatial Reference System API (Updated bindings to the GDAL Spatial Reference System API for gdalraster 2.0 #584)
• breaking change in srs_is_same(): argument srs1 is renamed to srs and argument srs2 to srs_other
• functions that previously required input as a WKT string now accept SRS definitions in any of the formats supported by srs_to_wkt() (wrapper of OSRSetFromUserInput())
• the documentation is grouped under two topics, ?srs_convert and ?srs_query, and now includes the following:
  • srs_convert functions: epsg_to_wkt(), srs_to_wkt()
  • srs_query functions: srs_find_epsg(), srs_get_name(), srs_is_geographic(), srs_is_derived_gcs(), srs_is_local(), srs_is_projected(), srs_is_compound(), srs_is_geocentric(), srs_is_vertical(), srs_is_dynamic(), srs_is_same(), srs_get_angular_units(), srs_get_linear_units(), srs_get_coord_epoch(), srs_get_utm_zone(), srs_get_axis_mapping_strategy()

GDALRaster-class

• add method $get_block_indexing(): helper to get indexing values for the block layout of a raster band (Add GDALRaster::get_block_indexing(): helper method to get indexing values for the block layout #667)
• add method $addBand(): add a band to a dataset if the underlying format supports this action, e.g., MEM and VRT
• add method $clearColorTable(): clear the color table associated with a raster band
• add method $getMaskBand(): return the mask filename and band number associated with a given band of the dataset
• add method $getMaskFlags(): return the status flags of the mask band associated with a given band of the dataset
• add method $setMetadata(): set dataset or band-level metadata from a character vector of NAME=VALUE pairs (instead of per metadata item with the existing method $setMetadataItem())
• support band = 0 in the existing method $setDescription() to set the dataset-level description
• improve methods $bbox() and $res() to handle south-up / rotated raster (with related fixes in read_ds() and plot_raster()) (GDALRaster-class: bbox() / res() for south-up raster / rotated geotransform #569)

GDAL VSI for operations on virtual file systems

• add vsi_get_actual_url(): return the actual URL of a supplied VSI filename, wrapper of VSIGetActualURL() in the GDAL API
• add vsi_get_signed_url(): return a signed URL for a supplied VSI filename, wrapper of VSIGetSignedURL() in the GDAL API
• add vsi_is_local(): returns whether the file/filesystem is "local", wrapper of VSIIsLocal() in the GDAL API

GDAL configuration

• add get_cache_max() and set_cache_max(): get/set maximum memory size available for the GDAL block cache
• get_cache_used(): change the return value to R numeric type carrying the integer64 class attribute, and add argument units defaulting to "MB"
• expose gdal_version_num() (previously internal/undocumented): return the full version number as an integer value (convenience for as.integer(gdal_version()[2]))
• add gdal_compute_version(): compute the integer version number (GDAL_VERSION_NUM) from the individual components (major, minor, revision)

Other stand-alone functions

• add pixel_extract(): extract pixel values at geospatial point locations, with options for multiple interpolation methods and returning the individual pixel values from a N x N kernel (Add pixel_extract() #570)
• add transform_bounds(): transform a bounding box, densifying the edges to account for nonlinear transformations along these edges and extracting the outermost bounds (wrapper of OCTTransformBounds() in the GDAL Spatial Reference System API, requires GDAL >= 3.4)
• add autoCreateWarpedVRT(): create a warped virtual dataset representing the input raster warped into the target coordinate system (wrapper of GDALAutoCreateWarpedVRT())
• add validateCreationOptions(): validate the list of creation options that are handled by a driver (Add validateCreationOptions(), validate the list of creation options that are handled by a driver #663)
• getCreationOptions(): change the return value to a named list of options with their information (getCreationOptions(): change the return value to a named list of options with their information #662)
• getCreationOptions(): include $min and $max attributes in the returned list if GDAL >= 3.11
• create(): add argument return_obj, TRUE to return an object of class GDALRaster with update access on the created dataset
• createCopy(): add argument return_obj, TRUE to return an object of class GDALRaster with update access on the created dataset
• createCopy(): an object of class GDALRaster can be given for argument src_filename to specify the source dataset
• warp(): source and destination rasters may be given as objects of class GDALRaster
• translate(): source raster can be given as a GDALRaster object
• inspectDataset(): handle the case if separate raster and vector drivers are identified but a specific flag for the dataset type was not given (inspectDataset(): handle case of separate raster and vector drivers identified when specific flag was not given #693)
• rasterize(): support passing a GDALRaster object for in-place updating (rasterize(): support passing a GDALRaster object for in-place updating #660)
• accept one (x, y) as a vector in functions that expect matrix or data frame input (transform_xy(), inverse_proj(), apply_geotransform(), get_pixel_line())
• transform_xy() / inv_project(): support input points with z vertices (three column xyz) or time values (four column xyzt), and optionally accept input of point geometries as character vector of WKT strings, WKB raw vector, or list of WKB raw vectors
• transform_xy() / inv_project(): account for behavior change in the GDAL Transform() methods of OGRCoordinateTransformation at GDAL 3.11 (transform_xy() / inv_project(): account for behavior change at GDAL 3.11 #631)
• plot_raster(): add argument pixel_fn to specify a function that will be applied to the input data for plotting, and handle input raster with complex data type (plot_raster(): add argument pixel_fn for applying a function to the input pixel values #582)
• inspectDataset() and warp(): set a quiet error handler around code checks that are based on a try() statement that attempts to open a raster dataset (inspectDataset() and warp(): wrap checks of raster dataset open in quiet error handler #709)

Bug fixes

• handle NA in the input coordinates to transform_xy(), inv_project(), transform_bounds(), apply_geotransform() and get_pixel_line() (Handle NA in the input coordinates to transform_xy(), inv_project(), transform_bounds(), apply_geotransform() and get_pixel_line() #592)
• fix plot_raster() to avoid integer overflow (plot_raster: avoid integer overflow  #613 thanks to @mdsumner)
• fix potential integer overflow when multiplying raster dimensions in R without explicit as.numeric() (Fix potential integer overflow when multiplying raster dimensions in R without explicit as.numeric() #620 thanks to @mdsumner)
• configure.ac: fix test for GDAL >= 3.1.0
• fix class method VSIFile$read(): the nbytes argument should accept values carrying the integer64 class attribute (fixes VSIFile: read() won't accept integer64 (feature request) #677 thanks to @mdsumner)

Internal

• configure.ac: remove configuration of PROJ include directory and libs as no longer needed (configure: remove configuration of PROJ include directory and libs #702)
• implement create(), createCopy() and autoCreateWarpedVRT() as GDALRaster object factories (Implement create(), createCopy() and autoCreateWarpedVRT() as object factories #606)
• implement ogr_ds_create() and ogr_layer_create() as GDALVector object factories (Implement ogr_ds_create() and ogr_layer_create() as GDALVector object factories #609)
• code linting for cppcheck style in src/geom_api.cpp and src/srs_api.cpp ([Lint] Code linting for cppcheck in geom_api.cpp and srs_api.cpp #658)
• various C++ code linting throughout ([Lint] various code linting throughout #624)
• add header src/gdal_vsi.h, and minor code cleanups in src/gdal_vsi.cpp
• rename files: src/wkt_conv.cpp -> src/srs_api.cpp, src/wkt_conv.h -> src/srs_api.h, tests/testthat/test-wkt_conv.R -> tests/testthat/test-srs_api.R
• use consistent naming convention for C++ class member variables
• pass arguments by const reference in some srs and geom functions
• use try/catch if potentially large allocation of std::vector (Try/catch when potentially large allocation of std::vector #485)
• replace CPLIsNan() with std::isnan() (Try/catch when potentially large allocation of std::vector #485)
• read_ds(): pre-allocate the output vector based on the bit size of the unioned data type across all bands
• validate input columns in the data frame-to-matrix internal C++ conversion functions

Documentation

• update the package Description
• add package vignette Vector API Overview
• update descriptions of the C++ exposed classes and emphasize lack of named argument support in those cases (i.e., argument order matters, mainly of concern with class constructors)
• update Raster API Tutorial to use the argument return_obj with create() and createCopy()
• additions to the section on Azure (/vsiaz/) in GDAL Config Quick Reference
• add the -srcband and -dstband command-line options in the documentation for warp()
• add an example in ogr2ogr() for dissolving features based on an attribute value
• minor updates for g_transform()
• restructure and edit ?ogr_define
• update examples for inspectDataset() and vsi_get_file_metadata() to use the new sample data file inst/extdata/ynp_features.zip (Add raster subdatasets in the sample file ynp_features.gpkg #691)
• add alt text to images in the package vignettes and other web-only articles
• code that cleans up temp files in the examples is now wrapped in \dontshow{}
• add Development practices in CONTRIBUTING.md
• add the OpenSSF best practices badge in README.md
• add the OpenSSF Scorecard badge in README.md

---

This discussion was created from the release gdalraster 2.0.0.