vyperdatum.utils package

Submodules

vyperdatum.utils.npz module

class vyperdatum.utils.npz.NPZ(fname: str)[source]

Bases: object

Handle loading and parsing of a .npz (numpy arrays) file.

Attributes

fname: str: Full path to the npz file.
content: np.lib.npyio.NpzFile: The object containing the numpy arrays stored in the npz file.

Example

>>> npz = NPZ('PATH_TO_NPZ_FILE')
>>> x, y, z, u = npz.xyzu()
>>> wkt = npz.wkt()
>>> mmx, mmy, mmz, mmu = npz.minmax()

load() → NpzFile[source]

Load a numpy .npz file (collection of numpy arrays).

Raises

ValueError:: If the file path is missing.
FileNotFoundError:: If the input file is not found.
TypeError:: If key names in the .npz file didn’t match the expected names.

Returns

numpy.lib.npyio.NpzFile

minmax() → Tuple[ndarray][source]

Extract the minmax values of the coordinated and uncertainty arrays.

Returns

x: numpy.ndarray: x coordinate numpy array.
y: numpy.ndarray: y coordinate numpy array.
z: numpy.ndarray: z coordinate numpy array.
u: numpy.ndarray: uncertainty numpy array.

wkt() → str[source]: Return wkt stored in the npz file.

xyzu() → Tuple[ndarray][source]

Slice the data array to extract x, y, z, u arrays.

Returns

x: numpy.ndarray: x coordinate numpy array.
y: numpy.ndarray: y coordinate numpy array.
z: numpy.ndarray: z coordinate numpy array.
u: numpy.ndarray: uncertainty numpy array.

vyperdatum.utils.raster_utils module

vyperdatum.utils.raster_utils.add_overview(raster_file: str, compression: str = '', embedded: bool = True) → None[source]

Add overview bands to a raster file with no existing overviews.

parameters

raster_file: str: Absolute full path to the raster file.
compression: str: The name of compression algorithm.
embedded: bool, default=True: If True, the overviews will be embedded in the file, otherwise stored externally.

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

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.band_stats(band_array: ndarray) → list[source]

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.crs_to_code_auth(crs: CRS) → str | None[source]

Return CRS string representation in form of code:authority

Raises

ValueError:: If either code of authority of the crs (or its sub_crs) can not be determined.

Returns

str:: crs string in form of code:authority

vyperdatum.utils.raster_utils.post_transformation_checks(source_meta: dict, target_meta: dict, target_crs: CRS | str, vertical_transform: bool)[source]

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

bool: Returns True if all checks pass, otherwise False.

vyperdatum.utils.raster_utils.pre_transformation_checks(source_meta: dict)[source]

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

bool: Returns True if all checks pass, otherwise False.

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

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.raster_metadata(raster_file: str, verbose: bool = False) → dict[source]

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

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[source]

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.warp(input_file: str, output_file: str, apply_vertical: bool, crs_from: CRS | str, crs_to: CRS | str, input_metadata: dict, warp_kwargs: dict | None = None)[source]

A gdal-warp wrapper to transform an NBS raster (GTiff) file with 3 bands: Elevation, Uncertainty, and Contributors.

Parameters

input_file: str: Path to the input raster file (gdal supported).
output_file: str: Path to the transformed raster file.
apply_vertical: bool: Apply GDAL vertical shift.
crs_from: pyproj.crs.CRS or input used to create one: Projection of input data.
crs_to: pyproj.crs.CRS or input used to create one: Projection of output data.
input_metadata: dict: Dictionary containing metadata generated by vyperdatum.raster_utils.raster_metadata()
warp_kwargs: dict: gdal kwargs.

Returns

str:: Absolute path to the transformed file.

vyperdatum.utils.spatial_utils module

vyperdatum.utils.spatial_utils.get_grid_list(vdatum_directory: str)[source]

Return all gtx files in the vdatum directory.

Parameters

vdatum_directory: absolute folder path to the vdatum directory

Returns

dict: dictionary of {grid name: grid path, …}
list: list of vdatum regions

vyperdatum.utils.spatial_utils.get_region_polygons(datums_directory: str, extension: str = 'kml') → dict[source]

” Search the datums directory to find all geometry files. All datums are assumed to reside in a subfolder.

Parameters

datums_directorystr: absolute folder path to the vdatum directory
extensionstr: the geometry file extension to search for

