Return List as output from `getCreationOptions()` #649

wiesehahn · 2025-03-06T14:09:30Z

wiesehahn
Mar 6, 2025

getCreationOptions() returns the list of creation options supported by a GDAL format driver as an XML string

> getCreationOptions("GTiff", "COMPRESS")
{xml_node}
<Option name="COMPRESS" type="string-select">
 [1] <Value>NONE</Value>
 [2] <Value>LZW</Value>
 [3] <Value>PACKBITS</Value>
 [4] <Value>JPEG</Value>
 [5] <Value>CCITTRLE</Value>
 [6] <Value>CCITTFAX3</Value>
 [7] <Value>CCITTFAX4</Value>
 [8] <Value>DEFLATE</Value>
 [9] <Value>LZMA</Value>
[10] <Value>ZSTD</Value>
[11] <Value>WEBP</Value>
[12] <Value>LERC</Value>
[13] <Value>LERC_DEFLATE</Value>
[14] <Value>LERC_ZSTD</Value>

Would it be possible or make sense to return options as a proper list?

e.g. I would like to use the output of getCreationOptions("GTiff", "COMPRESS") to loop through available options, I guess I can convert the xml output, but it would be more convenient with direct list output.

ctoney · 2025-03-07T01:57:46Z

ctoney
Mar 7, 2025
Maintainer

Good question. I originally thought of that function as a convenience to look up options, offline in R, but mainly in interactive use. I agree though that well-structured list output could be useful. It's straightforward to get a list from the XML that GDAL gives us, but would take more work to turn that into structured output that generalizes:

Code

library(gdalraster)
#> GDAL 3.8.4, released 2024/02/08, GEOS 3.12.1, PROJ 9.3.1

# The displayed output here is just the raw XML that's printed to the console by getCreationOptions(),
# but from it we can examine the structure that we need to account for.
# Using the output of xml2::as_list() seems less helpful to me than just parsing the XML directly in 
# this case, but it's an option.

