vyperdatum.utils.vdatum_rest_utils ================================== .. py:module:: vyperdatum.utils.vdatum_rest_utils Attributes ---------- .. autoapisummary:: vyperdatum.utils.vdatum_rest_utils.logger Functions --------- .. autoapisummary:: vyperdatum.utils.vdatum_rest_utils.vdatum_transform_point vyperdatum.utils.vdatum_rest_utils.api_region_alias vyperdatum.utils.vdatum_rest_utils.wkt_to_utm vyperdatum.utils.vdatum_rest_utils.wkt_to_crs vyperdatum.utils.vdatum_rest_utils.api_crs_aliases vyperdatum.utils.vdatum_rest_utils.index_to_xy vyperdatum.utils.vdatum_rest_utils.sample_raster vyperdatum.utils.vdatum_rest_utils.vdatum_cross_validate Module Contents --------------- .. py:data:: logger .. py:function:: 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 :param s_x: Source point longitude :type s_x: float :param s_y: Source point latitude :type s_y: float :param s_z: Source point height :type s_z: float :param region: Vdatum region name (e.g. ak, as, contiguous, gcnmi, prvi) https://vdatum.noaa.gov/docs/services.html#step140 :type region: str :param s_h_frame: Source horizontal reference frame (e.g. NAD83_2011) https://vdatum.noaa.gov/docs/services.html#step150 :type s_h_frame: str :param s_v_frame: source vertical reference frame (e.g. NAVD88, PRVD02, MLLW) https://vdatum.noaa.gov/docs/services.html#step160 :type s_v_frame: str :param t_h_frame: Target horizontal reference frame (e.g. NAD83_2011) https://vdatum.noaa.gov/docs/services.html#step150 :type t_h_frame: str :param t_v_frame: Target vertical reference frame (e.g. NAVD88, PRVD02, MLLW) https://vdatum.noaa.gov/docs/services.html#step160 :type t_v_frame: str :param s_v_goid: Source vertical GEOID model (e.g. geoid18 (default), geoid12b, geoid12a, geoid09, geoid06, geoid03, geoid99, geoid96, egm2008, egm1996, egm1984, xgeoid16b, xgeoid17b, xgeoid18b, xgeoid19b, xgeoid20b) :type s_v_goid: str :param t_v_goid: Target vertical GEOID model (e.g. geoid18 (default), geoid12b, geoid12a, geoid09, geoid06, geoid03, geoid99, geoid96, egm2008, egm1996, egm1984, xgeoid16b, xgeoid17b, xgeoid18b, xgeoid19b, xgeoid20b) :type t_v_goid: str :returns: * *Optional[tuple]* -- The transformed coordinates (lon, lat, height) * *Optional[dict]* -- The complete vdatum response object .. py:function:: 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`. :param region: Region name according to the vdatum grids directory. :type region: list[str] :rtype: str .. py:function:: wkt_to_utm(wkt: str) -> Optional[str] Receives WKT and returns the UTM zone, if applicable. :param wkt: WKT string :type wkt: str :returns: UTM zone :rtype: Optional[str] .. py:function:: wkt_to_crs(wkt: str) -> tuple[Optional[str], Optional[str]] Receives WKT and returns the horizontal/vertical CRS names. :param wkt: WKT string :type wkt: str :returns: Horizontal and vertical CRS names, if identified. :rtype: tuple[Optional[str], Optional[str]] .. py:function:: 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. :param wkt: WKT string. :type wkt: str :returns: Horizontal and vertical CRS names that are consumable by the vdatum REST api. :rtype: tuple[str, str] .. py:function:: index_to_xy(i: int, j: int, geot: tuple) Take indices of a raster's band array and return x, y. :param i: Raster's band array first index. :type i: int :param j: Raster's band array second index. :type j: int :param geot: Gdal GeoTransform tuple object. :type geot: tuple :returns: easting, northing :rtype: float, float .. py:function:: sample_raster(source_meta: dict, target_meta: dict, n_sample: int, sampling_band: int, pivot_h_crs: Optional[str]) -> tuple[list, list] Randomly draw `n_samples` points (not NoDataValue) from the `sampling_band` of the source and target rasters. :param source_meta: Source raster metadata generated by `raster_metadata` function. :type source_meta: dict :param target_meta: Target raster metadata generated by `raster_metadata` function. :type target_meta: dict :param n_sample: The number of sample points (coordinates). :type n_sample: int :param sampling_band: The index of the source band to be sampled (default 1). :type sampling_band: dict :param pivot_h_crs: 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' :type pivot_h_crs: Optional[str] :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]. :rtype: tuple[list, list] .. py:function:: vdatum_cross_validate(s_wkt: str, t_wkt: str, n_sample: int, s_raster_metadata: Optional[dict], t_raster_metadata: Optional[dict], s_point_samples: Optional[Union[list, numpy.ndarray]], t_point_samples: Optional[Union[list, numpy.ndarray]], tolerance: float = 0.3, raster_sampling_band: int = 1, region: Optional[str] = None, pivot_h_crs: Optional[str] = None, s_h_frame: Optional[str] = None, s_v_frame: Optional[str] = None, s_h_zone: Optional[str] = None, t_h_frame: Optional[str] = None, t_v_frame: Optional[str] = None, t_h_zone: Optional[str] = None) 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. :param s_wkt: WKT associated with the source data CRS. :type s_wkt: str :param t_wkt: WKT associated with the target data CRS. :type t_wkt: str :param n_sample: The number of sample points (coordinates). :type n_sample: int :param s_raster_metadata: Source file metadata. This only applies to raster files; otherwise, None. :type s_raster_metadata: Optional[dict] :param t_raster_metadata: Target file metadata. This only applies to raster files; otherwise, None. :type t_raster_metadata: Optional[dict] :param s_point_samples: Lists of source sample points in form of [x, y, sampled_value]. This parameter only applies to point transformations(not raster); otherwise, None. :type s_point_samples: Optional[Union[list, numpy.ndarray]] :param t_point_samples: Lists of source sample points in form of [x, y, sampled_value]. This parameter only applies to point transformations(not raster); otherwise, None. :type t_point_samples: Optional[Union[list, numpy.ndarray]] :param tolerance: Maximum elevation deviation [m] between transformations conducted by Vyperdatum compared with Vdatum. :type tolerance: float :param raster_sampling_band: The index of the source raster file band to be sampled (default 1). Only applies to raster file inputs. :type raster_sampling_band: dict :param region: Vdatum region name (e.g. ak, as, contiguous, gcnmi, prvi) https://vdatum.noaa.gov/docs/services.html#step140 :type region: Optional[str] :param pivot_h_crs: 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' :type pivot_h_crs: Optional[str] :param s_h_frame: Source horizontal reference frame (e.g. NAD83_2011) https://vdatum.noaa.gov/docs/services.html#step150 :type s_h_frame: Optional[str] :param s_v_frame: source vertical reference frame (e.g. NAVD88, PRVD02, MLLW) https://vdatum.noaa.gov/docs/services.html#step160 :type s_v_frame: Optional[str] :param s_h_zone: source CRS zone, if projected. The details of this parameter is not documented in vdatum services page. :type s_h_zone: Optional[str] :param t_h_frame: Target horizontal reference frame (e.g. NAD83_2011) https://vdatum.noaa.gov/docs/services.html#step150 :type t_h_frame: Optional[str] :param t_v_frame: Target vertical reference frame (e.g. NAVD88, PRVD02, MLLW) https://vdatum.noaa.gov/docs/services.html#step160 :type t_v_frame: Optional[str] :param t_h_zone: Target CRS zone, if projected. The details of this parameter is not documented in vdatum services page. :type t_h_zone: Optional[str] :returns: * *bool* -- True if all checks pass, otherwise False. * *pandas.DataFrame* -- Dataframe containing the sampled input, transferred, and vdatum points.