transformez 0.2.2__tar.gz → 0.3.0__tar.gz

transformez-0.3.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: transformez
+Version: 0.3.0
+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
+Author-email: Matthew Love <matthew.love@colorado.edu>, Christopher Amante <christopher.amante@colorado.edu>, Elliot Lim <elliot.lim@colorado.edu>, Michael MacFerrin <michael.macferrin@colorado.edu>, Matt Fisher <mfisher87@gmail.com>
+Maintainer-email: Matthew Love <matthew.love@colorado.edu>
+License: MIT License
+        
+        Copyright (c) 2010-2026 Regents of the University of Colorado
+        
+        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.
+License-File: AUTHORS.md
+License-File: LICENSE
+Keywords: Geospatial
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.12
+Requires-Dist: fetchez>=0.5.0
+Requires-Dist: numpy>1.24
+Requires-Dist: pyproj>3.6.1
+Requires-Dist: rasterio>1.4.0
+Requires-Dist: scipy
+Provides-Extra: full
+Requires-Dist: matplotlib; extra == 'full'
+Provides-Extra: preview
+Requires-Dist: matplotlib; extra == 'preview'
+Description-Content-Type: text/markdown
+
+<!-- <p align="center"> -->
+<!-- 	<a href="https://github.com/continuous-dems"> -->
+<!-- 		<img src="https://github.com/continuous-dems/fetchez/blob/modules/docs/source/_static/continuous_dems_logo.svg" height="80" alt="Continuous DEMs Logo"> -->
+<!-- 	</a> -->
+<!-- </p> -->
+<h1 align="center">Transformez</h1>
+<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.3.0-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>
+  <a href="https://cudem.zulip.org"><img src="https://img.shields.io/badge/zulip-join_chat-brightgreen.svg" alt="Project Chat"></a>
+</p>
+
+**Transformez** is a standalone Python engine for converting geospatial data between vertical datums (e.g., `MLLW` ↔ `NAVD88` ↔ `Ellipsoid`).
+
+---
+
+![Shift Grid Example](docs/images/mllw2nvd.png)
+*(Above: A generated vertical shift grid transforming MLLW to NAVD88)*
+
+## Installation
+
+### Prerequisites: HTDP
+Transformez relies on the NGS Horizontal Time-Dependent Positioning (HTDP) software to perform highly accurate plate tectonic and frame transformations. **You must install this separately.**
+
+**For Windows:**
+1. Download the pre-compiled executable (`htdp.exe`) directly from the [NOAA HTDP page](https://geodesy.noaa.gov/TOOLS/Htdp/Htdp.shtml).
+2. Place `htdp.exe` in a directory that is in your system's `PATH` (e.g., `C:\Windows\System32` or a custom scripts folder).
+
+**For Linux / macOS:**
+
+You will need a Fortran compiler (like `gfortran`) to compile the source code.
+
+```bash
+# 1. Download the Fortran source code
+wget https://geodesy.noaa.gov/TOOLS/Htdp/HTDP-download.zip
+unzip HTDP-download.zip
+
+# 2. Compile it
+gfortran -o htdp htdp.f
+
+# 3. Move it to your PATH
+sudo mv htdp /usr/local/bin/
+```
+
+### Install Transformez
+Once HTDP is accessible in your terminal, install the python package:
+
+```bash
+pip install transformez
+```
+
+## Usage
+
+**Generate a vertical shift grid for anywhere on Earth.**
+
+```bash
+# Transform MLLW to WGS84 Ellipsoid in Norton Sound, AK
+# (Where NOAA has no coverage!)
+transformez -R -166/-164/63/64 -E 3s \
+    --input-datum mllw \
+    --output-datum 4979 \
+    --output shift_ak.tif
+```
+
+**Transform a raster directly.** Transformez reads the bounds/resolution from the file.
+
+```bash
+transformez --dem input_bathymetry.tif \
+    --input-datum "mllw" \
+    --output-datum "5703:geoid=geoid12b" \
+    --output output_navd88.tif
+```
+
+**Integrate directly into your download pipeline.**
+
+```bash
+# Download GEBCO and shift EGM96 to WGS84 on the fly
+fetchez gebco ... --hook transformez:datum_in=5773,datum_out=4979
+```
+
+## Python API
+
+Transformez provides a high-level API for embedding transformations directly into your Python scripts, Jupyter Notebooks, or automated pipelines.
+
+```python
+import transformez
+
+# ---------------------------------------------------------
+# Generate a Shift Grid
+# ---------------------------------------------------------
+# Returns a 2D numpy array. Optionally saves to a file.
+# Requesting "mllw" in India triggers the Global Fallback (FES2014) automatically.
+
+shift_array = transformez.generate_grid(
+    region=[80, 85, 10, 15],  # [West, East, South, North]
+    increment="3s",           # Grid resolution
+    datum_in="mllw",
+    datum_out="4979",         # WGS84 Ellipsoid
+    out_fn="india_shift.tif"  # Optional: Save to disk
+)
+
+# ---------------------------------------------------------
+# Transform an Existing Raster
+# ---------------------------------------------------------
+# Applies the datum shift directly to a DEM and saves the result.
+
+out_file = transformez.transform_raster(
+    input_raster="my_dem_mllw.tif",
+    datum_in="mllw",
+    datum_out="5703:g2012b",  # NAVD88 using specific GEOID12B
+    output_raster="my_dem_navd88.tif"
+)
+```
+
+## Supported Datums
+
+* **Tidal**: mllw, mhhw, msl, lat
+
+* **Ellipsoidal**: 4979 (WGS84), 6319 (NAD83 2011)
+
+* **Orthometric**: 5703 (NAVD88), egm2008, egm96
+
+* **Geoids**: g2018, g2012b, geoid09, xgeoid20b
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/ciresdem/transformez/blob/main/LICENSE) file for details.
+Copyright (c) 2010-2026 Regents of the University of Colorado

