From fb454b6fde69bfd480409d022f11e939fe5245ca Mon Sep 17 00:00:00 2001 From: linsen <251731047+linsen458-spec@users.noreply.github.com> Date: Mon, 14 Sep 2026 15:13:52 +0800 Subject: [PATCH 1/2] testing: convert 'Channel reordering and padding' docs to a docs-verbatim testsuite test The oiiotool command lines from the 'Channel reordering and padding' section of the oiiotool docs now live verbatim inside run_commands() blocks in the run.py, bracketed by BEGIN/END-docs-channels-* marker comments, and src/doc/oiiotool.md literalincludes each command between its markers -- so the docs and the test are literally the same lines and can no longer drift apart. 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 made the channel-swap and alpha-from-red examples produce outputs indistinguishable by content hash. Contributes to #3992 Assisted-by: Claude Code / glm-5.3-flash Signed-off-by: linsen <251731047+linsen458-spec@users.noreply.github.com> --- src/doc/oiiotool.md | 49 ++++++++++++++------ testsuite/oiiotool-channels/ref/out.txt | 12 +++++ testsuite/oiiotool-channels/run.py | 59 +++++++++++++++++++++++++ 3 files changed, 106 insertions(+), 14 deletions(-) create mode 100644 testsuite/oiiotool-channels/ref/out.txt create mode 100644 testsuite/oiiotool-channels/run.py diff --git a/src/doc/oiiotool.md b/src/doc/oiiotool.md index 07511d39db..ddf7159f5c 100644 --- a/src/doc/oiiotool.md +++ b/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-channels/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-channels/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-channels/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-channels/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-channels/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-channels/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-channels/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 diff --git a/testsuite/oiiotool-channels/ref/out.txt b/testsuite/oiiotool-channels/ref/out.txt new file mode 100644 index 0000000000..d2b8a02f93 --- /dev/null +++ b/testsuite/oiiotool-channels/ref/out.txt @@ -0,0 +1,12 @@ +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 diff --git a/testsuite/oiiotool-channels/run.py b/testsuite/oiiotool-channels/run.py new file mode 100644 index 0000000000..237922178f --- /dev/null +++ b/testsuite/oiiotool-channels/run.py @@ -0,0 +1,59 @@ +#!/usr/bin/env python + +# Copyright Contributors to the OpenImageIO project. +# SPDX-License-Identifier: Apache-2.0 +# https://github.com/AcademySoftwareFoundation/OpenImageIO + +# This test exercises the oiiotool command examples from the "Channel +# reordering and padding" section of the oiiotool documentation. The command +# lines below, between the BEGIN-docs/END-docs marker comments, are the very +# same lines that appear verbatim in the docs -- src/doc/oiiotool.md +# literalincludes this section of the file, so any change made here must be +# made in the docs as well, and vice versa. + +redirect = " >> out.txt 2>&1 " + +# Set up the images the documentation examples operate on: an RGBA .tif, an +# RGBA .exr, and a 5-channel .exr with conventional channel names. +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) + +# The hashes in the out.txt info lines pin the exact contents of every +# output image, so comparing out.txt is sufficient. +outputs = [ "out.txt" ] From dfd0083589b8594650e377358b84f75f31c5f618 Mon Sep 17 00:00:00 2001 From: linsen <251731047+linsen458-spec@users.noreply.github.com> Date: Sun, 20 Sep 2026 10:21:45 +0800 Subject: [PATCH 2/2] testing: fold the channel docs-verbatim examples into oiiotool-copy As discussed in PR #5464, the few doc-example commands fit more naturally next to the other --ch/--chappend/--chnames tests in testsuite/oiiotool-copy than in a dedicated oiiotool-channels directory. The BEGIN/END-docs-channels-* marker comments and the oiiotool.md literalincludes move over unchanged, except that they now point at testsuite/oiiotool-copy/run.py. The expected content hashes in ref/out.txt are unchanged. Contributes to #3992 Assisted-by: Claude Code / glm-5.3-flash Signed-off-by: linsen <251731047+linsen458-spec@users.noreply.github.com> --- src/doc/oiiotool.md | 14 +++--- testsuite/oiiotool-channels/ref/out.txt | 12 ----- testsuite/oiiotool-channels/run.py | 59 ------------------------- testsuite/oiiotool-copy/ref/out.txt | 12 +++++ testsuite/oiiotool-copy/run.py | 49 ++++++++++++++++++++ 5 files changed, 68 insertions(+), 78 deletions(-) delete mode 100644 testsuite/oiiotool-channels/ref/out.txt delete mode 100644 testsuite/oiiotool-channels/run.py diff --git a/src/doc/oiiotool.md b/src/doc/oiiotool.md index ddf7159f5c..b04ab09305 100644 --- a/src/doc/oiiotool.md +++ b/src/doc/oiiotool.md @@ -793,7 +793,7 @@ 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: -```{literalinclude} ../../testsuite/oiiotool-channels/run.py +```{literalinclude} ../../testsuite/oiiotool-copy/run.py :language: bash :start-after: BEGIN-docs-channels-copy-color :end-before: END-docs-channels-copy-color @@ -802,7 +802,7 @@ Copy just the color from an RGBA file, truncating the A, yielding RGB only: Zero out the red and green channels: -```{literalinclude} ../../testsuite/oiiotool-channels/run.py +```{literalinclude} ../../testsuite/oiiotool-copy/run.py :language: bash :start-after: BEGIN-docs-channels-zero-rg :end-before: END-docs-channels-zero-rg @@ -811,7 +811,7 @@ Zero out the red and green channels: Swap the red and blue channels from an RGBA image: -```{literalinclude} ../../testsuite/oiiotool-channels/run.py +```{literalinclude} ../../testsuite/oiiotool-copy/run.py :language: bash :start-after: BEGIN-docs-channels-swap-rb :end-before: END-docs-channels-swap-rb @@ -821,7 +821,7 @@ Swap the red and blue channels from an RGBA image: Extract just the named channels from a many-channel image, as efficiently as possible (avoiding memory and I/O for the unused channels): -```{literalinclude} ../../testsuite/oiiotool-channels/run.py +```{literalinclude} ../../testsuite/oiiotool-copy/run.py :language: bash :start-after: BEGIN-docs-channels-extract :end-before: END-docs-channels-extract @@ -831,7 +831,7 @@ possible (avoiding memory and I/O for the unused channels): 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: -```{literalinclude} ../../testsuite/oiiotool-channels/run.py +```{literalinclude} ../../testsuite/oiiotool-copy/run.py :language: bash :start-after: BEGIN-docs-channels-add-alpha-const :end-before: END-docs-channels-add-alpha-const @@ -841,7 +841,7 @@ naming it "A" so it will be recognized as an alpha channel: 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: -```{literalinclude} ../../testsuite/oiiotool-channels/run.py +```{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 @@ -851,7 +851,7 @@ channel and naming it "A" so it will be recognized as an alpha channel: 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: -```{literalinclude} ../../testsuite/oiiotool-channels/run.py +```{literalinclude} ../../testsuite/oiiotool-copy/run.py :language: bash :start-after: BEGIN-docs-channels-add-z :end-before: END-docs-channels-add-z diff --git a/testsuite/oiiotool-channels/ref/out.txt b/testsuite/oiiotool-channels/ref/out.txt deleted file mode 100644 index d2b8a02f93..0000000000 --- a/testsuite/oiiotool-channels/ref/out.txt +++ /dev/null @@ -1,12 +0,0 @@ -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 diff --git a/testsuite/oiiotool-channels/run.py b/testsuite/oiiotool-channels/run.py deleted file mode 100644 index 237922178f..0000000000 --- a/testsuite/oiiotool-channels/run.py +++ /dev/null @@ -1,59 +0,0 @@ -#!/usr/bin/env python - -# Copyright Contributors to the OpenImageIO project. -# SPDX-License-Identifier: Apache-2.0 -# https://github.com/AcademySoftwareFoundation/OpenImageIO - -# This test exercises the oiiotool command examples from the "Channel -# reordering and padding" section of the oiiotool documentation. The command -# lines below, between the BEGIN-docs/END-docs marker comments, are the very -# same lines that appear verbatim in the docs -- src/doc/oiiotool.md -# literalincludes this section of the file, so any change made here must be -# made in the docs as well, and vice versa. - -redirect = " >> out.txt 2>&1 " - -# Set up the images the documentation examples operate on: an RGBA .tif, an -# RGBA .exr, and a 5-channel .exr with conventional channel names. -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) - -# The hashes in the out.txt info lines pin the exact contents of every -# output image, so comparing out.txt is sufficient. -outputs = [ "out.txt" ] diff --git a/testsuite/oiiotool-copy/ref/out.txt b/testsuite/oiiotool-copy/ref/out.txt index 02ef0e063f..340e3c3abf 100644 --- a/testsuite/oiiotool-copy/ref/out.txt +++ b/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 diff --git a/testsuite/oiiotool-copy/run.py b/testsuite/oiiotool-copy/run.py index eb7804a735..0a1835531b 100755 --- a/testsuite/oiiotool-copy/run.py +++ b/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")