Bathymetry Database
===================

The Bathymetry Database module is used to import bathymetric data from the Delft Dashboard OPeNDAP server at Deltares.

Getting started
---------------

It is required that you have or create a database folder in which bathymetric tiles can be cached.
For Delft Dashboard users, the path is typically something like:

.. code-block:: console

    d:\\delftdashboard\\data\\bathymetry

The Bathymetry Database can be initialized like this:

.. code-block:: console

   from cht.bathymetry_database import BathymetryDatabase
   
   bdb = BathymetryDatabase("d:\\delftdashboard\\data\\bathymetry")

Importing bathymetry
--------------------

Bathymetry data can now be downloaded using the ``get_data`` method. You'll need to prescribe the dataset name, the limits (bounding box),
and the minimum resolution for of the requested data. For example, if you wish to obtain gridded bathymetry data
from `GEBCO19 <https://www.gebco.net/data_and_products/gridded_bathymetry_data/gebco_2019/gebco_2019_info.html>`_ 
for an area in the Gulf of Mexico with a maximum cell size of 500 metres, you can do:

.. code-block:: console

    x, y, z = bdb.get_data('gebco19',
                           xlim=[-85.0, -80.0],
                           ylim=[ 28.0,  34.0],
                           max_cell_size=500.0)

This will return the 1D Numpy arrays *x* and *y* containing the horizontal coordinates of the data, and a 2D NumPy array *z* which contains the vertical elevation data. 

THE NEXT BIT HAS NOT YET BEEN IMPLEMENTED !!!

You can also import gridded data in a coordinate reference system (CRS) other than the native CRS of the requested data. In this case, you'll need to define the grid spacing
*dx* an *dy*, as well as the name of the requested CRS. The raw bathymetric data will be interpolated onto the grid specified by you.

.. code-block:: console

    x, y, z = bdb.get_data('gebco19',
                           xlim=[ 420000.0,  460000.0],
                           ylim=[3320000.0, 3420000.0],
                           dx=200.0,
                           dy=200.0,
                           crs='WGS 84 / UTM zone 17N')

.. note::
    If you do NOT prescribe a CRS, please ensure that *xlim* and *ylim* are specified in the native CRS of the requested dataset !

Obtaining a list of available datasets
--------------------------------------

You can show a list of available datasets with:

.. code-block:: console

    for dataset in bdb.dataset:
        print(dataset.name)

Obtaining meta-data for a dataset
---------------------------------

Meta data of a dataset are stored as attributes of the class Dataset. 

.. code-block:: console

    print(bdb.get_metadata('gebco19', variable='crs'))

You can also do this:

.. code-block:: console

    ds = bdb.get_dataset('gebco19')
    print(ds.crs)


Module
-------

Classes
-------

.. autoclass:: cht.bathymetry_database.BathymetryDatabase
    :members: read, get_data, get_crs
.. autoclass:: cht.bathymetry_database.BathymetryDataset
    :members: get_data, read_data_from_netcdf_tiles

Functions
---------