opts <- getCreationOptions("GTiff") |> xml2::read_xml() |> xml2::as_list()
#> {xml_node}
#> <Option name="COMPRESS" type="string-select">
#>  [1] <Value>NONE</Value>
#>  [2] <Value>LZW</Value>
#>  [3] <Value>PACKBITS</Value>
#>  [4] <Value>JPEG</Value>
#>  [5] <Value>CCITTRLE</Value>
#>  [6] <Value>CCITTFAX3</Value>
#>  [7] <Value>CCITTFAX4</Value>
#>  [8] <Value>DEFLATE</Value>
#>  [9] <Value>LZMA</Value>
#> [10] <Value>ZSTD</Value>
#> [11] <Value>WEBP</Value>
#> {xml_node}
#> <Option name="PREDICTOR" type="int" description="Predictor Type (1=default, 2=horizontal differencing, 3=floating point prediction)">
#> {xml_node}
#> <Option name="DISCARD_LSB" type="string" description="Number of least-significant bits to set to clear as a single value or comma-separated list of values for per-band values">
#> {xml_node}
#> <Option name="JPEG_QUALITY" type="int" description="JPEG quality 1-100" default="75">
#> {xml_node}
#> <Option name="JPEGTABLESMODE" type="int" description="Content of JPEGTABLES tag. 0=no JPEGTABLES tag, 1=Quantization tables only, 2=Huffman tables only, 3=Both" default="1">
#> {xml_node}
#> <Option name="ZLEVEL" type="int" description="DEFLATE compression level 1-12" default="6">
#> {xml_node}
#> <Option name="LZMA_PRESET" type="int" description="LZMA compression level 0(fast)-9(slow)" default="6">
#> {xml_node}
#> <Option name="ZSTD_LEVEL" type="int" description="ZSTD compression level 1(fast)-22(slow)" default="9">
#> {xml_node}
#> <Option name="WEBP_LOSSLESS" type="boolean" description="Whether lossless compression should be used" default="FALSE">
#> {xml_node}
#> <Option name="WEBP_LEVEL" type="int" description="WEBP quality level. Low values result in higher compression ratios" default="75">
#> {xml_node}
#> <Option name="NUM_THREADS" type="string" description="Number of worker threads for compression. Can be set to ALL_CPUS" default="1">
#> {xml_node}
#> <Option name="NBITS" type="int" description="BITS for sub-byte files (1-7), sub-uint16_t (9-15), sub-uint32_t (17-31), or float32 (16)">
#> {xml_node}
#> <Option name="INTERLEAVE" type="string-select" default="PIXEL">
#> [1] <Value>BAND</Value>
#> [2] <Value>PIXEL</Value>
#> {xml_node}
#> <Option name="TILED" type="boolean" description="Switch to tiled format">
#> {xml_node}
#> <Option name="TFW" type="boolean" description="Write out world file">
#> {xml_node}
#> <Option name="RPB" type="boolean" description="Write out .RPB (RPC) file">
#> {xml_node}
#> <Option name="RPCTXT" type="boolean" description="Write out _RPC.TXT file">
#> {xml_node}
#> <Option name="BLOCKXSIZE" type="int" description="Tile Width">
#> {xml_node}
#> <Option name="BLOCKYSIZE" type="int" description="Tile/Strip Height">
#> {xml_node}
#> <Option name="PHOTOMETRIC" type="string-select">
#> [1] <Value>MINISBLACK</Value>
#> [2] <Value>MINISWHITE</Value>
#> [3] <Value>PALETTE</Value>
#> [4] <Value>RGB</Value>
#> [5] <Value>CMYK</Value>
#> [6] <Value>YCBCR</Value>
#> [7] <Value>CIELAB</Value>
#> [8] <Value>ICCLAB</Value>
#> [9] <Value>ITULAB</Value>
#> {xml_node}
#> <Option name="SPARSE_OK" type="boolean" description="Should empty blocks be omitted on disk?" default="FALSE">
#> {xml_node}
#> <Option name="ALPHA" type="string-select" description="Mark first extrasample as being alpha">
#> [1] <Value>NON-PREMULTIPLIED</Value>
#> [2] <Value>PREMULTIPLIED</Value>
#> [3] <Value>UNSPECIFIED</Value>
#> [4] <Value aliasOf="NON-PREMULTIPLIED">YES</Value>
#> [5] <Value aliasOf="UNSPECIFIED">NO</Value>
#> {xml_node}
#> <Option name="PROFILE" type="string-select" default="GDALGeoTIFF">
#> [1] <Value>GDALGeoTIFF</Value>
#> [2] <Value>GeoTIFF</Value>
#> [3] <Value>BASELINE</Value>
#> {xml_node}
#> <Option name="PIXELTYPE" type="string-select" description="(deprecated, use Int8 datatype)">
#> [1] <Value>DEFAULT</Value>
#> [2] <Value>SIGNEDBYTE</Value>
#> {xml_node}
#> <Option name="BIGTIFF" type="string-select" description="Force creation of BigTIFF file">
#> [1] <Value>YES</Value>
#> [2] <Value>NO</Value>
#> [3] <Value>IF_NEEDED</Value>
#> [4] <Value>IF_SAFER</Value>
#> {xml_node}
#> <Option name="ENDIANNESS" type="string-select" default="NATIVE" description="Force endianness of created file. For DEBUG purpose mostly">
#> [1] <Value>NATIVE</Value>
#> [2] <Value>INVERTED</Value>
#> [3] <Value>LITTLE</Value>
#> [4] <Value>BIG</Value>
#> {xml_node}
#> <Option name="COPY_SRC_OVERVIEWS" type="boolean" default="NO" description="Force copy of overviews of source dataset (CreateCopy())">
#> {xml_node}
#> <Option name="SOURCE_ICC_PROFILE" type="string" description="ICC profile">
#> {xml_node}
#> <Option name="SOURCE_PRIMARIES_RED" type="string" description="x,y,1.0 (xyY) red chromaticity">
#> {xml_node}
#> <Option name="SOURCE_PRIMARIES_GREEN" type="string" description="x,y,1.0 (xyY) green chromaticity">
#> {xml_node}
#> <Option name="SOURCE_PRIMARIES_BLUE" type="string" description="x,y,1.0 (xyY) blue chromaticity">
#> {xml_node}
#> <Option name="SOURCE_WHITEPOINT" type="string" description="x,y,1.0 (xyY) whitepoint">
#> {xml_node}
#> <Option name="TIFFTAG_TRANSFERFUNCTION_RED" type="string" description="Transfer function for red">
#> {xml_node}
#> <Option name="TIFFTAG_TRANSFERFUNCTION_GREEN" type="string" description="Transfer function for green">
#> {xml_node}
#> <Option name="TIFFTAG_TRANSFERFUNCTION_BLUE" type="string" description="Transfer function for blue">
#> {xml_node}
#> <Option name="TIFFTAG_TRANSFERRANGE_BLACK" type="string" description="Transfer range for black">
#> {xml_node}
#> <Option name="TIFFTAG_TRANSFERRANGE_WHITE" type="string" description="Transfer range for white">
#> {xml_node}
#> <Option name="STREAMABLE_OUTPUT" type="boolean" default="NO" description="Enforce a mode compatible with a streamable file">
#> {xml_node}
#> <Option name="GEOTIFF_KEYS_FLAVOR" type="string-select" default="STANDARD" description="Which flavor of GeoTIFF keys must be used">
#> [1] <Value>STANDARD</Value>
#> [2] <Value>ESRI_PE</Value>
#> {xml_node}
#> <Option name="GEOTIFF_VERSION" type="string-select" default="AUTO" description="Which version of GeoTIFF must be used">
#> [1] <Value>AUTO</Value>
#> [2] <Value>1.0</Value>
#> [3] <Value>1.1</Value>
#> $CreationOptionList
#> $CreationOptionList$Option
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "NONE"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "LZW"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "PACKBITS"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "JPEG"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "CCITTRLE"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "CCITTFAX3"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "CCITTFAX4"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "DEFLATE"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "LZMA"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "ZSTD"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "WEBP"
#> 
#> 
#> attr(,"name")
#> [1] "COMPRESS"
#> attr(,"type")
#> [1] "string-select"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "PREDICTOR"
#> attr(,"type")
#> [1] "int"
#> attr(,"description")
#> [1] "Predictor Type (1=default, 2=horizontal differencing, 3=floating point prediction)"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "DISCARD_LSB"
#> attr(,"type")
#> [1] "string"
#> attr(,"description")
#> [1] "Number of least-significant bits to set to clear as a single value or comma-separated list of values for per-band values"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "JPEG_QUALITY"
#> attr(,"type")
#> [1] "int"
#> attr(,"description")
#> [1] "JPEG quality 1-100"
#> attr(,"default")
#> [1] "75"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "JPEGTABLESMODE"
#> attr(,"type")
#> [1] "int"
#> attr(,"description")
#> [1] "Content of JPEGTABLES tag. 0=no JPEGTABLES tag, 1=Quantization tables only, 2=Huffman tables only, 3=Both"
#> attr(,"default")
#> [1] "1"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "ZLEVEL"
#> attr(,"type")
#> [1] "int"
#> attr(,"description")
#> [1] "DEFLATE compression level 1-12"
#> attr(,"default")
#> [1] "6"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "LZMA_PRESET"
#> attr(,"type")
#> [1] "int"
#> attr(,"description")
#> [1] "LZMA compression level 0(fast)-9(slow)"
#> attr(,"default")
#> [1] "6"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "ZSTD_LEVEL"
#> attr(,"type")
#> [1] "int"
#> attr(,"description")
#> [1] "ZSTD compression level 1(fast)-22(slow)"
#> attr(,"default")
#> [1] "9"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "WEBP_LOSSLESS"
#> attr(,"type")
#> [1] "boolean"
#> attr(,"description")
#> [1] "Whether lossless compression should be used"
#> attr(,"default")
#> [1] "FALSE"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "WEBP_LEVEL"
#> attr(,"type")
#> [1] "int"
#> attr(,"description")
#> [1] "WEBP quality level. Low values result in higher compression ratios"
#> attr(,"default")
#> [1] "75"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "NUM_THREADS"
#> attr(,"type")
#> [1] "string"
#> attr(,"description")
#> [1] "Number of worker threads for compression. Can be set to ALL_CPUS"
#> attr(,"default")
#> [1] "1"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "NBITS"
#> attr(,"type")
#> [1] "int"
#> attr(,"description")
#> [1] "BITS for sub-byte files (1-7), sub-uint16_t (9-15), sub-uint32_t (17-31), or float32 (16)"
#> 
#> $CreationOptionList$Option
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "BAND"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "PIXEL"
#> 
#> 
#> attr(,"name")
#> [1] "INTERLEAVE"
#> attr(,"type")
#> [1] "string-select"
#> attr(,"default")
#> [1] "PIXEL"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "TILED"
#> attr(,"type")
#> [1] "boolean"
#> attr(,"description")
#> [1] "Switch to tiled format"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "TFW"
#> attr(,"type")
#> [1] "boolean"
#> attr(,"description")
#> [1] "Write out world file"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "RPB"
#> attr(,"type")
#> [1] "boolean"
#> attr(,"description")
#> [1] "Write out .RPB (RPC) file"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "RPCTXT"
#> attr(,"type")
#> [1] "boolean"
#> attr(,"description")
#> [1] "Write out _RPC.TXT file"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "BLOCKXSIZE"
#> attr(,"type")
#> [1] "int"
#> attr(,"description")
#> [1] "Tile Width"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "BLOCKYSIZE"
#> attr(,"type")
#> [1] "int"
#> attr(,"description")
#> [1] "Tile/Strip Height"
#> 
#> $CreationOptionList$Option
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "MINISBLACK"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "MINISWHITE"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "PALETTE"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "RGB"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "CMYK"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "YCBCR"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "CIELAB"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "ICCLAB"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "ITULAB"
#> 
#> 
#> attr(,"name")
#> [1] "PHOTOMETRIC"
#> attr(,"type")
#> [1] "string-select"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "SPARSE_OK"
#> attr(,"type")
#> [1] "boolean"
#> attr(,"description")
#> [1] "Should empty blocks be omitted on disk?"
#> attr(,"default")
#> [1] "FALSE"
#> 
#> $CreationOptionList$Option
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "NON-PREMULTIPLIED"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "PREMULTIPLIED"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "UNSPECIFIED"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "YES"
#> 
#> attr(,"aliasOf")
#> [1] "NON-PREMULTIPLIED"
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "NO"
#> 
#> attr(,"aliasOf")
#> [1] "UNSPECIFIED"
#> 
#> attr(,"name")
#> [1] "ALPHA"
#> attr(,"type")
#> [1] "string-select"
#> attr(,"description")
#> [1] "Mark first extrasample as being alpha"
#> 
#> $CreationOptionList$Option
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "GDALGeoTIFF"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "GeoTIFF"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "BASELINE"
#> 
#> 
#> attr(,"name")
#> [1] "PROFILE"
#> attr(,"type")
#> [1] "string-select"
#> attr(,"default")
#> [1] "GDALGeoTIFF"
#> 
#> $CreationOptionList$Option
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "DEFAULT"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "SIGNEDBYTE"
#> 
#> 
#> attr(,"name")
#> [1] "PIXELTYPE"
#> attr(,"type")
#> [1] "string-select"
#> attr(,"description")
#> [1] "(deprecated, use Int8 datatype)"
#> 
#> $CreationOptionList$Option
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "YES"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "NO"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "IF_NEEDED"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "IF_SAFER"
#> 
#> 
#> attr(,"name")
#> [1] "BIGTIFF"
#> attr(,"type")
#> [1] "string-select"
#> attr(,"description")
#> [1] "Force creation of BigTIFF file"
#> 
#> $CreationOptionList$Option
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "NATIVE"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "INVERTED"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "LITTLE"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "BIG"
#> 
#> 
#> attr(,"name")
#> [1] "ENDIANNESS"
#> attr(,"type")
#> [1] "string-select"
#> attr(,"default")
#> [1] "NATIVE"
#> attr(,"description")
#> [1] "Force endianness of created file. For DEBUG purpose mostly"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "COPY_SRC_OVERVIEWS"
#> attr(,"type")
#> [1] "boolean"
#> attr(,"default")
#> [1] "NO"
#> attr(,"description")
#> [1] "Force copy of overviews of source dataset (CreateCopy())"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "SOURCE_ICC_PROFILE"
#> attr(,"type")
#> [1] "string"
#> attr(,"description")
#> [1] "ICC profile"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "SOURCE_PRIMARIES_RED"
#> attr(,"type")
#> [1] "string"
#> attr(,"description")
#> [1] "x,y,1.0 (xyY) red chromaticity"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "SOURCE_PRIMARIES_GREEN"
#> attr(,"type")
#> [1] "string"
#> attr(,"description")
#> [1] "x,y,1.0 (xyY) green chromaticity"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "SOURCE_PRIMARIES_BLUE"
#> attr(,"type")
#> [1] "string"
#> attr(,"description")
#> [1] "x,y,1.0 (xyY) blue chromaticity"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "SOURCE_WHITEPOINT"
#> attr(,"type")
#> [1] "string"
#> attr(,"description")
#> [1] "x,y,1.0 (xyY) whitepoint"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "TIFFTAG_TRANSFERFUNCTION_RED"
#> attr(,"type")
#> [1] "string"
#> attr(,"description")
#> [1] "Transfer function for red"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "TIFFTAG_TRANSFERFUNCTION_GREEN"
#> attr(,"type")
#> [1] "string"
#> attr(,"description")
#> [1] "Transfer function for green"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "TIFFTAG_TRANSFERFUNCTION_BLUE"
#> attr(,"type")
#> [1] "string"
#> attr(,"description")
#> [1] "Transfer function for blue"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "TIFFTAG_TRANSFERRANGE_BLACK"
#> attr(,"type")
#> [1] "string"
#> attr(,"description")
#> [1] "Transfer range for black"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "TIFFTAG_TRANSFERRANGE_WHITE"
#> attr(,"type")
#> [1] "string"
#> attr(,"description")
#> [1] "Transfer range for white"
#> 
#> $CreationOptionList$Option
#> list()
#> attr(,"name")
#> [1] "STREAMABLE_OUTPUT"
#> attr(,"type")
#> [1] "boolean"
#> attr(,"default")
#> [1] "NO"
#> attr(,"description")
#> [1] "Enforce a mode compatible with a streamable file"
#> 
#> $CreationOptionList$Option
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "STANDARD"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "ESRI_PE"
#> 
#> 
#> attr(,"name")
#> [1] "GEOTIFF_KEYS_FLAVOR"
#> attr(,"type")
#> [1] "string-select"
#> attr(,"default")
#> [1] "STANDARD"
#> attr(,"description")
#> [1] "Which flavor of GeoTIFF keys must be used"
#> 
#> $CreationOptionList$Option
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "AUTO"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "1.0"
#> 
#> 
#> $CreationOptionList$Option$Value
#> $CreationOptionList$Option$Value[[1]]
#> [1] "1.1"
#> 
#> 
#> attr(,"name")
#> [1] "GEOTIFF_VERSION"
#> attr(,"type")
#> [1] "string-select"
#> attr(,"default")
#> [1] "AUTO"
#> attr(,"description")
#> [1] "Which version of GeoTIFF must be used"

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

