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

Осветлить карточку: яркость и гамма

Карточка товара выглядит тусклой. Сначала изменим одну настройку и сравним с исходником, затем попробуем другой способ осветления. На собственном градиенте фон идёт от 75 до 185 из 255; цветные плашки помогают заметить, меняются ли оттенки. Все картинки ниже — целые настоящие PNG320×200.

$image = new Gmagick(__DIR__ . "/tone.ppm");
$image->modulateImage(115, 100, 100);
$image->setImageDepth(8);
$image->setImageFormat("PNG");
$image->writeImage(__DIR__ . "/lighter.png");

Переменная $image хранит объект с изображением; -> вызывает его метод. Три числа modulateImage задают яркость, насыщенность и оттенок. Нейтральное значение каждого —100. Здесь 115 означает настройку яркости 115%, а 100 сохраняет остальные настройки. Это не прибавление 115 к каждому RGB-компоненту. setImageDepth(8) выбирает 8-битный результат, setImageFormat задаёт кодер, writeImage сохраняет файл. В полной программе clone создаёт независимые копии для сравнения.

<?php
declare(strict_types=1);
require __DIR__.'/gm97-color-fixture.php';
gmRestore();
$source=new Gmagick(__DIR__.'/tone.ppm');
$neutral=clone $source;
$neutral->modulateImage(100,100,100);
$light=clone $source;
$light->modulateImage(115,100,100);
$gamma=clone $source;
$gamma->gammaImage(1.4);
gm97Png($source,'gm97-color-light-before.png');
gm97Png($light,'gm97-color-light-modulate.png');
gm97Png($gamma,'gm97-color-light-gamma.png');
$errors=['gamma_type'=>gmTry(fn()=>(new Gmagick(__DIR__.'/tone.ppm'))->gammaImage([]))];

gmReport('gm97-color-light',["modulateimage", "gammaimage", "__construct", "getimagesignature", "setimagedepth", "setimageformat", "writeimage"],["gm97-color-light-before.png", "gm97-color-light-modulate.png", "gm97-color-light-gamma.png"],
    ['neutral_100'=>$neutral->getImageSignature()===$source->getImageSignature(),'brightness_changes'=>$light->getImageSignature()!==$source->getImageSignature(),'gamma_differs'=>$gamma->getImageSignature()!==$light->getImageSignature()],
    $errors ?? [], []);
echo "light: neutral100=yes brightness-and-gamma=different png=3 size=320x200\n";

light: neutral100=yes brightness-and-gamma=different png=3 size=320x200

Gamma — нелинейная коррекция тонов: gammaImage(1.4) в этой среде осветляет средние значения иначе, чем modulateImage. Единица нейтральна. У типичных фотографических настроек PHP.net приводит диапазон 0.8–2.3; это ориентир, а не обязательный предел PHP. Значение должно иметь смысл для выбранного изображения. Гамма не является калибровкой монитора или заменой работы с цветовым профилем. Упражнение: ослабить насыщенность, не меняя две другие настройки. Решение: modulateImage(100,80,100). Передача массива вместо числа отдельно ловится как TypeError.

Если это первый опыт с Gmagick, начните с чтения собственного изображения и проверенного сохранения. Здесь используются переменные, объекты и исключения. Сравнение вариантов основано на настоящих файлах; белый результат ошибки уровней показан как ошибка, не как художественная схема.

Далее: подавление шума; перед выпуском — глубина, метаданные и подписи файлов.

Задать точки чёрного и белого, проверить порядок

Нужно усилить контраст предсказуемо: выбрать, что считать чёрным и белым. Модель проста: исходные уровни 60 и 200 должны стать границами выходного диапазона, промежуточные — распределиться между ними. Значения ниже нижней точки и выше верхней обрезаются. Но сначала необходимо увидеть различие документации и проверенной библиотеки.

$image = new Gmagick(__DIR__ . "/tone.ppm");
$black = 60 * 257;
$white = 200 * 257;
$image->levelImage($black, 1.0, $white);
$image->setImageFormat("PNG");
$image->writeImage(__DIR__ . "/documented-order.png");