transformez-0.3.0/README.md

@@ -0,0 +1,132 @@
+<!-- <p align="center"> -->
+<!-- 	<a href="https://github.com/continuous-dems"> -->
+<!-- 		<img src="https://github.com/continuous-dems/fetchez/blob/modules/docs/source/_static/continuous_dems_logo.svg" height="80" alt="Continuous DEMs Logo"> -->
+<!-- 	</a> -->
+<!-- </p> -->
+<h1 align="center">Transformez</h1>
+<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.3.0-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>
+  <a href="https://cudem.zulip.org"><img src="https://img.shields.io/badge/zulip-join_chat-brightgreen.svg" alt="Project Chat"></a>
+</p>
+
+**Transformez** is a standalone Python engine for converting geospatial data between vertical datums (e.g., `MLLW` ↔ `NAVD88` ↔ `Ellipsoid`).
+
+---
+
+![Shift Grid Example](docs/images/mllw2nvd.png)
+*(Above: A generated vertical shift grid transforming MLLW to NAVD88)*
+
+## Installation
+
+### Prerequisites: HTDP
+Transformez relies on the NGS Horizontal Time-Dependent Positioning (HTDP) software to perform highly accurate plate tectonic and frame transformations. **You must install this separately.**
+
+**For Windows:**
+1. Download the pre-compiled executable (`htdp.exe`) directly from the [NOAA HTDP page](https://geodesy.noaa.gov/TOOLS/Htdp/Htdp.shtml).
+2. Place `htdp.exe` in a directory that is in your system's `PATH` (e.g., `C:\Windows\System32` or a custom scripts folder).
+
+**For Linux / macOS:**
+
+You will need a Fortran compiler (like `gfortran`) to compile the source code.
+
+```bash
+# 1. Download the Fortran source code
+wget https://geodesy.noaa.gov/TOOLS/Htdp/HTDP-download.zip
+unzip HTDP-download.zip
+
+# 2. Compile it
+gfortran -o htdp htdp.f
+
+# 3. Move it to your PATH
+sudo mv htdp /usr/local/bin/
+```
+
+### Install Transformez
+Once HTDP is accessible in your terminal, install the python package:
+
+```bash
+pip install transformez
+```
+
+## Usage
+
+**Generate a vertical shift grid for anywhere on Earth.**
+
+```bash
+# Transform MLLW to WGS84 Ellipsoid in Norton Sound, AK
+# (Where NOAA has no coverage!)
+transformez -R -166/-164/63/64 -E 3s \
+    --input-datum mllw \
+    --output-datum 4979 \
+    --output shift_ak.tif
+```
+
+**Transform a raster directly.** Transformez reads the bounds/resolution from the file.
+
+```bash
+transformez --dem input_bathymetry.tif \
+    --input-datum "mllw" \
+    --output-datum "5703:geoid=geoid12b" \
+    --output output_navd88.tif
+```
+
+**Integrate directly into your download pipeline.**
+
+```bash
+# Download GEBCO and shift EGM96 to WGS84 on the fly
+fetchez gebco ... --hook transformez:datum_in=5773,datum_out=4979
+```
+
+## Python API
+
+Transformez provides a high-level API for embedding transformations directly into your Python scripts, Jupyter Notebooks, or automated pipelines.
+
+```python
+import transformez
+
+# ---------------------------------------------------------
+# Generate a Shift Grid
+# ---------------------------------------------------------
+# Returns a 2D numpy array. Optionally saves to a file.
+# Requesting "mllw" in India triggers the Global Fallback (FES2014) automatically.
+
+shift_array = transformez.generate_grid(
+    region=[80, 85, 10, 15],  # [West, East, South, North]
+    increment="3s",           # Grid resolution
+    datum_in="mllw",
+    datum_out="4979",         # WGS84 Ellipsoid
+    out_fn="india_shift.tif"  # Optional: Save to disk
+)
+
+# ---------------------------------------------------------
+# Transform an Existing Raster
+# ---------------------------------------------------------
+# Applies the datum shift directly to a DEM and saves the result.
+
+out_file = transformez.transform_raster(
+    input_raster="my_dem_mllw.tif",
+    datum_in="mllw",
+    datum_out="5703:g2012b",  # NAVD88 using specific GEOID12B
+    output_raster="my_dem_navd88.tif"
+)
+```
+
+## Supported Datums
+
+* **Tidal**: mllw, mhhw, msl, lat
+
+* **Ellipsoidal**: 4979 (WGS84), 6319 (NAD83 2011)
+
+* **Orthometric**: 5703 (NAVD88), egm2008, egm96
+
+* **Geoids**: g2018, g2012b, geoid09, xgeoid20b
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/ciresdem/transformez/blob/main/LICENSE) file for details.
+Copyright (c) 2010-2026 Regents of the University of Colorado

