cht_utils 2.0.0__tar.gz

cht_utils-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 maartenvanormondt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cht_utils-2.0.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: cht_utils
+Version: 2.0.0
+Summary: Utility functions for the Coastal Hazards Toolkit
+Author-email: Maarten van Ormondt <maarten.vanormondt@deltares-usa.us>
+License: MIT
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3
+Requires-Dist: contextily
+Requires-Dist: geopandas
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: pandas
+Requires-Dist: paramiko
+Requires-Dist: pillow
+Requires-Dist: pyproj
+Requires-Dist: pyyaml
+Requires-Dist: scipy
+Requires-Dist: shapely
+Requires-Dist: rioxarray
+Requires-Dist: rasterio
+Requires-Dist: xarray
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Dynamic: license-file

cht_utils-2.0.0/cht_utils/__init__.py

@@ -0,0 +1,28 @@
+__version__ = "2.0.0"
+
+"""CHT utilities — common tools for the Deltares Coastal Hazard Toolkit.
+
+Subpackages
+-----------
+fileio
+    File I/O for Deltares formats (INI, Tekal, PLI/POL), YAML, JSON-JS, XML.
+fileops
+    File and directory operations (copy, move, delete, list).
+cog
+    Cloud-Optimized GeoTIFF conversion (from GeoTIFF, NetCDF, XYZ).
+physics
+    Coastal and wave physics (dispersion, shoaling, runup, wave decomposition).
+remote
+    Remote file transfer (AWS S3, SSH/SFTP).
+probabilistic
+    Ensemble post-processing and probability maps.
+maps
+    Floodmap and Topography map visualization.
+
+Top-level modules
+-----------------
+colors
+    Colormap registration, rendering, and conversion.
+interpolation
+    2-D interpolation on regular and unstructured grids.
+"""

cht_utils-2.0.0/cht_utils/cog/__init__.py

@@ -0,0 +1,6 @@
+"""Cloud-Optimized GeoTIFF (COG) conversion utilities."""
+
+from cht_utils.cog.geotiff_to_cog import geotiff_to_cog as geotiff_to_cog
+from cht_utils.cog.geotiff_to_cog import is_cog as is_cog
+from cht_utils.cog.netcdf_to_cog import netcdf_to_cog as netcdf_to_cog
+from cht_utils.cog.xyz_to_cog import xyz_to_cog as xyz_to_cog

cht_utils-2.0.0/cht_utils/cog/geotiff_to_cog.py

@@ -0,0 +1,79 @@
+"""Convert GeoTIFF files to Cloud-Optimized GeoTIFF (COG) format."""
+
+import shutil
+
+import rasterio
+from rasterio.shutil import copy as rio_copy
+
+
+def is_cog(tif_path: str) -> bool:
+    """Check if a GeoTIFF is Cloud-Optimized.
+
+    Verifies that the file is tiled and has overviews.
+
+    Parameters
+    ----------
+    tif_path : str
+        Path to the GeoTIFF file.
+
+    Returns
+    -------
+    bool
+        ``True`` if the file is a COG.
+    """
+    try:
+        with rasterio.open(tif_path) as src:
+            if not src.is_tiled:
+                return False
+            overviews = src.overviews(1)
+            return len(overviews) > 0
+    except Exception as e:
+        print(f"Error checking COG: {e}")
+        return False
+
+
+def geotiff_to_cog(
+    geotiff_path: str,
+    output_cog_path: str,
+    resampling: str = "average",
+) -> bool:
+    """Convert a GeoTIFF to Cloud-Optimized GeoTIFF.
+
+    If the input is already a COG, it is simply copied.
+
+    Parameters
+    ----------
+    geotiff_path : str
+        Path to the input GeoTIFF.
+    output_cog_path : str
+        Path for the output COG.
+    resampling : str
+        Resampling method for overviews (default: ``"average"``).
+
+    Returns
+    -------
+    bool
+        ``True`` on success, ``False`` on error.
+    """
+    try:
+        if is_cog(geotiff_path):
+            print(f"{geotiff_path} is already a COG! Copying to {output_cog_path}")
+            shutil.copy(geotiff_path, output_cog_path)
+            return True
+
+        with rasterio.open(geotiff_path) as src:
+            rio_copy(
+                src,
+                output_cog_path,
+                driver="COG",
+                compress="deflate",
+                blocksize=512,
+                overview_resampling=resampling,
+            )
+
+        print(f"COG saved to: {output_cog_path}")
+        return True
+
+    except Exception as e:
+        print(f"Error during conversion: {e}")
+        return False

