Replace formatQuality with formatOptions for additional configura…

…bility (#1327) * feat: replace formatQuality with formatOptions in config file formatQuality is more flexible and allows configuration of more than just quality for all formats. JPEG and WebP still have only their quality configurable. PNG has all the configuration options from the sharp library exposed. Signed-off-by: Nathan Reed <[email protected]> * feat: update docs for new formatOptions Signed-off-by: Nathan Reed <[email protected]> * feat: allow deprecated formatQuality with logged warning Signed-off-by: Nathan Reed <[email protected]> --------- Signed-off-by: Nathan Reed <[email protected]>
maptiler · Aug 10, 2024 · 1f5a580 · 1f5a580
1 parent 0943a74
commit 1f5a580
Show file tree

Hide file tree

Showing 2 changed files with 44 additions and 9 deletions.
diff --git a/docs/config.rst b/docs/config.rst
@@ -23,9 +23,13 @@ Example:
         "localhost:8080",
         "127.0.0.1:8080"
       ],
-      "formatQuality": {
-        "jpeg": 80,
-        "webp": 90
+      "formatOptions": {
+        "jpeg": {
+          "quality": 80
+        },
+        "webp": {
+          "quality": 90
+        }
       },
       "maxScaleFactor": 3,
       "maxSize": 2048,
@@ -85,10 +89,23 @@ Path to the html (relative to ``root`` path) to use as a front page.
 Use ``true`` (or nothing) to serve the default TileServer GL front page with list of styles and data.
 Use ``false`` to disable the front page altogether (404).
 
-``formatQuality``
+``formatOptions``
 -----------------
 
-Quality of the compression of individual image formats. [0-100]
+You can use this to specify options for the generation of images in the supported file formats.
+For JPEG and WebP, the only supported option is ``quality`` [0-100].
+For PNG, the full set of options `exposed by the sharp library <https://sharp.pixelplumbing.com/api-output#png>`_ is available, except ``force`` and ``colours`` (use ``colors``). If not set, their values are the defaults from ``sharp``.
+
+For example::
+
+  "formatOptions": {
+    "png": {
+      "palette": true,
+      "colors": 4
+    }
+  }
+
+Note: ``formatOptions`` replaced the ``formatQuality`` option in previous versions of TileServer GL. 
 
 ``maxScaleFactor``
 -----------

diff --git a/src/serve_rendered.js b/src/serve_rendered.js
@@ -504,14 +504,32 @@ const respondImage = (
         image.composite(composites);
       }
 
-      const formatQuality = (options.formatQuality || {})[format];
+      // Legacy formatQuality is deprecated but still works
+      const formatQualities = options.formatQuality || {};
+      if (Object.keys(formatQualities).length !== 0) {
+        console.log(
+          'WARNING: The formatQuality option is deprecated and has been replaced with formatOptions. Please see the documentation. The values from formatQuality will be used if a quality setting is not provided via formatOptions.',
+        );
+      }
+      const formatQuality = formatQualities[format];
+
+      const formatOptions = (options.formatOptions || {})[format] || {};
 
       if (format === 'png') {
-        image.png({ adaptiveFiltering: false });
+        image.png({
+          progressive: formatOptions.progressive,
+          compressionLevel: formatOptions.compressionLevel,
+          adaptiveFiltering: formatOptions.adaptiveFiltering,
+          palette: formatOptions.palette,
+          quality: formatOptions.quality,
+          effort: formatOptions.effort,
+          colors: formatOptions.colors,
+          dither: formatOptions.dither,
+        });
       } else if (format === 'jpeg') {
-        image.jpeg({ quality: formatQuality || 80 });
+        image.jpeg({ quality: formatOptions.quality || formatQuality || 80 });
       } else if (format === 'webp') {
-        image.webp({ quality: formatQuality || 90 });
+        image.webp({ quality: formatOptions.quality || formatQuality || 90 });
       }
       image.toBuffer((err, buffer, info) => {
         if (!buffer) {