Returns

dict: dictionary of {kml name: kml path, …}

vyperdatum.utils.spatial_utils.overlapping_extents(lon_min: float, lat_min: float, lon_max: float, lat_max: float) → list | None | DataFrame[source]

Return database predefined extents that intersect with an area of interest. The results are sorted by coverage ratios.

Parameters

lon_min: the minimum longitude of the area of interest
lat_min: the minimum latitude of the area of interest
lon_max: the maximum longitude of the area of interest
lat_max: the maximum latitude of the area of interest

vyperdatum.utils.spatial_utils.overlapping_regions(datums_directory: str, lon_min: float, lat_min: float, lon_max: float, lat_max: float)[source]

Return the region names that intersect with the provided bound. The input coordinate reference system is expected to be NAD83(2011) geographic.

Parameters

lon_min: the minimum longitude of the area of interest
lat_min: the minimum latitude of the area of interest
lon_max: the maximum longitude of the area of interest
lat_max: the maximum latitude of the area of interest

vyperdatum.utils.vdatum_rest_utils module

vyperdatum.utils.vdatum_rest_utils.api_crs_aliases(wkt: str) → tuple[str, str][source]

Vdatum REST api uses different CRS names compared to those of the PROJ/pyproj. This function expects to receive a CRS WKT and returns horizontal and vertical CRS names that are consumable by the vdatum REST api.

Raises

ValueError: When the standard CRS name can’t be matched with any Vdatum API CRS names.

Parameters

wkt: str: WKT string.

Returns

tuple[str, str]: Horizontal and vertical CRS names that are consumable by the vdatum REST api.

vyperdatum.utils.vdatum_rest_utils.api_region_alias(region: str)[source]

Vdatum REST api uses different region names compared to those listed in the vdatum grids directory. This function expects to receive region name according to the vdatum grids directory and returns region name consistent with the vdatum REST api. Default output is contiguous.

Parameters

region: str: Region name according to the vdatum grids directory.

Returns

str

vyperdatum.utils.vdatum_rest_utils.index_to_xy(i: int, j: int, geot: tuple)[source]

Take indices of a raster’s band array and return x, y.

Parameters

i: int: Raster’s band array first index.
j: int: Raster’s band array second index.
geot: tuple: Gdal GeoTransform tuple object.

Returns

float, float: easting, northing

vyperdatum.utils.vdatum_rest_utils.sample_raster(source_meta: dict, target_meta: dict, n_sample: int, sampling_band: int, pivot_h_crs: str | None) → tuple[list, list][source]

Randomly draw n_samples points (not NoDataValue) from the sampling_band of the source and target rasters.

Parameters

source_meta: dict: Source raster metadata generated by raster_metadata function.
target_meta: dict: Target raster metadata generated by raster_metadata function.
n_sample: int: The number of sample points (coordinates).
sampling_band: dict: The index of the source band to be sampled (default 1).
pivot_h_crs: Optional[str]: When not None, both source and target samples are transformed into a common horizontal CRS, otherwise ignored (default None). Example: pivot_h_crs = ‘EPSG:6318’

Raises

ValueError:: If there are less not-null values than n_sample in the target raster band.

Returns

bool: Returns n_samples points from the rasters in form of two lists of [x, y, sampled_value].

vyperdatum.utils.vdatum_rest_utils.vdatum_cross_validate_raster(s_file: str, t_file: str, n_sample: int, tolerance: float = 0.3, sampling_band: int = 1, region: str | None = None, pivot_h_crs: str | None = None, s_h_frame: str | None = None, s_v_frame: str | None = None, s_h_zone: str | None = None, t_h_frame: str | None = None, t_v_frame: str | None = None, t_h_zone: str | None = None)[source]

Randomly sample the source raster points and transform them to the target CRS using the vdatum API. Verify if the transformed values are consistent with the target raster values.

Parameters

