vyperdatum.utils.vdatum_rest_utils

Attributes

logger

Functions

`vdatum_transform_point`(s_x, s_y, s_z, region, ...[, ...])	Call point transformation GET endpoint (/convert) of the Vdatum REST API.
`api_region_alias`(vdatum_regions)	Vdatum REST api uses different region names compared to those
`wkt_to_utm`(→ Optional[str])	Receives WKT and returns the UTM zone, if applicable.
`wkt_to_crs`(→ tuple[Optional[str], Optional[str]])	Receives WKT and returns the horizontal/vertical CRS names.
`api_crs_aliases`(→ tuple[str, str])	Vdatum REST api uses different CRS names compared to those
`index_to_xy`(i, j, geot)	Take indices of a raster's band array and return x, y.
`sample_raster`(→ tuple[list, list])	Randomly draw n_samples points (not NoDataValue) from the sampling_band
`vdatum_cross_validate`(s_wkt, t_wkt, n_sample, ...[, ...])	Randomly sample the source raster points and transform them to the

Module Contents

vyperdatum.utils.vdatum_rest_utils.logger

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')

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.api_region_alias(vdatum_regions: list[str])

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 (list[str]) – Region name according to the vdatum grids directory.
Return type:: str

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

Receives WKT and returns the UTM zone, if applicable.

Parameters:: wkt (str) – WKT string
Returns:: UTM zone
Return type:: Optional[str]

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

Receives WKT and returns the horizontal/vertical CRS names.

Parameters:: wkt (str) – WKT string
Returns:: Horizontal and vertical CRS names, if identified.
Return type:: tuple[Optional[str], Optional[str]]

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

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.

Parameters:: wkt (str) – WKT string.
Returns:: Horizontal and vertical CRS names that are consumable by the vdatum REST api.
Return type:: tuple[str, str]

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

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:

easting, northing

Return type:

float, float

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

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:

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

Return type:

tuple[list, list]

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_wkt (str) – WKT associated with the source data CRS.
t_wkt (str) – WKT associated with the target data CRS.
n_sample (int) – The number of sample points (coordinates).
s_raster_metadata (Optional[dict]) – Source file metadata. This only applies to raster files; otherwise, None.
t_raster_metadata (Optional[dict]) – Target file metadata. This only applies to raster files; otherwise, None.
s_point_samples (Optional[Union[list, numpy.ndarray]]) – Lists of source sample points in form of [x, y, sampled_value]. This parameter only applies to point transformations(not raster); otherwise, None.
t_point_samples (Optional[Union[list, numpy.ndarray]]) – Lists of source sample points in form of [x, y, sampled_value]. This parameter only applies to point transformations(not raster); otherwise, None.
tolerance (float) – Maximum elevation deviation [m] between transformations conducted by Vyperdatum compared with Vdatum.
raster_sampling_band (dict) – The index of the source raster file band to be sampled (default 1). Only applies to raster file inputs.
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.