Introduce resizing thresholds

This commit brings deeper changes to the image sizes concept. The goal
was to allow more flexible input in resizing vs. supplied files mixed
mode. Instead of hard <noresize> flags the decision whether to resize
or copy an image is now based on threshold. While not 100% universal,
it brings more control regarding image size bounds. Also brings a level
of tolerance for specific errors (off-by-one exports).

Image sizes' rules are a bit simpler, hopefully easier to understand.
A lot can be achieved by combination of thresholds.

1 files changed, 50 insertions, 49 deletions

diff --git a/templates/classic/default.xml b/templates/classic/default.xml
index 8cf709e..6db84ee 100644
--- a/templates/classic/default.xml
+++ b/templates/classic/default.xml
@@ -3,59 +3,69 @@
 
   <!-- image size definitions -->
   <image_sizes>
-    <!-- Every image size automatically corresponds to the <item> tag parameter
-         of the same name in album source files. E.g. image size named "hires"
-         would correspond to <item hires=".."> tags. Use the image size parameter
-         "tagname" to override that.   -->
+    <!-- Every item in an album may carry multiple sizes for the particular image.
+         The base and source image file is specified by the <item src> tag and
+         should point to the largest available size. This attribute is mandatory
+         and serves as a source of metadata (e.g. EXIF). Defined image sizes are
+         then resized from this source image unless a custom image file is supplied.
+         Custom image may be supplied from the album XML file in form of an extra
+         attribute of the <item> tag. Image size names are matched automatically
+         with these attributes. I.e. image size named "hires" would correspond
+         to <item hires=".."> attribute. Use the image size parameter "tagname"
+         to override that name.   -->
+
+    <!-- Not all image sizes are always available for every album item and themes
+         should handle that gracefully. Unless a custom image file is supplied
+         the image is resized from the base image file pointed to by the <item src>
+         tag given that its dimensions are larger than desired size. Should the
+         base image dimensions be smaller, the image size is marked as unavailable
+         for the particular album item. In case of a custom image file is supplied
+         for the particular image size, no resizing or size checking is performed
+         at all and the file is simply copied to destination. -->
 
-    <!-- "original", "preview" and "thumbnail" sizes are somewhat special here
-         in order to keep compatibility with previous versions.  -->
+    <!-- The "preview" size is considered default and should be displayed
+         on a first visit.  -->
+    <size name="preview" tagname="preview">
+      <landscape w="1067" h="600" />
+      <portrait w="800" h="800" />
+      <quality value="95" />
+    </size>
 
     <!-- Meaning of "original" is shifted here from previous versions;
-         it's considered more like a bigger preview size for large screens now.
-         However it still serves the purpose of supplying metadata (EXIF etc.). -->
-    <!-- Corresponds with mandatory <item src> tag in album source file.  -->
-    <!-- Note that the series of legacy <nofullsize> and <fullsize> tags control
-         this image size availability on the page. -->
+         it's independent now and considered more like a bigger image size for
+         large screens. -->
     <size name="original">
       <landscape w="1200" h="800" />
       <portrait w="1024" h="1024" />
       <quality value="97" />
-      <!-- With the presence of the "no_resize" tag, no resizing will be done and
-           image file will be copied as is (this is a default for backwards
-           compatibility). -->
-      <no_resize />
-      <!-- Normally an image is resized to the given dimensions from the original
-           image when an image is not supplied from the album XML file for the
-           particular image size. This tag tells the generator to use the fallback
-           image size instead when an image has not been supplied. Can be freely
-           combined with the <no_resize /> tags, in that case it only applies
-           to supplied images.  -->
-      <!-- In case when the "original" size is not available due to the legacy
-           <nofullsize> tag present, the "preview" size will be used instead.  -->
+      <!-- Thresholds affect resizing and availability. Value units are pixels
+           or percent (quality only). -->
+      <!-- The "no_resize" threshold brings size tolerance before performing
+           resizing. Only applicable when custom image file is not supplied,
+           source image whose dimensions are larger than defined image size bounds
+           yet whose difference is smaller than the "no_resize" threshold is
+           considered usable and no resizing is performed. This is useful to
+           prevent resizing similarly sized images which brings nasty pixel
+           distortion effects.  -->
+      <!-- Similarly, the "availability" threshold specifies how much smaller
+           image can still be considered usable for the particular image size.
+           No resizing is peformed either case. This is useful mostly for legacy
+           reasons for images that have not been exported precisely to the
+           requested dimensions.  -->
+      <!-- The "quality" threshold indicates how much higher JPEG quality value
+           is tolerated (in percents).  -->
+      <threshold no_resize="10" availability="100" quality="5" />
+      <!-- In case no custom image has been supplied and dimensions of the source
+           image are smaller than required dimensions, a fallback image size might
+           be used instead. This is useful to prevent missing images on a page,
+           with the cost of uneven image sizes displayed.  -->
       <fallback size="preview" />
     </size>
 
-    <!-- The "preview" size is considered default and should be displayed
-         on a first visit.  -->
-    <size name="preview" tagname="preview">
-      <!-- Note that "preview" sizes can be further overriden by album legacy
-           <images> tag and also per-image by "width"/"height" <item> tag
-           attributes. Same goes for quality. -->
-      <landscape w="1067" h="600" />
-      <portrait w="800" h="800" />
-      <quality value="95" />
-      <!-- Similar to the "original" size where the image has to be always supplied,
-           the image won't get resized only when an image file is supplied by the
-           <item preview="..."> tag. Otherwise this tag is ignored and image will
-           be resized from the "original" size (backwards compatibility).
-           This rule applies also for any other optional image sizes.  -->
-      <no_resize />
-    </size>
 
     <!-- Thumbnail section is mandatory. -->
     <!-- The "type" attribute has to be set to "thumbnail" to be treated as such. -->
-    <!-- Note that thumbnail images are always resized even for custom supplied files.  -->
+    <!-- Note that thumbnail images are always resized even for custom supplied image.  -->
     <!-- An optional "style" attribute affects cropping:
            * normal  - image is resized to fit the dimension limits, maintaining
                        aspect ratio without any crop (default)
@@ -70,15 +80,6 @@
       <crop w="180" h="120" />   <!--  valid only for the "fixed" crop style  -->
       <quality value="80" />
     </size>
-
-    <!-- Here you can define custom sizes which will be generated from the file
-         defined in <item src> tag. Currently, there's no way how to supply custom
-         sized images from album source file (might be changed in the future). -->
-    <size name="mobile">
-      <landscape w="320" h="240" />
-      <portrait w="240" h="320" />
-      <quality value="90" />
-    </size>
   </image_sizes>
 
   <!-- Global support files, common files used by several themes. -->