transformez 0.5.2__tar.gz → 0.5.3__tar.gz

{transformez-0.5.2 → transformez-0.5.3}/CITATION.cff

@@ -14,6 +14,6 @@ authors:
 
 website: https://transformez.readthedocs.io
 title: "Transformez"
-version: 0.5.0
-date-released: 2026-06-06
+version: 0.5.3
+date-released: 2026-07-22
 url: "https://github.com/continuous-dems/transformez"

{transformez-0.5.2 → transformez-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: transformez
-Version: 0.5.2
+Version: 0.5.3
 Summary: A standalone utility for vertical elevation datum transformations.
 Project-URL: Homepage, https://github.com/continuous-dems/transformez
 Project-URL: Issues, https://github.com/continuous-dems/transformez/issues
@@ -57,7 +57,7 @@ Description-Content-Type: text/markdown
 <p align="center"><strong>Global vertical datum transformations, simplified.</strong></p>
 
 <p align="center">
-  <a href="https://github.com/continuous-dems/transformez"><img src="https://img.shields.io/badge/version-0.5.1-blue.svg" alt="Version"></a>
+  <a href="https://github.com/continuous-dems/transformez"><img src="https://img.shields.io/badge/version-0.5.3-blue.svg" alt="Version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
   <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12+-yellow.svg" alt="Python"></a>
   <a href="https://badge.fury.io/py/transformez"><img src="https://badge.fury.io/py/transformez.svg" alt="PyPI version"></a>
@@ -71,14 +71,6 @@ Originally developed as the core transformation engine for the [CUDEM](https://g
 
 ---
 
-## ❓ Why Transformez?
-
-Vertical Datum transformations can cause a lot of confusion and headache when trying to process heterogeneous data from around the world into a single unified vertial reference.
-
-**Transformez simplifies this process!**
-
----
-
 ## 📦 Installation
 
 **Install Transformez**

{transformez-0.5.2 → transformez-0.5.3}/README.md

@@ -7,7 +7,7 @@
 <p align="center"><strong>Global vertical datum transformations, simplified.</strong></p>
 
 <p align="center">
-  <a href="https://github.com/continuous-dems/transformez"><img src="https://img.shields.io/badge/version-0.5.1-blue.svg" alt="Version"></a>
+  <a href="https://github.com/continuous-dems/transformez"><img src="https://img.shields.io/badge/version-0.5.3-blue.svg" alt="Version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
   <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12+-yellow.svg" alt="Python"></a>
   <a href="https://badge.fury.io/py/transformez"><img src="https://badge.fury.io/py/transformez.svg" alt="PyPI version"></a>
@@ -21,14 +21,6 @@ Originally developed as the core transformation engine for the [CUDEM](https://g
 
 ---
 
-## ❓ Why Transformez?
-
-Vertical Datum transformations can cause a lot of confusion and headache when trying to process heterogeneous data from around the world into a single unified vertial reference.
-
-**Transformez simplifies this process!**
-
----
-
 ## 📦 Installation
 
 **Install Transformez**

{transformez-0.5.2 → transformez-0.5.3}/pyproject.toml

@@ -51,9 +51,9 @@ test = [
     "pytest-cov",
 ]
 docs = [
-    "sphinx",
+    "sphinx<9.0.0",  # temp pin for sphinx-click
     "sphinx-autodoc-typehints>=2.0.1",
-    "sphinx-argparse-cli",
+    "sphinx-click>=6.0",
     "pydata-sphinx-theme",
     "myst-parser",
 ]

{transformez-0.5.2 → transformez-0.5.3}/src/transformez/_version.py

@@ -1,4 +1,4 @@
 # This file is auto-generated by Hatchling. As such, do not:
 #   - modify
 #   - track in version control e.g. be sure to add to .gitignore
-__version__ = VERSION = '0.5.2'
+__version__ = VERSION = '0.5.3'

{transformez-0.5.2 → transformez-0.5.3}/src/transformez/api.py

@@ -359,3 +359,127 @@ def transform_raster(
     if success:
         return output_raster
     return None
+
+
+def prefetch_region(
+    region: Union[List[float], str, Region],
+    datum_in: Optional[str] = None,
+    datum_out: Optional[str] = None,
+    fetch_all: bool = False,
+    cache_dir: Optional[str] = None,
+    verbose: bool = True,
+) -> bool:
+    """Pre-download transformation grids and reference datasets for offline field use.
+
+    Args:
+        region: Bounds as [W, E, S, N], a 'loc:' string, or a Region object.
+        datum_in: Source datum string (e.g. 'mllw') to limit fetching to a specific chain.
+        datum_out: Target datum string (e.g. '5703') to limit fetching to a specific chain.
+        fetch_all: If True, fetches ALL available geoids, tidal surfaces, and coastlines for the region.
+        cache_dir: Directory where downloaded assets will be cached.
+        verbose: Enable detailed logging.
+
+    Returns:
+        bool: True if prefetching succeeded, False otherwise.
+    """
+
+    if isinstance(region, Region):
+        region_obj = region
+    else:
+        regions = parse_region(region)
+        if not regions:
+            logger.error(f"Could not parse region: {region}")
+            return False
+        region_obj = regions[0]
+
+    logger.info(f"Initiating offline prefetch for region: {region_obj}")
+
+    # Minimal dimensions (10x10) to avoid allocating memory for large arrays
+    vt_nx, vt_ny = 10, 10
+
+    try:
+        if fetch_all or (not datum_in and not datum_out):
+            logger.info(
+                "Mode: FULL PREFETCH. Downloading all geoids, VDatum grids, and coastlines..."
+            )
+
+            # Instantiate base engine to leverage internal fetchers
+            vt = VerticalTransform(
+                region=region_obj,
+                nx=vt_nx,
+                ny=vt_ny,
+                epsg_in=4979,  # Base WGS84
+                epsg_out=6319,  # Base NAD83
+                cache_dir=cache_dir,
+                verbose=verbose,
+            )
+
+            # Vector Coastline Tiles (GSHHG / CUSP)
+            logger.info(" -> [1/5] Fetching coastline vector tiles...")
+            vt._fetch_coastline_shapefiles()
+
+            # All Registered Geoids
+            logger.info(" -> [2/5] Fetching Geoid grids...")
+            for g_name, g_def in Datums.GEOIDS.items():
+                provider = g_def.get("provider", "proj")
+                logger.info(f"    - Fetching Geoid: {g_name} ({provider})")
+                try:
+                    vt.fetch_grid(provider, datatype=g_name, query=g_name)
+                except Exception as e:
+                    logger.warning(f"    - Skipping '{g_name}': {e}")
+
+            # USA VDatum Tidal Grids
+            logger.info(" -> [3/5] Fetching VDatum regional grids...")
+            for s_key, s_def in Datums.SURFACES.items():
+                s_name = s_def.get("name", s_key)
+                if s_def.get("region") == "usa":
+                    logger.info(f"    - Fetching VDatum Surface: {s_name}")
+                    try:
+                        vt.fetch_grid("vdatum", datatype=s_name, query=s_name)
+                    except Exception as e:
+                        logger.warning(f"    - Skipping VDatum '{s_name}': {e}")
+
+            # Topography of the Sea Surface (TSS)
+            logger.info(" -> [4/5] Fetching VDatum TSS grid...")
+            try:
+                vt.fetch_grid("vdatum", datatype="tss", query="tss")
+            except Exception as e:
+                logger.warning(f"    - Skipping TSS: {e}")
+
+            # Global Satellite Models (FES / SEANOE)
+            logger.info(" -> [5/5] Fetching Global FES / MSS proxy grids...")
+            for proxy_name in ["lat", "msl", "mss"]:
+                logger.info(f"    - Fetching Global Proxy: {proxy_name}")
+                try:
+                    vt.fetch_grid("fes", datatype=proxy_name, query=proxy_name)
+                except Exception as e:
+                    logger.warning(f"    - Skipping Global '{proxy_name}': {e}")
+
+        else:
+            epsg_in, geoid_in = _parse_datum(datum_in) if datum_in else (4979, None)
+            epsg_out, geoid_out = _parse_datum(datum_out) if datum_out else (6319, None)
+
+            logger.info(
+                f"Mode: TARGETED PREFETCH for chain ({datum_in or 'WGS84'} ➔ {datum_out or 'NAD83'})..."
+            )
+
+            vt = VerticalTransform(
+                region=region_obj,
+                nx=vt_nx,
+                ny=vt_ny,
+                epsg_in=epsg_in or 4979,
+                epsg_out=epsg_out or 6319,
+                geoid_in=geoid_in,
+                geoid_out=geoid_out,
+                cache_dir=cache_dir,
+                verbose=verbose,
+            )
+
+            vt._vertical_transform(vt.epsg_in, vt.epsg_out)
+
+        logger.info("Successfully populated offline cache!")
+        return True
+
+    except Exception as e:
+        logger.error(f"Prefetch failed: {e}")
+        return False

{transformez-0.5.2 → transformez-0.5.3}/src/transformez/cli.py

@@ -20,8 +20,8 @@ from fetchez.cli import setup_logging
 from transformez import api
 
 TRANSFORMEZ_COMMANDS = {
-    "Execution": ["run", "grid", "raster"],
-    "Discovery": ["list"],
+    "Execution": ["grid", "raster"],
+    "Discovery": ["list", "prefetch"],
     "External": ["htdp", "vdatum"],
 }
 
@@ -401,7 +401,9 @@ def transform_list():
 
 
 # --- HTDP CLI GROUP ---
-@transformez_cli.group(cls=FetchezMainGroup, name="htdp", fetchez_commands=["install"])
+@transformez_cli.group(
+    cls=FetchezMainGroup, name="htdp", fetchez_commands=["install", "run"]
+)
 def htdp_group():
     """Manage and run NGS HTDP (Horizontal Time-Dependent Positioning)."""
 
@@ -422,9 +424,19 @@ def install_htdp(version):
     install_htdp_binary(version=version)
 
 
+@htdp_group.command("run", cls=FetchezMainCommand)
+@click.option("--control", help="input control file, if omitted, run interactively")
+def run_htpd(control):
+    """Run HTDP from transformez"""
+
+    from transformez.htdp import HTDP
+
+    HTDP.run_cmd(control)
+
+
 # --- VDATUM CLI GROUP ---
 @transformez_cli.group(
-    cls=FetchezMainGroup, name="vdatum", fetchez_commands=["install", "run"]
+    cls=FetchezMainGroup, name="vdatum", fetchez_commands=["install"]
 )
 def vdatum_group():
     """Manage and run the NOAA VDatum Java engine."""
@@ -480,5 +492,56 @@ def vdatum_list():
     click.echo(vd)
 
 
+# --- PREFETCH CLI GROUP ---
+@transformez_cli.command("prefetch", cls=FetchezMainCommand)
+@click.option("-R", "--region", required=True, help="Bounding box or location string.")
+@click.option(
+    "-I",
+    "--input-datum",
+    help="Source Datum (Optional: limits fetch to specific chain).",
+)
+@click.option(
+    "-O",
+    "--output-datum",
+    help="Target Datum (Optional: limits fetch to specific chain).",
+)
+@click.option(
+    "--all",
+    "fetch_all",
+    is_flag=True,
+    help="Fetch ALL available geoids, tidal models, and coastlines for this region.",
+)
+def transform_prefetch(region, input_datum, output_datum, fetch_all):
+    """Pre-download transformation grids and reference data for offline field use.
+
+    Examples:\n
+      Prefetch a specific conversion : transformez prefetch -R loc:"Newport, OR" -I mllw -O 5703
+      Prefetch EVERYTHING for a region: transformez prefetch -R loc:"Miami, FL" --all
+      Prefetch the entire planet      : transformez prefetch -R -180/180/-90/90 --all
+    """
+
+    click.secho(
+        f"Populating offline cache for region: {region}...", fg="cyan", bold=True
+    )
+
+    result = api.prefetch_region(
+        region=region,
+        datum_in=input_datum,
+        datum_out=output_datum,
+        fetch_all=fetch_all,
+        verbose=True,
+    )
+
+    if result:
+        click.secho(
+            f"Successfully pre-cached all assets for {region}. Ready for offline use!",
+            fg="green",
+            bold=True,
+        )
+    else:
+        click.secho("Prefetch encountered errors. Check logs for details.", fg="red")
+        sys.exit(1)
+
+
 if __name__ == "__main__":
     transformez_cli()

{transformez-0.5.2 → transformez-0.5.3}/src/transformez/definitions.py

@@ -12,6 +12,7 @@ and definitions.
 :license: MIT, see LICENSE for more details.
 """
 
+from typing import Any, Dict
 import logging
 
 logger = logging.getLogger(__name__)
@@ -42,7 +43,7 @@ class Datums:
     # =========================================================================
     # Vertical Datum References
     # =========================================================================
-    SURFACES = {
+    SURFACES: Dict[int, Dict[str, Any]] = {
         # --- Tidal Datums ---
         1089: {"name": "mllw", "description": "Mean Lower Low Water", "region": "usa"},
         5866: {"name": "mllw", "description": "Mean Lower Low Water", "region": "usa"},
@@ -104,7 +105,7 @@ class Datums:
         9003: {"name": "mss", "description": "Mean Sea Surface", "region": "global"},
     }
 
-    GLOBAL_ALIASES = {
+    GLOBAL_ALIASES: Dict[str, Any] = {
         "mllw": "lat",  # Mean Lower Low Water -> Lowest Astronomical Tide
         "mlw": "lat",  # Mean Low Water       -> LAT (Conservative)
         "mhhw": "hat",  # Mean Higher High Water -> Highest Astronomical Tide
@@ -114,7 +115,7 @@ class Datums:
         "dtl": "mss",  # Diurnal Tide Level     -> MSS
     }
 
-    HTDP = {
+    HTDP: Dict[int, Dict[str, Any]] = {
         4269: {
             "name": "NAD_83(2011/CORS96/2007)",
             "description": "(North American plate fixed)",
@@ -362,7 +363,7 @@ class Datums:
         },
     }
 
-    CDN = {
+    CDN: Dict[int, Dict[str, Any]] = {
         # CONUS / Alaska / Hawaii / PR / VI
         5703: {
             "name": "NAVD88 height",
@@ -415,7 +416,7 @@ class Datums:
         # 4979: {'name': 'WGS84', 'vdatum_id': 'wgs84:m:height'},
     }
 
-    GEOIDS = {
+    GEOIDS: Dict[str, Dict[str, Any]] = {
         # Standard PROJ-CDN Geoids (Default provider is 'proj')
         "g2018": {"name": "geoid 2018", "uncertainty": 0.0127, "provider": "proj"},
         "g2012b": {"name": "geoid 2012b", "uncertainty": 0.017, "provider": "proj"},
@@ -428,7 +429,7 @@ class Datums:
         "CGG2013": {"name": "CGG2013", "uncertainty": 0.01, "provider": "proj"},
     }
 
-    MODELS = {
+    MODELS: Dict[str, Dict[str, Any]] = {
         "fes2014": {"provider": "seanoe", "grids": {"lat": "LAT", "mss": "MSL"}},
         "dtu10": {"provider": "dtu", "grids": {"mss": "mss", "mdt": "mdt"}},
         "egm2008": {"provider": "proj", "grid": "egm2008"},

{transformez-0.5.2 → transformez-0.5.3}/src/transformez/grid_engine.py

@@ -454,6 +454,52 @@ class GridWriter:
         return filename
 
 
+def calculate_psmsl_msl(csv_path: str) -> float:
+    """Reads a PSMSL time-series CSV generated by fetchez, filters out
+    missing data flags (-99999), and calculates the all-time Mean Sea Level.
+
+    Returns the MSL value in METERS.
+    """
+
+    import csv
+
+    valid_measurements = []
+
+    try:
+        with open(csv_path, "r", encoding="utf-8") as f:
+            reader = csv.reader(f, delimiter=";")
+            for row in reader:
+                if len(row) < 4:
+                    continue
+
+                try:
+                    # Column 1 is the MSL value in millimeters
+                    msl_mm = float(row[1].strip())
+
+                    # -99999 is the PSMSL nodata flag
+                    if msl_mm != -99999.0:
+                        valid_measurements.append(msl_mm)
+                except ValueError:
+                    continue
+
+        if not valid_measurements:
+            logger.warning(f"No valid data found in {csv_path}")
+            return np.nan
+
+        # Calculate the mean in mm, then convert to meters
+        mean_mm = sum(valid_measurements) / len(valid_measurements)
+        mean_meters = mean_mm / 1000.0
+
+        logger.info(
+            f"Processed {len(valid_measurements)} months of data. MSL: {mean_meters:.3f} m"
+        )
+        return mean_meters
+
+    except Exception as e:
+        logger.error(f"Failed to process PSMSL file {csv_path}: {e}")
+        return np.nan
+
+
 class GridGen:
     @staticmethod
     def from_stations(
@@ -463,7 +509,7 @@ class GridGen:
         If a station lacks the target datum, it falls back to MSL and uses the
         baseline_grid (FES) to bridge the gap to the geodetic frame.
         """
-        import os
+
         import json
         from fetchez.modules.tides import Tides
         import fetchez

{transformez-0.5.2 → transformez-0.5.3}/src/transformez/htdp.py

@@ -23,19 +23,41 @@ import zipfile
 import numpy as np
 from typing import Tuple
 
-from . import utils
+# from . import utils
 from .definitions import Datums  # Required for ID lookups
 
 logger = logging.getLogger(__name__)
 
-ae = ".exe" if sys.platform == "win32" else ""
-# Validating HTDP existence
-htdp_cmd = (
-    "echo 0 | htdp 2>&1"
-    if sys.platform == "win32"
-    else "echo 0 | htdp 2>&1 | grep SOFTWARE | awk '{print $3}'"
-)
-HAS_HTDP = utils.cmd_check(f"htdp{ae}", htdp_cmd)
+# ae = ".exe" if sys.platform == "win32" else ""
+# # Validating HTDP existence
+# htdp_cmd = (
+#     "echo 0 | htdp 2>&1"
+#     if sys.platform == "win32"
+#     else "echo 0 | htdp 2>&1 | grep SOFTWARE | awk '{print $3}'"
+# )
+# HAS_HTDP = utils.cmd_check(f"htdp{ae}", htdp_cmd)
+
+
+def resolve_htdp_path(version="3.5.0"):
+    """Finds the HTDP executable, prioritizing the local cache over system PATH."""
+
+    clean_version = version.replace("v", "")
+    ae = ".exe" if sys.platform == "win32" else ""
+
+    # Check local transformez_cache/bin/
+    cache_bin = os.path.join(
+        os.getcwd(), "transformez_cache", "bin", f"htdp_{clean_version}{ae}"
+    )
+    if os.path.exists(cache_bin):
+        return cache_bin
+
+    # Check system PATH
+    import shutil
+
+    if shutil.which(f"htdp{ae}"):
+        return f"htdp{ae}"
+
+    return None
 
 
 class HTDP:
@@ -47,7 +69,11 @@ class HTDP:
         self.htdp_bin = htdp_bin
         self.version = version
         self.verbose = verbose
-        if not HAS_HTDP:
+
+        self.htdp_bin = htdp_bin or resolve_htdp_path(self.version)
+        self.has_htdp = self.htdp_bin is not None
+
+        if not self.has_htdp:
             logger.error(
                 f"HTDP {self.version} is not installed or not in PATH. Run 'transformez htdp install --version {self.version}"
             )
@@ -57,7 +83,7 @@ class HTDP:
         Generates a shift grid between two frames.
         """
 
-        if not HAS_HTDP:
+        if not self.has_htdp:
             logger.warning("HTDP missing. Returning zero shift.")
             return np.zeros((ny, nx))
 
@@ -190,6 +216,7 @@ class HTDP:
 
     def run_cmd(self, control_fn):
         """Executes the binary."""
+
         try:
             with open(control_fn, "r") as stdin:
                 subprocess.run(
@@ -268,29 +295,26 @@ def install_htdp_binary(version="3.5.0"):
     v_tag = f"v{version}" if not version.startswith("v") else version
     clean_version = v_tag.replace("v", "")
 
-    if sys.platform == "win32":
-        logger.info(f"Downloading Windows HTDP executable ({v_tag})...")
-        url = f"https://github.com/noaa-ngs/HTDP/releases/download/{v_tag}/htdp.exe"
-        exe_path = os.path.join(cache_dir, f"htdp_{clean_version}.exe")
-
-        try:
-            urllib.request.urlretrieve(url, exe_path)
-            logger.info(f"HTDP {clean_version} installed successfully to: {exe_path}")
-        except Exception as e:
-            logger.error(f"Failed to download {v_tag} from GitHub: {e}")
-
-    else:
-        logger.info(f"Downloading Unix HTDP source code ({v_tag})...")
-        url = f"https://github.com/noaa-ngs/HTDP/archive/refs/tags/{v_tag}.zip"
-        zip_path = os.path.join(cache_dir, f"htdp_{clean_version}.zip")
+    logger.info(f"Downloading HTDP reposity ({v_tag})...")
+    url = f"https://github.com/noaa-ngs/HTDP/archive/refs/tags/{v_tag}.zip"
+    zip_path = os.path.join(cache_dir, f"htdp_{clean_version}.zip")
 
-        try:
-            urllib.request.urlretrieve(url, zip_path)
+    try:
+        urllib.request.urlretrieve(url, zip_path)
 
+        if sys.platform == "win32":
+            with zipfile.ZipFile(zip_path, "r") as z:
+                exe_name = next(name for name in z.namelist() if name.endswith(".exe"))
+                extracted_path = z.extract(exe_name, cache_dir)
+                exe_path = os.path.join(cache_dir, f"htdp_{clean_version}.exe")
+
+                if os.path.exists(exe_path):
+                    os.remove(exe_path)
+                shutil.move(extracted_path, exe_path)
+        else:
             extract_dir = os.path.join(cache_dir, f"htdp_src_{clean_version}")
             with zipfile.ZipFile(zip_path, "r") as z:
                 z.extractall(extract_dir)
-            os.remove(zip_path)
 
             # GitHub extracts to a folder named Repository-Tag (e.g., HTDP-3.5.0)
             source_folder = os.path.join(extract_dir, f"HTDP-{clean_version}")
@@ -308,8 +332,10 @@ def install_htdp_binary(version="3.5.0"):
             # Clean up the raw source files
             shutil.rmtree(extract_dir)
 
-        except Exception as e:
-            logger.error(f"Failed to install HTDP {clean_version}: {e}")
+        os.remove(zip_path)
+
+    except Exception as e:
+        logger.error(f"Failed to install HTDP {clean_version}: {e}")
 
 
 def _install_htdp_binary():

{transformez-0.5.2 → transformez-0.5.3}/src/transformez/srs.py

@@ -17,7 +17,7 @@ import logging
 from pyproj import CRS, Transformer
 
 import numpy as np
-from rasterio.warp import transform_bounds, reproject, Resampling
+from rasterio.warp import reproject, Resampling
 from rasterio.transform import from_bounds
 
 from fetchez.spatial import Region
@@ -184,19 +184,15 @@ class SRSParser:
 
             # Determine Native WGS84 Region for Transformez
             src_is_projected = self.tc["src_crs"].is_projected
+            if not proc_region.srs:
+                proc_region.srs = (self.tc["src_crs"],)
+
             if src_is_projected:
                 # Transform the native bounding box to WGS84 to query the shift models
-                w, s, e, n = transform_bounds(
-                    self.tc["src_crs"],
-                    "EPSG:4326",
-                    proc_region.xmin,
-                    proc_region.ymin,
-                    proc_region.xmax,
-                    proc_region.ymax,
-                )
-                vt_region = Region(w, e, s, n)
+                vt_region = proc_region.copy()
+                vt_region.warp("EPSG:4326")
             else:
-                vt_region = proc_region
+                vt_region = proc_region.copy()
 
             # Generate grid resolution based on WGS84 bounds (approx 3 arc-seconds)
             inc_deg = 3.0 / 3600.0

{transformez-0.5.2 → transformez-0.5.3}/src/transformez/transform.py

@@ -29,6 +29,12 @@ WGS84_EPSG = 4979
 NAD83_EPSG = 6319
 
 
+class MissingGridError(Exception):
+    """Raised when a required shift grid cannot be fetched, is missing, or is persistently corrupted."""
+
+    pass
+
+
 class VerticalTransform:
     """Generate a vertical transformation grid using Transformez."""
 
@@ -107,7 +113,7 @@ class VerticalTransform:
 
         files = fetchez.get(
             module=module_name,
-            region=self.region.to_list(),
+            region=self.region,
             outdir=self.cache_dir,
             threads=2,
             check_size=True,
@@ -212,7 +218,8 @@ class VerticalTransform:
         from .grid_engine import GridCorruptionError
 
         if not name:
-            return np.zeros((self.ny, self.nx))
+            # return np.zeros((self.ny, self.nx))
+            raise MissingGridError("A valid grid name must be provided to the fetcher.")
 
         if not provider:
             provider = "proj"
@@ -298,7 +305,30 @@ class VerticalTransform:
                 files.sort(key=sort_key, reverse=True)
 
             if not files:
-                return np.zeros((self.ny, self.nx))
+                # return np.zeros((self.ny, self.nx))
+                if attempt < max_retries - 1:
+                    logger.warning(
+                        f"Grid '{name}' not found. Wiping cache for '{provider}' and retrying (Attempt {attempt + 2}/{max_retries})..."
+                    )
+
+                    if os.path.exists(self.cache_dir):
+                        for f in os.listdir(self.cache_dir):
+                            if (
+                                name.lower() in f.lower()
+                                or provider.lower() in f.lower()
+                            ):
+                                try:
+                                    os.remove(os.path.join(self.cache_dir, f))
+                                except OSError:
+                                    pass
+                    continue
+                else:
+                    logger.error(
+                        f"FATAL: Max retries exhausted. Could not locate grid '{name}' from '{provider}'."
+                    )
+                    raise MissingGridError(
+                        f"Required shift grid '{name}' is missing or unavailable."
+                    )
 
             try:
                 if provider == "seanoe" or provider == "fes":
@@ -327,11 +357,15 @@ class VerticalTransform:
                     logger.error(
                         "Max retries reached. Could not secure an uncorrupted grid."
                     )
-                    return np.zeros((self.ny, self.nx))
+                    # return np.zeros((self.ny, self.nx))
+                    raise MissingGridError(f"Grid '{name}' is persistently corrupted.")
 
-        return np.zeros((self.ny, self.nx))
+        # return np.zeros((self.ny, self.nx))
+        raise MissingGridError(
+            f"Failed to fetch grid '{name}' due to an unknown error."
+        )
 
-    def _get_htdp_shift(self, epsg_from, epsg_to, epoch_from, epoch_to):
+    def _get_htdp_shift(self, epsg_from, epsg_to, epoch_from, epoch_to, context=""):
         """Calculate Frame Shift via HTDP with Fallback."""
 
         if epsg_from == epsg_to and epoch_from == epoch_to:
@@ -340,7 +374,10 @@ class VerticalTransform:
         from . import htdp
 
         try:
-            logger.info(f"    [HTDP] Frame Shift: EPSG:{epsg_from} -> EPSG:{epsg_to}")
+            ctx_str = f" {context}" if context else ""
+            logger.info(
+                f"    [HTDP] Frame Shift: EPSG:{epsg_from} -> EPSG:{epsg_to}{ctx_str}"
+            )
             tool = htdp.HTDP(version="3.5.0", verbose=False)
 
             # Attempt 1: Full Cross-Epoch Shift (Datum Shift + Crustal Velocity)
@@ -548,7 +585,11 @@ class VerticalTransform:
 
                     if global_shift is not None and np.any(global_shift):
                         htdp_wgs_to_nad = self._get_htdp_shift(
-                            WGS84_EPSG, NAD83_EPSG, self.epoch_in, 2010.0
+                            WGS84_EPSG,
+                            NAD83_EPSG,
+                            self.epoch_in,
+                            2010.0,
+                            context="(Aligning Global Proxy to NAD83)",
                         )
                         fes_nad83 = global_shift + htdp_wgs_to_nad
                         fes_navd88 = fes_nad83 - geoid_grid
@@ -748,7 +789,11 @@ class VerticalTransform:
         if chain_shift is not None:
             if native_epsg != self.hub_epsg:
                 htdp_shift = self._get_htdp_shift(
-                    native_epsg, self.hub_epsg, epoch, self.epoch_out
+                    native_epsg,
+                    self.hub_epsg,
+                    epoch,
+                    self.epoch_out,
+                    context="(Stepping to Central Hub)",
                 )
                 chain_shift += htdp_shift
                 chain_desc += f" + Frame({native_epsg}->{self.hub_epsg})"
@@ -769,7 +814,11 @@ class VerticalTransform:
 
         if self.hub_epsg != native_epsg:
             htdp_shift = self._get_htdp_shift(
-                self.hub_epsg, native_epsg, self.epoch_in, epoch
+                self.hub_epsg,
+                native_epsg,
+                self.epoch_in,
+                epoch,
+                context="(Extracting from Central Hub)",
             )
             total_out += htdp_shift
             desc_parts.append(f"Hub({self.hub_epsg}->{native_epsg})")