We could return a list or character vector for xml nodes of type="string-select". But types boolean, int and string have only a free-form description and a default value (so just character string return values for those elements).

Possible format of the return value:
The output list for one creation option would have named elements matching the xml nodes: $name, $type, $description, $default and $values.
$default would sometimes be NA, and $values would only be populated if $type == "string-select".

It probably would be structured as a nested list in order to return all the options for a driver, i.e., a list of named elements for the option names, and each of those is a list with $type, $description, $default and $values. Each of those is a character string, except $values would be a character vector.

Let me know if you have thoughts or suggestion along those lines. Does the complexity of a nested list like that seem reasonable for this case?

0 replies

ctoney · 2025-03-07T04:44:05Z

ctoney
Mar 7, 2025
Maintainer

Prototype here but documentation and tests have not been updated yet:
https://github.com/ctoney/gdalraster/tree/get_creation_opts

# get a specific option
opt <- getCreationOptions("GTiff", "COMPRESS")
names(opt)
#> [1] "COMPRESS"

(opt$COMPRESS$type == "string-select")
#> [1] TRUE

opt$COMPRESS$values
#> [1] "NONE"      "LZW"       "PACKBITS"  "JPEG"      "CCITTRLE"  "CCITTFAX3"
#> [7] "CCITTFAX4" "DEFLATE"   "LZMA"      "ZSTD"      "WEBP"

