vyperdatum.transformer ====================== .. py:module:: vyperdatum.transformer Attributes ---------- .. autoapisummary:: vyperdatum.transformer.logger vyperdatum.transformer.PASS1_TILED_PIXEL_THRESHOLD vyperdatum.transformer.PASS1_DEFAULT_TILE_SIZE Classes ------- .. autoapisummary:: vyperdatum.transformer.Transformer Module Contents --------------- .. py:data:: logger .. py:data:: PASS1_TILED_PIXEL_THRESHOLD :value: 250000000 .. py:data:: PASS1_DEFAULT_TILE_SIZE :value: 4096 .. py:class:: Transformer(crs_from: Union[pyproj.CRS, int, str], crs_to: Union[pyproj.CRS, int, str], steps: Optional[list[str]] = None) .. py:attribute:: crs_from .. py:attribute:: crs_to .. py:attribute:: steps .. py:method:: from_GTiff_raster(input_file: str, crs_to: Union[pyproj.CRS, int, str], steps: Optional[list[dict]]) -> Transformer :classmethod: Create a Transformer instance from a GeoTiff raster file. :raises FileNotFoundError: If the input file is not found. :raises ValueError: If the input raster does not have the `Vyperdatum_Metadata` metadata tag. :param input_file: Path to the input raster file. :type input_file: str :param crs_to: Projection of output data. :type crs_to: pyproj.crs.CRS or input used to create one :param steps: A list of dicts containing source and target CRSs in form of `authority:code`, and a boolean key to signify if the step impose a vertical shift. This parameter represents the overall transformation steps connecting the `crs_from` to `crs_to`. When `None` is passed, vyperdatum will attempt to automatically determine the steps. :type steps: Optional[list[dict]] .. py:method:: gdal_extensions() -> list[str] :staticmethod: Return a lower-cased list of driver names supported by gdal. :rtype: list[str] .. py:method:: transform(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = False, **kwargs) -> bool Top-level transform method. :param input_file: Path to the input file. :type input_file: str :param output_file: Path to the output transformed file. :type output_file: str :param pre_post_checks: If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation. :type pre_post_checks: bool, default=True :raises FileNotFoundError:: If the input file is not found. :raises NotImplementedError:: If the input file is not supported by vyperdatum. :returns: True if successful, otherwise False. :rtype: bool .. py:method:: transform_points(x: Union[list, numpy.ndarray], y: Union[list, numpy.ndarray], z: Union[list, numpy.ndarray], always_xy: bool = False, vdatum_check: bool = False, area_of_interest: Optional[pyproj._transformer.AreaOfInterest] = None, authority: Optional[str] = None, accuracy: Optional[float] = None, allow_ballpark: Optional[bool] = True, force_over: bool = False, only_best: Optional[bool] = True) -> tuple[Optional[Union[list, numpy.ndarray]], Optional[Union[list, numpy.ndarray]], Optional[Union[list, numpy.ndarray]]] Conduct point transformation between two coordinate reference systems. :param x: Input x coordinate(s). :type x: numeric array :param y: Input y coordinate(s). :type y: numeric array :param z: Input z coordinate(s). :type z: numeric array, optional :param always_xy: If true, the transform method will accept as input and return as output coordinates using the traditional GIS order, that is longitude, latitude for geographic CRS and easting, northing for most projected CRS. :type always_xy: bool, default=False :param vdatum_check: If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API. :type vdatum_check: bool, default=False :param area_of_interest: The area of interest to help select the transformation. :type area_of_interest: :class:`.AreaOfInterest`, optional :param authority: When not specified, coordinate operations from any authority will be searched, with the restrictions set in the authority_to_authority_preference database table related to the authority of the source/target CRS themselves. If authority is set to “any”, then coordinate operations from any authority will be searched. If authority is a non-empty string different from "any", then coordinate operations will be searched only in that authority namespace (e.g. EPSG). :type authority: str, optional :param accuracy: The minimum desired accuracy (in metres) of the candidate coordinate operations. :type accuracy: float, optional :param allow_ballpark: Set to False to disallow the use of Ballpark transformation in the candidate coordinate operations. Default is to allow. :type allow_ballpark: bool, optional, default=True :param force_over: If True, it will to force the +over flag on the transformation. Requires PROJ 9+. :type force_over: bool, default=False :param only_best: Can be set to True to cause PROJ to error out if the best transformation known to PROJ and usable by PROJ if all grids known and usable by PROJ were accessible, cannot be used. Best transformation should be understood as the transformation returned by :c:func:`proj_get_suggested_operation` if all known grids were accessible (either locally or through network). Note that the default value for this option can be also set with the :envvar:`PROJ_ONLY_BEST_DEFAULT` environment variable, or with the ``only_best_default`` setting of the ``proj.ini`` file. The only_best kwarg overrides the default value if set. Requires PROJ 9.2+. :type only_best: bool, optional, default=True :returns: * *bool* -- True if successful, otherwise False. * *numeric scalar or array* -- Transformed x coordinate(s). * *numeric scalar or array* -- Transformed y coordinate(s). * *numeric scalar or array, optional* -- Transformed z coordinate(s). .. py:method:: transform_vrbag(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = True) -> bool Transform variable resolution BAG file. :param input_file: Path to the input vrbag file. :type input_file: str :param output_file: Path to the output transformed vrbag file. :type output_file: str :param pre_post_checks: If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation. :type pre_post_checks: bool, default=True :param vdatum_check: If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API. :type vdatum_check: bool, default=True :raises FileNotFoundError:: If the input file is not found. :raises TypeError: If the passed BAG file is not a valid variable resolution bag file. :returns: True if successful, otherwise False. :rtype: bool .. py:method:: transform_laz(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = True) -> bool Transform point-cloud LAZ file. :param input_file: Path to the input laz file. :type input_file: str :param output_file: Path to the output transformed laz file. :type output_file: str :param pre_post_checks: If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation. :type pre_post_checks: bool, default=True :param vdatum_check: If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API. :type vdatum_check: bool, default=True :raises FileNotFoundError:: If the input file is not found. :raises TypeError: If the passed LAZ file is not valid. :returns: True if successful, otherwise False. :rtype: bool .. py:method:: transform_xyz(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = True, **kwargs) -> bool Transform point-cloud XYZ file. :param input_file: Path to the input xyz file. :type input_file: str :param output_file: Path to the output transformed xyz file. :type output_file: str :param pre_post_checks: If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation. :type pre_post_checks: bool, default=True :param vdatum_check: If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API. :type vdatum_check: bool, default=True :raises FileNotFoundError:: If the input file is not found. :raises TypeError: If the passed xyz file is not valid. :returns: True if successful, otherwise False. :rtype: bool .. py:method:: transform_geoparquet(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = True) -> bool Transform a geoparquet point file. :param input_file: Path to the input geoparquet file. :type input_file: str :param output_file: Path to the output transformed file. :type output_file: str :param pre_post_checks: If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation. :type pre_post_checks: bool, default=True :param vdatum_check: If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API. :type vdatum_check: bool, default=True :raises FileNotFoundError:: If the input file is not found. :raises TypeError: If the passed file is not valid. :returns: True if successful, otherwise False. :rtype: bool .. py:method:: transform_npz(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = True) -> bool Transform a numpy npz file. :param input_file: Path to the input npz file. :type input_file: str :param output_file: Path to the output transformed npz file. :type output_file: str :param pre_post_checks: If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation. :type pre_post_checks: bool, default=True :param vdatum_check: If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API. :type vdatum_check: bool, default=True :raises FileNotFoundError:: If the input file is not found. :raises TypeError: If the passed npz file is not valid. :returns: True if successful, otherwise False. :rtype: bool .. py:method:: transform_pdal(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = True) -> bool Transform point-cloud data using PDAL. :param input_file: Path to the input file. :type input_file: str :param output_file: Path to the output transformed file. :type output_file: str :param pre_post_checks: If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation. :type pre_post_checks: bool, default=True :param vdatum_check: If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API. :type vdatum_check: bool, default=True :raises FileNotFoundError:: If the input file is not found. :raises TypeError: If the passed file is not valid. :returns: True if successful, otherwise False. :rtype: bool .. py:method:: transform_raster(input_file: str, output_file: str, overview: bool = True, pre_post_checks: bool = True, vdatum_check: bool = True, _allow_different_horizontal_crs: bool = False) -> bool Transform the gdal-supported input rater file (`input_file`) and store the transformed file on the local disk (`output_file`). Horizontal CRS limitation ------------------------- As of this release, raster transformation requires the input and output horizontal CRSs to match. The current pipeline anchors the output to the input's pixel grid (origin, resolution, dimensions) which is well-defined only when both ends share a horizontal CRS; across different horizontal CRSs the existing code path produces non-elevation bands that are silently misregistered. Attempting to run such a transformation raises ``NotImplementedError`` by default. The bypass parameter ``_allow_different_horizontal_crs`` is intended for development testing only and should not be used in production until the different-horizontal-CRS path has been properly implemented. :raises FileNotFoundError:: If the input raster file is not found. :raises NotImplementedError:: If the input file is not supported by gdal, or if the input and output horizontal CRSs differ and the bypass flag is not set. :param input_file: Path to the input raster file (gdal supported). :type input_file: str :param output_file: Path to the transformed raster file. :type output_file: str :param overview: If True, overview bands are added to the output raster file (only GTiff support). :type overview: bool, default=True :param pre_post_checks: If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation. :type pre_post_checks: bool, default=True :param vdatum_check: If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API. :type vdatum_check: bool, default=True :param _allow_different_horizontal_crs: Development bypass for the horizontal-CRS-equality safety check. Leave at its default in production. Setting True permits transformations across different horizontal CRSs but does not guarantee correct results. :type _allow_different_horizontal_crs: bool, default=False :returns: True if successful, otherwise False. :rtype: bool .. py:method:: transform_vector(input_file: str, output_file: str) -> bool Transform the gdal-supported input vector file (`input_file`) and store the transformed file on the local disk (`output_file`). :raises FileNotFoundError:: If the input vector file is not found. :raises NotImplementedError:: If the input vector file is not supported by gdal. :param input_file: Path to the input vector file (gdal supported). :type input_file: str :param output_file: Path to the transformed vector file. :type output_file: str :returns: True if successful, otherwise False. :rtype: bool