Merge pull request #997 from openzim/illustration_api_enhancement

Illustration API enhancement

Author: kelson42

include/zim/archive.h

@@ -24,6 +24,7 @@
 
 #include "zim.h"
 #include "entry.h"
+#include "illustration.h"
 #include "uuid.h"
 
 #include <string>
@@ -101,6 +102,7 @@ namespace zim
     public:
       template<EntryOrder order> class EntryRange;
       template<EntryOrder order> class iterator;
+      typedef std::vector<IllustrationInfo> IllustrationInfos;
 
       /** Archive constructor.
        *
@@ -338,6 +340,18 @@ namespace zim
        */
       std::vector<std::string> getMetadataKeys() const;
 
+      /** Get the illustration item of the archive with specified parameters.
+       *
+       *  Illustration is an icon for the archive that can be used in catalog
+       *  and so to illustrate the archive.
+       *
+       *  @param ii parameters of the requested illustration.
+       *  @return The illustration item.
+       *  @exception EntryNotFound If no illustration item with specified
+       *             parameters can be found.
+       */
+      Item getIllustrationItem(const IllustrationInfo& ii) const;
+
       /** Get the illustration item of the archive.
        *
        *  Illustration is a icon for the archive that can be used in catalog and so to illustrate the archive.
@@ -348,15 +362,34 @@ namespace zim
        */
       Item getIllustrationItem(unsigned int size=48) const;
 
-      /** Return a list of available sizes (width) for the illustations in the archive.
+      /** Return a list of available sizes (width) for the illustrations in the archive.
        *
        * Illustration is an icon for the archive that can be used in catalog and elsewehere to illustrate the archive.
        * An Archive may contains several illustrations with different size.
        * This method allows to know which illustration are in the archive (by size: width)
        *
        * @return A set of size.
        */
-      std::set<unsigned int> getIllustrationSizes() const;
+      DEPRECATED std::set<unsigned int> getIllustrationSizes() const;
+
+
+      /** Return the list of available illustrations in the archive.
+       *
+       * @return A vector of IllustrationInfo data.
+       */
+      IllustrationInfos getIllustrationInfos() const;
+
+      /** Return the list of illustrations with the specified dimensions.
+       *
+       *  @param w width in CSS pixels
+       *  @param h height in CSS pixels
+       *  @param minScale lower limit on the devicePixelRatio value of the
+       *                  targeted display media. The result will include
+       *                  any entries with the scale value equal to or greater
+       *                  than this filter value.
+       * @return A vector of IllustrationInfo data.
+       */
+      IllustrationInfos getIllustrationInfos(uint32_t w, uint32_t h, float minScale) const;
 
 
       /** Get an entry using its "path" index.

include/zim/illustration.h

@@ -0,0 +1,68 @@
+/*
+ * Copyright (C) 2025 Veloman Yunkan
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * is provided AS IS, WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, and
+ * NON-INFRINGEMENT.  See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+ *
+ */
+
+#ifndef ZIM_ILLUSTRATION_H
+#define ZIM_ILLUSTRATION_H
+
+#include "zim/zim.h"
+
+#include <map>
+
+namespace zim
+{
+
+class LIBZIM_API Attributes : public std::map<std::string, std::string>
+{
+  typedef std::map<std::string, std::string> ImplType;
+
+public:
+  Attributes() {}
+  Attributes(const ImplType& x) : ImplType(x) {}
+
+  Attributes(const std::initializer_list<ImplType::value_type>& x)
+    : ImplType(x)
+  {}
+
+  static Attributes parse(const std::string& s);
+};
+
+/**
+ * Information about illustrations stored as metadata in the ZIM archive
+ */
+struct LIBZIM_API IllustrationInfo
+{
+  uint32_t width;  // in CSS pixels
+  uint32_t height; // in CSS pixels
+  float    scale;  // devicePixelRatio value of the targeted display media
+  Attributes extraAttributes; // additional attributes of the illustration
+
+  std::string asMetadataItemName() const;
+  static IllustrationInfo fromMetadataItemName(const std::string& s);
+};
+
+inline bool operator==(const IllustrationInfo& a, const IllustrationInfo& b) {
+  return a.width  == b.width
+      && a.height == b.height
+      && a.scale  == b.scale
+      && a.extraAttributes == b.extraAttributes;
+}
+
+} // namespace zim
+
+#endif // ZIM_ILLUSTRATION_H

include/zim/meson.build