# all options
all_opt <- getCreationOptions("GTiff")
names(all_opt)
#>  [1] "COMPRESS"                       "PREDICTOR"                     
#>  [3] "DISCARD_LSB"                    "JPEG_QUALITY"                  
#>  [5] "JPEGTABLESMODE"                 "ZLEVEL"                        
#>  [7] "LZMA_PRESET"                    "ZSTD_LEVEL"                    
#>  [9] "WEBP_LOSSLESS"                  "WEBP_LEVEL"                    
#> [11] "NUM_THREADS"                    "NBITS"                         
#> [13] "INTERLEAVE"                     "TILED"                         
#> [15] "TFW"                            "RPB"                           
#> [17] "RPCTXT"                         "BLOCKXSIZE"                    
#> [19] "BLOCKYSIZE"                     "PHOTOMETRIC"                   
#> [21] "SPARSE_OK"                      "ALPHA"                         
#> [23] "PROFILE"                        "PIXELTYPE"                     
#> [25] "BIGTIFF"                        "ENDIANNESS"                    
#> [27] "COPY_SRC_OVERVIEWS"             "SOURCE_ICC_PROFILE"            
#> [29] "SOURCE_PRIMARIES_RED"           "SOURCE_PRIMARIES_GREEN"        
#> [31] "SOURCE_PRIMARIES_BLUE"          "SOURCE_WHITEPOINT"             
#> [33] "TIFFTAG_TRANSFERFUNCTION_RED"   "TIFFTAG_TRANSFERFUNCTION_GREEN"
#> [35] "TIFFTAG_TRANSFERFUNCTION_BLUE"  "TIFFTAG_TRANSFERRANGE_BLACK"   
#> [37] "TIFFTAG_TRANSFERRANGE_WHITE"    "STREAMABLE_OUTPUT"             
#> [39] "GEOTIFF_KEYS_FLAVOR"            "GEOTIFF_VERSION" 

