README

PHP extension for Aura, a library for extracting prominent color swatches from images.

Aura handles only the color processing. Reading and decoding the image is the caller's responsibility — the extension operates on raw RGBA pixel data provided as a binary string.

Installation via PIE

PIE (PHP Installer for Extensions) is the recommended way to install this extension.

The extension locates libaura via pkg-config. If libaura is installed in a standard system prefix, no extra flags are needed:

pie install libaura/ext-aura

If libaura is installed in a custom prefix, point pkg-config at it first:

PKG_CONFIG_PATH=/path/to/libaura-prefix/lib/pkgconfig pie install libaura/ext-aura

You can download a pre-built libaura prefix from the libaura releases:

curl -fL -o libaura.tar.gz \
  "https://gitlab.com/api/v4/projects/libaura%2Faura/packages/generic/libaura/v1.0.1/libaura-linux-x86_64.tar.gz"
mkdir -p libaura-prefix && tar -xzf libaura.tar.gz -C libaura-prefix

PKG_CONFIG_PATH=$PWD/libaura-prefix/lib/pkgconfig pie install libaura/ext-aura

PIE will add extension=aura to your php.ini automatically.

Manual build

PKG_CONFIG_PATH=/path/to/libaura-prefix/lib/pkgconfig phpize
./configure
make

If you prefer to pass the prefix directly instead of using pkg-config:

phpize
./configure --with-aura=/path/to/libaura-prefix
make

Load the built extension manually:

php -d extension=modules/aura.so your_script.php

Usage

The extension exposes five classes under the Aura\ namespace. The entry point is the static Palette::generate() method, which accepts raw RGBA pixel data as a binary string:

$palette = Aura\Palette::generate($imageContents);

if ($palette->vibrant !== null) {
    $r = $palette->vibrant->color->r;
    $g = $palette->vibrant->color->g;
    $b = $palette->vibrant->color->b;
}

An optional Aura\Config can be passed to control filtering behaviour:

$config = new Aura\Config(ignore_ineligible: true, filter: false);
$palette = Aura\Palette::generate($imageContents, $config);

Swatch roles

Palette exposes six nullable Swatch properties, not all of which may be present for a given image:

Property	Description
`vibrant`	Vivid, saturated color
`vibrant_dark`	Dark variant of vibrant
`vibrant_light`	Light variant of vibrant
`muted`	Desaturated color
`muted_dark`	Dark variant of muted
`muted_light`	Light variant of muted

Each Swatch has:

color: Aura\Color — r, g, b (0–255)
hsl: Aura\Hsl — h (0–360), s (0–1), l (0–1)
population: int — pixel count; indicates dominance
was_ineligible: bool — true if the swatch was only selected because no eligible candidate existed
is_text_white: bool — suggested text color for contrast

Preparing pixel data

generate() expects tightly-packed RGBA bytes — 4 bytes per pixel, no stride or padding. The length of the string must be a multiple of 4.

Using Imagick:

function imagickToRgba(string $path): string {
    $img = new Imagick($path);
    return pack('C*', ...$img->exportImagePixels(
        0, 0, $img->getImageWidth(), $img->getImageHeight(), 'RGBA', Imagick::PIXEL_CHAR
    ));
}

Note: exportImagePixels() returns a PHP array of integers before pack() converts it to a string. For large images this intermediate array can be substantial. For best performance, downsample images before passing them to generate().

Using GD:

function gdToRgba(string $path): string {
    $img = imagecreatefromstring(file_get_contents($path));
    imagepalettetotruecolor($img);

    $out = '';
    for ($y = 0, $h = imagesy($img); $y < $h; $y++) {
        for ($x = 0, $w = imagesx($img); $x < $w; $x++) {
            $c = imagecolorat($img, $x, $y);
            $out .= pack('C4',
                ($c >> 16) & 0xFF,
                ($c >> 8)  & 0xFF,
                 $c        & 0xFF,
                (127 - (($c >> 24) & 0x7F)) * 2
            );
        }
    }

    imagedestroy($img);
    return $out;
}

Note: The GD pixel loop is slow on large images. For best performance, downsample images before passing them to generate().

Version constants

echo Aura\VERSION;        // e.g. "1.0.1"
echo Aura\VERSION_MAJOR;  // 1
echo Aura\VERSION_MINOR;  // 0
echo Aura\VERSION_PATCH;  // 1

Requirements

PHP 8.1+
libaura (linux/x86_64 pre-built prefix available from libaura releases)
pkg-config (for auto-detection; or use --with-aura=DIR to bypass it)

libaura / ext-aura

Maintainers

Package info

Statistics

Security