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.

pie install libaura/ext-aura --with-aura=/path/to/libaura-prefix

--with-aura must point to a directory containing the pre-built libaura prefix (an include/ tree and lib/libaura.a). You can download a pre-built 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

pie install libaura/ext-aura --with-aura=$PWD/libaura-prefix

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

Manual build

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:

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
    ));
}

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+
• Pre-built libaura prefix (linux/x86_64 tarball available from libaura releases)