docs: Make an example of doc-to-test in the imagebufalgo chapter (#4012)

Slightly different set of issues, so I wanted to provide a full example
for anyone who wants to work on this chapter.

Signed-off-by: Larry Gritz <lg@larrygritz.com>

Author: lgritz

src/doc/imagebufalgo.rst

@@ -998,19 +998,27 @@ Shuffling channels
 
     .. tabs::
 
-       .. code-tab:: c++
+       .. tab:: C++
 
-          ImageBuf A ("grid.jpg");
-          ImageBuf B = ImageBufAlgo::circular_shift (A, 70, 30);
+          .. literalinclude:: ../../testsuite/docs-examples-cpp/src/docs-examples-imagebufalgo.cpp
+             :language: c++
+             :start-after: BEGIN-imagebufalgo-cshift
+             :end-before: END-imagebufalgo-cshift
+             :dedent: 4
 
-       .. code-tab:: py
+       .. tab:: Python
 
-          A = ImageBuf("tahoe.jpg")
-          A = ImageBufAlgo.circular_shift (A, 70, 30)
+          .. literalinclude:: ../../testsuite/docs-examples-python/src/docs-examples-imagebufalgo.py
+             :language: c++
+             :start-after: BEGIN-imagebufalgo-cshift
+             :end-before: END-imagebufalgo-cshift
+             :dedent: 4
 
-       .. code-tab:: bash oiiotool
+       .. tab:: oiiotool
+
+          .. code-block:: bash
 
-          oiiotool tahoe.jpg --cshift +70+30 -o out.jpg
+             oiiotool tahoe.jpg --cshift +70+30 -o out.jpg
 
 .. |cshiftimg1| image:: figures/grid-small.jpg
    :width: 2.0 in
@@ -1063,8 +1071,6 @@ Shuffling channels
 .. doxygengroup:: resize
 ..
 
-  Examples::
-
   Examples:
 
     .. tabs::

testsuite/common/grid-small.exr

@@ -1,3 +1,5 @@
+cshift.exr           :  256 x  256, 4 channel, half openexr
+    SHA-1: 000F95FDC44D4DBDA8B4041C2506149C7AE28ACA
 Comparing "simple.tif" and "ref/simple.tif"
 PASS
 Comparing "scanlines.tif" and "ref/scanlines.tif"

testsuite/docs-examples-cpp/ref/out.txt

@@ -6,19 +6,33 @@
 
 
 if platform.system() == 'Windows' :
-    prefix = "Release\\"
+    prefix = ".\\build\\Release\\"
 else :
-    prefix = "./"
+    prefix = "./build/"
 
-# command += "echo test_source_dir=" + test_source_dir + " >> build.txt ;"
-command += run_app("cmake " + test_source_dir + " -DCMAKE_BUILD_TYPE=Release >> build.txt 2>&1", silent=True)
-command += run_app("cmake --build . --config Release >> build.txt 2>&1", silent=True)
+# Prep:
+command += run_app("cmake -E copy ../common/grid-small.exr grid.exr")
+
+# Build
+command += run_app("cmake -S " + test_source_dir + " -B build -DCMAKE_BUILD_TYPE=Release >> build.txt 2>&1", silent=True)
+command += run_app("cmake --build build --config Release >> build.txt 2>&1", silent=True)
 
 # Run the examples for each chapter
 for chapter in [ "imageioapi", "imageoutput", "imageinput", "writingplugins",
                  "imagecache", "texturesys", "imagebuf", "imagebufalgo" ] :
     command += run_app(prefix + "docs-examples-" + chapter)
 
+# hashes merely check that the images don't change, but saves us the space
+# of checking in a full copy of the image if it's not needed.
+hashes = [
+    # Outputs from the ImageBufAlgo chapter:
+    "cshift.exr",
+]
+for file in hashes :
+    command += info_command(file, verbose=False)
+
+# outputs should contain all the images that need to be checked directly
+# and need the images checked into the ref directory.
 outputs = [
     # Outputs from the ImageOutput chapter:
     "simple.tif", "scanlines.tif",

testsuite/docs-examples-cpp/run.py

@@ -12,6 +12,8 @@
 
 // BEGIN-imagebufalgo-example1
 #include <OpenImageIO/imageio.h>
+#include <OpenImageIO/imagebuf.h>
+#include <OpenImageIO/imagebufalgo.h>
 using namespace OIIO;
 
 void example1()
@@ -31,11 +33,75 @@ void example1()
 ///////////////////////////////////////////////////////////////////////////
 
 
+// Section: ImageBufAlgo common principles
+
+
+// Section: Pattern Generation
+
+
+// Section: Image transformation and data movement
+
+void example_circular_shift()
+{
+// BEGIN-imagebufalgo-cshift
+    ImageBuf A("grid.exr");
+    ImageBuf B = ImageBufAlgo::circular_shift(A, 70, 30);
+    B.write("cshift.exr");
+// END-imagebufalgo-cshift
+}
+
+
+
+// Section: Image Arithmetic
+
+
+// Section: Image comparison and statistics
+
+
+// Section: Convolution and frequency-space algorithms
+
+
+// Section: Image enhancement / restoration
+
+
+// Section: Morphological filters
+
+
+// Section: Color space conversion
+
+
+// Section: Import / export
+
+
+
+
 
 int main(int /*argc*/, char** /*argv*/)
 {
     // Each example function needs to get called here, or it won't execute
     // as part of the test.
     example1();
+
+    // Section: ImageBufAlgo common principles
+
+    // Section: Pattern Generation
+
+    // Section: Image transformation and data movement
+    example_circular_shift();
+
+    // Section: Image Arithmetic
+
+    // Section: Image comparison and statistics
+
+    // Section: Convolution and frequency-space algorithms
+
+    // Section: Image enhancement / restoration
+
+    // Section: Morphological filters
+
+    // Section: Color space conversion
+
+    // Section: Import / export
+
     return 0;
 }

testsuite/docs-examples-cpp/src/docs-examples-imagebufalgo.cpp

@@ -1,3 +1,5 @@
+cshift.exr           :  256 x  256, 4 channel, half openexr
+    SHA-1: 000F95FDC44D4DBDA8B4041C2506149C7AE28ACA
 Comparing "simple.tif" and "ref/simple.tif"
 PASS
 Comparing "scanlines.tif" and "ref/scanlines.tif"

testsuite/docs-examples-python/ref/out.txt

@@ -5,11 +5,25 @@
 # https://github.com/AcademySoftwareFoundation/OpenImageIO
 
 
+# Prep:
+command += run_app("cmake -E copy ../common/grid-small.exr grid.exr")
+
 # Run the examples for each chapter
 for chapter in [ "imageioapi", "imageoutput", "imageinput", "writingplugins",
                  "imagecache", "texturesys", "imagebuf", "imagebufalgo" ] :
     command += pythonbin + " src/docs-examples-" + chapter + ".py >> out.txt ;"
 
+# hashes merely check that the images don't change, but saves us the space
+# of checking in a full copy of the image if it's not needed.
+hashes = [
+    # Outputs from the ImageBufAlgo chapter:
+    "cshift.exr",
+]
+for file in hashes :
+    command += info_command(file, verbose=False)
+
+# outputs should contain all the images that need to be checked directly
+# and need the images checked into the ref directory.
 outputs = [
     # Outputs from the ImageOutput chapter:
     "simple.tif", "scanlines.tif",

testsuite/docs-examples-python/run.py

@@ -18,6 +18,7 @@
 
 # BEGIN-imagebufalgo-example1
 import OpenImageIO as oiio
+from OpenImageIO import *
 import numpy as np
 
 def example1() :
@@ -37,10 +38,69 @@ def example1() :
 ############################################################################
 
 
+# Section: ImageBufAlgo common principles
+
+
+# Section: Pattern Generation
+
+
+# Section: Image transformation and data movement
+
+def example_circular_shift() :
+    # BEGIN-imagebufalgo-cshift
+    A = ImageBuf("grid.exr")
+    B = ImageBufAlgo.circular_shift(A, 70, 30)
+    # END-imagebufalgo-cshift
+    B.write("cshift.exr");
+
+
+# Section: Image Arithmetic
+
+
+# Section: Image comparison and statistics
+
+
+# Section: Convolution and frequency-space algorithms
+
+
+# Section: Image enhancement / restoration
+
+
+# Section: Morphological filters
+
+
+# Section: Color space conversion
+
+
+# Section: Import / export
+
+
+
 
 
 
 if __name__ == '__main__':
     # Each example function needs to get called here, or it won't execute
     # as part of the test.
     example1()
+
+    # Section: ImageBufAlgo common principles
+
+    # Section: Pattern Generation
+
+    # Section: Image transformation and data movement
+    example_circular_shift()
+
+    # Section: Image Arithmetic
+
+    # Section: Image comparison and statistics
+
+    # Section: Convolution and frequency-space algorithms
+
+    # Section: Image enhancement / restoration
+
+    # Section: Morphological filters
+
+    # Section: Color space conversion
+
+    # Section: Import / export