Quickstart

The Transformer class handles the transformation of point and raster data. A transformer is constructed from a source CRS (crs_from) and a target CRS (crs_to). By default, the transformation steps are determined automatically.

Automatic steps

from vyperdatum.transformer import Transformer

crs_from = "EPSG:6346"            # NAD83(2011) 17N (vertical: Ellipsoid)
crs_to = "EPSG:6346+NOAA:98"      # NAD83(2011) 17N + MLLW
tf = Transformer(crs_from=crs_from,
                 crs_to=crs_to,
                 )

Prescribed steps

The transformation steps may also be prescribed explicitly. Each step is a dictionary that names a source and target CRS as authority:code and a boolean v_shift flag indicating whether the step applies a vertical shift.

from vyperdatum.transformer import Transformer

crs_from = "EPSG:6346"            # NAD83(2011) 17N
crs_to = "EPSG:6346+NOAA:98"      # NAD83(2011) 17N + MLLW
steps = [{"crs_from": "EPSG:6346", "crs_to": "EPSG:6318", "v_shift": False},
         {"crs_from": "EPSG:6319", "crs_to": "EPSG:6318+NOAA:98", "v_shift": True},
         {"crs_from": "EPSG:6318", "crs_to": "EPSG:6346", "v_shift": False}
         ]
tf = Transformer(crs_from=crs_from,
                 crs_to=crs_to,
                 steps=steps
                 )

Transforming a file

Once a transformer has been created, the transform method is called with an input path and an output path. The input format is detected automatically, and the appropriate file-specific routine is dispatched. GDAL-supported raster drivers, variable-resolution BAG, LAZ, NPZ, XYZ, and GeoParquet inputs are supported.

tf.transform(input_file="<PATH_TO_INPUT_FILE>",
             output_file="<PATH_TO_OUTPUT_FILE>")

File-specific methods

The file-specific transform methods may be called directly instead of the generic transform method. Direct point transformation accepts lists or NumPy arrays for x, y, and z and returns a four-tuple in the order (success, x, y, z).

import numpy as np

# Direct point transformation.
xi, yi, zi = np.array([278881.198]), np.array([2719890.433]), np.array([0])
success, xt, yt, zt = tf.transform_points(x=xi, y=yi, z=zi, always_xy=True)

# GDAL-supported raster transform.
tf.transform_raster(input_file="<PATH_TO_INPUT_RASTER_FILE>",
                    output_file="<PATH_TO_OUTPUT_RASTER_FILE>")

# VRBAG transform.
tf.transform_vrbag(input_file="<PATH_TO_INPUT_VRBAG_FILE>",
                   output_file="<PATH_TO_OUTPUT_VRBAG_FILE>")

# LAZ transform.
tf.transform_laz(input_file="<PATH_TO_INPUT_LAZ_FILE>",
                 output_file="<PATH_TO_OUTPUT_LAZ_FILE>")

# NPZ transform.
tf.transform_npz(input_file="<PATH_TO_INPUT_NPZ_FILE>",
                 output_file="<PATH_TO_OUTPUT_NPZ_FILE>")

# GeoParquet transform.
tf.transform_geoparquet(input_file="<PATH_TO_INPUT_PARQUET_FILE>",
                        output_file="<PATH_TO_OUTPUT_PARQUET_FILE>")

The supported formats and the behavior of the raster path are described in Supported formats and drivers and Raster transformation.