feat(oiiotool): New expression pseudo-metadata term: SUBIMAGES (AcademySoftwareFoundation#4804)

When doing oiiotool command line expression substitution, asking for
this metadata evaluates to the number of subimages in the referenced
image.

The purpose is that asking to retrieve, say, `{TOP.'oiio:subimages'}`
might look right, but generally it's only added to images (or format
readers) that are potentially multi-image. Whereas SUBIMAGES is not
actual image metadata, it's just an evaluation token that will always be
the number of subimages.

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

Author: lgritz

src/doc/oiiotool.rst

@@ -165,6 +165,7 @@ contents of an expression may be any of:
     be printed with `oiiotool -stats`.
   * `IS_CONSTANT`: metadata to check if the image pixels are of constant color, returns 1 if true, and 0 if false.
   * `IS_BLACK`: metadata to check if the image pixels are all black, a subset of IS_CONSTANT. Also returns 1 if true, and 0 if false.
+  * `SUBIMAGES`: the number of subimages in the file.
 
 * *imagename.'metadata'*
 

src/oiiotool/expressions.cpp

@@ -339,6 +339,8 @@ Oiiotool::express_parse_atom(const string_view expr, string_view& s,
                     // Not even constant color case -> We don't want those to count as black frames.
                     result = "0";
                 }
+            } else if (metadata == "SUBIMAGES") {
+                result = Strutil::to_string(img->subimages());
 
             } else if (using_bracket) {
                 // For the TOP[meta] syntax, if the metadata doesn't exist,

testsuite/oiiotool-control/ref/out.txt

@@ -326,6 +326,7 @@ TOP = ../common/grid.tif, BOTTOM = ../common/tahoe-tiny.tif
 Stack holds [1] = ../common/tahoe-small.tif
 filename=../common/tahoe-tiny.tif file_extension=.tif file_noextension=../common/tahoe-tiny
 MINCOLOR=0,0,0 MAXCOLOR=0.745098,1,1 AVGCOLOR=0.101942,0.216695,0.425293
+SUBIMAGES=1
 Testing expressions IS_BLACK, IS_CONSTANT:
   grey is-black? 0 is-constant? 1
   black is-black? 1 is-constant? 1

testsuite/oiiotool-control/run.py

@@ -181,7 +181,8 @@
 # Test some special attribute evaluation names
 command += oiiotool ("../common/tahoe-tiny.tif " +
                      "--echo \"filename={TOP.filename} file_extension={TOP.file_extension} file_noextension={TOP.file_noextension}\" " +
-                     "--echo \"MINCOLOR={TOP.MINCOLOR} MAXCOLOR={TOP.MAXCOLOR} AVGCOLOR={TOP.AVGCOLOR}\"")
+                     "--echo \"MINCOLOR={TOP.MINCOLOR} MAXCOLOR={TOP.MAXCOLOR} AVGCOLOR={TOP.AVGCOLOR}\" " +
+                     "--echo \"SUBIMAGES={TOP.SUBIMAGES}\"")
 
 command += oiiotool ("--echo \"Testing expressions IS_BLACK, IS_CONSTANT:\" " +
                      "--pattern:type=uint16 constant:color=0.5,0.5,0.5 4x4 3 " +