From 1f5a58035b7b7e987845970374338c39e4c42337 Mon Sep 17 00:00:00 2001
From: Nathan Reed <nathreed@gmail.com>
Date: Sat, 10 Aug 2024 09:15:14 -0400
Subject: [PATCH] Replace `formatQuality` with `formatOptions` for additional
 configurability (#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 <nathreed@gmail.com>

* feat: update docs for new formatOptions

Signed-off-by: Nathan Reed <nathreed@gmail.com>

* feat: allow deprecated formatQuality with logged warning

Signed-off-by: Nathan Reed <nathreed@gmail.com>

---------

Signed-off-by: Nathan Reed <nathreed@gmail.com>
---
 docs/config.rst       | 27 ++++++++++++++++++++++-----
 src/serve_rendered.js | 26 ++++++++++++++++++++++----
 2 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/docs/config.rst b/docs/config.rst
index 9078d99e1..1e8ecb9c5 100644
--- 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
index a159997c7..2043ce391 100644
--- 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) {