From db31b6dfa9c8fe37d5706d95ce81012b8db3c3b9 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Wed, 22 Jan 2020 18:31:26 +0100 Subject: Merge RFC4 (#1865) This commit is the result of the squashing of rfc4_dev branch in a single commit. It implements mostly RFC 4 related work. * Grid handling: - remove obsolete and presumably unfinished implementation of grid catalog functionality - all grid functionality is in grids.cpp/.hpp - vertical and horizontal grid shift: rework to no longer load whole grid into memory - remove hgrids and vgrids member from PJ structure, and store them in hgridshift/vgridshift/deformation structures - build systems: add optional libtiff dependency. Must be explicitly disabled if not desired - add support for horizontal and vertical grids in GeoTIFF, if libtiff is available - add GenericShiftGridSet and GenericShiftGrid classes, relying on TIFF grids, that can be used for generic purpose grid-based adjustment - add a +proj=xyzgridshift method to perform geocentric translation by grid. Used for French NTF to RGF93 transformation using gr3df97a.tif grid - deformation: add support for +grids= for GeoTIFF grids - horizontal grid shift: fix failures on points slightly outside a subgrid (fixes #209) * File management: - add a filemanager.cpp/.hpp to deal with file related work - test for legacy proj_api.h fileapi - proj.h: add proj_context_set_fileapi() and proj_context_set_sqlite3_vfs_name() (fixes #866) - add capability to read resource files from the user writable directory * Network access: - build systems: add optional curl dependency - add a curl-based default implementation for network related functionality - proj.h: add C API to control network functionality, and optionaly provide network callbacks - add data/proj.ini with default settings - add a SQLite3 local cache of downloaded chunks - add proj_is_download_needed() and proj_download_file() * Use Win32 Unicode APIs and expect all strings to be UTF-8 (fixes #1765) For backward compatibility, if PROJ_LIB content is found to be not UTF-8 or pointing to a non existing directory, then an attempt at interpretating it in the ANSI page encoding is done. proj_context_set_search_paths() now assumes strings to be in UTF-8, and functions returning paths will also return values in UTF-8. --- .../operations/transformations/deformation.rst | 39 +++++++++- docs/source/operations/transformations/index.rst | 1 + .../operations/transformations/xyzgridshift.rst | 91 ++++++++++++++++++++++ 3 files changed, 129 insertions(+), 2 deletions(-) create mode 100644 docs/source/operations/transformations/xyzgridshift.rst (limited to 'docs/source/operations/transformations') diff --git a/docs/source/operations/transformations/deformation.rst b/docs/source/operations/transformations/deformation.rst index 3a9d025c..02924a25 100644 --- a/docs/source/operations/transformations/deformation.rst +++ b/docs/source/operations/transformations/deformation.rst @@ -35,6 +35,9 @@ GTX format. Both grids are expected to contain grid-values in units of mm/year. GDAL both reads and writes both file formats. Using GDAL for construction of new grids is recommended. +Starting with PROJ 7.0, use of a GeoTIFF format is recommended to store both +the horizontal and vertical velocities. + Example ------------------------------------------------------------------------------- @@ -89,13 +92,15 @@ Parameters .. option:: +xy_grids= - Comma-separated list of grids to load. If a grid is prefixed by an `@` the + Comma-separated list of grids to load. If a grid is prefixed by an ``@`` the grid is considered optional and PROJ will the not complain if the grid is not available. - Grids for the horizontla component of a deformation model is expected to be + Grids for the horizontal component of a deformation model is expected to be in CTable2 format. + .. note:: :option:`+xy_grids` is mutually exclusive with :option:`+grids` + .. option:: +z_grids= Comma-separated list of grids to load. If a grid is prefixed by an `@` the @@ -105,6 +110,36 @@ Parameters Grids for the vertical component of a deformation model is expected to be in either GTX format. + .. note:: :option:`+z_grids` is mutually exclusive with :option:`+grids` + +.. option:: +grids= + + .. versionadded:: 7.0.0 + + Comma-separated list of grids to load. If a grid is prefixed by an `@` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids should be in GeoTIFF format with the first 3 components being + respectively the easting, northing and up velocities in mm/year. + Setting the Description and Unit Type GDAL band metadata items is strongly + recommended, so that gdalinfo reports: + + :: + + Band 1 Block=... Type=Float32, ColorInterp=Gray + Description = east_velocity + Unit Type: mm/year + Band 2 Block=... Type=Float32, ColorInterp=Undefined + Description = north_velocity + Unit Type: mm/year + Band 3 Block=... Type=Float32, ColorInterp=Undefined + Description = up_velocity + Unit Type: mm/year + + .. note:: :option:`+grids` is mutually exclusive with :option:`+xy_grids` + and :option:`+z_grids` + .. option:: +t_epoch= Central epoch of transformation given in decimalyears. Will be used in diff --git a/docs/source/operations/transformations/index.rst b/docs/source/operations/transformations/index.rst index d4bbf4e0..6bd503d4 100644 --- a/docs/source/operations/transformations/index.rst +++ b/docs/source/operations/transformations/index.rst @@ -19,3 +19,4 @@ systems are based on different datums. molobadekas hgridshift vgridshift + xyzgridshift diff --git a/docs/source/operations/transformations/xyzgridshift.rst b/docs/source/operations/transformations/xyzgridshift.rst new file mode 100644 index 00000000..30537032 --- /dev/null +++ b/docs/source/operations/transformations/xyzgridshift.rst @@ -0,0 +1,91 @@ +.. _xyzgridshift: + +================================================================================ +Geocentric grid shift +================================================================================ + +.. versionadded:: 7.0.0 + +Geocentric translation using a grid shift + ++-----------------+-------------------------------------------------------------------+ +| **Domain** | 3D | ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ + +Perform a geocentric translation by bilinear interpolation of dx, dy, dz +translation values from a grid. The grid is referenced against either the +2D geographic CRS corresponding to the input (or sometimes output) CRS. + +This method is described (in French) in :cite:`NTF_88` +and as EPSG operation method code 9655 in :cite:`IOGP2018` (ยง2.4.4.1.1 +France geocentric interpolation). + +The translation in the grids are added to the input coordinates in the forward direction, +and subtracted in the reverse direction. +By default (if ``grid_ref=input_crs``), in the forward direction, the input coordinates +are converted to their geographic equivalent to directly read and interpolate from +the grid. In the reverse direction, an iterative method is used to be able to find +the grid locations to read. +If ``grid_ref=output_crs`` is used, then the reverse strategy is applied: iterative +method in the forward direction, and direct read in the reverse direction. + +Example +------------------------------------------------------------------------------- + +NTF to RGF93 transformation using gr3df97a.tif grid + +:: + + +proj=pipeline + +step +proj=push +v_3 + +step +proj=cart +ellps=clrk80ign + +step +proj=xyzgridshift +grids=gr3df97a.tif +grid_ref=output_crs +ellps=GRS80 + +step +proj=cart +ellps=GRS80 +inv + +step +proj=pop +v_3 + +Parameters +################################################################################ + +The ellipsoid parameters should be the ones consistent with ``grid_ref``. +They are used to perform a geocentric to geographic conversion to find the +translation parameters. + + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. include:: ../options/ellps.rst + +.. option:: +grids= + + Comma-separated list of grids to load. If a grid is prefixed by an ``@`` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids are expected to be in GeoTIFF format. If no metadata is provided, + the first, second and third samples are assumed to be the geocentric + translation along X, Y and Z axis respectively, in metres. + +Optional ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +grid_ref=input_crs/output_crs + + Specify in which CRS the grid is referenced to. The default value is + input_crs. That is the grid is referenced in the geographic CRS corresponding + to the input geocentric CRS. + + If output_crs is specified, the grid is referenced in the geographic CRS corresponding + to the output geocentric CRS. This is for example the case for the French + gr3df97a.tif grid converting from NTF to RGF93, but referenced against RGF93. + Thus in the forward direction (NTF->RGF93), an iterative method is used to find + the appropriate shift. + +.. option:: +multiplier= + + Specify the multiplier to apply to the grid values. Defaults to 1.0 + -- cgit v1.2.3