Add 'jobs', 'cmm', 'deflum', 'hlglum' & 'bpc'

Author: S1SYPHOS

README.md

@@ -62,19 +62,41 @@ $profile = $image->identify();
 For further details, have a look at the following sections.
 
 #### Configuration
-You may also change certain options from your `config.php` globally (`'fundevogel.colorist.optionName'`):
+You may also change certain options from your `config.php` globally, like this: `'fundevogel.colorist.optionName'` (or simply pass them to the `thumb()` method:
 
-| Option       | Type        | Default                     | Description                                                                            |
+| Option       | Type        | Default(s to)               | Description                                                                            |
 | ------------ | ----------- | --------------------------- | -------------------------------------------------------------------------------------- |
 | `'bin'`      | string      | `__DIR__ . '/bin/colorist'` | Path to `colorist` executable                                                          |
+| `'bpc'`      | integer     | `'auto'`                    | Set bits-per-channel (J2K/JP2 only); ranging from `8` to `16`                          |
 | `'formats'`  | array       | `['webp']`                  | Default file formats to be used on image uploads                                       |
-| `'speed'`    | integer     | `0`                         | Quality/speed tradeoff when encoding (AVIF only); `0` = best quality, `10` = fastest   |
+| `'deflum'`   | integer     | `80`                        | default/fallback luminance value in nits                                               |
+| `'hlglum'`   | integer     | `null`                      | Like `'deflum'`, but uses an appropriate diffuse white based on peak HLG               |
+| `'jobs'`     | integer     | `0`                         | Number of jobs to use when working (`0` = unlimited)                                   |
+| `'speed'`    | integer     | `'auto'`                    | Quality/speed tradeoff when encoding (AVIF only); `0` = best quality, `10` = fastest   |
 | `'template'` | string      | `'image'`                   | Set file blueprint for generated images                                                |
-| `'tonemap'`  | string      | `'off'`                     | Set tonemapping (`'on'` or `'off'`)                                                    |
-| `'yuv'`      | string      | `'420'`                     | Choose yuv output format for supported formats (`'444'`, `'422'`, `'420'` or `'yv12'`) |
+| `'tonemap'`  | string|bool | `'auto'`                    | Set tonemapping (`'on'` or `'off'`, but `true` & `false` are possible, too)            |
+| `'yuv'`      | string      | `'auto'`                    | Choose yuv output format for supported formats (`'444'`, `'422'`, `'420'` or `'yv12'`) |
 
 The `colorist` library has [much more](https://github.com/joedrago/colorist/blob/master/docs/Usage.md) to offer, and more options will be made available in time - if one of it's many features you really feel is missing, feel free to open a PR!
 
+**Note:** When working with multiple formats, you may want to turn `thumbs.quality` into an array and pass the desired `format` explicitly, like this:
+
+```php
+// config.php
+
+return [
+    // ..
+    'thumbs.quality' => [
+        'avif' => 60,
+        'webp' => 80,
+    ],
+];
+
+
+// template.php
+$image->thumb(['width' => 300, 'format' => 'avif']);
+```
+
 #### Methods
 For now, the following methods are available:
 

composer.json

@@ -3,7 +3,7 @@
     "description": "Kirby v3 wrapper for colorist",
     "type": "kirby-plugin",
     "license": "MIT",
-    "version": "1.5.0",
+    "version": "1.6.0",
     "keywords": ["kirby3", "image", "graphics"],
     "homepage": "https://github.com/Fundevogel/kirby3-colorist#readme",
     "authors": [

src/Colorist.php

@@ -21,10 +21,14 @@ class Colorist extends Darkroom
     protected function defaults(): array
     {
         return parent::defaults() + [
+            'cmm'     => option('fundevogel.colorist.cmm', null),
+            'deflum'  => option('fundevogel.colorist.deflum', null),
             'format'  => null,
-            'speed'   => option('fundevogel.colorist.speed', 10),
-            'tonemap' => option('fundevogel.colorist.tonemap', 'off'),
-            'yuv'     => option('fundevogel.colorist.yuv', '420'),
+            'hlglum'  => option('fundevogel.colorist.hlglum', null),
+            'jobs'    => option('fundevogel.colorist.jobs', 0),
+            'speed'   => option('fundevogel.colorist.speed', null),
+            'tonemap' => option('fundevogel.colorist.tonemap', null),
+            'yuv'     => option('fundevogel.colorist.yuv', null),
         ];
     }
 
@@ -64,8 +68,6 @@ public static function exec_enabled(): bool
 
 
     /**
-     * Helpers
-     *
      * Building command strings
      */
 
@@ -74,37 +76,34 @@ protected function convert(string $file): string
         return sprintf(option('fundevogel.colorist.bin') . ' convert %s', $file);
     }
 
-    protected function format(array $options): string
+    protected function save(string $file): string
     {
-        $formats = [
-            'avif',
-            'bmp',
-            'jpg',
-            'jp2',
-            'j2k',
-            'png',
-            'tiff',
-            'webp',
-        ];
+        return sprintf('%s', $file);
+    }
 
-        if (in_array($options['format'], $formats)) {
-            return '--format ' . $options['format'];
-        }
 
-        return '';
-    }
+    /**
+     * Overwriting Darkroom options
+     */
 
+    # https://github.com/joedrago/colorist/blob/master/docs/Usage.md#-q---quality
     protected function quality(array $options): string
     {
         $quality = $options['quality'];
 
-        if (is_array($quality) && in_array($options['format'], $quality)) {
-            $quality = $quality[$options['format']];
+        if (is_array($quality) === true) {
+            if (isset($options['format']) === true && in_array($options['format'], $quality) === true) {
+                $quality = $quality[$options['format']];
+            } else {
+                return '';
+            }
         }
 
         return '--quality ' . $quality;
     }
 
+    # See https://github.com/joedrago/colorist/blob/master/docs/Usage.md#--resize
+    # See https://github.com/joedrago/colorist/blob/master/docs/Usage.md#-z---rect---crop
     protected function resize(string $file, array $options): string
     {
         if ($options['crop'] === false) {
@@ -252,34 +251,91 @@ protected function resize(string $file, array $options): string
         return $command;
     }
 
-    protected function tonemap(array $options): string
+
+    /**
+     * Implementing Colorist options
+     *
+     * (1) Basic options
+     * (2) Output format options
+     */
+
+    # (1) Basic options
+
+    # See https://github.com/joedrago/colorist/blob/master/docs/Usage.md#-j---jobs
+    protected function jobs(array $options): string
     {
-        $tonemap = [
-            'on',
-            'off',
+        return '--jobs ' . $options['jobs'];
+    }
+
+    # See https://github.com/joedrago/colorist/blob/master/docs/Usage.md#--cmm---cms
+    protected function cmm(array $options): string
+    {
+        $modules = [
+            'colorist',
+            'lcms',
         ];
 
-        if (in_array($options['tonemap'], $tonemap)) {
-            return '--tonemap ' . $options['tonemap'];
+        if (in_array($options['cmm'], $modules) === true) {
+            return '--cmm ' . $options['cmm'];
         }
 
-        return '--tonemap auto';
+        return '';
     }
 
-    protected function yuv(array $options): string
+    # See https://github.com/joedrago/colorist/blob/master/docs/Usage.md#--deflum---hlglum
+    protected function deflum(array $options): string
     {
-        $yuv = [
-            '444',
-            '422',
-            '420',
-            'yv12',
+        if ($options['deflum'] !== null) {
+            return '--deflum ' . $options['deflum'];
+        }
+
+        return '';
+    }
+
+    # See https://github.com/joedrago/colorist/blob/master/docs/Usage.md#--deflum---hlglum
+    protected function hlglum(array $options): string
+    {
+        if ($options['hlglum'] !== null) {
+            return '--hlglum ' . $options['hlglum'];
+        }
+
+        return '';
+    }
+
+    # (2) Output format options
+
+    # See https://github.com/joedrago/colorist/blob/master/docs/Usage.md#-b---bpc
+    protected function bpc(array $options): string
+    {
+        $min = 8;
+        $max = 16;
+
+        if (($min <= (int) $options['bpc']) && ((int) $options['bpc'] <= $max)) {
+            return '--bpc ' . $options['bpc'];
+        }
+
+        return '';
+    }
+
+    # See https://github.com/joedrago/colorist/blob/master/docs/Usage.md#-f---format
+    protected function format(array $options): string
+    {
+        $formats = [
+            'avif',
+            'bmp',
+            'jpg',
+            'jp2',
+            'j2k',
+            'png',
+            'tiff',
+            'webp',
         ];
 
-        if (in_array($options['yuv'], $yuv)) {
-            return '--yuv ' . $options['yuv'];
+        if (in_array($options['format'], $formats) === true) {
+            return '--format ' . $options['format'];
         }
 
-        return '--yuv auto';
+        return '';
     }
 
     protected function speed(array $options): string
@@ -291,23 +347,48 @@ protected function speed(array $options): string
             return '--speed ' . $options['speed'];
         }
 
-        return '--speed auto';
+        return '';
     }
 
-    protected function save(string $file): string
+    # See https://github.com/joedrago/colorist/blob/master/docs/Usage.md#-t---tonemap
+    protected function tonemap(array $options): string
     {
-        return sprintf('%s', $file);
+        # Normalize booleans
+        if ($options['tonemap'] === true) {
+            $options['tonemap'] = 'on';
+        }
+
+        if ($options['tonemap'] === false) {
+            $options['tonemap'] = 'off';
+        }
+
+        $tonemap = [
+            'on',
+            'off',
+        ];
+
+        if (in_array($options['tonemap'], $tonemap) === true) {
+            return '--tonemap ' . $options['tonemap'];
+        }
+
+        return '';
     }
 
-    public function preprocess(string $file, array $options = [])
+    # See https://github.com/joedrago/colorist/blob/master/docs/Usage.md#--yuv
+    protected function yuv(array $options): string
     {
-        $options = $this->options($options);
+        $yuv = [
+            '444',
+            '422',
+            '420',
+            'yv12',
+        ];
 
-        # TODO: As the underlying PHP function `getimagesize`
-        # doesn't recognize next-gen image formats (like AVIF) yet,
-        # this has to suffice ..
+        if (in_array($options['yuv'], $yuv) === true) {
+            return '--yuv ' . $options['yuv'];
+        }
 
-        return $options;
+        return '';
     }
 
 
@@ -317,6 +398,7 @@ public function preprocess(string $file, array $options = [])
 
     public static function identify(string $file, bool $asArray = true)
     {
+        # Build `identify` command
         $command = sprintf(option('fundevogel.colorist.bin') . ' identify --json %s', $file);
 
         exec($command, $output, $status);
@@ -328,15 +410,28 @@ public static function identify(string $file, bool $asArray = true)
         return json_decode($output[0], $asArray);
     }
 
+    public function preprocess(string $file, array $options = [])
+    {
+        $options = $this->options($options);
+
+        # TODO: As the underlying PHP function `getimagesize`
+        # doesn't recognize next-gen image formats (like AVIF) yet,
+        # we need to overwrite this function, at least for now
+
+        return $options;
+    }
+
     public function toFormat(string $src, string $dst, string $format)
     {
         $options = $this->preprocess($src, ['format' => $format]);
         $command = [];
 
+        # Build `convert` command
         $command[] = $this->convert($src, $options);
         $command[] = $this->format($options);
         $command[] = $this->save($dst);
 
+        # Let's get ready to rumble
         # (1) Remove falsey entries
         # (2) Convert command to string
         $command = implode(' ', array_filter($command));
@@ -354,15 +449,26 @@ public function process(string $file, array $options = []): array
         $options = $this->preprocess($file, $options);
         $command = [];
 
+        # Build `convert` command
         $command[] = $this->convert($file);
-        $command[] = $this->format($options);
+        # (1) Darkroom options
         $command[] = $this->quality($options);
-        $command[] = $this->speed($options);
         $command[] = $this->resize($file, $options);
+        # (2) Basic options
+        $command[] = $this->jobs($options);
+        $command[] = $this->cmm($options);
+        $command[] = $this->deflum($options);
+        $command[] = $this->hlglum($options);
+        # (3) Output format options
+        $command[] = $this->bpc($options);
+        $command[] = $this->format($options);
+        $command[] = $this->speed($options);
         $command[] = $this->tonemap($options);
         $command[] = $this->yuv($options);
+        # (4) Save image
         $command[] = $this->save($file);
 
+        # Let's get ready to rumble
         # (1) Remove falsey entries
         # (2) Convert command to string
         $command = implode(' ', array_filter($command));