# Note:
# '$description' and '$default' will be NA if no value is assigned by GDAL in the XML
# '$values' will be NULL if the option is not a 'string-select' type

# 'int' type
all_opt$PREDICTOR
#> $type
#> [1] "int"
#> 
#> $description
#> [1] "Predictor Type (1=default, 2=horizontal differencing, 3=floating point prediction)"
#> 
#> $default
#> [1] NA
#> 
#> $values
#> NULL

all_opt$BIGTIFF
#> $type
#> [1] "string-select"
#> 
#> $description
#> [1] "Force creation of BigTIFF file"
#> 
#> $default
#> [1] NA
#> 
#> $values
#> [1] "YES"       "NO"        "IF_NEEDED" "IF_SAFER"

0 replies

ctoney · 2025-03-16T17:07:43Z

ctoney
Mar 16, 2025
Maintainer

This has been implemented in #662. As noted there,

it was assumed that the new return value is satisfactory. Otherwise, glad to make other changes as needed.

The updated documentation is now available at:
https://usdaforestservice.github.io/gdalraster/reference/getCreationOptions.html

1 reply

wiesehahn Mar 17, 2025
Author

thanks, this looks good to me.

what I am still missing though is more information about possible values/combinations (e.g. PREDICTOR is only valid for LZW, DEFLATE and ZSTD; highest LEVEL is 9 or 22 depending on COMPRESSION, ...), but I guess this is not in the hands of gdalraster.