cht_utils-2.0.0/cht_utils/cog/netcdf_to_cog.py

@@ -0,0 +1,85 @@
+"""Convert NetCDF variables to Cloud-Optimized GeoTIFF (COG) format."""
+
+from typing import Optional
+
+import xarray as xr
+from pyproj import CRS
+
+
+def netcdf_to_cog(
+    netcdf_path: str,
+    variable_name: str,
+    output_cog_path: str,
+    time_index: Optional[int] = None,
+) -> bool:
+    """Convert a NetCDF variable to a Cloud-Optimized GeoTIFF.
+
+    Assumes EPSG:4326 if no CRS information is found in the dataset.
+
+    Parameters
+    ----------
+    netcdf_path : str
+        Path to the NetCDF file.
+    variable_name : str
+        Name of the variable to extract.
+    output_cog_path : str
+        Output path for the COG.
+    time_index : int or None
+        Optional time dimension index to select.
+
+    Returns
+    -------
+    bool
+        ``True`` on success, ``False`` on error.
+    """
+    try:
+        ds = xr.open_dataset(netcdf_path)
+
+        if variable_name not in ds:
+            raise ValueError(
+                f"Variable '{variable_name}' not found in the NetCDF file."
+            )
+        da = ds[variable_name]
+
+        if "time" in da.dims and time_index is not None:
+            da = da.isel(time=time_index)
+
+        crs = _get_crs(ds)
+        crs_str = f"EPSG:{crs.to_epsg()}"
+
+        if crs.is_projected:
+            da.rio.set_spatial_dims(x_dim="x", y_dim="y", inplace=True)
+        else:
+            da.rio.set_spatial_dims(x_dim="lon", y_dim="lat", inplace=True)
+
+        da.rio.write_crs(crs_str, inplace=True)
+        da.rio.to_raster(
+            output_cog_path,
+            driver="COG",
+            compress="deflate",
+            blocksize=512,
+            overview_resampling="average",
+            dtype=da.dtype,
+        )
+        print(f"COG saved to: {output_cog_path}")
+        return True
+
+    except Exception as e:
+        print(f"Error during conversion: {e}")
+        return False
+
+
+def _get_crs(ds: xr.Dataset) -> CRS:
+    """Extract CRS from a dataset, defaulting to EPSG:4326."""
+    if "crs" not in ds:
+        return CRS.from_epsg(4326)
+
+    for attr_name in ("crs_wkt", "spatial_ref"):
+        wkt = ds["crs"].attrs.get(attr_name)
+        if wkt:
+            crs = CRS.from_wkt(wkt)
+            if crs.to_epsg() is None and "NAD83" in crs.name:
+                return CRS.from_epsg(4269)
+            return crs
+
+    return CRS.from_epsg(4326)

cht_utils-2.0.0/cht_utils/cog/xyz_to_cog.py

