vyperdatum.transformer

Attributes

logger

PASS1_TILED_PIXEL_THRESHOLD

PASS1_DEFAULT_TILE_SIZE

Classes

Transformer

Module Contents

vyperdatum.transformer.logger
vyperdatum.transformer.PASS1_TILED_PIXEL_THRESHOLD = 250000000
vyperdatum.transformer.PASS1_DEFAULT_TILE_SIZE = 4096
class vyperdatum.transformer.Transformer(crs_from: pyproj.CRS | int | str, crs_to: pyproj.CRS | int | str, steps: list[str] | None = None)
crs_from
crs_to
steps
classmethod from_GTiff_raster(input_file: str, crs_to: pyproj.CRS | int | str, steps: list[dict] | None) → Transformer

Create a Transformer instance from a GeoTiff raster file.

Raises:

  • FileNotFoundError – If the input file is not found.

  • ValueError – If the input raster does not have the Vyperdatum_Metadata metadata tag.

Parameters:

  • input_file (str) – Path to the input raster file.

  • crs_to (pyproj.crs.CRS or input used to create one) – Projection of output data.

  • steps (Optional[list[dict]]) – 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.

static gdal_extensions() → list[str]

Return a lower-cased list of driver names supported by gdal.

Return type:

list[str]

transform(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = False, **kwargs) → bool

Top-level transform method.

Parameters:

  • input_file (str) – Path to the input file.

  • output_file (str) – Path to the output transformed file.

  • pre_post_checks (bool, default=True) – If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation.

Raises:

  • FileNotFoundError: – If the input file is not found.

  • NotImplementedError: – If the input file is not supported by vyperdatum.

Returns:

True if successful, otherwise False.

Return type:

bool

transform_points(x: list | numpy.ndarray, y: list | numpy.ndarray, z: list | numpy.ndarray, always_xy: bool = False, vdatum_check: bool = False, area_of_interest: pyproj._transformer.AreaOfInterest | None = None, authority: str | None = None, accuracy: float | None = None, allow_ballpark: bool | None = True, force_over: bool = False, only_best: bool | None = True) → tuple[list | numpy.ndarray | None, list | numpy.ndarray | None, list | numpy.ndarray | None]

Conduct point transformation between two coordinate reference systems.

Parameters:

  • x (numeric array) – Input x coordinate(s).

  • y (numeric array) – Input y coordinate(s).

  • z (numeric array, optional) – Input z coordinate(s).

  • always_xy (bool, default=False) – 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.

  • vdatum_check (bool, default=False) – If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API.

  • area_of_interest (AreaOfInterest, optional) – The area of interest to help select the transformation.

  • authority (str, optional) – 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).

  • accuracy (float, optional) – The minimum desired accuracy (in metres) of the candidate coordinate operations.

  • allow_ballpark (bool, optional, default=True) – Set to False to disallow the use of Ballpark transformation in the candidate coordinate operations. Default is to allow.

  • force_over (bool, default=False) – If True, it will to force the +over flag on the transformation. Requires PROJ 9+.

  • only_best (bool, optional, default=True) – 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 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 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+.

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).

transform_vrbag(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = True) → bool

Transform variable resolution BAG file.

Parameters:

  • input_file (str) – Path to the input vrbag file.

  • output_file (str) – Path to the output transformed vrbag file.

  • pre_post_checks (bool, default=True) – If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation.

  • vdatum_check (bool, default=True) – If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API.

Raises:

  • FileNotFoundError: – If the input file is not found.

  • TypeError – If the passed BAG file is not a valid variable resolution bag file.

Returns:

True if successful, otherwise False.

Return type:

bool

transform_laz(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = True) → bool

Transform point-cloud LAZ file.

Parameters:

  • input_file (str) – Path to the input laz file.

  • output_file (str) – Path to the output transformed laz file.

  • pre_post_checks (bool, default=True) – If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation.

  • vdatum_check (bool, default=True) – If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API.

Raises:

  • FileNotFoundError: – If the input file is not found.

  • TypeError – If the passed LAZ file is not valid.

Returns:

True if successful, otherwise False.

Return type:

bool

transform_xyz(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = True, **kwargs) → bool

Transform point-cloud XYZ file.

Parameters:

  • input_file (str) – Path to the input xyz file.

  • output_file (str) – Path to the output transformed xyz file.

  • pre_post_checks (bool, default=True) – If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation.

  • vdatum_check (bool, default=True) – If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API.

Raises:

  • FileNotFoundError: – If the input file is not found.

  • TypeError – If the passed xyz file is not valid.

Returns:

True if successful, otherwise False.

Return type:

bool

transform_geoparquet(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = True) → bool

Transform a geoparquet point file.

Parameters:

  • input_file (str) – Path to the input geoparquet file.

  • output_file (str) – Path to the output transformed file.

  • pre_post_checks (bool, default=True) – If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation.

  • vdatum_check (bool, default=True) – If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API.

Raises:

  • FileNotFoundError: – If the input file is not found.

  • TypeError – If the passed file is not valid.

Returns:

True if successful, otherwise False.

Return type:

bool

transform_npz(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = True) → bool

Transform a numpy npz file.

Parameters:

  • input_file (str) – Path to the input npz file.

  • output_file (str) – Path to the output transformed npz file.

  • pre_post_checks (bool, default=True) – If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation.

  • vdatum_check (bool, default=True) – If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API.

Raises:

  • FileNotFoundError: – If the input file is not found.

  • TypeError – If the passed npz file is not valid.

Returns:

True if successful, otherwise False.

Return type:

bool

transform_pdal(input_file: str, output_file: str, pre_post_checks: bool = True, vdatum_check: bool = True) → bool

Transform point-cloud data using PDAL.

Parameters:

  • input_file (str) – Path to the input file.

  • output_file (str) – Path to the output transformed file.

  • pre_post_checks (bool, default=True) – If True, runs a series of validation checks, such as validating the input and output CRSs, before and after transformation operation.

  • vdatum_check (bool, default=True) – If True, a random sample of the transformed data are compared with transformation outcomes produced by Vdatum REST API.

Raises:

  • FileNotFoundError: – If the input file is not found.

  • TypeError – If the passed file is not valid.

Returns:

True if successful, otherwise False.

Return type:

bool

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

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.

  • NotImplementedError: – If the input vector file is not supported by gdal.

Parameters:

  • input_file (str) – Path to the input vector file (gdal supported).

  • output_file (str) – Path to the transformed vector file.

Returns:

True if successful, otherwise False.

Return type:

bool