Developer API#

The high-level Python API for fetching data in a single line of code.

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",
)
transformez.api.plot_grid(grid_array, region, title='Vertical Shift Preview')[source]#

Plot the transformation grid using Matplotlib.

transformez.api.generate_grid(region, increment, datum_in, datum_out, decay_pixels=100, out_fn=None, cache_dir=None, verbose=False)[source]#

Generate a vertical shift grid for a specific region.

Parameters:

  • region (List[float] | str | Region) – Bounds as [W, E, S, N], a ‘loc:’ string, or a Region object.

  • increment (str | float) – Resolution (e.g., ‘3s’ or 0.0008333).

  • datum_in (str) – Source datum (e.g., ‘mllw’, ‘5703’).

  • datum_out (str) – Target datum (e.g., ‘4979’, ‘6319’).

  • decay_pixels (int, default: 100) – Set the pixel decay in case extrapolation is required.

  • out_fn (str | None, default: None) – If provided, saves the grid to this file (.tif or .gtx).

  • cache_dir (str | None, default: None) – Path to store downloaded grids.

  • verbose (bool, default: False) – Enable debug logging.

Returns:

np.ndarray – The 2D vertical shift grid, or None if failed.

transformez.api.transform_raster(input_raster, datum_in, datum_out, decay_pixels=100, output_raster=None, cache_dir=None, z_unit_in='auto', z_unit_out='auto', verbose=False)[source]#

Apply a vertical datum transformation directly to an existing raster file.

Parameters:

  • input_raster (str) – Path to the input DEM.

  • datum_in (str) – Source datum of the DEM.

  • datum_out (str) – Target datum for the output DEM.

  • output_raster (str | None, default: None) – Path to save the transformed DEM. If None, auto-generates a name.

  • decay_pixels (int, default: 100) – Set the pixel decay in case extrapolation is required.

  • cache_dir (str | None, default: None) – Path to store downloaded grids.

  • z_unit_in (str | None, default: 'auto') – Input DEM z units.

  • z_unit_out (str | None, default: 'auto') – Output DEM z units.

  • verbose (bool, default: False) – Enable debug logging.

Returns:

str – The path to the transformed output raster, or None if failed.