@@ -0,0 +1,86 @@
+"""Convert XYZ point-cloud data to Cloud-Optimized GeoTIFF (COG) format."""
+
+import os
+from typing import Union
+
+import numpy as np
+import pandas as pd
+import xarray as xr
+from pyproj import CRS
+from rasterio.enums import Resampling
+from rasterio.transform import from_origin
+
+
+def xyz_to_cog(
+    xyz_path: str,
+    output_cog_path: str,
+    crs: Union[int, CRS] = 4326,
+) -> bool:
+    """Grid scattered XYZ data and write as a COG.
+
+    Parameters
+    ----------
+    xyz_path : str
+        Path to a whitespace-separated XYZ file (columns: x, y, z).
+    output_cog_path : str
+        Output COG file path.
+    crs : int or pyproj.CRS
+        Coordinate reference system (default: EPSG:4326).
+
+    Returns
+    -------
+    bool
+        ``True`` on success, ``False`` on error.
+    """
+    try:
+        df = pd.read_csv(xyz_path, sep=r"\s+", names=["x", "y", "z"])
+
+        x_unique = np.sort(df["x"].unique())
+        y_unique = np.sort(df["y"].unique())
+
+        dx = np.round(np.min(np.diff(x_unique)), 6)
+        dy = np.round(np.min(np.diff(y_unique)), 6)
+
+        z_grid = np.full((len(y_unique), len(x_unique)), np.nan)
+        x_to_idx = {x: i for i, x in enumerate(x_unique)}
+        y_to_idx = {y: i for i, y in enumerate(y_unique)}
+
+        for row in df.itertuples(index=False):
+            z_grid[y_to_idx[row.y], x_to_idx[row.x]] = row.z
+
+        da = xr.DataArray(
+            data=z_grid,
+            dims=["y", "x"],
+            coords={"x": x_unique, "y": y_unique},
+            name="topography",
+        )
+
+        if y_unique[0] > y_unique[-1]:
+            da = da.sortby("y")
+
+        transform = from_origin(x_unique[0] - dx / 2, y_unique[-1] + dy / 2, dx, dy)
+        da.rio.write_transform(transform, inplace=True)
+
+        if isinstance(crs, int):
+            crs_string = f"EPSG:{crs}"
+        elif isinstance(crs, CRS):
+            crs_string = f"EPSG:{crs.to_epsg()}"
+        else:
+            crs_string = str(crs)
+
+        da.rio.write_crs(crs_string, inplace=True)
+        da.rio.to_raster(
+            output_cog_path,
+            driver="COG",
+            compress="deflate",
+            dtype="float32",
+            nodata=np.nan,
+            resampling=Resampling.average,
+        )
+
+        print(f"Saved to: {os.path.abspath(output_cog_path)}")
+        return True
+
+    except Exception as e:
+        print(f"Error: {e}")
+        return False

cht_utils-2.0.0/cht_utils/colors/__init__.py

@@ -0,0 +1,6 @@
+"""Colormap utilities for reading, registering, and rendering colormaps."""
+
+from cht_utils.colors.colors import cm2png as cm2png
+from cht_utils.colors.colors import read_color_maps as read_color_maps
+from cht_utils.colors.colors import read_colormap as read_colormap
+from cht_utils.colors.colors import rgb2hex as rgb2hex

cht_utils-2.0.0/cht_utils/colors/colors.py