ctoney · 2025-03-17T16:06:26Z

ctoney
Mar 17, 2025
Maintainer

Re: the possible values/valid range, I intended to include $min and $max in the returned list, but those lines are currently commented out:
https://github.com/USDAForestService/gdalraster/blob/6efd39a4a4f240a24e98d67411433fbc1c838948/R/gdal_helpers.R#L323

Although min/max attributes are populated by the GDAL driver when the XML is created, for some reason they are not included when the XML string is returned, at least with current GDAL versions. An issue has been opened with further details: OSGeo/gdal#11967

That would not address valid combinations though. Checking for valid combinations may require implementing custom logic for a specific use case, but even so, would be helped if the min/max issue is resolved and you could access those numeric values from the returned list.

We could add a wrapper for GDALValidateCreationOptions(), but from its documentation it does not appear to account for combinations, rather just checks for compatibility "with with the capabilities declared by the GDAL_DMD_CREATIONOPTIONLIST metadata item", which is the list we're now returning. That would be easy to wrap in gdalraster though if you think it would be helpful.

1 reply

wiesehahn Mar 17, 2025
Author

I think it might be helpful, but it may be more a convenient function than nessessary, at least from m side.

ctoney · 2025-03-17T22:57:58Z

ctoney
Mar 17, 2025
Maintainer

