From dc663b5d20a65707b5b35a335cc1e770f5004223 Mon Sep 17 00:00:00 2001
From: Larry Gritz <lg@larrygritz.com>
Date: Fri, 20 Sep 2024 17:01:13 -0700
Subject: [PATCH] docs: IBA::st_warp was missing from the documentation (#4431)

Oops.

I didn't really have time to add an "example" right now. I hope to
return to beef this up (or that somebody else takes it on).

Signed-off-by: Larry Gritz <lg@larrygritz.com>
---
 src/doc/imagebufalgo.rst   | 37 +++++++++++++++++++++++++++++++++++++
 src/doc/pythonbindings.rst | 20 ++++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/src/doc/imagebufalgo.rst b/src/doc/imagebufalgo.rst
index eaf288e256..2559dc9f1f 100644
--- a/src/doc/imagebufalgo.rst
+++ b/src/doc/imagebufalgo.rst
@@ -1112,6 +1112,43 @@ Shuffling channels
 |
 
 
+.. doxygengroup:: st_warp
+..
+
+..
+  Examples:
+
+    FIX ME! This is not complete, examples need to be added to docs-examples-imagebufalgo.{cpp,py}
+    .. tabs::
+
+       .. tab:: C++
+             .. literalinclude:: ../../testsuite/docs-examples-cpp/src/docs-examples-imagebufalgo.cpp
+              :language: c++
+              :start-after: BEGIN-imagebufalgo-st_warp
+              :end-before: END-imagebufalgo-st_warp
+              :dedent: 4
+
+       .. tab:: Python
+          .. literalinclude:: ../../testsuite/docs-examples-python/src/docs-examples-imagebufalgo.py
+              :language: py
+              :start-after: BEGIN-imagebufalgo-st_warp
+              :end-before: END-imagebufalgo-st_warp
+              :dedent: 4
+
+       .. tab:: oiiotool
+         .. code-block:: bash
+
+             oiiotool mandrill.tif distortion_st.tif --st_warp -o mandrill_distorted.tif
+
+             # Using an `st` map authored in terms of a lower-left origin (e.g. by
+             # Nuke), so flip the vertical (`t`) coordinate.
+             oiiotool mandrill.tif st_from_nuke.tif --st_warp:filter=triangle:flip_t=1 -o mandrill_distorted.tif
+
+             oiiotool grid.exr --st_warp 0.7071068,0.7071068,0,-0.7071068,0.7071068,0,20,-8.284271,1 -o out.exr
+
+|
+
+
 .. doxygenfunction:: demosaic(const ImageBuf &src, KWArgs options = {}, ROI roi = {}, int nthreads = 0)
 ..
 
diff --git a/src/doc/pythonbindings.rst b/src/doc/pythonbindings.rst
index ba304408ac..65eee9ff75 100644
--- a/src/doc/pythonbindings.rst
+++ b/src/doc/pythonbindings.rst
@@ -2696,6 +2696,26 @@ Image transformations and data movement
 
 
 
+.. py:method:: ImageBuf ImageBufAlgo.st_warp (src, M, filtername="", filtersize=0.0, wrap="default", recompute_roi=False, roi=ROI.All, nthreads=0)
+               bool ImageBufAlgo.st_warp (dst, src, M, filtername="", filtersize=0.0, wrap="default", recompute_roi=False, roi=ROI.All, nthreads=0)
+
+    Compute a warped (transformed) copy of `src`, with the warp specified by
+    `M` consisting of 9 floating-point numbers representing a 3x3
+    transformation matrix.  If the filter and size are not specified, an
+    appropriate default will be chosen.
+
+    Example:
+
+    .. code-block:: python
+
+        # distortion_st.tif is a map where every pixel value contains the 2D
+        # coordinate of where to copy from.
+        Distort = ImageBuf("distortion_st.tif")
+        Src = ImageBuf("tahoe.exr")
+        Dst = ImageBufAlgo.st_warp(Src, Distort)
+
+
+
 .. py:method:: ImageBuf ImageBufAlgo.resize (src, filtername="", filtersize=0.0, roi=ROI.All, nthreads=0)
                bool ImageBufAlgo.resize (dst, src, filtername="", filtersize=0.0, roi=ROI.All, nthreads=0)