feat(oiiotool): allow easy splitting of subimages by name (AcademySoftwareFoundation#4874)

Say you need to take a multi-part exr file and split it into separate
files for each part. (Note: what OpenEXR calls "parts", OIIO calls
"subimages.") You could do this

    oiiotool multipart.exr --sisplit -o:all=1 "part.%04d.exr"

But this would name the parts part.0001.exr, part.0002.exr, etc. Maybe
you would prefer to split them into files that contain the subimage name
rather than just the inscrutible index number (which may also not be
consistent across files)? You could try this dance to loop over the
subimages and write each one with a name extracted from its metadata:

oiiotool multipart.exr --for i {TOP.SUBIMAGES} --dup --subimage {i} -o
"subimage_{TOP.'oiio:subimagename'}.exr

That works, but that's a little awkward and hard to remember off the top
of your head. Perhaps instead we would prefer a simpler version:

oiiotool multipart.exr --sisplit -o:all=1
"part.{TOP.'oiio:subimagename'}.exr"

This PR makes that last command work. It actually only required a small
change, which is that the function that handles the `-o` command needs
to defer the evaluation of the expression subsitution in the filename to
occur separately for each subimage being output, rather than just once
for the whole `-o:all=1` (which would have baked the FIRST subimage name
into all the output file names).

Docs are updated to give examples of how to do this.

Also fixed a silly typo in the test script.

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

Author: lgritz

src/doc/oiiotool.rst

@@ -868,11 +868,17 @@ Split a multi-image file into separate files
 --------------------------------------------
 
 Take a multi-image TIFF file, split into its constituent subimages and
-output each one to a different file, with names `sub0001.tif`,
-`sub0002.tif`, etc.::
+output each one to a different file, with names `sub.0001.tif`,
+`sub.0002.tif`, etc.::
 
-    oiiotool multi.tif -sisplit -o:all=1 sub%04d.tif
+    oiiotool multi.tif -sisplit -o:all=1 sub.%04d.tif
 
+Take a multi-image OpenEXR file (called "multi-part" in OpenEXR parlance),
+split into its constituent subimages and output each one to a different file,
+with names `sub.beauty.exr`, `sub.albedo.exr`, etc., using the name of each
+subimage according to its metadata::
+
+    oiiotool multi.exr -sisplit -o:all=1 "sub.{TOP.'oiio:subimagename'}.exr"
 
 
 |
@@ -1498,17 +1504,25 @@ Writing images
         Output all images currently on the stack using a pattern.
         See further explanation below.
 
-    The `all=n` option causes *all* images on the image stack to be output,
-    with the filename argument used as a pattern assumed to contain a `%d`,
-    which will be substituted with the index of the image (beginning with
-    *n*). For example, to take a multi-image TIFF and extract all the
-    subimages and save them as separate files::
+    The `all=n` option causes *all* images on the image stack to be output. If
+    the *filename* argument contains expression substitution notation, the
+    substitution will be re-evaluated for each image output. Also, if the
+    *filename* argument contains a `%d`, that will be substituted with the
+    index of the image (beginning with *n*). For example, to take a
+    multi-image TIFF and extract all the subimages and save them as separate
+    files::
     
         oiiotool multi.tif -sisplit -o:all=1 sub%04d.tif
     
     This will output the subimges as separate files `sub0001.tif`,
     `sub0002.tif`, and so on.
 
+    Expression substitution can be used to insert the subimage name
+    into each filename::
+    
+        oiiotool multi.tif -sisplit -o:all=1 "sub.{TOP.'oiio:subimagename'}.tif"
+    
+
 
 .. option:: -otex <filename>
             -oenv <filename>

src/oiiotool/oiiotool.cpp

@@ -5556,6 +5556,9 @@ output_file(Oiiotool& ot, cspan<const char*> argv)
         remove_all_cmd(newcmd);
         new_argv[0]              = newcmd.c_str();
         ImageRecRef saved_curimg = ot.curimg;  // because we'll overwrite it
+        // Revert back to the UN-expression-substituted filename. It will get
+        // expression substitution in the subsequent call to output_file.
+        filename = argv[1];
         for (int i = 0; i < nimages; ++i) {
             if (i < nimages - 1)
                 ot.curimg = ot.image_stack[i];

testsuite/oiiotool-subimage/ref/out.txt

@@ -1,5 +1,13 @@
-Reading gpgr.exr
-gpgr.exr             :   64 x   64, 3 channel, half openexr
+subimage.layerA.exr  :   64 x   64, 3 channel, half openexr
+    SHA-1: 0C27059220A256F197900FB4EB8C7CF63349A26B
+subimage.layerB.exr  :   64 x   64, 3 channel, half openexr
+    SHA-1: 0E19BEFEF868E356A6A4C6450DA9A7B17DD11E12
+subimage.layerC.exr  :   64 x   64, 3 channel, half openexr
+    SHA-1: CFAF4AFC253320AC35B8E9014C6D750768354059
+subimage.layerD.exr  :   64 x   64, 3 channel, half openexr
+    SHA-1: 5FFA4616F46509627873D2C53744E47E2F492719
+Reading jpgr.exr
+jpgr.exr             :   64 x   64, 3 channel, half openexr
     4 subimages: 64x64 [h,h,h], 64x64 [h,h,h], 64x64 [h,h,h], 64x64 [h,h,h]
  subimage  0:   64 x   64, 3 channel, half openexr
     SHA-1: 0C27059220A256F197900FB4EB8C7CF63349A26B

testsuite/oiiotool-subimage/run.py

@@ -24,10 +24,12 @@
 command += oiiotool ("subimages-4.exr --subimage 3 -o subimageD3.exr")
 command += oiiotool ("subimages-4.exr --subimage layerB -o subimageB1.exr")
 command += oiiotool ("subimages-2.exr --sisplit -o:all=1 subimage%d.exr")
+command += oiiotool ("subimages-4.exr --sisplit -o:all=1 \"subimage.{TOP.'oiio:subimagename'}.exr\"")
+command += info_command ("subimage.layerA.exr subimage.layerB.exr subimage.layerC.exr subimage.layerD.exr", verbose=False)
 
 # test that we can set attributes on individual subimages
-command += oiiotool ("subimages-4.exr --attrib:subimages=0 Beatle John --attrib:subimages=1 Beatle Paul --attrib:subimages=2 Beatle George --attrib:subimages=3 Beatle Ringo -o gpgr.exr")
-command += info_command ("-a -v gpgr.exr", safematch=1)
+command += oiiotool ("subimages-4.exr --attrib:subimages=0 Beatle John --attrib:subimages=1 Beatle Paul --attrib:subimages=2 Beatle George --attrib:subimages=3 Beatle Ringo -o jpgr.exr")
+command += info_command ("-a -v jpgr.exr", safematch=1)
 
 # Test extraction of MIP levels
 command += oiiotool ("../common/textures/grid.tx --selectmip 4 -o mip4.tif")