vyperdatum.utils.raster_utils

Attributes

logger

Functions

`band_stats`(→ list)	Return a list containing the min, max, mean, and std of the band array.
`raster_metadata`(→ dict)
`add_overview`(→ None)	Add overview bands to a raster file.
`add_rat`(→ None)	Add Raster Attribute Table (RAT) to all bands of a raster file.
`set_nodatavalue`(→ None)	Change the NoDataValue of the raster file bands.
`unchanged_to_nodata`(→ None)	Compare the xform_band values of the src_raster_file and xform_raster_file.
`raster_compress`(raster_file_path, output_file_path, ...)	Compress raster file.
`preserve_raster_size`(input_file, output_file)	Resize the output_file raster dimensions to those of the input input_file.
`crs_to_code_auth`(→ Optional[str])	Return CRS string representation in form of code:authority
`push_pop_at_vshift`(→ str)	Sandwich the vgrid_shift operation with push/pop of the horizontal CRS components.
`raster_pre_transformation_checks`(source_meta, source_crs)	Run a number of sanity checks on the source raster file, before transformation.
`raster_post_transformation_checks`(source_meta, ...)	Run a number of sanity checks on the transformed raster file.
`update_raster_wkt`(→ None)	Assign a new WKT to a GeoTIFF in-place, or to a BAG by recreating the file.
`overwrite_with_original`(→ None)	Copy the non-elevation bands from `input_file` into `output_file`
`update_stats`(input_file)	Update statistics for the raster file.
`apply_nbs_bandnames`(input_file)	Apply NBS band names to the raster file.
`add_uncertainty_band`(→ None)
`apply_nbs_band_standards`(→ None)	Apply NBS band standards to the raster file.
`create_cutline_from_grid`(grid_path, output_cutline[, ...])	Create a cutline polygon from a GTG grid's valid (non-nodata) area,
`create_cutline_file`(→ Optional[str])	Create a cutline file from the provided grid files if vertical shift is applied.
`clip_raster_to_cutline`(→ Optional[str])	Clip a raster against a cutline polygon while preserving the input's
`add_vyper_tag`(→ None)	Add a Vyperdatum tag to the raster file to indicate it has been processed.

Module Contents

vyperdatum.utils.raster_utils.logger

vyperdatum.utils.raster_utils.band_stats(band_array: numpy.ndarray) → list

Return a list containing the min, max, mean, and std of the band array.

Parameters:

band_array (numpy.ndarray) – raster band array
Returns
--------
list – min, max, mean, and std of the band array.

vyperdatum.utils.raster_utils.raster_metadata(raster_file: str, verbose: bool = False) → dict

vyperdatum.utils.raster_utils.add_overview(raster_file: str, compression: str = '', embedded: bool = True, levels=None, resampling: str = 'AVERAGE') → None

Add overview bands to a raster file.

Parameters:

raster_file (str) – Absolute full path to the raster file.
compression (str) – The name of compression algorithm (e.g. DEFLATE, LZW). For float rasters compressed with DEFLATE or LZW, PREDICTOR=3 is set so the overview pyramid compresses as efficiently as the original. Empty string leaves compression at GDAL defaults.
embedded (bool, default=True) – If True the overviews are embedded in the file, otherwise stored externally as a .ovr sidecar.
levels (list[int] | None, default=None) – Overview decimation factors. When None, an automatic pyramid is derived from the raster’s longer side so the smallest level is no larger than approximately 256 pixels along its longer axis. For typical bathymetric tiles this produces seven to eight levels (e.g. 2, 4, 8, 16, 32, 64, 128).
resampling (str, default="AVERAGE") – Resampling algorithm. AVERAGE is appropriate for continuous data such as elevation; NEAREST is appropriate for categorical bands such as a contributor identifier raster.

vyperdatum.utils.raster_utils.add_rat(raster: str) → None

Add Raster Attribute Table (RAT) to all bands of a raster file.

Parameters:: raster_file (str) – Absolute full path to the raster file.