{transformez-0.2.2 → transformez-0.3.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 name = 'transformez'
 description = 'A standalone utility for vertical elevation datum transformations.'
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.12"
 license = { file = "LICENSE" }
 dynamic = ["version"]
 authors = [
@@ -14,6 +14,7 @@ authors = [
     {name = "Christopher Amante", email = "christopher.amante@colorado.edu"},
     {name = "Elliot Lim", email = "elliot.lim@colorado.edu"},
     {name = "Michael MacFerrin", email = "michael.macferrin@colorado.edu"},
+    {name = "Matt Fisher", email = "mfisher87@gmail.com"},
 ]
 maintainers = [
     {name = "Matthew Love", email = "matthew.love@colorado.edu"},
@@ -24,22 +25,30 @@ classifiers = [
     'Topic :: Scientific/Engineering :: GIS',
 ]
 dependencies = [
-    'numpy<2.0.0',
-    'pyproj',
-    'rasterio',
-    'fetchez>0.3.3',
+    'numpy>1.24',
+    'pyproj>3.6.1',
+    'rasterio>1.4.0',
+    'fetchez>=0.5.0',
     'scipy',
 ]
 
 keywords = ["Geospatial"]
 
+[project.optional-dependencies]
+preview = ["matplotlib"]
+
+full = ["transformez[preview]"]
+
 [dependency-groups]
+dev = [
+    "mypy",
+]
 test = [
     "pytest",
     "pytest-cov",
 ]
 
-[project.entry-points."fetchez.plugins"]
+[project.entry-points."fetchez.modules"]
 transformez = "transformez"
 
 [project.scripts]
@@ -73,3 +82,22 @@ exclude = [
   ".github",
 ]
 
+# --- Devtools configuration ---
+
+[tool.mypy]
+mypy_path = "src"
+packages = ["transformez"]
+python_version = "3.12"
+disable_error_code = ["import-untyped"]
+# strict = true
+
+[[tool.mypy.overrides]]
+module = [
+    "matplotlib.*",
+    "rasterio.*",
+    "scipy.*",
+    "pyproj.*",
+    "fetchez.*",
+]
+ignore_missing_imports = true
+follow_untyped_imports = true

{transformez-0.2.2 → transformez-0.3.0}/src/transformez/__init__.py

@@ -5,19 +5,15 @@
 transformez
 ~~~~~~~~~~~~~
 
+Initialize the API and fetchez extension.
+
 :copyright: (c) 2010-2026 Regents of the University of Colorado
 :license: MIT, see LICENSE for more details.
 """
 
-__author__ = "Matthew Love"
-__credits__ = "CIRES"
-
 try:
     from transformez._version import __version__
 except ImportError:
-    # Fallback when using the package from source without installing
-    # in editable mode with pip (nobody should do this):
-    # <https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs>
     import warnings
 
     warnings.warn(
@@ -29,12 +25,12 @@ except ImportError:
     __version__ = "dev"
 
 
+from .api import generate_grid, transform_raster
+
 import os
 import glob
-# from .hooks import TransformezHook
-# from fetchez.hooks.registry import HookRegistry
-from fetchez.registry import FetchezRegistry
 
+# Expose the module for fetchez
 from .modules import TransformezMod
 
 def _find_proj_lib():
@@ -73,29 +69,4 @@ if "PROJ_LIB" in os.environ:
 if target_proj_lib:
     os.environ["PROJ_LIB"] = target_proj_lib
 
-def setup_fetchez(registry_cls):
-    """Called by fetchez when loading plugins.
-
-    Registers modules, hooks, and presets.
-    """
-
-    registry_cls.register_module(
-        'transformez',
-        TransformezMod,
-        metadata={
-            'desc': 'Generate vertical datum shift grids on-demand.',
-            "tags": ["vdatum", "transformation", "shift-grid"],
-            "category": "Tools"
-        }
-    )
-
-    # HookRegistry.register_hook(TransformezHook)
-    # from fetchez.presets import register_global_preset
-    # register_global_preset(
-    #     name="make-shift-grid",
-    #     help_text="Download datum grids and composite them into a single shift grid.",
-    #     hooks=[
-    #         {"name": "transformez", "args": {}}
-    #     ]
-    # )
-setup_fetchez(FetchezRegistry)
+__all__ = ["generate_grid", "transform_raster", "TransformezMod"]

{transformez-0.2.2 → transformez-0.3.0}/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.2.2'
+__version__ = VERSION = '0.3.0'

transformez-0.3.0/src/transformez/api.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+transformez.api
+~~~~~~~~~~~~~~~
+High-level Python Interface for Transformez.
+
+Usage:
+    import transformez
+
+    # Generate a shift grid (returns a numpy array)
+    shift_array = transformez.generate_grid(
+        region=[-90, -89, 29, 30],
+        increment="3s",
+        datum_in="mllw",
+        datum_out="5703"
+    )
+
+    # Transform an existing DEM directly
+    out_file = transformez.transform_raster(
+        input_raster="my_dem_mllw.tif",
+        datum_in="mllw",
+        datum_out="5703:g2012b",
+        output_raster="my_dem_navd88.tif"
+    )
+"""
+
+import os
+import logging
+import numpy as np
+from typing import List, Union, Optional, Tuple
+
+from .transform import VerticalTransform
+from .definitions import Datums
+from .grid_engine import GridWriter, GridEngine
+from fetchez.spatial import parse_region, Region
+from fetchez import utils
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_datum(datum_arg: str) -> Tuple[Optional[int], Optional[str]]:
+    """Helper to parse compound datum strings (e.g. '5703:g2012b')."""
+
+    if not datum_arg:
+        return None, None
+    s = str(datum_arg)
+    if ':' in s:
+        parts = s.split(':')
+        geoid_part = parts[1]
+        geoid = (
+            geoid_part.split('=')[1] if 'geoid=' in geoid_part else geoid_part
+        )
+        return Datums.get_vdatum_by_name(parts[0]), geoid
+    return Datums.get_vdatum_by_name(s), None
+
+
+def generate_grid(
+    region: Union[List[float], str, Region],
+    increment: Union[str, float],
+    datum_in: str,
+    datum_out: str,
+    out_fn: Optional[str] = None,
+    cache_dir: Optional[str] = None,
+    verbose: bool = False
+) -> Optional[np.ndarray]:
+    """Generate a vertical shift grid for a specific region.
+
+    Args:
+        region: Bounds as [W, E, S, N], a 'loc:' string, or a Region object.
+        increment: Resolution (e.g., '3s' or 0.0008333).
+        datum_in: Source datum (e.g., 'mllw', '5703').
+        datum_out: Target datum (e.g., '4979', '6319').
+        out_fn: If provided, saves the grid to this file (.tif or .gtx).
+        cache_dir: Path to store downloaded grids.
+        verbose: Enable debug logging.
+
+    Returns:
+        np.ndarray: The 2D vertical shift grid, or None if failed.
+    """
+
+    if isinstance(region, Region):
+        region_obj = region
+    else:
+        regions = parse_region(region)
+        if not regions:
+            logger.error(f"Could not parse region: {region}")
+            return None
+        region_obj = regions[0]
+
+    try:
+        inc_val = utils.str2inc(str(increment))
+        nx = int(region_obj.width / inc_val)
+        ny = int(region_obj.height / inc_val)
+    except Exception as e:
+        logger.error(f"Invalid increment '{increment}': {e}")
+        return None
+
+    epsg_in, geoid_in = _parse_datum(datum_in)
+    epsg_out, geoid_out = _parse_datum(datum_out)
+
+    if not epsg_in or not epsg_out:
+        logger.error(f"Invalid datum specified: {datum_in} -> {datum_out}")
+        return None
+
+    vt = VerticalTransform(
+        region=region_obj,
+        nx=nx, ny=ny,
+        epsg_in=epsg_in, epsg_out=epsg_out,
+        geoid_in=geoid_in, geoid_out=geoid_out,
+        cache_dir=cache_dir,
+        verbose=verbose
+    )
+
+    shift_array, _ = vt._vertical_transform(vt.epsg_in, vt.epsg_out)
+
+    if shift_array is None:
+        logger.error("Transformation failed to generate a grid.")
+        return None
+
+    if out_fn:
+        GridWriter.write(out_fn, shift_array, [region_obj.xmin, region_obj.xmax, region_obj.ymin, region_obj.ymax])
+        logger.info(f"Saved shift grid to {out_fn}")
+
+    return shift_array
+
+
+def transform_raster(
+    input_raster: str,
+    datum_in: str,
+    datum_out: str,
+    output_raster: Optional[str] = None,
+    cache_dir: Optional[str] = None,
+    verbose: bool = False
+) -> Optional[str]:
+    """Apply a vertical datum transformation directly to an existing raster file.
+
+    Args:
+        input_raster: Path to the input DEM.
+        datum_in: Source datum of the DEM.
+        datum_out: Target datum for the output DEM.
+        output_raster: Path to save the transformed DEM. If None, auto-generates a name.
+        cache_dir: Path to store downloaded grids.
+        verbose: Enable debug logging.
+
+    Returns:
+        str: The path to the transformed output raster, or None if failed.
+    """
+
+    import rasterio
+
+    if not os.path.exists(input_raster):
+        logger.error(f"Input raster not found: {input_raster}")
+        return None
+
+    with rasterio.open(input_raster) as src:
+        bounds = src.bounds
+        region_obj = (
+            Region(bounds.left, bounds.right, bounds.bottom, bounds.top)
+        )
+        nx, ny = src.width, src.height
+
+    epsg_in, geoid_in = _parse_datum(datum_in)
+    epsg_out, geoid_out = _parse_datum(datum_out)
+
+    if not epsg_in or not epsg_out:
+        logger.error(f"Invalid datum specified: {datum_in} -> {datum_out}")
+        return None
+
+    if not output_raster:
+        base, ext = os.path.splitext(input_raster)
+        output_raster = f"{base}_trans_{datum_out.replace(':', '_')}{ext}"
+
+    vt = VerticalTransform(
+        region=region_obj,
+        nx=nx, ny=ny,
+        epsg_in=epsg_in, epsg_out=epsg_out,
+        geoid_in=geoid_in, geoid_out=geoid_out,
+        cache_dir=cache_dir,
+        verbose=verbose
+    )
+
+    shift_array, _ = vt._vertical_transform(vt.epsg_in, vt.epsg_out)
+
+    if shift_array is None:
+        logger.error("Failed to generate shift array for the raster bounds.")
+        return None
+
+    success = GridEngine.apply_vertical_shift(input_raster, shift_array, output_raster)
+
+    if success:
+        return output_raster
+    return None