From eccaa6896da1ec3fed34cef0f188ea0b53660412 Mon Sep 17 00:00:00 2001 From: Daniel Baston Date: Fri, 13 Sep 2024 13:56:28 -0400 Subject: [PATCH 1/2] Doc: Clarify behavior of gdalwarp -et option --- doc/source/programs/gdalwarp.rst | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/doc/source/programs/gdalwarp.rst b/doc/source/programs/gdalwarp.rst index 27c5d115e3fb..c449d6c07c48 100644 --- a/doc/source/programs/gdalwarp.rst +++ b/doc/source/programs/gdalwarp.rst @@ -214,10 +214,10 @@ with control information. .. option:: -et - Error threshold for transformation approximation (in pixel units - - defaults to 0.125, unless, starting with GDAL 2.1, the RPC_DEM transformer + Error threshold for transformation approximation in source pixel units. + Defaults to 0.125 source pixels unless the ``RPC_DEM`` transformer option is specified, in which case, an exact transformer, i.e. - err_threshold=0, will be used). + ``err_threshold=0``, will be used). .. option:: -refine_gcps [] @@ -559,17 +559,21 @@ Approximate transformation -------------------------- By default :program:`gdalwarp` uses a linear approximator for the -transformations with a permitted error of 0.125 pixels. The approximator -basically transforms three points on a scanline: the start, end and middle. -Then it compares the linear approximation of the center based on the end points -to the real thing and checks the error. If the error is less than the error -threshold then the remaining points are approximated (in two chunks utilizing -the center point). If the error exceeds the threshold, the scanline is split -into two sections, and the approximator is recursively applied to each section -until the error is less than the threshold or all points have been exactly -computed. - -The error threshold (in pixels) can be controlled with the gdalwarp +transformations with a permitted error of 0.125 pixels in the source dataset. +The approximator precisely transforms three points per output scanline (the +start, middle, and end) from a row and column in the output dataset to a +row and column in the source dataset. +It then compares a linear approximation of the center point coordinates to the +precisely transformed value. +If the sum of the horizontal and vertical errors is less than the error +threshold then the remaining source points are approximated using linear +interpolation between the start and middle point, and between the middle and +end point. +If the error exceeds the threshold, the scanline is split into two sections and +the approximator is recursively applied to each section until the error is less +than the threshold or all points have been exactly computed. + +The error threshold (in source dataset pixels) can be controlled with the gdalwarp :option:`-et` switch. If you want to compare a true pixel-by-pixel reprojection use :option:`-et 0` which disables this approximator entirely. From e3f54649d5273311de28404f2c84dad53dc01e36 Mon Sep 17 00:00:00 2001 From: Daniel Baston Date: Sat, 14 Sep 2024 17:24:19 -0400 Subject: [PATCH 2/2] GDALCreateApproxTransformer: Clarify dfMaxError description in docstring [ci skip] --- alg/gdaltransformer.cpp | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/alg/gdaltransformer.cpp b/alg/gdaltransformer.cpp index 256a79ed6b8b..3eda4c75b31c 100644 --- a/alg/gdaltransformer.cpp +++ b/alg/gdaltransformer.cpp @@ -3828,7 +3828,8 @@ static CPLXMLNode *GDALSerializeApproxTransformer(void *pTransformArg) * @param pBaseTransformArg the callback argument for the high precision * transformer. * @param dfMaxError the maximum cartesian error in the "output" space that - * is to be accepted in the linear approximation. + * is to be accepted in the linear approximation, evaluated as a Manhattan + * distance. * * @return callback pointer suitable for use with GDALApproxTransform(). It * should be deallocated with GDALDestroyApproxTransformer().