PHP: полный мануал с примерами, функциями и ООП

Получить иллюстрацию с понятным правилом цвета

Для каталога требуется уменьшить набор цветов, оформить иллюстрации фирменными красками или получить цветной тональный рисунок для памятки. Эти требования похожи на словах, но дают разные правила: автоматически подобрать до K цветов, использовать заданный набор либо прочитать упорядоченную таблицу. Исходный цвет товара сохраняем отдельно: это оформление, а не цветопроба.

RGB — три численных компоненты цвета: R, G, B. На наших сохранённых файлах каждая имеет значения 0..255. Q — QuantumRange, максимум внутреннего канала; в проверенной Q16-сборке Q = 65535. K — ограничение общего числа цветов, а не число ступеней каждой компоненты. Colorspace обозначает пространство выбора цветов; treedepth — глубину цветового дерева, здесь 0 выбирает её автоматически. True и false — логические значения; measureError = false означает, что внутренний расчёт ошибки не запрашивается. R′, G′ и B′ — компоненты результата. Палитра — набор разрешённых цветов; CLUT — упорядоченная таблица, в которой положение имеет смысл. v — исходное значение одной компоненты; table[v].R означает красную компоненту цвета в выбранной позиции таблицы. В полной реализации позиция масштабируется из диапазона 0..Q в длину таблицы; записи 0..255 здесь относятся к нашему 256-столбцовому входу. Интенсивность — численная яркость, полученная из цветовых компонентов; прямой CLUT сравнения ниже её не вычисляет. Dithering переносит ошибку выбора цвета в соседние пиксели, создавая узор. Интерполяция вычисляет промежуточное значение между точками таблицы.

Квантование: весь вход → группы похожих цветов → ограниченный набор представителей → назначение цвета пикселям. Remap: заданные четыре краски → ближайший доступный цвет для каждого пикселя. CLUT: значение каждой компоненты → позиция таблицы → новая компонента; серый вход сначала делает три индекса одинаковыми. Ни одна модель не распознаёт смысл SKU или товара; это качественный путь данных, не полный независимый алгоритм выбора палитры.

Самая маленькая запись

В $image уже загружена независимая копия. 8 — int-предел общего числа цветов; COLORSPACE_SRGB — именованная int-константа пространства; 0 — автоматическая глубина дерева; true — фактический NoDither этой сборки; последний false отключает внутренний расчёт ошибки. Все пять аргументов обязательны. $ начинает имя переменной; -> вызывает метод объекта, скобки содержат аргументы, запятые разделяют их, ; завершает команду. Imagick::ИМЯ без скобок читает константу класса.

$image->quantizeImage(8, Imagick::COLORSPACE_SRGB, 0, true, false);

$image = clone $source; создаёт отдельный объект; обычное присваивание объект не копирует. Метод меняет текущую картинку и возвращает true, поэтому нельзя присваивать этот bool вместо изображения. В полном коде if (!...) проверяет отказ, throw new RuntimeException прерывает цепочку; clear освобождает ресурсы после сохранения. Подготовка: объекты и методы, копирование clone, исключения.

Распакуйте example.php, palette-fixture.php и source.png.b64 рядом. Начало <?php включает PHP, declare(strict_types=1) требует строгих типов вызовов. Require подключает помощник из __DIR__, папки программы. LoadPaletteSource проверяет Base64 и SHA256, восстанавливает точный source.png и возвращает Imagick. SavePaletteComparison создаёт файл сравнения с исходником слева, печатает его имя; изображение открывают просмотрщиком. Ресурсы Imagick нужны при запуске, сеть и шрифты не нужны.

<?php
declare(strict_types=1);

require __DIR__ . '/palette-fixture.php';
$source = loadPaletteSource();
$image = clone $source;
if (!$image->quantizeImage(8, Imagick::COLORSPACE_SRGB, 0, true, false)) {
    throw new RuntimeException('Не удалось применить quantizeImage');
}
savePaletteComparison([$source, $image], 'palette-first.png');
$source->clear();
$image->clear();

palette-first.png

<?php
declare(strict_types=1);