vyperdatum.utils.raster_utils.set_nodatavalue(raster_file: str, band_nodatavalue: list[tuple[int, float]] | float) → None

Change the NoDataValue of the raster file bands.

Parameters:

raster_file (str) – Absolute full path to the raster file.
band_nodatavalue (Union[list[tuple[int, float]], float]) – A list of tuples: (band_index, NoDataValue). If a single float is passed, all bands will be affected.

vyperdatum.utils.raster_utils.unchanged_to_nodata(src_raster_file: str, xform_raster_file: str, xform_band: int) → None

Compare the xform_band values of the src_raster_file and xform_raster_file. Change the values to NoDataValue if the transformed value is the same as the original value (indicating that the transformation has failed). Currentl, PROJ keep the source raster unchanged when fails to apply the transformation. The transformation fails when the source data is outside any of the underlying transformation grids. This function is meant to replace the failed transformation points with NoDataValue.

Parameters:

src_raster_file (str) – Absolute full path to the source raster file.
xform_raster_file (str) – Absolute full path to the transformed raster file.
xform_band (int) – The reference band index that is used for comparison between the source and transformed file.

vyperdatum.utils.raster_utils.raster_compress(raster_file_path: str, output_file_path: str, format: str, compression: str)

Compress raster file.

Parameters:

raster_file_path (str) – absolute path to the input raster file.
output_file_path (str) – absolute path to the compressed output raster file.
format (str) – raster file format.
compression (str) – compression algorithm.

vyperdatum.utils.raster_utils.preserve_raster_size(input_file: str, output_file: str)

Resize the output_file raster dimensions to those of the input input_file.

Parameters:

input_file (str) – absolute path to the input raster file.
output_file (str) – absolute path to the compressed output raster file.

vyperdatum.utils.raster_utils.crs_to_code_auth(crs: pyproj.CRS) → str | None

Return CRS string representation in form of code:authority

Raises:: ValueError: – If either code or authority of the crs (or its sub_crs) can not be determined.
Returns:: crs string in form of code:authority
Return type:: str

vyperdatum.utils.raster_utils.push_pop_at_vshift(pipe: str) → str

Sandwich the vgrid_shift operation with push/pop of the horizontal CRS components.

Parameters:: pipe (proj pipeline string.)

vyperdatum.utils.raster_utils.raster_pre_transformation_checks(source_meta: dict, source_crs: pyproj.CRS | str)

Run a number of sanity checks on the source raster file, before transformation. Warns if a check fails.

Parameters:: source_meta (dict) – Source raster metadata generated by raster_metadata function.
Returns:: Returns True if all checks pass, otherwise False.
Return type:: bool

vyperdatum.utils.raster_utils.raster_post_transformation_checks(source_meta: dict, target_meta: dict, target_crs: pyproj.CRS | str, vertical_transform: bool)

Run a number of sanity checks on the transformed raster file. Warns if a check fails.

Parameters:

source_meta (dict) – Source raster metadata generated by raster_metadata function.
target_meta (dict) – Target raster metadata generated by raster_metadata function.
target_crs (pyproj.crs.CRS or input used to create one) – The expected CRS object for the target raster file.
vertical_transform (bool) – True if it’s a vertical transformation, otherwise False.

Returns:

Returns True if all checks pass, otherwise False.

Return type:

bool

vyperdatum.utils.raster_utils.update_raster_wkt(input_file: str, wkt: str) → None

Assign a new WKT to a GeoTIFF in-place, or to a BAG by recreating the file. WARNING: This only assigns the SRS. If you’re actually changing CRS (e.g., degrees->meters), you must reproject with gdal.Warp instead.

Parameters:

input_file (str) – Absolute path to the input raster file.
wkt (str) – New WKT to update the raster file.

vyperdatum.utils.raster_utils.overwrite_with_original(input_file: str, output_file: str) → None

Copy the non-elevation bands from input_file into output_file and mask their values to NoData wherever the output elevation is NoData.