@@ -5,6 +5,7 @@ install_headers(
     'archive.h',
     'blob.h',
     'error.h',
+    'illustration.h',
     'item.h',
     'entry.h',
     'uuid.h',

include/zim/writer/creator.h

@@ -24,6 +24,7 @@
 
 #include <memory>
 #include <zim/zim.h>
+#include <zim/illustration.h>
 #include <zim/writer/item.h>
 
 namespace zim
@@ -161,6 +162,24 @@ namespace zim
          */
         void addMetadata(const std::string& name, std::unique_ptr<ContentProvider> provider, const std::string& mimetype = "text/plain;charset=utf-8");
 
+        /**
+         * Add illustration to the archive.
+         *
+         * @param ii parameters of the illustration.
+         * @param content the content of the illustration (must be a png
+         *        content)
+         */
+        void addIllustration(const IllustrationInfo& ii, const std::string& content);
+
+        /**
+         * Add illustration to the archive.
+         *
+         * @param ii parameters of the illustration.
+         * @param provider the provider of the content of the illustration
+         *        (must be a png content)
+         */
+        void addIllustration(const IllustrationInfo& ii, std::unique_ptr<ContentProvider> provider);
+
         /**
          * Add illustration to the archive.
          *

include/zim/zim.h

@@ -30,7 +30,7 @@
 #elif defined(_MSC_VER)
 #define DEPRECATED __declspec(deprecated)
 #else
-#praga message("WARNING: You need to implement DEPRECATED for this compiler")
+#pragma message("WARNING: You need to implement DEPRECATED for this compiler")
 #define DEPRECATED
 #endif
 

src/archive.cpp

@@ -181,24 +181,19 @@ namespace zim
   }
 
   Item Archive::getIllustrationItem(unsigned int size) const {
-    auto r = m_impl->findx('M', Formatter() << "Illustration_" << size << "x"
-                                            << size << "@" << 1);
+    // XXX: A square illustration of the requested size may exist with
+    // XXX: non-empty attributes or at a scale different from 1. Shouldn't
+    // XXX: we test for it too, if the {size}x{size}@1 one is not available?
+    return getIllustrationItem(IllustrationInfo{size, size, 1.0, {}});
+  }
+
+  Item Archive::getIllustrationItem(const IllustrationInfo& ii) const {
+    auto r = m_impl->findx('M', ii.asMetadataItemName());
     if (r.first) {
       return getEntryByPath(entry_index_type(r.second)).getItem();
     }
-    // We haven't found the exact entry. Let's "search" for a illustration and
-    // use the first one we found.
-#if 0
-    // We have decided to not implement fallback in case of wrong resolution for now.
-    // We keep this code for reference.
-    r = m_impl->findx('M', "Illustration");
-    auto entry = getEntryByPath(entry_index_type(r.second));
-    if (entry.getPath().find("Illustration") == 0) {
-      return entry.getItem();
-    }
-#endif
     // For 48x48 illustration, return favicon for older zims.
-    if (size == 48) {
+    if ( ii == IllustrationInfo{48, 48, 1.0, {}} ) {
       auto r = findFavicon(*m_impl);
       return getEntryByPath(entry_index_type(r.second)).getItem(true);
     }
@@ -233,6 +228,45 @@ namespace zim
     return ret;
   }
 
+  Archive::IllustrationInfos Archive::getIllustrationInfos() const {
+    IllustrationInfos r;
+    for(auto e = m_impl->findx('M', "Illustration_").second; ; ++e ) {
+      try {
+        const auto path = getEntryByPath(entry_index_type(e)).getPath();
+        if (path.find("Illustration_") != 0) {
+          break;
+        }
+        try {
+          r.push_back(zim::IllustrationInfo::fromMetadataItemName(path));
+        } catch (...) {}
+      } catch (const std::out_of_range& e) {
+        break;
+      }
+    }
+    const IllustrationInfo faviconLikeIllustration{48, 48, 1.0, {}};
+    if (std::find(r.begin(), r.end(), faviconLikeIllustration) == r.end()) {
+      try {
+        // raise a exception if we cannot find the (old format) favicon.
+        findFavicon(*m_impl);
+        r.push_back(faviconLikeIllustration);
+      } catch(EntryNotFound&) {}
+    }
+    return r;
+  }
+
+  Archive::IllustrationInfos Archive::getIllustrationInfos(uint32_t w,
+                                                           uint32_t h,
+                                                           float minScale) const
+  {
+    IllustrationInfos r;
+    for ( const auto& ii : getIllustrationInfos() ) {
+      if ( ii.width == w && ii.height == h && ii.scale >= minScale ) {
+        r.push_back(ii);
+      }
+    }
+    return r;
+  }
+
   bool Archive::hasIllustration(unsigned int size) const {
     try {
       getIllustrationItem(size);

src/tools.cpp

@@ -21,6 +21,7 @@
 
 #include "tools.h"
 #include "zim/tools.h"
+#include "zim/illustration.h"
 #include "fs.h"
 #include "writer/_dirent.h"
 
@@ -110,13 +111,64 @@ unsigned int zim::parseIllustrationPathToSize(const std::string& s)
 {
   int nw(0), nh(0), nEnd(0);
   long int w(-1), h(-1);
-  if ( sscanf(s.c_str(), "Illustration_%n%ldx%n%ld@1%n)", &nw, &w, &nh, &h, &nEnd) == 2
+  if ( sscanf(s.c_str(), "Illustration_%n%ldx%n%ld@1%n", &nw, &w, &nh, &h, &nEnd) == 2
      && (size_t)nEnd == s.size() && !isspace(s[nw]) && !isspace(s[nh]) && w == h && w >= 0) {
     return (unsigned int)w;
   }
   throw std::runtime_error("");
 }
 
+std::string zim::IllustrationInfo::asMetadataItemName() const
+{
+  std::ostringstream oss;
+  oss << "Illustration_" << width << "x" << height << "@" << scale;
+  for ( const auto& kv : extraAttributes ) {
+    oss << ";" << kv.first << "=" << kv.second;
+  }
+  return oss.str();
+}
+
+zim::Attributes zim::Attributes::parse(const std::string& s)
+{
+  zim::Attributes a;
+  for (const std::string& nameAndValue : split(s, ";") ) {
+    const auto i = nameAndValue.find('=');
+    const std::string name = nameAndValue.substr(0, i);
+    const std::string value = i == std::string::npos
+                            ? ""
+                            : nameAndValue.substr(i+1);
+    a[name] = value;
+  }
+  return a;
+}
+
+zim::IllustrationInfo zim::IllustrationInfo::fromMetadataItemName(const std::string& s)
+{
+  int nw(0), nh(0), ns(0), nEnd(0);
+  long int w(-1), h(-1);
+  float scale(0);
+
+  const char fmt[] = "Illustration_%n%ldx%n%ld@%n%f%n;";
+  if ( sscanf(s.c_str(), fmt, &nw, &w, &nh, &h, &ns, &scale, &nEnd) != 3
+     || isspace(s[nw])
+     || isspace(s[nh])
+     || isspace(s[ns])
+     || w < 0
+     || h < 0
+     || scale < 0
+     || (size_t(nEnd) != s.size() && s[nEnd] != ';') ) {
+    throw std::runtime_error("Invalid name of illustration metadata item");
+  }
+
+  const auto attrStart = std::min(s.size(), size_t(nEnd) + 1);
+  const auto attributes = Attributes::parse(s.substr(attrStart));
+  const auto ii = IllustrationInfo{uint32_t(w), uint32_t(h), scale, attributes};
+  if ( ii.asMetadataItemName() != s ) {
+    throw std::runtime_error("Invalid name of illustration metadata item");
+  }
+  return ii;
+}
+
 uint32_t zim::randomNumber(uint32_t max)
 {
   static std::default_random_engine random(

src/writer/creator.cpp

@@ -182,18 +182,27 @@ namespace zim
       data->handle(dirent);
     }
 
-    void Creator::addIllustration(unsigned int size, const std::string& content)
+    void Creator::addIllustration(const IllustrationInfo& ii, const std::string& content)
     {
       checkError();
       auto provider = std::unique_ptr<ContentProvider>(new StringProvider(content));
-      addIllustration(size, std::move(provider));
+      addIllustration(ii, std::move(provider));
     }
 
-    void Creator::addIllustration(unsigned int size, std::unique_ptr<ContentProvider> provider)
+    void Creator::addIllustration(const IllustrationInfo& ii, std::unique_ptr<ContentProvider> provider)
     {
       checkError();
-      addMetadata(Formatter() << "Illustration_" << size << "x" << size << "@1",
-                  std::move(provider), "image/png");
+      addMetadata(ii.asMetadataItemName(), std::move(provider), "image/png");
+    }
+
+    void Creator::addIllustration(unsigned int size, const std::string& content)
+    {
+      addIllustration(IllustrationInfo{size, size, 1, {}}, content);
+    }
+
+    void Creator::addIllustration(unsigned int size, std::unique_ptr<ContentProvider> provider)
+    {
+      addIllustration(IllustrationInfo{size, size, 1, {}}, std::move(provider));
     }
 
     void Creator::addRedirection(const std::string& path, const std::string& title, const std::string& targetPath, const Hints& hints)