See resolution to OSGeo/gdal#11967 (comment). We aren't able to access min/max with current GDAL versions, but this should work with a future GDAL 3.11 release. I will probably enable $min and $max in the returned list once I have chance to test with GDAL 3.11 dev. However, min/max would always be returned as NA unless gdalraster is built against GDAL 3.11, so I'll probably include them in the list only when GDAL >= 3.11 is detected (i.e., those list elements would be documented as GDAL >= 3.11).

I'll also add a wrapper for GDALValidateCreationOptions(). It should be useful in some situations, but I don't think it will do the validation you're describing for combinations. I would also expect that with current GDAL versions, it will have the same limitations in terms of not validating min/max values.

0 replies

ctoney · 2025-04-02T05:32:18Z

ctoney
Apr 2, 2025
Maintainer

Closing this as completed in #662, augmented with #663 and #666

0 replies

Return List as output from getCreationOptions() #649

Uh oh!

wiesehahn Mar 6, 2025

Replies: 6 comments · 2 replies

Uh oh!

Uh oh!

ctoney Mar 7, 2025 Maintainer

Uh oh!

Uh oh!

ctoney Mar 7, 2025 Maintainer

Uh oh!

ctoney Mar 16, 2025 Maintainer

Uh oh!

wiesehahn Mar 17, 2025 Author

Uh oh!

ctoney Mar 17, 2025 Maintainer

Uh oh!

wiesehahn Mar 17, 2025 Author

Uh oh!

ctoney Mar 17, 2025 Maintainer

Uh oh!

ctoney Apr 2, 2025 Maintainer

Return List as output from `getCreationOptions()` #649

wiesehahn
Mar 6, 2025

Replies: 6 comments 2 replies

ctoney
Mar 7, 2025
Maintainer

ctoney
Mar 7, 2025
Maintainer

ctoney
Mar 16, 2025
Maintainer

wiesehahn Mar 17, 2025
Author

ctoney
Mar 17, 2025
Maintainer

wiesehahn Mar 17, 2025
Author

ctoney
Mar 17, 2025
Maintainer

ctoney
Apr 2, 2025
Maintainer