different results with getMetadataItem depending on variable input order

[wiesehahn]

Is it expected that getMetadataItem returns different reults depending on variable order in function?

I expected both variants to return "DEFLATE".
(I didnt test development version, so it might be fixed already)

library(gdalraster)
#> Warning: package 'gdalraster' was built under R version 4.4.3
#> GDAL 3.10.1, released 2025/01/08, GEOS 3.13.0, PROJ 9.5.1

tcc_file <- system.file("extdata/storml_tcc.tif", package="gdalraster")
ds <- new(GDALRaster, tcc_file, read_only = TRUE)
ds$getMetadata(band = 0, domain = "IMAGE_STRUCTURE")
#> [1] "COMPRESSION=DEFLATE" "INTERLEAVE=BAND"

ds$getMetadataItem(band = 0, domain = "IMAGE_STRUCTURE", mdi_name = "COMPRESSION")
#> [1] ""
ds$getMetadataItem(band = 0, mdi_name = "COMPRESSION", domain = "IMAGE_STRUCTURE")
#> [1] "DEFLATE"

^{Created on 2025-03-06 with reprex v2.1.0}

[wiesehahn]

also to my understanding the band > domain > mdi_name order seems more logical if I had to choose one.

[ctoney]

Is it expected that getMetadataItem returns different reults depending on variable order in function?

Well, it is expected, but no, it would not be expected by most R users. GDALRaster, as well as GDALVector that will be in the upcoming 2.0 release, are implemented as C++ classes exposed in R via Rcpp's capability do that in a fairly direct way. In gdalraster this is done without any additional R wrapping in front (i.e., not wrapped in S4 classes or other possibilities like that). Since C++ itself does not support named arguments, that is what we also get with these classes, they're pretty close to C++ and the just the argument order matters.

Mainly, your question highlighted the need to document that clearly which was lacking. That has been done in #654, and now rendered online at

GDALRaster: https://usdaforestservice.github.io/gdalraster/reference/GDALRaster-class.html
GDALVector: https://usdaforestservice.github.io/gdalraster/reference/GDALVector-class.html

Happy to take suggestions for any changes that would improve.

There is a longer answer relating to the design choice with directly exposed C++ classes, which has certain implications for usability as you discovered. Legitimate criticism of the approach can be made. I believe the overall downsides are limited and involve trade offs that are worthwhile, especially given the intent and role that I see for the package. It's been on my mind for a long time to document my rationale, which could be helpful for potential users to better understand and adopt the interface. I will try to do that in the near future.

also to my understanding the band > domain > mdi_name order seems more logical if I had to choose one.

That makes sense to me. However, since the package aims to provide API-level bindings to GDAL (roughly "osgeo-like" bindings), I almost always follow its method signatures and calling semantics (probably to a fault in some cases, and a small number of lapses in others). With some exceptions, most of the GDALRaster class methods are straightforward wrappers of the underlying API. For getMetadataItem, it is what the GDAL API uses so we are consistent with that:
https://gdal.org/en/stable/doxygen/classGDALRasterBand.html#aca9ff0114b8d1b25d5243ef060e0e5de
same in the osgeo bindings:
https://gdal.org/en/stable/api/python/osgeo.gdal.html#osgeo.gdal.MajorObject.GetMetadataItem

[wiesehahn]

Thanks for the detailed description, this wasn't clear to me but now I guess I understand the concept.

[mdsumner]

Should we make a internal (R) versions for the export, and save the external name/s for the R wrapper?

I'm used to doing that with Rcpp, names like "package_fun_cpp" wrapped by "package_fun()" - but is there more to it with modules, I guess we lose the documentation but can't we get that by documenting the R wrapper?

(Asking, without trying... 🙏)