Same-CRS path

When the input and output rasters have identical dimensions (the expected case for same-CRS transforms after the cutline-anchored two-pass warp), non-elevation bands are copied verbatim from the input. No resampling is performed. The uncertainty (or other non-elevation) band is masked so that values outside the valid elevation region become the elevation’s NoData value.

Different-CRS path

When dimensions differ, the function falls back to GDAL’s resampling via buf_xsize / buf_ysize (the legacy behaviour). This path is not yet anchored to a target-CRS pixel grid and will produce a sub-pixel registration shift relative to the elevation band. A warning is logged so this case is visible in production. A correct different-CRS implementation requires re-warping each non-elevation band through the same coordinate pipeline as the elevation band and is deferred until that path is exercised.

param input_file:: Path to the reference raster carrying the original non-elevation bands (typically the original input to transform_raster).
type input_file:: str
param output_file:: Path to the transformed raster whose non-elevation bands are to be overwritten in place.
type output_file:: str
raises ValueError:: When the input or output cannot be opened, when no elevation band is identified in the input, or when the input has fewer than two bands (in which case nothing to do).

vyperdatum.utils.raster_utils.update_stats(input_file)

Update statistics for the raster file.

Parameters:: input_file (str): Path to the raster file.

vyperdatum.utils.raster_utils.apply_nbs_bandnames(input_file)

Apply NBS band names to the raster file. Sets the first band description to ‘elevation’ and the second band description to ‘uncertainty’ if the raster has more than one band.

Parameters:: input_file (str): Path to the raster file.

vyperdatum.utils.raster_utils.add_uncertainty_band(input_file: str) → None

vyperdatum.utils.raster_utils.apply_nbs_band_standards(input_file: str) → None

Apply NBS band standards to the raster file. Sets the first band description to ‘elevation’ and the second band description to ‘uncertainty’ if the raster has more than one band. Adds uncertainty band if it does not exist, and updates statistics.

Parameters:: input_file (str): Path to the raster file.

vyperdatum.utils.raster_utils.create_cutline_from_grid(grid_path: str, output_cutline: str, input_extent=None, input_wkt: str = None): Create a cutline polygon from a GTG grid’s valid (non-nodata) area, restricted to the vicinity of input_extent (bbox) when provided. This version supports rasters that span multiple subgrids by unioning all overlapping valid areas.

vyperdatum.utils.raster_utils.create_cutline_file(v_shift: bool, grid_files: list[str], cutline_path: str, input_metadata: dict) → str | None

Create a cutline file from the provided grid files if vertical shift is applied. Otherwise, return None.

TODO: what if more than one NWLD grids are involved?

vyperdatum.utils.raster_utils.clip_raster_to_cutline(input_path: str, cutline_path: str, output_path: str) → str | None

Clip a raster against a cutline polygon while preserving the input’s exact pixel grid.

The clipped output is anchored to the input’s geotransform: every output pixel boundary coincides with an input pixel boundary, so no sub-pixel shift is introduced by the clip step. The output extent is the smallest input-pixel-aligned rectangle that contains the cutline’s envelope (intersected with the input’s extent).

The cutline polygon may be in a different CRS than the input raster; its envelope is reprojected on the fly into the input’s CRS before snapping to the input’s pixel grid.

Pixels outside the cutline polygon are written as NoData. The output resolution, NoData value, metadata tags, and CRS match the input.

Parameters:

input_path (str) – Path to the input raster.
cutline_path (str) – Path to the cutline vector dataset (e.g. GeoPackage). Polygon CRS may differ from the input raster’s CRS.
output_path (str) – Path where the clipped raster is written.

Returns:

output_path on success, None on failure.

Return type:

str or None

vyperdatum.utils.raster_utils.add_vyper_tag(raster_file: str, pipe: str, crs_to: pyproj.CRS, steps: list) → None: Add a Vyperdatum tag to the raster file to indicate it has been processed.