BAG --- Bathymetry Attributed Grid

This driver provides read-only support, and starting with GDAL 2.4 for creation,
for bathymetry data in the BAG format.
BAG files are actually a specific product profile in an HDF5 file, but a
custom driver exists to present the data in a more convenient manner than
is available through the generic HDF5 driver.

BAG files have two or three image bands representing Elevation (band 1),
Uncertainty (band 2) and Nominal Elevation (band 3) values for each cell in a
raster grid area.

The geotransform and coordinate system is extracted from the internal XML
metadata provided with the dataset. However, some products may have
unsupported coordinate system formats, if using the non-WKT way of encoding
the spatial reference system.

The full XML metadata is available in the "xml:BAG" metadata domain.

Nodata, minimum and maximum values for each band are also reported.

Variable resolution (VR) grid support

Starting with GDAL 2.4, GDAL can handle BAG files with
variable resolution grids. Such datasets are made of a low-resolution grid,
which is the one presented by default by the driver, and for each of those
low-resolution cells, a higher resolution grid can be present in the file.
Such higher resolution grids are dubbed "supergrids" in GDAL.

The driver has different modes of working which can be controlled by the
MODE open option:

MODE=LOW_RES_GRID: this is the default mode. The driver will expose the
low resolution grid, and indicate in the dataset metadata if the dataset has
supergrids (HAS_SUPERGRIDS=TRUE), as well as the minimum and maximum resolution
of those grids.

MODE=LIST_SUPERGRIDS: in this mode, the driver will report the various
supergrids in the subdataset list.
It is possible to apply in this mode additional open options to restrict the
search

SUPERGRIDS_INDICES=(y1,x1),(y2,x2),...: Tuple or list of tuples, of
supergrids described by their y,x indices (starting from 0, y
from the south of the grid, x from the west o the grid).

MINX=value: Minimum georeferenced X value to use as a filter for the
supergrids to list.

MINY=value: Minimum georeferenced Y value to use as a filter for the
supergrids to list.

MAXX=value: Maximum georeferenced X value to use as a filter for the
supergrids to list.

MAXY=value: Maximum georeferenced Y value to use as a filter for the
supergrids to list.

RES_FILTER_MIN=value: Minimum resolution of supergrids to take into
account (excluded bound)

RES_FILTER_MAX=value: Maximum resolution of supergrids to take into
account (included bound)

Opening a supergrid. This mode is triggered by using as a dataset name a
string formatted like BAG:my.bag:supergrid:{y}:{x}, which is the value of
the SUBDATASET_x_NAME metadata items reported by the above described mode.
{y} is the index (starting from 0, from the south of the grid), and {x} is the
index (starting from 0, from the west of the grid) of the supergrid to open.

MODE=RESAMPLED_GRID: in this mode, the user specify the extent and
resolution of a target grid, and for each cell of this target grid, the driver
will find the nodes of the supergrids that fall into that cell. By default, it
will select the node with the maximum elevation value to populate the cell value.
Or if no node of any supergrid are found, the cell value will be set to the
nodata value. Interpolation of cells at nodata value can also be done using
a inverse distance weighting interpolation. Overviews are reported: note that,
those overviews correspond to resampled grids computed with different values
of the RESX and RESY parameters, but using the same value
population rules (and not nearest neighbour resampling of the full resolution
resampled grid).

The available open options in this mode are:

MINX=value: Minimum georeferenced X value for the resampled grid. By
default, the corresponding value of the low resolution grid.

MINY=value: Minimum georeferenced Y value for the resampled grid. By
default, the corresponding value of the low resolution grid.

MAXX=value: Maximum georeferenced X value for the resampled grid. By
default, the corresponding value of the low resolution grid.

MAXY=value: Maximum georeferenced Y value for the resampled grid. By
default, the corresponding value of the low resolution grid.

RESX=value: Horizontal resolution. By default, and if RES_STRATEGY is set
to AUTO, this will be the minimum resolution among all the supergrids.

RESY=value: Vertical resolution (positive value). By default, and if
RES_STRATEGY is set to AUTO, this will be the minimum resolution among all the
supergrids.

RES_STRATEGY=AUTO/MIN/MAX/MEAN: Which strategy to apply to set the
resampled grid resolution. By default, if none of RESX, RESY, RES_FILTER_MIN and
RES_FILTER_MAX is specified, the AUTO strategy will correspond to
the MIN strategy: that is the minimum resolution among all the supergrids is
used.
If MAX is specified, the maximum resolution among all the supergrids
is used.
If MEAN is specified, the mean resolution among all the supergrids is used.
RESX and RESY, if defined, will override the resolution determined by
RES_STRATEGY.

RES_FILTER_MIN=value: Minimum resolution of supergrids to take into
account (excluded bound, except if it is the minimum resolution of supergrids).
By default, the minimum resolution of supergrids available.
If this value is specified and none of RES_STRATEGY, RES_FILTER_MAX, RESX or RESY
is specified, the maximum resolution among all the supergrids will be used
as the resolution for the resampled grid.

RES_FILTER_MAX=value: Maximum resolution of supergrids to take into
account (included bound). By default, the maximum resolution of supergrids
available. If this value is specified and none of RES_STRATEGY, RESX or RESY
is specified, this will also be used as the resolution for the resampled grid.

