README

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).

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 / kirby3-colorist

Maintainers

Details