BOTTOM as symonym for the bottom of the stack

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

Author: lgritz

src/doc/oiiotool.rst

@@ -126,9 +126,10 @@ contents of an expression may be any of:
   The *imagename* may be one of:
 
   * `TOP` : the top or current image;
+  * `BOTTOM` : the image at the bottom of the stack;
   * `IMG[index]` : if `index` evaluates to an integer `i`, the i-th image on
     the stack (thus `TOP` is a synonym for `IMG[0]`, the next image on the
-    stack is `IMG[1]`, etc.);
+    stack is `IMG[1]`, ..., and `BOTTOM` is a synonmym for `IMG[NIMAGES-1]`);
   * `IMG[name]` : an image named by filename or by label name.
 
   Remember that the positions on the stack (including `TOP`) refer to *at that

src/oiiotool/expressions.cpp

@@ -149,11 +149,14 @@ Oiiotool::express_parse_atom(const string_view expr, string_view& s,
             return false;
 
     } else if (Strutil::starts_with(s, "TOP")
+               || Strutil::starts_with(s, "BOTTOM")
                || Strutil::starts_with(s, "IMG[")) {
         // metadata substitution
         ImageRecRef img;
         if (Strutil::parse_prefix(s, "TOP")) {
             img = curimg;
+        } else if (Strutil::parse_prefix(s, "BOTTOM")) {
+            img = (image_stack.size() <= 1) ? curimg : image_stack[0];
         } else if (Strutil::parse_prefix(s, "IMG[")) {
             std::string until_bracket = Strutil::parse_until(s, "]");
             if (until_bracket.empty() || !Strutil::parse_char(s, ']')) {

testsuite/oiiotool-control/ref/out.txt

@@ -259,8 +259,9 @@ Stats FiniteCount: 12288 12288 12288
 Constant: No
 Monochrome: No
 
-Stack holds [0] = ../common/tahoe-small.tif, [1] = ../common/tahoe-tiny.tif
-Stack holds [1] = ../common/tahoe-tiny.tif
+Stack holds [0] = ../common/grid.tif, [1] = ../common/tahoe-small.tif, [2] = ../common/tahoe-tiny.tif
+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
 Testing NIMAGES:

testsuite/oiiotool-control/run.py

@@ -134,11 +134,13 @@
                      + " --echo \"\\nMeta native: {TOP.METANATIVE}\""
                      + " --echo \"\\nStats:\\n{TOP.STATS}\\n\"")
 
-# Test IMG[]
-command += oiiotool ("../common/tahoe-tiny.tif ../common/tahoe-small.tif " +
-                     "--echo \"Stack holds [0] = {IMG[0].filename}, [1] = {IMG[1].filename}\" " +
+# Test IMG[], TOP, BOTTOM
+command += oiiotool ("../common/tahoe-tiny.tif ../common/tahoe-small.tif ../common/grid.tif " +
+                     "--echo \"Stack holds [0] = {IMG[0].filename}, [1] = {IMG[1].filename}, [2] = {IMG[2].filename}\" " +
+                     "--echo \"TOP = {TOP.filename}, BOTTOM = {BOTTOM.filename}\" " +
                      "--set i 1 " +
-                     "--echo \"Stack holds [{i}] = {IMG[i].filename}\" ")
+                     "--echo \"Stack holds [{i}] = {IMG[i].filename}\" "
+                     )
 
 # Test some special attribute evaluation names
 command += oiiotool ("../common/tahoe-tiny.tif " +