function loadPaletteSource(): Imagick
{
    $encoded = file_get_contents(__DIR__ . '/source.png.b64');
    if ($encoded === false) {
        throw new RuntimeException('Не найден source.png.b64: распакуйте весь архив');
    }
    $bytes = base64_decode($encoded, true);
    if ($bytes === false || hash('sha256', $bytes) !== '453b22e19273f2fdd54ec6a7f0cd9e96a7b08c70cc4cc854838d1428fea207c6') {
        throw new RuntimeException('Повреждён исходный PNG');
    }
    $path = __DIR__ . '/source.png';
    if (file_put_contents($path, $bytes) !== strlen($bytes)) {
        throw new RuntimeException('Не удалось восстановить source.png');
    }
    return new Imagick($path);
}

function savePaletteComparison(array $panels, string $filename): void
{
    if ($panels === []) {
        throw new InvalidArgumentException('Нужна хотя бы одна панель');
    }
    $output = new Imagick();
    $output->newImage(400 * count($panels), 320, 'white');
    $output->setImageFormat('png');
    foreach ($panels as $index => $panel) {
        if (!$panel instanceof Imagick || $panel->getImageWidth() !== 400 || $panel->getImageHeight() !== 320) {
            throw new InvalidArgumentException('Панель должна быть Imagick 400 на 320 пикселей');
        }
        if (!$output->compositeImage($panel, Imagick::COMPOSITE_OVER, 400 * $index, 0)) {
            throw new RuntimeException('Не удалось собрать сравнение');
        }
    }
    $output->setImageDepth(8);
    $output->setOption('png:color-type', '2');
    if (!$output->writeImage(__DIR__ . '/' . $filename)) {
        throw new RuntimeException('Не удалось записать результат');
    }
    $output->clear();
    echo $filename, "\n";
}

function createPaletteReference(): Imagick {
    $colors = [[24,46,67],[33,132,147],[224,155,59],[244,235,214]];
    $row = '';
    foreach ($colors as $rgb) { $row .= str_repeat(pack('C*', ...$rgb), 64); }
    $image = new Imagick();
    $image->readImageBlob("P6\n256 32\n255\n" . str_repeat($row, 32));
    return $image;
}
function createLookupTable(): Imagick {
    $row = '';
    for ($x = 0; $x < 256; $x++) {
        $row .= pack('C*', (int) round(16 + 224 * $x / 255),
            (int) round(32 + 176 * $x / 255), (int) round(64 + 64 * $x / 255));
    }
    $image = new Imagick();
    $image->readImageBlob("P6\n256 32\n255\n" . str_repeat($row, 32));
    return $image;
}
function savePaletteReference(Imagick $image, string $filename): void {
    $image->setImageFormat('png');
    $image->setImageDepth(8);
    $image->setOption('png:color-type', '2');
    if (!$image->writeImage(__DIR__ . '/' . $filename)) {
        throw new RuntimeException('Не удалось сохранить таблицу цветов');
    }
}

Function объявляет именованную функцию; Imagick после двоеточия — тип возвращаемого объекта, void означает отсутствие возвращаемого значения. Array хранит список, foreach перебирает элементы, for повторяет шаг для x от 0 до 255. Pack с C* собирает однобайтовые компоненты, str_repeat повторяет строку; P6 — простой двоичный RGB-растр в памяти, readImageBlob читает его без внешнего файла. Это инфраструктура двух маленьких reference, не скрытая обработка каталога. Помощник сохраняет PNG с 8 битами на компоненту RGB, color-type 2; число цветов ограничено обработкой, но формат не переключается в indexed PNG. Подготовка: массивы, циклы, файлы.

Разделить число цветов, палитру и индекс таблицы

Фирменная палитра содержит четыре точных RGB: (24,46,67), (33,132,147), (224,155,59), (244,235,214). CreatePaletteReference создаёт 256×32, по 64 одинаковых столбца на цвет. Все 32 строки одинаковы; размеры удобны для просмотра, remap использует набор цветов. SavePaletteReference сохраняет этот реальный вход отдельно. Обеим программам remap передаётся та же палитра.

CreateLookupTable создаёт другой объект 256×32: в столбце x красный равен round(16+224×x/255), зелёный round(32+176×x/255), синий round(64+64×x/255). Round округляет до целого, (int) задаёт целочисленное значение. При x = 0 это (16,32,64), при 255 — (240,208,128); строки повторяются. CLUT трактует расположение как шкалу, remap — как набор; переставить столбцы CLUT означает изменить преобразование.

