Skip to content

fundevogel/kirby3-colorist

Repository files navigation

kirby3-colorist

Release License Issues Status

A Kirby v3 wrapper for colorist.

What

This library acts as alternative thumb driver and is fully Darkroom compliant. Therefore, kirby3-colorist doesn't interfere with custom thumb() methods (shipped with other plugins), while also being fully compatible to the popular 'Focus' plugin.

It is a Kirby v3 wrapper for the Joe Drago's colorist. While it is capable of generating and manipulating next-gen image formats (unlimited - AVIF - power!), some features aren't supported (like applying blur or grayscale).

From the colorist README:

Colorist is an image file and ICC profile converter, generator, and identifier. Why make such a tool when the venerable ImageMagick already exists and seems to offer every possible image processing tool you can imagine? The answer is absolute luminance.

If that sounds interesting and you want to read on, be sure to check it out on the commandline or just visit its homepage for more information.

How

Install this package with Composer:

composer require fundevogel/kirby3-colorist

Now, enable the plugin:

// config.php

return [
    // ..
    'thumbs.driver' => 'colorist',
];

Note: If you just want to generate something like webp, you don't need to, because gd and im can handle it, hassle-free. Using toFormat('webp') doesn't require colorist to be selected as thumb.driver (see below).

Usage

This plugin exposes several methods & configuration options.

For example, if you want to convert an image to another format:

// Converting a single image to single format:
$image = $page->image('example.jpg');
$webp = $image->toFormat('webp');
// Since this method return a `$file` object, chaining works as usual
$thumb = $webp->thumb('some-preset');

// Converting a single image to multiple formats:
$image = $page->image('example.jpg');
$results = $image->toFormats(['png', 'webp']);

For convenience, there are also methods for multiple images:

// Converting multiple images to single format:
$images = $page->images();
$webps = $images->toFormat('webp');

// Converting multiple images to multiple formats:
$images = $page->images();
$results = $images->toFormats(['png', 'webp']);

You may also extract image profile information, like this:

$image = $page->image('example.jpg');
$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, like this: 'fundevogel.colorist.optionName' (or simply pass them to the thumb() method:

Plugin options
Option Type Default(s to) Description
'bin' string __DIR__ . '/bin/colorist' Path to colorist executable
'formats' array ['webp'] Default file formats to be used on image uploads
'template' string null Set file blueprint for images generated with toFormat()
Basic options
Option Type Default(s to) Description
'jobs' int 0 Number of jobs to use when working (0 = unlimited)
'cmm' string 'auto' Color Management Module/System (lcms or colorist)
'deflum' int 80 default/fallback luminance value in nits
'hlglum' int null Like 'deflum', but uses an appropriate diffuse white based on peak HLG
Input profile options
Option Type Default(s to) Description
'iccin' string null Path to source ICC profile. default is to use embedded profile (if any) or sRGB@deflum
'frameindex' bool 0 Source frame from an image sequence (AVIF only)
Output profile options
Option Type Default(s to) Description
'iccout' string null Path to ICC profile. Disables all other output profile options
'autograde' bool false Enable automatic color grading of max luminance and gamma
'description' string null ICC profile copyright string
'copyright' string null ICC profile description
'gamma' string 'auto' Output gamma ('pq' = PQ, 'hlg' = HLG, 'source' = force source gamma)
'luminance' string int 'source'
'primaries' string null Color primaries. Use builtin (bt709, bt2020, p3) or in the form: rx,ry,gx,gy,bx,by,wx,wy
'noprofile' bool false Do not write the converted image's profile to the output file
Output format options
Option Type Default(s to) Description
'bpc' int 'auto' Set bits-per-channel (J2K/JP2 only); ranging from 8 to 16
'rate' int 0 Output rate for for supported output formats. If 0, codec uses quality value
'tonemap' string bool 'auto'
'yuv' string 'auto' Choose yuv output format for supported formats ('444', '422', '420' or 'yv12')
'speed' int 'auto' Quality/speed tradeoff when encoding (AVIF only); 0 = best quality, 10 = fastest
'nclx' string null Force the output NCLX color profile to specific values: PRI,TF,MTX (AVIF only)

Note: When working with multiple formats, you may want to turn thumbs.quality into an array:

// config.php

return [
    // ..
    'thumbs.quality' => [
        'avif' => 60,
        'webp' => 80,
    ],
];


// template.php
$image->toFormat('avif')->thumb(['width' => 300]);

Note: You may also define file templates on a per-format basis:

// config.php

return [
    // ..
    'fundevogel.colorist.template' => [
        'avif' => 'early-bird',
        'webp' => 'google-lover',
    ],
];

Methods

For now, the following methods are available:

identify (bool $asArray)

Provides information about an image's color profile (primaries, luminance and such) as well as width, height & depth.

toFormat (string $format = 'avif')

Converts an image to $format and places it alongside the original version in the respective content folder. It returns a $file object, ready to be used via thumb() etc.

toFormats (array $formats)

Converts an image to multiple $formats and places them alongside the original version in the respective content folder. It returns a $files object.

hasFormat (string $format)

Checks if $file has image of given $format, returns bool.

isFormat (string $format)

Checks if $file is image of given $format, returns bool.

Hooks

On image upload, files are automatically converted to all formats in the 'fundevogel.colorist.formats' option (['webp'] by default).

Tag

The (colorist: example.jpg) tag supports converting / resizing right from the editor.

Options

WIP

Roadmap

The colorist library has much more 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!

  • Add tests
  • Add hooks for file upload/update
  • Add tag for editor use
  • Add compatibility with 'Focus' plugin by @flokosiol
  • Add methods for editing ICC color profile

Credits

Credit where credit is due - as creator of colorist, Joe Drago is the man of the hour. The included binary powers this project, and I'm thankful for his great work.

Also, I want to say thanks to @flokosiol and @hashandsalt, from whose work I learned (and borrowed) one or two things.

Happy coding!

©️ Fundevogel Kinder- und Jugendbuchhandlung