VALUE_POPULATION=MIN/MAX/MEAN: Which value population strategy to apply to
compute the resampled cell values. This default to MAX: the elevation value of a
target cell is the maximum elevation of all supergrid nodes (potentially filtered
with RES_FILTER_MIN and/or RES_FILTER_MAX) that fall into this cell; the
corresponding uncertainty will be the uncertainty of the source node where this
maximum elevation si reached. If no supergrid node fall into the target cell, the
nodata value is set.
The MIN strategy is similar, except that this is the
minimum elevation value among intersecting nodes that is selected.
The MEAN strategy use the mean value of the elevation of intersecting nodes, and
the maximum uncertainty of those nodes.

SUPERGRIDS_MASK=YES/NO. Default to NO. If set to YES, instead of the
elevation and uncertainty band, the dataset contains a single Byte band which is
boolean valued. For a target cell, if at least one supergrids nodes (potentially
filtered with RES_FILTER_MIN and/or RES_FILTER_MAX) falls into the cell, the
cell value is set at 255. Otherwise it is set at 0. This can be used to
distinguish if elevation values at nodata are due to no source supergrid node
falling into them, or if that/those supergrid nodes were themselves at the
nodata value.

INTERPOLATION=NO/INVDIST. Default to NO. If set to INVDIST, a inverse
distance weighting interpolation of nodata values is applied after the above
describe value population.
Interpolation cannot be used together with SUPERGRIDS_MASK=YES.

NODATA_VALUE=value. Override the default value, which is usually 1000000.

Creation support

Starting with GDAL 2.4, the driver can create a BAG dataset (without variable
resolution extension) with the elevation and uncertainty bands from a source
dataset. The source dataset must be georeferenced, and have one or two bands.
The first band is assumed to be the elevation band, and the second band the
uncertainty band. If the second band is missing, the uncertainty will be set to
nodata.

The driver will instantiate the BAG XML metadata by using a template file,
which is by default,
bag_template.xml, found in the GDAL data definition files. This template
contains variables, present as ${KEYNAME} or ${KEYNAME:default_value} in the
XML file, that can be substituted by providing a creation option whose name is
the VAR_ string prefixed to the key name. Currently those creation options are:

VAR_INDIVIDUAL_NAME=string: to fill contact/CI_ResponsibleParty/individualName.
If not provided, default to "unknown".

VAR_ORGANISATION_NAME=string: to fill contact/CI_ResponsibleParty/organisationName.
If not provided, default to "unknown".

VAR_POSITION_NAME=string: to fill contact/CI_ResponsibleParty/positionName.
If not provided, default to "unknown".

VAR_DATE=YYYY-MM-DD: to fill dateStamp/Date. If not provided, default to
current date.

VAR_VERT_WKT=wkt_string: to fill referenceSystemInfo/MD_ReferenceSystem/referenceSystemIdentifier/RS_Identifier/code
for the vertical coordinate reference system. If not provided, and if the
input CRS is not a compound CRS, default to
VERT_CS["unknown", VERT_DATUM["unknown", 2000]].

VAR_ABSTRACT=string: to fill identificationInfo/abstract. If not provided,
default to empty string

VAR_PROCESS_STEP_DESCRIPTION=string: to fill dataQualityInfo/lineage/LI_Lineage/processStep/LI_ProcessStep/description.
If not provided, default to "Generated by GDAL x.y.z".

VAR_DATETIME=YYYY-MM-DDTHH:MM:SS : to fill dataQualityInfo/lineage/LI_Lineage/processStep/LI_ProcessStep/dateTime/DateTime.
If not provided, default to current datetime.

VAR_RESTRICTION_CODE=enumerated_value: to fill metadataConstraints/MD_LegalConstraints/useConstraints/MD_RestrictionCode.
If not provided, default to "otherRestrictions".

VAR_OTHER_CONSTRAINTS=string: to fill metadataConstraints/MD_LegalConstraints/otherConstraints.
If not provided, default to "unknown".

VAR_CLASSIFICATION=enumerated_value: to fill metadataConstraints/MD_SecurityConstraints/classification/MD_ClassificationCode.
If not provided, default to "unclassified".

VAR_SECURITY_USER_NOTE=string: to fill metadataConstraints/MD_SecurityConstraints/userNote.
If not provided, default to "none".

Other required variables found in the template, such as RES, RESX, RESY,
RES_UNIT, HEIGHT, WIDTH, CORNER_POINTS and HORIZ_WKT will be automatically
filled from the input dataset metadata.

The other following creation options are available:

TEMPLATE=filename: Path to a XML file that can serve as a template. This
will typically be a customized version of the base bag_template.xml file. The
file can contain other substituable variables than the ones mentioned above
by using a similar syntax.

VAR_xxxx=value: Substitute variable ${xxxx} in the template XML value by
the provided value.

BAG_VERSION=string: Value to write in the /BAG_root/BAG Version attribute.
Default to 1.6.2.

COMPRESS=NONE/DEFLATE: Compression for elevation and uncertainty grids. Default
to DEFLATE.

ZLEVEL=[1-9]: Deflate compression level. Defaults to 6.

BLOCK_SIZE=value_in_pixel: Chunking size of the HDF5 arrays. Default to 100,
or the maximum dimension of the raster if smaller than 100.