Перед следующей программой: $palette и $lookup создаются предоставленными функциями; $mapped и $colored — независимые clone исходника. TransformImageColorspace(GRAY) меняет сами значения, а не только метку. SetInterpolateMethod(BILINEAR) задаёт способ вычисления между точками таблицы. Похожий setImageInterpolateMethod в этой сборке меняет другую настройку, которую clutImage здесь не читает. Константы с :: — целые значения настроек, а не строки с цветами.

$image->quantizeImage(8, Imagick::COLORSPACE_SRGB, 0, true, false);
$palette = createPaletteReference();
$mapped->remapImage($palette, Imagick::DITHERMETHOD_NO);
$lookup = createLookupTable();
$colored->transformImageColorspace(Imagick::COLORSPACE_GRAY);
$colored->setInterpolateMethod(Imagick::INTERPOLATE_BILINEAR);
$colored->clutImage($lookup);

<?php
declare(strict_types=1);

require __DIR__ . '/palette-fixture.php';
$source = loadPaletteSource();
$image = clone $source;
if (!$image->quantizeImage(8, Imagick::COLORSPACE_SRGB, 0, true, false)) {
    throw new RuntimeException('Не удалось применить quantizeImage');
}
$palette = createPaletteReference();
savePaletteReference($palette, 'palette-reference.png');
$mapped = clone $source;
if (!$mapped->remapImage($palette, Imagick::DITHERMETHOD_NO)) {
    throw new RuntimeException('Не удалось применить remapImage');
}
$lookup = createLookupTable();
savePaletteReference($lookup, 'lookup-table.png');
$colored = clone $source;
if (!$colored->transformImageColorspace(Imagick::COLORSPACE_GRAY)) {
    throw new RuntimeException('Не удалось применить transformImageColorspace');
}
$colored->setInterpolateMethod(Imagick::INTERPOLATE_BILINEAR);
if (!$colored->clutImage($lookup)) {
    throw new RuntimeException('Не удалось применить clutImage');
}
savePaletteComparison([$source, $image, $mapped, $colored], 'palette-controls.png');
$source->clear();
$image->clear();
$mapped->clear();
$colored->clear();
$palette->clear();
$lookup->clear();

palette-controls.png

Разобрать обязательность, единицы и версии

RGB — три численных компоненты цвета: R, G, B. На наших сохранённых файлах каждая имеет значения 0..255. Q — QuantumRange, максимум внутреннего канала; в проверенной Q16-сборке Q = 65535. K — ограничение общего числа цветов, а не число ступеней каждой компоненты. Colorspace обозначает пространство выбора цветов; treedepth — глубину цветового дерева, здесь 0 выбирает её автоматически. True и false — логические значения; measureError = false означает, что внутренний расчёт ошибки не запрашивается. R′, G′ и B′ — компоненты результата. Палитра — набор разрешённых цветов; CLUT — упорядоченная таблица, в которой положение имеет смысл. v — исходное значение одной компоненты; table[v].R означает красную компоненту цвета в выбранной позиции таблицы. В полной реализации позиция масштабируется из диапазона 0..Q в длину таблицы; записи 0..255 здесь относятся к нашему 256-столбцовому входу. Интенсивность — численная яркость, полученная из цветовых компонентов; прямой CLUT сравнения ниже её не вычисляет. Dithering переносит ошибку выбора цвета в соседние пиксели, создавая узор. Интерполяция вычисляет промежуточное значение между точками таблицы.

Quantize имеет пять обязательных аргументов; remap — объект и int enum, оба обязательны; у CLUT обязательна таблица и необязательна маска каналов. Bool quantize и int remap не взаимозаменяемы. Нельзя перенести совет о включении dithering из старой IM6-команды без проверки связки. В наших двух режимах quantize при K = 8 и автоматической глубине различаются и выбранные RGB-представители, и распределение; у remap reference фиксирован.

Предел цветов и хранение файла — разные вещи. Наши результаты содержат RGB с 8 битами на компоненту и color-type 2, даже когда используются всего два или четыре сочетания. Индексированный PNG хранит номера палитры и требует отдельного выбора формата. Наша глава проверяет оформление и точные цвета, не обещает определённый размер или структуру индексированного файла.

Выбрать и повторно использовать палитру