s_file: str: Absolute path to the source raster file.
t_file: str: Absolute path to the target (transferred) raster file.
n_sample: int: The number of sample points (coordinates).
sampling_band: dict: The index of the source band to be sampled (default 1).
region: Optional[str]: Vdatum region name (e.g. ak, as, contiguous, gcnmi, prvi) https://vdatum.noaa.gov/docs/services.html#step140
pivot_h_crs: Optional[str]: When not None, both source and target samples are transformed into a common horizontal CRS, otherwise ignored (default None). Example: pivot_h_crs = ‘EPSG:6318’
s_h_frame: Optional[str]: Source horizontal reference frame (e.g. NAD83_2011) https://vdatum.noaa.gov/docs/services.html#step150
s_v_frame: Optional[str]: source vertical reference frame (e.g. NAVD88, PRVD02, MLLW) https://vdatum.noaa.gov/docs/services.html#step160
s_h_zone: Optional[str]: source CRS zone, if projected. The details of this parameter is not documented in vdatum services page.
t_h_frame: Optional[str]: Target horizontal reference frame (e.g. NAD83_2011) https://vdatum.noaa.gov/docs/services.html#step150
t_v_frame: Optional[str]: Target vertical reference frame (e.g. NAVD88, PRVD02, MLLW) https://vdatum.noaa.gov/docs/services.html#step160
t_h_zone: Optional[str]: Target CRS zone, if projected. The details of this parameter is not documented in vdatum services page.

Returns

bool: True if all checks pass, otherwise False.
pandas.DataFrame: Dataframe containing the sampled input, transferred, and vdatum points.

vyperdatum.utils.vdatum_rest_utils.vdatum_transform_point(s_x, s_y, s_z, region, s_h_frame, s_v_frame, s_h_zone, t_h_frame, t_v_frame, t_h_zone, s_v_goid='geoid18', t_v_goid='geoid18')[source]

Call point transformation GET endpoint (/convert) of the Vdatum REST API. API docs: https://vdatum.noaa.gov/docs/services.html

Parameters

s_x: float: Source point longitude
s_y: float: Source point latitude
s_z: float: Source point height
region: str: Vdatum region name (e.g. ak, as, contiguous, gcnmi, prvi) https://vdatum.noaa.gov/docs/services.html#step140
s_h_frame: str: Source horizontal reference frame (e.g. NAD83_2011) https://vdatum.noaa.gov/docs/services.html#step150
s_v_frame: str: source vertical reference frame (e.g. NAVD88, PRVD02, MLLW) https://vdatum.noaa.gov/docs/services.html#step160
t_h_frame: str: Target horizontal reference frame (e.g. NAD83_2011) https://vdatum.noaa.gov/docs/services.html#step150
t_v_frame: str: Target vertical reference frame (e.g. NAVD88, PRVD02, MLLW) https://vdatum.noaa.gov/docs/services.html#step160
s_v_goid: str: Source vertical GEOID model (e.g. geoid18 (default), geoid12b, geoid12a, geoid09, geoid06, geoid03, geoid99, geoid96, egm2008, egm1996, egm1984, xgeoid16b, xgeoid17b, xgeoid18b, xgeoid19b, xgeoid20b)
t_v_goid: str: Target vertical GEOID model (e.g. geoid18 (default), geoid12b, geoid12a, geoid09, geoid06, geoid03, geoid99, geoid96, egm2008, egm1996, egm1984, xgeoid16b, xgeoid17b, xgeoid18b, xgeoid19b, xgeoid20b)

Returns

Optional[tuple]: The transformed coordinates (lon, lat, height)
Optional[dict]: The complete vdatum response object

vyperdatum.utils.vdatum_rest_utils.wkt_to_crs(wkt: str) → tuple[str | None, str | None][source]

Receives WKT and returns the horizontal/vertical CRS names.

Parameters

wkt: str: WKT string

Returns

tuple[Optional[str], Optional[str]]: Horizontal and vertical CRS names, if identified.

vyperdatum.utils.vdatum_rest_utils.wkt_to_utm(wkt: str) → str | None[source]

Receives WKT and returns the UTM zone, if applicable.

Parameters

wkt: str: WKT string

Returns

Optional[str]: UTM zone

vyperdatum.utils package

Submodules

vyperdatum.utils.npz module

Attributes

Example

Raises

Returns

Returns

Returns

vyperdatum.utils.raster_utils module

parameters

parameters

Parameters

Returns:

Raises

Returns

Parameters

Returns

Parameters

Returns

Parameters

parameters

parameters

Parameters

Returns

vyperdatum.utils.spatial_utils module

Parameters

Returns

Parameters

Returns

Parameters

Parameters

vyperdatum.utils.vdatum_rest_utils module

Raises

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Raises

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Module contents