1.. _raster.bag: 2 3================================================================================ 4BAG -- Bathymetry Attributed Grid 5================================================================================ 6 7.. shortname:: BAG 8 9.. build_dependencies:: libhdf5 10 11This driver provides read-only support, and starting with GDAL 2.4 for 12creation, for bathymetry data in the BAG format. BAG files are actually 13a specific product profile in an HDF5 file, but a custom driver exists 14to present the data in a more convenient manner than is available 15through the generic HDF5 driver. 16 17BAG files have two image bands representing Elevation (band 1), 18Uncertainty (band 2) values for each cell in a raster grid area. 19Nominal Elevation values may also be present, and starting with GDAL 3.2, any 202D array of numeric data type and with the same dimensions as Elevation present 21under BAG_root will be reported as a GDAL band. 22 23The geotransform and coordinate system is extracted from the internal 24XML metadata provided with the dataset. However, some products may have 25unsupported coordinate system formats, if using the non-WKT way of 26encoding the spatial reference system. 27 28The full XML metadata is available in the "xml:BAG" metadata domain. 29 30Nodata, minimum and maximum values for each band are also reported. 31 32Driver capabilities 33------------------- 34 35.. supports_createcopy:: 36 37.. supports_create:: 38 39 This driver supports the :cpp:func:`GDALDriver::Create` operation 40 41 .. versionadded:: 3.2 42 43.. supports_georeferencing:: 44 45.. supports_virtualio:: 46 47Open options 48------------ 49 50For open options specific to variable resolution, see following chapter. 51 52Other open options are: 53 54- REPORT_VERTCRS=YES/NO (starting with GDAL 3.2). Defaults to YES. To report 55 the vertical CRS from BAG XML metadata as the vertical component of a 56 compound CRS. If set to NO, only the horizontal part will be reported. 57 58Variable resolution (VR) grid support 59------------------------------------- 60 61Starting with GDAL 2.4, GDAL can handle BAG files with `variable 62resolution 63grids <https://bitbucket.org/ccomjhc/openns/raw/master/docs/VariableResolution/2017-08-10_VariableResolution.docx>`__. 64Such datasets are made of a low-resolution grid, which is the one 65presented by default by the driver, and for each of those low-resolution 66cells, a higher resolution grid can be present in the file. Such higher 67resolution grids are dubbed "supergrids" in GDAL. 68 69The driver has different modes of working which can be controlled by the 70MODE open option: 71 72- MODE=LOW_RES_GRID: this is the default mode. The driver will expose 73 the low resolution grid, and indicate in the dataset metadata if the 74 dataset has supergrids (HAS_SUPERGRIDS=TRUE), as well as the minimum 75 and maximum resolution of those grids. 76- MODE=LIST_SUPERGRIDS: in this mode, the driver will report the 77 various supergrids in the subdataset list. It is possible to apply in 78 this mode additional open options to restrict the search 79 80 - SUPERGRIDS_INDICES=(y1,x1),(y2,x2),...: Tuple or list of tuples, 81 of supergrids described by their y,x indices (starting from 0, y 82 from the south of the grid, x from the west o the grid). 83 - MINX=value: Minimum georeferenced X value to use as a filter for 84 the supergrids to list. 85 - MINY=value: Minimum georeferenced Y value to use as a filter for 86 the supergrids to list. 87 - MAXX=value: Maximum georeferenced X value to use as a filter for 88 the supergrids to list. 89 - MAXY=value: Maximum georeferenced Y value to use as a filter for 90 the supergrids to list. 91 - RES_FILTER_MIN=value: Minimum resolution of supergrids to take 92 into account (excluded bound) 93 - RES_FILTER_MAX=value: Maximum resolution of supergrids to take 94 into account (included bound) 95 96- Opening a supergrid. This mode is triggered by using as a dataset 97 name a string formatted like BAG:my.bag:supergrid:{y}:{x}, which is 98 the value of the SUBDATASET_x_NAME metadata items reported by the 99 above described mode. {y} is the index (starting from 0, from the 100 south of the grid), and {x} is the index (starting from 0, from the 101 west of the grid) of the supergrid to open. 102- MODE=RESAMPLED_GRID: in this mode, the user specify the extent and 103 resolution of a target grid, and for each cell of this target grid, 104 the driver will find the nodes of the supergrids that fall into that 105 cell. By default, it will select the node with the maximum elevation 106 value to populate the cell value. Or if no node of any supergrid are 107 found, the cell value will be set to the nodata value. 108 Overviews are reported: note that, those 109 overviews correspond to resampled grids computed with different 110 values of the RESX and RESY parameters, but using the same value 111 population rules (and not nearest neighbour resampling of the full 112 resolution resampled grid). 113 114 The available open options in this mode are: 115 116 - MINX=value: Minimum georeferenced X value for the resampled grid. 117 By default, the corresponding value of the low resolution grid. 118 - MINY=value: Minimum georeferenced Y value for the resampled grid. 119 By default, the corresponding value of the low resolution grid. 120 - MAXX=value: Maximum georeferenced X value for the resampled grid. 121 By default, the corresponding value of the low resolution grid. 122 - MAXY=value: Maximum georeferenced Y value for the resampled grid. 123 By default, the corresponding value of the low resolution grid. 124 - RESX=value: Horizontal resolution. By default, and if RES_STRATEGY 125 is set to AUTO, this will be the minimum resolution among all the 126 supergrids. 127 - RESY=value: Vertical resolution (positive value). By default, and 128 if RES_STRATEGY is set to AUTO, this will be the minimum 129 resolution among all the supergrids. 130 - RES_STRATEGY=AUTO/MIN/MAX/MEAN: Which strategy to apply to set the 131 resampled grid resolution. By default, if none of RESX, RESY, 132 RES_FILTER_MIN and RES_FILTER_MAX is specified, the AUTO strategy 133 will correspond to the MIN strategy: that is the minimum 134 resolution among all the supergrids is used. If MAX is specified, 135 the maximum resolution among all the supergrids is used. If MEAN 136 is specified, the mean resolution among all the supergrids is 137 used. RESX and RESY, if defined, will override the resolution 138 determined by RES_STRATEGY. 139 - RES_FILTER_MIN=value: Minimum resolution of supergrids to take 140 into account (excluded bound, except if it is the minimum 141 resolution of supergrids). By default, the minimum resolution of 142 supergrids available. If this value is specified and none of 143 RES_STRATEGY, RES_FILTER_MAX, RESX or RESY is specified, the 144 maximum resolution among all the supergrids will be used as the 145 resolution for the resampled grid. 146 - RES_FILTER_MAX=value: Maximum resolution of supergrids to take 147 into account (included bound). By default, the maximum resolution 148 of supergrids available. If this value is specified and none of 149 RES_STRATEGY, RESX or RESY is specified, this will also be used as 150 the resolution for the resampled grid. 151 - VALUE_POPULATION=MIN/MAX/MEAN/COUNT: Which value population strategy to 152 apply to compute the resampled cell values. This default to MAX: 153 the elevation value of a target cell is the maximum elevation of 154 all supergrid nodes (potentially filtered with RES_FILTER_MIN 155 and/or RES_FILTER_MAX) that fall into this cell; the corresponding 156 uncertainty will be the uncertainty of the source node where this 157 maximum elevation si reached. If no supergrid node fall into the 158 target cell, the nodata value is set. The MIN strategy is similar, 159 except that this is the minimum elevation value among intersecting 160 nodes that is selected. The MEAN strategy uses the mean value of 161 the elevation of intersecting nodes, and the maximum uncertainty 162 of those nodes. 163 The COUNT strategy (GDAL >= 3.2) exposes one single UInt32 band where 164 each target cell contains the count of supergrid nodes that fall into it. 165 - SUPERGRIDS_MASK=YES/NO. Default to NO. If set to YES, instead of 166 the elevation and uncertainty band, the dataset contains a single 167 Byte band which is boolean valued. For a target cell, if at least 168 one supergrids nodes (potentially filtered with RES_FILTER_MIN 169 and/or RES_FILTER_MAX) falls into the cell, the cell value is set 170 at 255. Otherwise it is set at 0. This can be used to distinguish 171 if elevation values at nodata are due to no source supergrid node 172 falling into them, or if that/those supergrid nodes were 173 themselves at the nodata value. 174 - NODATA_VALUE=value. Override the default value, which is usually 175 1000000. 176 177Spatial metadata support 178------------------------ 179 180Starting with GDAL 3.2, GDAL can expose BAG files with `spatial metadata 181<https://github.com/OpenNavigationSurface/BAG/issues/2>`__. 182 183When such spatial metadata is present, the subdataset list will include 184names of the form 'BAG:"{filename}":georef_metadata:{name_of_layer}' 185where ``name_of_layer`` is the name of a subgroup under ``/BAG_root/Georef_metadata`` 186 187The values of the ``keys`` dataset under each metadata layer are used as the 188GDAL raster value. And the corresponding ``values`` dataset is exposed as a 189GDAL Raster Attribute Table associated to the GDAL raster band. If ``keys`` 190is absent, record 1 of ``values`` is assumed to be met for each elevation point 191that does not match the nodata value of the elevation band. 192 193When variable resolution grids are present, the MODE=LIST_SUPERGRIDS open option 194will cause subdatasets of names of the form 'BAG:"{filename}":georef_metadata:{name_of_layer}:{y}:{x}' 195to be reported. When opening such a subdataset, the ``varres_keys`` dataset will 196be used to populate the GDAL raster value. 197If ``varres_keys`` is absent, record 1 of ``values`` is assumed to be met for 198each elevation point that does not match the nodata value of the variable resolution 199elevation band. 200 201Tracking list support 202--------------------- 203 204When the dataset is opened in vector mode (ogrinfo, ogr2ogr, etc.), the tracking_list 205dataset will be reported as a OGR vector layer 206 207Creation support 208---------------- 209 210Starting with GDAL 2.4, the driver can create a BAG dataset (without 211variable resolution extension) with the elevation and uncertainty bands 212from a source dataset. The source dataset must be georeferenced, and 213have one or two bands. The first band is assumed to be the elevation 214band, and the second band the uncertainty band. If the second band is 215missing, the uncertainty will be set to nodata. 216 217The driver will instantiate the BAG XML metadata by using a template 218file, which is by default, 219`bag_template.xml <https://raw.githubusercontent.com/OSGeo/gdal/master/gdal/data/bag_template.xml>`__, 220found in the GDAL data definition files. This template contains 221variables, present as ${KEYNAME} or ${KEYNAME:default_value} in the XML 222file, that can be substituted by providing a creation option whose name 223is the VAR\_ string prefixed to the key name. Currently those creation 224options are: 225 226- VAR_INDIVIDUAL_NAME=string: to fill 227 contact/CI_ResponsibleParty/individualName. If not provided, default 228 to "unknown". 229- VAR_ORGANISATION_NAME=string: to fill 230 contact/CI_ResponsibleParty/organisationName. If not provided, 231 default to "unknown". 232- VAR_POSITION_NAME=string: to fill 233 contact/CI_ResponsibleParty/positionName. If not provided, default to 234 "unknown". 235- VAR_DATE=YYYY-MM-DD: to fill dateStamp/Date. If not provided, default 236 to current date. 237- VAR_VERT_WKT=wkt_string: to fill 238 referenceSystemInfo/MD_ReferenceSystem/referenceSystemIdentifier/RS_Identifier/code 239 for the vertical coordinate reference system. If not provided, and if 240 the input CRS is not a compound CRS, default to VERT_CS["unknown", 241 VERT_DATUM["unknown", 2000]]. 242- VAR_ABSTRACT=string: to fill identificationInfo/abstract. If not 243 provided, default to empty string 244- VAR_PROCESS_STEP_DESCRIPTION=string: to fill 245 dataQualityInfo/lineage/LI_Lineage/processStep/LI_ProcessStep/description. 246 If not provided, default to "Generated by GDAL x.y.z". 247- VAR_DATETIME=YYYY-MM-DDTHH:MM:SS : to fill 248 dataQualityInfo/lineage/LI_Lineage/processStep/LI_ProcessStep/dateTime/DateTime. 249 If not provided, default to current datetime. 250- VAR_RESTRICTION_CODE=enumerated_value: to fill 251 metadataConstraints/MD_LegalConstraints/useConstraints/MD_RestrictionCode. 252 If not provided, default to "otherRestrictions". 253- VAR_OTHER_CONSTRAINTS=string: to fill 254 metadataConstraints/MD_LegalConstraints/otherConstraints. If not 255 provided, default to "unknown". 256- VAR_CLASSIFICATION=enumerated_value: to fill 257 metadataConstraints/MD_SecurityConstraints/classification/MD_ClassificationCode. 258 If not provided, default to "unclassified". 259- VAR_SECURITY_USER_NOTE=string: to fill 260 metadataConstraints/MD_SecurityConstraints/userNote. If not provided, 261 default to "none". 262 263Other required variables found in the template, such as RES, RESX, RESY, 264RES_UNIT, HEIGHT, WIDTH, CORNER_POINTS and HORIZ_WKT will be 265automatically filled from the input dataset metadata. 266 267The other following creation options are available: 268 269- TEMPLATE=filename: Path to a XML file that can serve as a template. 270 This will typically be a customized version of the base 271 bag_template.xml file. The file can contain other substituable 272 variables than the ones mentioned above by using a similar syntax. 273- VAR_xxxx=value: Substitute variable ${xxxx} in the template XML value 274 by the provided value. 275- BAG_VERSION=string: Value to write in the /BAG_root/BAG Version 276 attribute. Default to 1.6.2. 277- COMPRESS=NONE/DEFLATE: Compression for elevation and uncertainty 278 grids. Default to DEFLATE. 279- ZLEVEL=[1-9]: Deflate compression level. Defaults to 6. 280- BLOCK_SIZE=value_in_pixel: Chunking size of the HDF5 arrays. Default 281 to 100, or the maximum dimension of the raster if smaller than 100. 282 283Usage examples 284-------------- 285 286- Opening in low resolution mode: 287 288 :: 289 290 $ gdalinfo data/test_vr.bag 291 292 [...] 293 Size is 6, 4 294 [...] 295 HAS_SUPERGRIDS=TRUE 296 MAX_RESOLUTION_X=29.900000 297 MAX_RESOLUTION_Y=31.900000 298 MIN_RESOLUTION_X=4.983333 299 MIN_RESOLUTION_Y=5.316667 300 [...] 301 302- Displaying available supergrids: 303 304 :: 305 306 $ gdalinfo data/test_vr.bag -oo MODE=LIST_SUPERGRIDS 307 308 [...] 309 Subdatasets: 310 SUBDATASET_1_NAME=BAG:"data/test_vr.bag":supergrid:0:0 311 SUBDATASET_1_DESC=Supergrid (y=0, x=0) from (x=70.100000,y=499968.100000) to (x=129.900000,y=500031.900000), resolution (x=29.900000,y=31.900000) 312 SUBDATASET_2_NAME=BAG:"data/test_vr.bag":supergrid:0:1 313 SUBDATASET_2_DESC=Supergrid (y=0, x=1) from (x=107.575000,y=499976.075000) to (x=152.424999,y=500023.924999), resolution (x=14.950000,y=15.950000) 314 [...] 315 SUBDATASET_24_NAME=BAG:"data/test_vr.bag":supergrid:3:5 316 SUBDATASET_24_DESC=Supergrid (y=3, x=5) from (x=232.558335,y=500077.391667) to (x=267.441666,y=500114.608334), resolution (x=4.983333,y=5.316667) 317 [...] 318 319- Opening a particular supergrid: 320 321 :: 322 323 $ gdalinfo BAG:"data/test_vr.bag":supergrid:3:5 324 325- Converting a BAG in resampling mode with default parameters (use of 326 minimum resolution of supergrids, MAX value population rule): 327 328 :: 329 330 $ gdal_translate data/test_vr.bag -oo MODE=RESAMPLED_GRID out.tif 331 332- Converting a BAG in resampling mode with a particular grid origin and 333 resolution 334 335 :: 336 337 $ gdal_translate data/test_vr.bag -oo MODE=RESAMPLED_GRID -oo MINX=80 -oo MINY=500000 -oo RESX=16 -oo RESY=16 out.tif 338 339- Converting a BAG in resampling mode, with a mask indicating where 340 supergrids nodes intersect the cell of the resampled dataset. 341 342 :: 343 344 $ gdal_translate data/test_vr.bag -oo MODE=RESAMPLED_GRID -oo SUPERGRIDS_MASK=YES out.tif 345 346- Converting a BAG in resampling mode, by filtering on supergrid 347 resolutions (and the resampled grid will use 4 meter resolution by 348 default) 349 350 :: 351 352 $ gdal_translate data/test_vr.bag -oo MODE=RESAMPLED_GRID -oo RES_FILTER_MIN=4 -oo RES_FILTER_MAX=8 out.tif 353 354- Converting a GeoTIFF file to a BAG dataset, and provide a custom 355 value for the ABSTRACT substituable variable. 356 357 :: 358 359 $ gdal_translate in.tif out.bag -co "VAR_ABSTRACT=My abstract" 360 361- Converting a (VR) BAG in resampling mode with a particular grid 362 resolution (5m) to a BAG dataset (without variable resolution 363 extension), and provide a custom value for the ABSTRACT metadata: 364 365 :: 366 367 $ gdal_translate data/test_vr.bag -oo MODE=RESAMPLED_GRID -oo RESX=5 -oo RESY=5 out.bag -co "VAR_ABSTRACT=My abstract" 368 369- Displaying the tracking list: 370 371 :: 372 373 $ ogrinfo -al data/my.bal 374 375See Also 376-------- 377 378- Implemented as ``gdal/frmts/hdf5/bagdataset.cpp``. 379- `The Open Navigation Surface Project <http://www.opennavsurf.org>`__ 380- `Description of Bathymetric Attributed Grid Object (BAG) Version 381 1.6 <https://github.com/OpenNavigationSurface/BAG/raw/master/docs/BAG_FSD_Release_1.6.3.doc>`__ 382- `Variable resolution grid extension for BAG 383 files <https://github.com/OpenNavigationSurface/BAG/raw/master/docs/VariableResolution/2017-08-10_VariableResolution.docx>`__ 384