From 3931396f2057b93ef2a8a6b4dbfb45cbcb2a85fd Mon Sep 17 00:00:00 2001
From: Even Rouault <even.rouault@spatialys.com>
Date: Mon, 16 Sep 2024 22:16:16 +0200
Subject: [PATCH] gdalwarper.cpp: more details about OPTIMIZE_SIZE
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

and document XSCALE and YSCALE warping options

Ref #10813
---
 alg/gdalwarper.cpp               | 17 ++++++++++++++++-
 doc/source/spelling_wordlist.txt |  1 +
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/alg/gdalwarper.cpp b/alg/gdalwarper.cpp
index ca78650897b3..fd28bb15b7df 100644
--- a/alg/gdalwarper.cpp
+++ b/alg/gdalwarper.cpp
@@ -1167,6 +1167,17 @@ CPLErr GDALWarpDstAlphaMasker(void *pMaskFuncArg, int nBandCount,
  * will be selected, not just those whose center point falls within the
  * polygon.</li>
  *
+ * <li>XSCALE=<ratio>: Ratio expressing the resampling factor along the target
+ * horizontal axis. Equals to one for no resampling, below one for downsampling
+ * and above one for upsampling. This is automatically computed, for each
+ * processing chunk, and may thus vary among them, depending on the
+ * shape of output regions vs input regions. Such variations can be undesired
+ * in some situations. If the resampling factor can be considered as constant
+ * over the warped area, setting a constant value can lead to more reproducible
+ * pixel output.</li>
+ *
+ * <li>YSCALE=<ratio>: Same as XSCALE, but along the horizontal axis.</li>
+ *
  * <li>OPTIMIZE_SIZE: This defaults to FALSE, but may be set to TRUE
  * typically when writing to a compressed dataset (GeoTIFF with
  * COMPRESS creation option set for example) for achieving a smaller
@@ -1176,7 +1187,11 @@ CPLErr GDALWarpDstAlphaMasker(void *pMaskFuncArg, int nBandCount,
  * of the file. However sticking to target block size may cause major
  * processing slowdown for some particular reprojections. Starting
  * with GDAL 3.8, OPTIMIZE_SIZE mode is automatically enabled when it is safe
- * to do so.</li>
+ * to do so.
+ * As this parameter influences the shape of warping chunk, and by default the
+ * XSCALE and YSCALE parameters are computed per warping chunk, this parameter may
+ * influence the pixel output.
+ * </li>
  *
  * <li>NUM_THREADS: (GDAL >= 1.10) Can be set to a numeric value or ALL_CPUS to
  * set the number of threads to use to parallelize the computation part of the
diff --git a/doc/source/spelling_wordlist.txt b/doc/source/spelling_wordlist.txt
index e1447916c7b9..991c9919ec42 100644
--- a/doc/source/spelling_wordlist.txt
+++ b/doc/source/spelling_wordlist.txt
@@ -3360,6 +3360,7 @@ UpdateFeature
 updateTime
 UpperLeftX
 UpperLeftY
+upsampling
 upsert
 uri
 url