Это официальный порядок: blackPoint, gamma, whitePoint, затем необязательный канал. В Q16 максимальное значение 65535; поэтому 8-битные 60 и 200 умножаются на 257. Гамма 1.0 должна оставить линейное растяжение. На GraphicsMagick 1.3.42 этот конкретный вызов реально дал белый PNG. В исходниках Wand параметры gamma и white переставлены перед Core. Мы сохраняем этот результат рядом с исправленным, чтобы ошибку библиотеки нельзя было принять за обычное действие уровней.

<?php
declare(strict_types=1);
require __DIR__.'/gm97-color-fixture.php';
gmRestore();
$source=new Gmagick(__DIR__.'/tone.ppm');
$documented=clone $source;
gm97KnownLevelRuntime();
$documented->levelImage(60*257,1.0,200*257);
$leveled=clone $source;
gm97Levels($leveled,60*257,1.0,200*257);
$normal=clone $source;
$normal->normalizeImage();
gm97Png($source,'gm97-color-levels-before.png');
gm97Png($documented,'gm97-color-levels-documented.png');
gm97Png($leveled,'gm97-color-levels-adapted.png');
gm97Png($normal,'gm97-color-levels-auto.png');
$errors=['normalize_channel'=>gmTry(fn()=>(new Gmagick(__DIR__.'/tone.ppm'))->normalizeImage(Gmagick::CHANNEL_RED))];

gmReport('gm97-color-levels',["levelimage", "normalizeimage", "getimagedepth", "__construct", "getimagesignature", "setimagedepth", "setimageformat", "writeimage"],["gm97-color-levels-before.png", "gm97-color-levels-documented.png", "gm97-color-levels-adapted.png", "gm97-color-levels-auto.png"],
    ['known_runtime_threshold'=>$documented->getImageDepth()===1,'adapted_has_tones'=>$leveled->getImageDepth()>1,'adapted_differs'=>$leveled->getImageSignature()!==$documented->getImageSignature(),'normal_changes'=>$normal->getImageSignature()!==$source->getImageSignature()],
    $errors ?? [], []);
echo "levels: documented=white adapted=tones normalize=changed png=4\n";

levels: documented=white adapted=tones normalize=changed png=4

Полный пример использует gm97Levels: он допускает только Gmagick 2.0.6RC1/GraphicsMagick 1.3.42 Q16, проверяет 0≤black<white и gamma>0, затем передаёт аргументы в порядке, исправляющем подтверждённую перестановку. В другой версии помощник останавливается. При переходе на исправленную реализацию сначала сравните результат контрольного входа, затем используйте обычный levelImage($black,$gamma,$white); не переносите перестановку вслепую. normalizeImage выбирает растяжение автоматически, поэтому его результат иной. В нашем runtime normalizeImage не принимает канал: дополнительный аргумент дал ArgumentCountError. Упражнение: восстановит ли растяжение уже потерянные светлые детали? Решение: нет, обрезанные значения нельзя восстановить из одной итоговой белой области.

function gm97KnownLevelRuntime():void {
    $version=Gmagick::getVersion()['versionString'];
    if(phpversion('gmagick')!=='2.0.6RC1'||!str_starts_with($version,'GraphicsMagick 1.3.42 ')||Gmagick::QUANTUM_DEPTH!==16) {
        throw new LogicException('Recheck levelImage argument order in this runtime before using the 1.3.42 adapter');
    }
}
function gm97Levels(Gmagick $image,float $black,float $gamma,float $white,int $channel=Gmagick::CHANNEL_ALL):void {
    gm97KnownLevelRuntime();
    if(!is_finite($black)||!is_finite($gamma)||!is_finite($white)||$black<0||$white<=$black||$gamma<=0) {
        throw new InvalidArgumentException('Require finite 0 <= black < white and gamma > 0');
    }
    // GraphicsMagick 1.3.42 Wand swaps gamma and white on its way to Core.
    // Only this explicitly checked runtime uses the reversed PHP arguments.
    $image->levelImage($black,$white,$gamma,$channel);
}

Далее: подавление шума; перед выпуском — глубина, метаданные и подписи файлов.

Сравнить растяжение диапазона и выравнивание гистограммы

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

