testsuite: test the oiiotool 'Channel reordering and padding' doc examples

src/doc/oiiotool.md

@@ -793,48 +793,69 @@ oiiotool RGB.tif --chsum:weight=.2126,.7152,.0722 -o luma.tif
 
 Copy just the color from an RGBA file, truncating the A, yielding RGB only:
 
-```
-oiiotool rgba.tif --ch R,G,B -o rgb.tif
+```{literalinclude} ../../testsuite/oiiotool-copy/run.py
+:language: bash
+:start-after: BEGIN-docs-channels-copy-color
+:end-before: END-docs-channels-copy-color
+:dedent:
 ```
 
 Zero out the red and green channels:
 
-```
-oiiotool rgb.tif --ch R=0,G=0,B -o justblue.tif
+```{literalinclude} ../../testsuite/oiiotool-copy/run.py
+:language: bash
+:start-after: BEGIN-docs-channels-zero-rg
+:end-before: END-docs-channels-zero-rg
+:dedent:
 ```
 
 Swap the red and blue channels from an RGBA image:
 
-```
-oiiotool rgba.tif --ch R=B,G,B=R,A -o bgra.tif
+```{literalinclude} ../../testsuite/oiiotool-copy/run.py
+:language: bash
+:start-after: BEGIN-docs-channels-swap-rb
+:end-before: END-docs-channels-swap-rb
+:dedent:
 ```
 
 Extract just the named channels from a many-channel image, as efficiently as
 possible (avoiding memory and I/O for the unused channels):
 
-```
-oiiotool -i:ch=R,G,B manychannels.exr -o rgb.exr
+```{literalinclude} ../../testsuite/oiiotool-copy/run.py
+:language: bash
+:start-after: BEGIN-docs-channels-extract
+:end-before: END-docs-channels-extract
+:dedent:
 ```
 
 Add an alpha channel to an RGB image, setting it to 1.0 everywhere, and
 naming it "A" so it will be recognized as an alpha channel:
 
-```
-oiiotool rgb.tif --ch R,G,B,A=1.0 -o rgba.tif
+```{literalinclude} ../../testsuite/oiiotool-copy/run.py
+:language: bash
+:start-after: BEGIN-docs-channels-add-alpha-const
+:end-before: END-docs-channels-add-alpha-const
+:dedent:
 ```
 
 Add an alpha channel to an RGB image, setting it to be the same as the R
 channel and naming it "A" so it will be recognized as an alpha channel:
 
-```
-oiiotool rgb.tif --ch R,G,B,A=R -o rgba.tif
+```{literalinclude} ../../testsuite/oiiotool-copy/run.py
+:language: bash
+:start-after: BEGIN-docs-channels-add-alpha-from-r
+:end-before: END-docs-channels-add-alpha-from-r
+:dedent:
 ```
 
 Add a *z* channel to an RGBA image, setting it to 3.0 everywhere, and naming
 it "Z" so it will be recognized as a depth channel:
 