@@ -0,0 +1,117 @@
+"""Colormap utilities for reading, registering, and rendering colormaps."""
+
+import os
+from typing import List, Tuple
+
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+
+def read_color_maps(path_name: str) -> List[str]:
+    """Read all colormaps from a folder and register them with matplotlib.
+
+    Each ``.txt`` file in *path_name* is expected to contain whitespace-separated
+    RGB values (one row per colour, values in 0-1 range).
+
+    Parameters
+    ----------
+    path_name : str
+        Directory containing colormap text files.
+
+    Returns
+    -------
+    List[str]
+        Full list of registered matplotlib colormap names.
+    """
+    for file in os.listdir(path_name):
+        if file.endswith(".txt"):
+            name = os.path.splitext(file)[0]
+            rgb = read_colormap(os.path.join(path_name, file))
+            cmap = mpl.colors.ListedColormap(rgb, name=name)
+            mpl.colormaps.register(cmap=cmap)
+    return plt.colormaps()
+
+
+def cm2png(
+    cmap: mpl.colors.Colormap,
+    file_name: str = "colorbar.png",
+    orientation: str = "horizontal",
+    vmin: float = 0.0,
+    vmax: float = 1.0,
+    legend_title: str = "",
+    legend_label: str = "",
+    units: str = "",
+    unit_string: str = "",
+    decimals: int = -1,
+) -> None:
+    """Render a colormap to a PNG image.
+
+    Parameters
+    ----------
+    cmap : matplotlib.colors.Colormap
+        Colormap to render.
+    file_name : str
+        Output PNG path.
+    orientation : str
+        ``"horizontal"`` or ``"vertical"``.
+    vmin, vmax : float
+        Value range for the colour scale.
+    legend_label : str
+        Label shown alongside the colorbar.
+    """
+    if orientation == "horizontal":
+        fig = plt.figure(figsize=(2.5, 1))
+        ax = fig.add_axes([0.05, 0.80, 0.9, 0.15])
+    else:
+        fig = plt.figure(figsize=(1, 2.5))
+        ax = fig.add_axes([0.80, 0.05, 0.15, 0.90])
+
+    norm = mpl.colors.Normalize(vmin=vmin, vmax=vmax)
+    cb = mpl.colorbar.ColorbarBase(
+        ax, cmap=cmap, norm=norm, orientation=orientation, label=legend_label
+    )
+    cb.ax.tick_params(labelsize=6)
+
+    fig.savefig(file_name, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+
+
+def read_colormap(file_name: str) -> np.ndarray:
+    """Read a colormap from a whitespace-separated RGB text file.
+
+    Parameters
+    ----------
+    file_name : str
+        Path to the colormap file.
+
+    Returns
+    -------
+    np.ndarray
+        Array of shape ``(N, 3)`` with RGB values.
+    """
+    df = pd.read_csv(
+        file_name,
+        index_col=False,
+        header=None,
+        sep=r"\s+",
+        names=["r", "g", "b"],
+    )
+    return df.to_numpy()
+
+
+def rgb2hex(rgb: Tuple[int, int, int]) -> str:
+    """Convert an RGB tuple to a hex colour string.
+
+    Parameters
+    ----------
+    rgb : Tuple[int, int, int]
+        Red, green, blue values (0-255).
+
+    Returns
+    -------
+    str
+        Six-character hex string (no leading ``#``).
+    """
+    return "%02x%02x%02x" % rgb

cht_utils-2.0.0/cht_utils/fileio/__init__.py

@@ -0,0 +1,21 @@
+"""File I/O utilities for various Deltares and common data formats."""
+
+from cht_utils.fileio.deltares_ini import IniStruct as IniStruct
+from cht_utils.fileio.deltares_ini import Keyword as Keyword
+from cht_utils.fileio.deltares_ini import Section as Section
+from cht_utils.fileio.json_js import read_json_js as read_json_js
+from cht_utils.fileio.json_js import write_csv_js as write_csv_js
+from cht_utils.fileio.json_js import write_json_js as write_json_js
+from cht_utils.fileio.pli_file import gdf2pli as gdf2pli
+from cht_utils.fileio.pli_file import gdf2pol as gdf2pol
+from cht_utils.fileio.pli_file import pli2gdf as pli2gdf
+from cht_utils.fileio.pli_file import pol2gdf as pol2gdf
+from cht_utils.fileio.pli_file import read_pli_file as read_pli_file
+from cht_utils.fileio.tekal import tekal as tekal
+from cht_utils.fileio.tekal import tekalblock as tekalblock
+from cht_utils.fileio.xml import dict2xml as dict2xml
+from cht_utils.fileio.xml import get_value as get_xml_value  # noqa: F401
+from cht_utils.fileio.xml import obj2xml as obj2xml
+from cht_utils.fileio.xml import xml2obj as xml2obj
+from cht_utils.fileio.yaml import dict2yaml as dict2yaml
+from cht_utils.fileio.yaml import yaml2dict as yaml2dict