$source = new Gmagick(__DIR__ . "/tone.ppm");
$normal = clone $source;
$normal->normalizeImage();
$equal = clone $source;
$equal->equalizeImage();
$equal->setImageFormat("PNG");
$equal->writeImage(__DIR__ . "/equalized.png");

normalizeImage усиливает контраст, растягивая используемые значения. equalizeImage выравнивает гистограмму: широко представленные и редкие уровни перераспределяются иначе. Оба метода меняют объект, не возвращают отдельный файл. clone отделяет варианты; исходный объект остаётся для сравнения. Скобки без аргументов означают, что собственных числовых настроек этим вызовам здесь не передаём.

<?php
declare(strict_types=1);
require __DIR__.'/gm97-color-fixture.php';
gmRestore();
$source=new Gmagick(__DIR__.'/tone.ppm');
$normal=clone $source;
$normal->normalizeImage();
$equal=clone $source;
$equal->equalizeImage();
gm97Png($source,'gm97-color-histogram-before.png');
gm97Png($normal,'gm97-color-histogram-normal.png');
gm97Png($equal,'gm97-color-histogram-equal.png');

gmReport('gm97-color-histogram',["normalizeimage", "equalizeimage", "__construct", "getimagesignature", "setimagedepth", "setimageformat", "writeimage"],["gm97-color-histogram-before.png", "gm97-color-histogram-normal.png", "gm97-color-histogram-equal.png"],
    ['normalize_changed'=>$normal->getImageSignature()!==$source->getImageSignature(),'equalize_changed'=>$equal->getImageSignature()!==$source->getImageSignature(),'different_algorithms'=>$normal->getImageSignature()!==$equal->getImageSignature()],
    $errors ?? [], []);
echo "histogram: normalize-and-equalize=different png=3 size=320x200\n";

histogram: normalize-and-equalize=different png=3 size=320x200

Ожидаются три PNG320×200; подписи пикселей двух обработанных вариантов различны. Смотрите на фон и цвет плашек: «контрастнее» не означает «точнее передаёт цвет товара». Автоматическая коррекция может выделить шум и изменить цветовые отношения. Упражнение: какой метод выбрать для точного порога 60–200? Решение: levelImage с проверенным контрактом, потому что normalize/equalize не получают эти две границы. Для серии товаров сначала сравните несколько характерных входов, а не утверждайте универсальность одного пресета.

Далее: подавление шума; перед выпуском — глубина, метаданные и подписи файлов.

Собрать умеренную коррекцию для каталога

Соберём небольшой рабочий маршрут для тусклой карточки: осторожно расширим диапазон, затем немного ослабим насыщенность. Промежуточная картинка делает каждый шаг наблюдаемым. Здесь не пытаемся угадать правильный цвет товара: исходник остаётся рядом с результатом для осознанного выбора.

$source = new Gmagick(__DIR__ . "/tone.ppm");
$result = clone $source;
gm97Levels($result, 40 * 257, 1.0, 220 * 257);
$result->modulateImage(105, 85, 100);
$result->setImageFormat("PNG");
$result->writeImage(__DIR__ . "/catalog-tone.png");

gm97Levels — наша функция из предыдущего шага, а не метод расширения. Она ограничена проверенной версией 1.3.42. Числа 40 и 220 дают менее сильное растяжение, чем 60 и 200. Затем modulateImage получает яркость 105, насыщенность 85 и нейтральный оттенок 100. Полная программа сохраняет исходник, результат первого шага и окончательный PNG, поэтому видно вклад обоих действий.

<?php
declare(strict_types=1);
require __DIR__.'/gm97-color-fixture.php';
gmRestore();
$source=new Gmagick(__DIR__.'/tone.ppm');
$result=clone $source;
gm97Levels($result,40*257,1.0,220*257);
$levels=clone $result;
$result->modulateImage(105,85,100);
gm97Png($source,'gm97-color-preset-before.png');
gm97Png($levels,'gm97-color-preset-levels.png');
gm97Png($result,'gm97-color-preset-final.png');
$errors=['invalid_levels'=>gmTry(fn()=>gm97Levels(clone $source,200,1,100))];