-```
-oiiotool rgba.exr --ch R,G,B,A,Z=3.0 -o rgbaz.exr
+```{literalinclude} ../../testsuite/oiiotool-copy/run.py
+:language: bash
+:start-after: BEGIN-docs-channels-add-z
+:end-before: END-docs-channels-add-z
+:dedent:
 ```
 
 ### Copy metadata from one image to another

testsuite/oiiotool-copy/ref/out.txt

@@ -84,6 +84,18 @@ chname.exr           :   38 x   38, 5 channel, float openexr
     screenWindowWidth: 1
     oiio:subimages: 1
     openexr:lineOrder: "increasingY"
+rgb.tif              :   64 x   64, 3 channel, uint8 tiff
+    SHA-1: 0A989C358454065E07E7375FCAD8064FEEB54256
+justblue.tif         :   64 x   64, 3 channel, uint8 tiff
+    SHA-1: E664F311950331458E61F0281A311A96D9068EF6
+bgra.tif             :   64 x   64, 4 channel, uint8 tiff
+    SHA-1: 3F9154AE01632D66C4792D770CDC9BF031EDF918
+rgb.exr              :   64 x   64, 3 channel, half openexr
+    SHA-1: 33C471A3638AB1286B97F5D27A977077E8FEE802
+rgba.tif             :   64 x   64, 4 channel, uint8 tiff
+    SHA-1: 7DF6F499949D5B0847BCAD56D0FEBEF16A13A581
+rgbaz.exr            :   64 x   64, 5 channel, half openexr
+    SHA-1: E75770A20AF2FDCAD410A4FA02841388123E6583
 Reading green.exr
 green.exr            :   64 x   64, 3 channel, half openexr
     SHA-1: 8B61993247469F3C208CA894D71856727B11606A

testsuite/oiiotool-copy/run.py

@@ -108,6 +108,55 @@
 command += oiiotool ("src/rgbaz.exr --chnames Red,,,,Depth -o chname.exr")
 command += info_command ("chname.exr", safematch=1)
 
+
+# The oiiotool command lines in the BEGIN-docs/END-docs brackets below are
+# the same lines that appear verbatim in the "Channel reordering and
+# padding" section of the docs -- src/doc/oiiotool.md literalincludes each
+# command between its markers, so any change made here must be made in the
+# docs as well, and vice versa. The setup images use asymmetric per-channel
+# colors on purpose: with the default black/white checker, R and B are
+# identical in every pixel, which would make the swap and alpha-from-R
+# examples produce outputs indistinguishable by content hash.
+command += run_commands("""
+    oiiotool -pattern checker:color1=0.9,0.2,0.1,1:color2=0.1,0.4,0.9,1 64x64 4 -d uint8 -o rgba.tif
+    oiiotool -pattern constant:color=0.25,0.5,0.75,0.8 64x64 4 -d half -o rgba.exr
+    oiiotool -pattern constant:color=0.1,0.5,0.9,0.3,0.7 64x64 5 -d half --chnames R,G,B,A,Z -o manychannels.exr
+    """)
+
+command += run_commands("""
+    # BEGIN-docs-channels-copy-color
+    oiiotool rgba.tif --ch R,G,B -o rgb.tif
+    # END-docs-channels-copy-color
+    # BEGIN-docs-channels-zero-rg
+    oiiotool rgb.tif --ch R=0,G=0,B -o justblue.tif
+    # END-docs-channels-zero-rg
+    # BEGIN-docs-channels-swap-rb
+    oiiotool rgba.tif --ch R=B,G,B=R,A -o bgra.tif
+    # END-docs-channels-swap-rb
+    # BEGIN-docs-channels-extract
+    oiiotool -i:ch=R,G,B manychannels.exr -o rgb.exr
+    # END-docs-channels-extract
+    # BEGIN-docs-channels-add-alpha-const
+    oiiotool rgb.tif --ch R,G,B,A=1.0 -o rgba.tif
+    # END-docs-channels-add-alpha-const
+    # BEGIN-docs-channels-add-alpha-from-r
+    oiiotool rgb.tif --ch R,G,B,A=R -o rgba.tif
+    # END-docs-channels-add-alpha-from-r
+    # BEGIN-docs-channels-add-z
+    oiiotool rgba.exr --ch R,G,B,A,Z=3.0 -o rgbaz.exr
+    # END-docs-channels-add-z
+    """)
+
+# Verify the results of the documented examples by content hash, so that any
+# change in the documented behavior turns this test red.
+command += info_command("rgb.tif", verbose=False, hash=True)
+command += info_command("justblue.tif", verbose=False, hash=True)
+command += info_command("bgra.tif", verbose=False, hash=True)
+command += info_command("rgb.exr", verbose=False, hash=True)
+command += info_command("rgba.tif", verbose=False, hash=True)
+command += info_command("rgbaz.exr", verbose=False, hash=True)
+
+
 # test --crop
 command += oiiotool ("../common/grid.tif --crop 100x400+50+200 -o crop.tif")