На нашем входе оба режима квантования дали восемь цветов. Это не четыре RGB-ступени предыдущей главы и не гарантированное использование каждого K на любом изображении. В малом 256-пиксельном опыте запрос восьми дал семь. Определять качество только числом цветов нельзя: узор dithering способен мешать буквам, а без него заметны границы областей.

Обе программы remap используют одинаковые RGB/RGBA-пиксели палитры, созданной из тех же четырёх RGB. Байты сохранённых PNG могут различаться из-за метаданных; это не обещание идентичности файлов. Полный результат имеет четыре цвета; у локального варианта весь кадр содержит больше, поскольку неизменённые поля и шкалы сохраняют исходные цвета. Внутри ROI все цвета принадлежат reference; изменено 46464 пикселя, снаружи ноль. Палитра относится к обрабатываемой области, не требует перекрасить защищённую SKU.

Прочитать таблицу по значению компоненты

R′, G′ и B′ — компоненты результата. Для цветного RGB они читают разные позиции: (120,80,40) использует x = 120, 80, 40. После явного преобразования в серый три индекса равны, поэтому цвет берётся с одной позиции градиента. Это тонирование и тональная настройка, а не научное восстановление свойств товара.

В Q16 таблица сопоставляется диапазону 0..65535, даже когда её PNG содержит 256 столбцов. Для таблицы произвольной длины значение канала не обязательно равно номеру столбца. Интерполяция смешивает соседние точки: ограничить вход дискретными метками и получить точный список красок — отдельное требование. Для набора разрешённых цветов удобнее remap; для CLUT заранее определяют шкалу, интерполяцию и политику alpha.

В основном вызове Bilinear задаётся через setInterpolateMethod: это способ вычисления между точками таблицы. Похожее setImageInterpolateMethod в этой сборке меняет другую настройку, которую clutImage здесь не читает. Выбор маски CHANNEL_RED не меняет геометрию; G/B в сохранённом результате совпали с исходником во всех пикселях.

Проверить потери, ошибки и прозрачность

Восемь программ выполнены в PHP 8.5.11, Imagick 3.8.1, ImageMagick 7.1.1-46 Q16. Сохранены точные stdout, пустой stderr, восемь основных PNG и шесть PNG-reference. Исходник восстановлен побайтно во всех папках; панели сравнения не меняют масштаб. Это подтверждает реальные примеры и конкретные свойства, не полноту всего PHP Manual или художественную пригодность любого файла.

Отдельный малый RGBA-опыт показал сохранение alpha у выбранного quantize-вызова и у CLUT с CHANNEL_RED, но remap с непрозрачной палитрой сделал alpha непрозрачной. Это не проверка default CLUT alpha и не гарантия для любого прозрачного/ICC/CMYK/HDR/многокадрового входа. Основные программы намеренно используют непрозрачный RGB. Любую требуемую прозрачность проектируют и проверяют отдельно.

MeasureError — внутренний расчёт, без автоматического вывода метрик в PHP. В малом опыте оба значения флага дали одинаковые декодированные RGBA-пиксели при экспорте и после повторного чтения PNG; не выводим поведение всей цепочки из одного условия C. Размер, скорость и память зависят от данных, K, глубины и dithering. Для сервиса отдельно ограничивают файл и параметры, обрабатывают ошибки чтения/эффекта/записи и не раскрывают внутренние пути в ответах.

Выбрать инструмент и оформить свой макет

• Нужен предел общего числа цветов — quantize с понятными K, пространством и глубиной.
• Нужны конкретные разрешённые RGB — remap с явной палитрой и int dither enum.
• Нужно связать уровень компоненты с новой компонентой — CLUT с заданными шкалой, интерполяцией и маской.
• Нужен цвет по яркости — сначала явная серая подготовка, затем CLUT; не выдавать такой макет за научные измерения.

Упражнение: применить четыре фирменных цвета только к товарной области, сохранив артикул. Решение: createPaletteReference; clone; cropImage(352,132,24,88); setImagePage(0,0,0,0); remapImage($palette, DITHERMETHOD_NO); COMPOSITE_OVER в (24,88). Полный переносимый код — локальное применение общей палитры. Затем объясните, почему заменить палитру теми же четырьмя цветами в CLUT недостаточно для того же результата.

Дальше: поканальные ступени и цветовые эффекты, художественные фактуры, тонирование и инверсия, надёжная работа с файлами. Новый вариант начинайте с того, какие данные должны остаться точными.