transformez 0.1.0__tar.gz

transformez-0.1.0/AUTHORS.md

@@ -0,0 +1,10 @@
+# Credits
+
+## Maintainers
+* Matthew Love <matthew.love@colorado.edu>
+
+## Contributors
+* Elliot Lim (@e1im)
+* Christopher Amante (@camante)
+* Michael McFerrin (@mmacferrin)
+* Matt Fisher (@mfisher87)

transformez-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

transformez-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: transformez
+Version: 0.1.0
+Summary: A standalone utility for vertical elevation datum transformations.
+Author: Matthew Love
+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.
+Project-URL: Homepage, https://github.com/ciresdem/transformez
+Project-URL: Issues, https://github.com/ciresdem/transformez/issues
+Keywords: Geospatial
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.md
+Requires-Dist: numpy<2.0.0
+Requires-Dist: pyproj
+Requires-Dist: rasterio
+Requires-Dist: fetchez>0.3.3
+Dynamic: license-file
+
+# 🌍 Transformez ↕
+
+**Vertical datum transformations, simplified.**
+
+> ⚠️ **BETA STATUS:** This project is in active development (v0.1.0).
+
+Transformez is a standalone Python library and CLI for converting geospatial data between vertical datums (e.g., MLLW to NAVD88).
+
+## Why Transformez?
+
+Vertical datum transformation is often the hardest part of coastal DEM generation. Existing tools are either massive, complex desktop software or buried deep within heavy GIS libraries that are difficult to automate in a headless Linux environment.
+
+**Transformez solves this by being:**
+* **Lightweight:** A pure Python package that does one thing well. It doesn't require a GUI or a 5GB installer.
+* **Grid-Based:** It uses the official VDatum GTIF/GTX grids directly, ensuring your transformations match authoritative standards. 
+* **Developer Friendly:** It offers a clean Python API for integrating vertical shifts directly into your numpy/rasterio pipelines, plus a CLI for quick batch processing.
+
+It works in two ways:
+1.  **Standalone CLI:** Generate shift grids (TIF) for any region or match an existing DEM.
+2.  **Fetchez Plugin:** Automatically transform data as it is downloaded.
+
+![Shift Grid Example](docs/images/mllw2nvd.png)
+*(Above: A generated vertical shift grid transforming MLLW to NAVD88)*
+
+## Features
+
+* **Tidal Transformations:** Wraps NOAA's **VDatum** to transform between tidal surfaces (MLLW, MHHW) and geometric datums.
+* **Geoid Grids:** Seamlessly applies PROJ-CDN geoids (GEOID18, GEOID12B, EGM2008).
+* **Time-Dependent Shifts:** Integrates **HTDP** to handle crustal velocities and epoch transformations.
+* **Grid Engine:** Automates the fetching, stitching, and mosaicking of partial VDatum grids into a single continuous shift surface.
+
+---
+
+## Installation
+
+* Requires **Fetchez** (v0.3.3+) and standard geospatial libs.
+
+* **HTDP / VDatum**: See [NOAA Geodesy Tools](https://geodesy.noaa.gov/TOOLS/Htdp/Htdp.shtml).
+
+```bash
+# Clone and install
+git clone https://github.com/ciresdem/transformez.git
+cd transformez
+pip install -e .
+```
+
+## Usage
+1. Standalone CLI
+Use transformez to generate shift grids for use in other software (PDAL, GDAL, CARIS) or to transform a specific DEM directly.
+
+* Mode A: Region & Resolution
+
+Generate a generic shift grid for a specific bounding box.
+
+```bash
+# Generate a shift grid from MLLW (5866) to NAVD88 (5703)
+# -R: West/East/South/North
+# -E: Grid resolution (e.g., 3 arc-seconds)
+transformez -R -95.5/-94.5/28.5/29.5 -E 3s \
+    --vdatum-in "5866" \
+    --vdatum-out "5703:g2018" \
+    --output mllw_to_navd88.tif
+```
+
+* Mode B: Match Input DEM
+
+Automatically extract the bounds and resolution from an input DEM and generate a matching transformed output.
+
+```bash
+# Transform an existing DEM from Ellipsoidal (6319) to Orthometric (5703)
+transformez --dem input_dem.tif \
+    --vdatum-in "6319" \
+    --vdatum-out "5703" \
+    --output output_navd88.tif
+```
+
+2. As a Fetchez Hook
+Configure fetchez to generate transformation grids automatically for downloaded data regions.
+
+```bash
+# Download SRTM and prepare a shift grid from EGM96 to WGS84
+fetchez srtm_plus -R -120/-119/33/34 --hook transformez:datum_in=5773,datum_out=4979
+```
+
+## Python API
+
+Transformez can be used directly in Python scripts to generate shift grids or transform arrays.
+
+### 1. Generate a Vertical Shift Grid
+Use `VerticalTransform` to calculate the shift array (numpy) between two datums for a specific region.
+
+```python
+from transformez.transform import VerticalTransform
+from fetchez.spatial import Region
+from transformez.grid_engine import GridWriter
+
+# 1. Define the Region (West, East, South, North)
+#    and the Grid Dimensions (nx, ny)
+region = Region(-95.5, -94.5, 28.5, 29.5)
+nx, ny = 1200, 1200 
+
+# 2. Initialize the Transformer
+#    - MLLW (5866) -> NAVD88 (5703) via GEOID18
+vt = VerticalTransform(
+    region=region,
+    nx=nx, ny=ny,
+    epsg_in="5866",       
+    epsg_out="5703:geoid=g2018" 
+)
+
+# 3. Generate the Shift Array (numpy)
+#    Returns: (shift_grid, uncertainty_grid)
+shift_grid, unc = vt._vertical_transform(vt.epsg_in, vt.epsg_out)
+
+# 4. Save to GeoTIFF
+GridWriter.write("mllw_to_navd88.tif", shift_grid, region)
+```
+
+### 2. Transform an Existing DEM
+
+If you have a DEM and a generated shift grid, you can apply the transformation mathematically using GridEngine.
+
+```python
+from transformez.grid_engine import GridEngine
+
+# Apply the vertical shift: Output = Input + Shift
+# Matches pixels 1:1, handling NoData and bounds automatically.
+GridEngine.apply_vertical_shift(
+    src_dem="input_ellipsoidal.tif",
+    shift_array=shift_grid,  # numpy array from step above
+    dst_dem="output_orthometric.tif"
+)
+```
+
+### 3. Parse SRS & Datums
+
+You can use the helper classes to resolve complex datum strings or EPSG codes.
+
+```python
+from transformez.definitions import Datums
+
+# Get VDatum CLI string for an EPSG
+v_str = Datums.get_vdatum_id(5866) 
+# Returns: 'mllw:m:height'
+
+# Get Default Geoid for a Datum
+geoid = Datums.get_default_geoid(5703)
+# Returns: 'g2018'
+```
+
+## Supported Datums
+
+Transformez supports EPSG codes and common vertical datum names.
+
+**Ellipsoidal:** 6319 (NAD83 2011), 4979 (WGS84)
+
+**Orthometric:** 5703 (NAVD88), 5702 (NGVD29), 3855 (EGM2008)
+
+**Tidal:** 5866 (MLLW), 5869 (MHHW), 5714 (MSL)
+
+**Geoids:** g2018, g2012b, xgeoid20b, egm2008
+
+## 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.1.0/README.md

@@ -0,0 +1,168 @@
+# 🌍 Transformez ↕
+
+**Vertical datum transformations, simplified.**
+
+> ⚠️ **BETA STATUS:** This project is in active development (v0.1.0).
+
+Transformez is a standalone Python library and CLI for converting geospatial data between vertical datums (e.g., MLLW to NAVD88).
+
+## Why Transformez?
+
+Vertical datum transformation is often the hardest part of coastal DEM generation. Existing tools are either massive, complex desktop software or buried deep within heavy GIS libraries that are difficult to automate in a headless Linux environment.
+
+**Transformez solves this by being:**
+* **Lightweight:** A pure Python package that does one thing well. It doesn't require a GUI or a 5GB installer.
+* **Grid-Based:** It uses the official VDatum GTIF/GTX grids directly, ensuring your transformations match authoritative standards. 
+* **Developer Friendly:** It offers a clean Python API for integrating vertical shifts directly into your numpy/rasterio pipelines, plus a CLI for quick batch processing.
+
+It works in two ways:
+1.  **Standalone CLI:** Generate shift grids (TIF) for any region or match an existing DEM.
+2.  **Fetchez Plugin:** Automatically transform data as it is downloaded.
+
+![Shift Grid Example](docs/images/mllw2nvd.png)
+*(Above: A generated vertical shift grid transforming MLLW to NAVD88)*
+
+## Features
+
+* **Tidal Transformations:** Wraps NOAA's **VDatum** to transform between tidal surfaces (MLLW, MHHW) and geometric datums.
+* **Geoid Grids:** Seamlessly applies PROJ-CDN geoids (GEOID18, GEOID12B, EGM2008).
+* **Time-Dependent Shifts:** Integrates **HTDP** to handle crustal velocities and epoch transformations.
+* **Grid Engine:** Automates the fetching, stitching, and mosaicking of partial VDatum grids into a single continuous shift surface.
+
+---
+
+## Installation
+
+* Requires **Fetchez** (v0.3.3+) and standard geospatial libs.
+
+* **HTDP / VDatum**: See [NOAA Geodesy Tools](https://geodesy.noaa.gov/TOOLS/Htdp/Htdp.shtml).
+
+```bash
+# Clone and install
+git clone https://github.com/ciresdem/transformez.git
+cd transformez
+pip install -e .
+```
+
+## Usage
+1. Standalone CLI
+Use transformez to generate shift grids for use in other software (PDAL, GDAL, CARIS) or to transform a specific DEM directly.
+
+* Mode A: Region & Resolution
+
+Generate a generic shift grid for a specific bounding box.
+
+```bash
+# Generate a shift grid from MLLW (5866) to NAVD88 (5703)
+# -R: West/East/South/North
+# -E: Grid resolution (e.g., 3 arc-seconds)
+transformez -R -95.5/-94.5/28.5/29.5 -E 3s \
+    --vdatum-in "5866" \
+    --vdatum-out "5703:g2018" \
+    --output mllw_to_navd88.tif
+```
+
+* Mode B: Match Input DEM
+
+Automatically extract the bounds and resolution from an input DEM and generate a matching transformed output.
+
+```bash
+# Transform an existing DEM from Ellipsoidal (6319) to Orthometric (5703)
+transformez --dem input_dem.tif \
+    --vdatum-in "6319" \
+    --vdatum-out "5703" \
+    --output output_navd88.tif
+```
+
+2. As a Fetchez Hook
+Configure fetchez to generate transformation grids automatically for downloaded data regions.
+
+```bash
+# Download SRTM and prepare a shift grid from EGM96 to WGS84
+fetchez srtm_plus -R -120/-119/33/34 --hook transformez:datum_in=5773,datum_out=4979
+```
+
+## Python API
+
+Transformez can be used directly in Python scripts to generate shift grids or transform arrays.
+
+### 1. Generate a Vertical Shift Grid
+Use `VerticalTransform` to calculate the shift array (numpy) between two datums for a specific region.
+
+```python
+from transformez.transform import VerticalTransform
+from fetchez.spatial import Region
+from transformez.grid_engine import GridWriter
+
+# 1. Define the Region (West, East, South, North)
+#    and the Grid Dimensions (nx, ny)
+region = Region(-95.5, -94.5, 28.5, 29.5)
+nx, ny = 1200, 1200 
+
+# 2. Initialize the Transformer
+#    - MLLW (5866) -> NAVD88 (5703) via GEOID18
+vt = VerticalTransform(
+    region=region,
+    nx=nx, ny=ny,
+    epsg_in="5866",       
+    epsg_out="5703:geoid=g2018" 
+)
+
+# 3. Generate the Shift Array (numpy)
+#    Returns: (shift_grid, uncertainty_grid)
+shift_grid, unc = vt._vertical_transform(vt.epsg_in, vt.epsg_out)
+
+# 4. Save to GeoTIFF
+GridWriter.write("mllw_to_navd88.tif", shift_grid, region)
+```
+
+### 2. Transform an Existing DEM
+
+If you have a DEM and a generated shift grid, you can apply the transformation mathematically using GridEngine.
+
+```python
+from transformez.grid_engine import GridEngine
+
+# Apply the vertical shift: Output = Input + Shift
+# Matches pixels 1:1, handling NoData and bounds automatically.
+GridEngine.apply_vertical_shift(
+    src_dem="input_ellipsoidal.tif",
+    shift_array=shift_grid,  # numpy array from step above
+    dst_dem="output_orthometric.tif"
+)
+```
+
+### 3. Parse SRS & Datums
+
+You can use the helper classes to resolve complex datum strings or EPSG codes.
+
+```python
+from transformez.definitions import Datums
+
+# Get VDatum CLI string for an EPSG
+v_str = Datums.get_vdatum_id(5866) 
+# Returns: 'mllw:m:height'
+
+# Get Default Geoid for a Datum
+geoid = Datums.get_default_geoid(5703)
+# Returns: 'g2018'
+```
+
+## Supported Datums
+
+Transformez supports EPSG codes and common vertical datum names.
+
+**Ellipsoidal:** 6319 (NAD83 2011), 4979 (WGS84)
+
+**Orthometric:** 5703 (NAVD88), 5702 (NGVD29), 3855 (EGM2008)
+
+**Tidal:** 5866 (MLLW), 5869 (MHHW), 5714 (MSL)
+
+**Geoids:** g2018, g2012b, xgeoid20b, egm2008
+
+## 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.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ['setuptools>=61.0']
+build-backend = 'setuptools.build_meta'
+
+[project]
+name = 'transformez'
+version = '0.1.0'
+description = 'A standalone utility for vertical elevation datum transformations.'
+readme = "README.md"
+authors = [{ name = 'Matthew Love' }]
+license = { file = 'LICENSE' }
+classifiers = [
+    'Programming Language :: Python :: 3',
+    'License :: OSI Approved :: MIT License',
+    'Operating System :: OS Independent',
+    'Topic :: Scientific/Engineering :: GIS',
+]
+dependencies = [
+    'numpy<2.0.0',
+    'pyproj',
+    'rasterio',
+    'fetchez>0.3.3', 
+]
+
+keywords = ["Geospatial"]
+
+[project.entry-points."fetchez.plugins"]
+transformez = "transformez"
+
+[project.scripts]
+transformez = 'transformez.cli:transformez_cli'
+
+[project.urls]
+Homepage = "https://github.com/ciresdem/transformez"
+Issues = "https://github.com/ciresdem/transformez/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]  # Look for packages inside the 'src' folder
+include = ["transformez*"]  # Include the package named 'transformez'
+exclude = ["tests*", "docs*", "scripts*", "examples*"]
+namespaces = false 

transformez-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

transformez-0.1.0/setup.py

@@ -0,0 +1,2 @@
+from setuptools import setup
+setup()

transformez-0.1.0/src/transformez/__init__.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+
+__version__ = "0.1.0"
+__author__ = "Matthew Love"
+__credits__ = "CIRES"
+
+import os
+
+# --- fix the PROJ_LIB path to work with rasterio/pyproj
+def _find_proj_lib():
+    """Locate the best available PROJ_LIB path."""
+    
+    try:
+        import rasterio
+        # Common path in wheels: site-packages/rasterio/proj_data
+        r_path = os.path.join(os.path.dirname(rasterio.__file__), 'proj_data')
+        if os.path.exists(os.path.join(r_path, 'proj.db')):
+            return r_path
+            
+        # Linux wheels often put it in .libs adjacent to the package
+        # e.g. site-packages/rasterio.libs/proj.db
+        parent = os.path.dirname(os.path.dirname(rasterio.__file__))
+        libs = glob.glob(os.path.join(parent, 'rasterio.libs*'))
+        if libs:
+            # Look inside the libs folder
+            for root, _, files in os.walk(libs[0]):
+                if 'proj.db' in files:
+                    return root
+    except ImportError:
+        pass
+
+    # Try PyProj's bundled data (Fallback)
+    try:
+        import pyproj
+        p_path = pyproj.datadir.get_data_dir()
+        if os.path.exists(os.path.join(p_path, 'proj.db')):
+            return p_path
+    except ImportError:
+        pass
+        
+    return None
+
+target_proj_lib = _find_proj_lib()
+
+# Unset conflicting system/conda vars if we found a better one
+if 'PROJ_LIB' in os.environ:
+    del os.environ['PROJ_LIB']
+
+if target_proj_lib:
+    os.environ['PROJ_LIB'] = target_proj_lib
+    # print(f"DEBUG: PROJ_LIB set to {target_proj_lib}")
+
+# # --- PROJ_LIB Fix (Run before any geo-imports) ---
+# # This prevents "PROJ: proj_create_from_database: Cannot find proj.db" errors
+# # when conflicting Conda/System PROJ installations exist.
+# try:
+#     # 1. We must import pyproj first to let it find its own bundled data
+#     import os
+#     import pyproj
+    
+#     # 2. Get the valid data directory from the wheel
+#     proj_lib = pyproj.datadir.get_data_dir()
+#     #print(proj_lib)
+#     # 3. Force the environment variable to use this valid path
+#     #    (Overriding any bad global/Conda defaults)
+#     os.environ['PROJ_LIB'] = proj_lib
+    
+# except ImportError:
+#     # If pyproj isn't installed yet (e.g. during pip install), skip this.
+#     pass
+
+# --- End PROJ_LIB Fix ---
+
+from .hooks import TransformezHook
+#from .modules import DatumGridFetcher
+from fetchez.hooks.registry import HookRegistry
+# form fetchez.registry import FetchezRegistry # Implicitly handled via setup_fetchez passing cls
+
+def setup_fetchez(registry_cls):
+    """Called by fetchez when loading plugins.
+    Registers modules, hooks, and presets.
+    """
+
+    # module should gather necessary grids to do the transformation
+    # Register the Module with Fetchez
+    # registry_cls.register_module(
+    #     mod_key='datum_grids',
+    #     mod_cls=DatumGridFetcher,
+    #     metadata={
+    #         'desc': 'Fetch NOAA VDatum and PROJ-CDN grids for a region',
+    #         'tags': ['vdatum', 'geoid', 'transformation']
+    #     }
+    # )
+
+    # Register Fetchez Hooks
+    HookRegistry.register_hook(TransformezHook)
+    
+    # Register Global Presets
+    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 GTX shift grid.",
+        hooks=[
+            {"name": "transformez", "args": {}} 
+        ]
+    )
+
+
+    # "transform-pipeline": {
+    #     "help_text": "Generate shift grid based on region, then apply it to files.",
+    #     "hooks": [
+    #         {
+    #             "name": "transformez", 
+    #             "args": {"stage": "pre", "datum_in": "5703", "output_grid": "/tmp/shift.gtx"}
+    #         },
+    #         {
+    #             "name": "transformez", 
+    #             "args": {"stage": "file", "apply": "True", "output_grid": "/tmp/shift.gtx"}
+    #         },
+    #         {
+    #              "name": "audit" 
+    #         }
+    #     ]
+    # }