gmReport('gm97-color-preset',["levelimage", "modulateimage", "__construct", "getimagesignature", "setimagedepth", "setimageformat", "writeimage"],["gm97-color-preset-before.png", "gm97-color-preset-levels.png", "gm97-color-preset-final.png"],
    ['levels_changed'=>$levels->getImageSignature()!==$source->getImageSignature(),'second_step_changed'=>$result->getImageSignature()!==$levels->getImageSignature(),'source_unchanged_object'=>$source->getImageSignature()===(new Gmagick(__DIR__."/tone.ppm"))->getImageSignature()],
    $errors ?? [], []);
echo "preset: levels40-220 then brightness105 saturation85 hue100 png=3\n";

preset: levels40-220 then brightness105 saturation85 hue100 png=3

Ожидаются три разных состояния 320×200, исходный файл не изменяется. Переставленные точки 200 и 100 отвергает наша функция с InvalidArgumentException: это собственное правило, не обещание одинаковой проверки внутри каждой версии Gmagick. Упражнение: сохранить силу насыщенности, но оставить это осветление. Решение: заменить 85 на 100. Если каталогу нужна достоверная цветопередача, этот учебный пресет надо согласовать по эталонным изображениям и цветовому процессу.

Далее: подавление шума; перед выпуском — глубина, метаданные и подписи файлов.

Проверить порядок гаммы и выравнивания

Два хороших действия не обязательно взаимозаменяемы по порядку. Перед массовой обработкой проверим маршруты «гамма → гистограмма» и «гистограмма → гамма». У каждого маршрута независимый объект, а исходник один и тот же.

$source = new Gmagick(__DIR__ . "/tone.ppm");
$first = clone $source;
$first->gammaImage(1.4);
$first->equalizeImage();
$second = clone $source;
$second->equalizeImage();
$second->gammaImage(1.4);

Каждая строка действует на текущее состояние объекта. Во втором вызове входом служит уже изменённое изображение. Полная программа сохраняет оба результата отдельно, а getImageSignature сравнивает их пиксельные потоки. Эта строковая подпись понадобится в главе о проверке экспорта; она удобна для проверки равенства, но не оценивает красоту.

<?php
declare(strict_types=1);
require __DIR__.'/gm97-color-fixture.php';
gmRestore();
$source=new Gmagick(__DIR__.'/tone.ppm');
$first=clone $source;
$first->gammaImage(1.4);
$first->equalizeImage();
$second=clone $source;
$second->equalizeImage();
$second->gammaImage(1.4);
gm97Png($source,'gm97-color-order-before.png');
gm97Png($first,'gm97-color-order-gamma-equal.png');
gm97Png($second,'gm97-color-order-equal-gamma.png');

gmReport('gm97-color-order',["gammaimage", "equalizeimage", "__construct", "getimagesignature", "setimagedepth", "setimageformat", "writeimage"],["gm97-color-order-before.png", "gm97-color-order-gamma-equal.png", "gm97-color-order-equal-gamma.png"],
    ['order_matters'=>$first->getImageSignature()!==$second->getImageSignature(),'first_changed'=>$first->getImageSignature()!==$source->getImageSignature(),'second_changed'=>$second->getImageSignature()!==$source->getImageSignature()],
    $errors ?? [], []);
echo "order: gamma-then-equalize differs-from equalize-then-gamma png=3\n";

order: gamma-then-equalize differs-from equalize-then-gamma png=3

На нашем входе подписи различаются: операции не переставляются без изменения результата. Упражнение: зачем clone, если переменная называется иначе? Решение: обычное присваивание объекта не создаёт независимый растр; обе переменные могут обращаться к одному объекту. Для рабочего каталога фиксируйте порядок обработки вместе со значениями настроек и сохраняйте исходник. Следующий шаг — убрать шум до финального кодирования, чтобы JPEG не закрепил его артефакты.

Далее: подавление шума; перед выпуском — глубина, метаданные и подписи файлов.

Из реального вопроса разработчика

How to change brightness using Imagick?. Автор вопроса об Imagick хочет изменить яркость, сохранив насыщенность и оттенок, и не знает нейтральных значений. Проблема применима к выбору настроек, но API другого расширения не переносим автоматически. Наш Gmagick-пример отдельно проверяет нейтральный набор100,100,100, сохраняет самостоятельные варианты яркости и гаммы и показывает разницу.