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

PECL imagick 3 >= 3.3.0 · imagick

Imagick::autoLevelImage(int $channel = Imagick::CHANNEL_DEFAULT): bool

Картинка выглядит тусклой, поскольку её значения используют только часть доступного диапазона. Нужна быстрая исходная попытка без выбора двух отсечек.

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

В $image уже находится независимая копия рисунка. Пустые скобки допустимы: единственный аргумент channel необязателен и берётся CHANNEL_DEFAULT. В нашей копии метод растянет крайние 20/230 к 0/255; главная картинка с диапазоном 70..190 займёт внутреннюю часть. Стрелка вызывает метод объекта; круглые скобки содержат аргументы, точка с запятой завершает команду. До изменения создайте $image = clone $source: присваивание без clone оставило бы два имени одного объекта.

$image->autoLevelImage();

Это поясняющий фрагмент. Полная программа ниже загрузит переносимый вход, проверит возврат и сохранит PNG. Основы: объект и метод, копирование, аргумент вызова.

Сигнатура и параметры

Imagick::autoLevelImage(int $channel = Imagick::CHANNEL_DEFAULT): bool

Метод ищет текущий минимум и максимум и растягивает их к полному QuantumRange. В простой модели result=(value−minimum)/(maximum−minimum)×QuantumRange. В нашей RGB-копии крайние нейтральные точки 20/230 задают общий диапазон. Метод не отличает полезную деталь от выброса.

Возвращаемое значение, версии и отказ

Возвращается bool: true при успехе. Метод меняет пиксели текущего объекта Imagick; $ok = $image->autoLevelImage(...) сохранит флаг, не новую картинку. Доступность по PHP Manual: PECL imagick 3 >= 3.3.0. Обязательные параметры и default сохранены в сигнатуре выше.

AutoLevelImage добавлен в PECL imagick 3.3.0; точная C-сборка также содержит условие MagickLibVersion >0x655, то есть библиотека новее 6.5.5. Проверьте наличие метода при поддержке старых установок.

Хотя у этих страниц нет отдельного описания ошибок, точная обвязка и preflight подтверждают ImagickException на пустом изображении и преобразование native-отказа в исключение. Чтение и запись могут отказать отдельно. В полном коде ! означает «вернулся false», throw создаёт отказ; clear освобождает native-ресурсы. Для сайта перехватите исключение и выдайте понятное сообщение без внутренних путей. True не обещает нужного качества, допустимых настроек или сохранения деталей.

Первый управляемый результат

<?php
declare(strict_types=1);

require __DIR__ . '/stretch-fixture.php';
$source = loadStretchSource();
$image = clone $source;
if (!$image->autoLevelImage()) {
    throw new RuntimeException('Не удалось применить autoLevelImage');
}
saveStretchComparison([$source, $image], 'auto-level-basic.png');
$source->clear();
$image->clear();

auto-level-basic.png

Практическая задача: Исключить посторонние крайние точки выбором области товара

Края макета содержат служебные метки, но контраст нужен самой картинке коробки и кружки. Знаем её прямоугольник и вычисляем min/max только внутри него; нижние шкалы и внешние выбросы оставляем без изменения.

CropImage получает ширину 352,высоту 184 и начало x=24,y=36; setImagePage сбрасывает виртуальное смещение вырезки. CompositeImage с COMPOSITE_OVER возвращает готовую область в(24,36). Переменная $region хранит отдельный объект; координаты задаёт макет, библиотека не узнаёт предмет сама. Границы и гистограмма определяются внутри вырезки.

<?php
declare(strict_types=1);

require __DIR__ . '/stretch-fixture.php';
$source = loadStretchSource();
$image = clone $source;
$region = clone $source;
$region->cropImage(352, 184, 24, 36);
$region->setImagePage(0, 0, 0, 0);
if (!$region->autoLevelImage()) {
    throw new RuntimeException('Не удалось применить autoLevelImage');
}
if (!$image->compositeImage($region, Imagick::COMPOSITE_OVER, 24, 36)) {
    throw new RuntimeException('Не удалось вернуть область');
}
$region->clear();
saveStretchComparison([$source, $image], 'auto-level-region.png');
$source->clear();
$image->clear();

auto-level-region.png

Ошибки, ограничения и альтернативы

Даже единичный крайний пиксель способен ограничить min/max. Если уже есть 0 и QuantumRange, полезного расширения может не быть. На ровной плашке 50% в нашей проверке метод вернул true и оставил значение прежним: отсутствующий контраст не возникает из ничего. Для контролируемой устойчивости к выбросам нужны другие критерии или выбранная область.

Основные программы используют один непрозрачный sRGB PNG. На отдельном RGBA-образце нашей сборки default этих четырёх операций менял alpha; у трёх методов с channel явная маска RED|GREEN|BLUE сохранила её. У linearStretchImage channel-аргумента нет. Для прозрачных файлов заранее выберите и проверьте самостоятельную политику alpha. Цветовые профили и многокадровые файлы также требуют отдельной обработки.

Соседние методы: normalizeImage · contrastStretchImage · linearStretchImage. Для яркости, контраста и gamma: гамма, яркость и контраст; для двоичного документа: пороги.

• Imagick::autoLevelImage
• Imagick 3.8.1 PHP-wrapper
• ImageMagick 7.1.1-46 enhance.c

PECL imagick 2, PECL imagick 3 · imagick

Imagick::normalizeImage(int $channel = Imagick::CHANNEL_DEFAULT): bool

Редкие крайние метки или отдельные дефекты не должны сжимать полезный диапазон всей картинки. Нужна готовая автоматическая политика.

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

В $image находится независимая копия. Пустые скобки выбирают default channel. Нормализация найдёт границы своей встроенной политики; на нашем входе редкие 20/230 не будут единственными опорами диапазона. Это решение по гистограмме, не распознавание коробки или дефекта. Стрелка вызывает метод объекта; круглые скобки содержат аргументы, точка с запятой завершает команду. До изменения создайте $image = clone $source: присваивание без clone оставило бы два имени одного объекта.

$image->normalizeImage();

Это поясняющий фрагмент. Полная программа ниже загрузит переносимый вход, проверит возврат и сохранит PNG. Основы: объект и метод, копирование, аргумент вызова.

Сигнатура и параметры

Imagick::normalizeImage(int $channel = Imagick::CHANNEL_DEFAULT): bool

Общее описание PHP Manual обещает расширение доступного диапазона. Точная ImageMagick 7.1.1-46 реализует NormalizeImage через ContrastStretchImage с black_point=0.02×N и white_point=0.99×N: нижние 2% и верхний 1% по накопленной гистограмме. Это конкретная встроенная политика, а не просто другое имя autoLevel.

Возвращаемое значение, версии и отказ

Возвращается bool: true при успехе. Метод меняет пиксели текущего объекта Imagick; $ok = $image->normalizeImage(...) сохранит флаг, не новую картинку. Доступность по PHP Manual: PECL imagick 2, PECL imagick 3. Обязательные параметры и default сохранены в сигнатуре выше.

В старой ветви PHP-обвязки channel передаётся в специальный native-вызов только при MagickLibVersion >0x628; иначе используется вызов без канала. Не переносите маску текущей версии на старую библиотеку по одной PHP-сигнатуре.

Хотя у этих страниц нет отдельного описания ошибок, точная обвязка и preflight подтверждают ImagickException на пустом изображении и преобразование native-отказа в исключение. Чтение и запись могут отказать отдельно. В полном коде ! означает «вернулся false», throw создаёт отказ; clear освобождает native-ресурсы. Для сайта перехватите исключение и выдайте понятное сообщение без внутренних путей. True не обещает нужного качества, допустимых настроек или сохранения деталей.

Первый управляемый результат

<?php
declare(strict_types=1);

require __DIR__ . '/stretch-fixture.php';
$source = loadStretchSource();
$image = clone $source;
if (!$image->normalizeImage()) {
    throw new RuntimeException('Не удалось применить normalizeImage');
}
saveStretchComparison([$source, $image], 'normalize-basic.png');
$source->clear();
$image->clear();

normalize-basic.png

Практическая задача: Проверить нормализацию только красной составляющей

При подборе цветовой коррекции требуется увидеть вклад одной составляющей, сохранив остальные для сравнения. Изменяем только R и сохраняем G/B исходными. Получится служебный вариант для оценки, а не автоматический баланс белого.

Imagick::CHANNEL_RED — именованная константа выбора канала. Двойное двоеточие обращается к константе класса, а не вызывает метод. Если нужны несколько каналов, их объединяют |, например RED | GREEN; это побитовый оператор, отличный от логического ||. В данном опыте цель — изменённый R при точно сохранённых G/B, поэтому выбирается только RED.

<?php
declare(strict_types=1);

require __DIR__ . '/stretch-fixture.php';
$source = loadStretchSource();
$image = clone $source;
if (!$image->normalizeImage(Imagick::CHANNEL_RED)) {
    throw new RuntimeException('Не удалось применить normalizeImage');
}
saveStretchComparison([$source, $image], 'normalize-red-channel.png');
$source->clear();
$image->clear();

normalize-red-channel.png

Ошибки, ограничения и альтернативы

Доля отсечки не равна гарантированному числу потерянных пикселей: граница выбирается по уровням и повторяющимся значениям. Полезные тёмные/светлые детали могут попасть в обрезанный хвост. Повторная нормализация не восстанавливает их. На равномерном входе в нашем preflight true не означало появления деталей. Для иной доли используйте явные параметры contrastStretch/linearStretch.

Основные программы используют один непрозрачный sRGB PNG. На отдельном RGBA-образце нашей сборки default этих четырёх операций менял alpha; у трёх методов с channel явная маска RED|GREEN|BLUE сохранила её. У linearStretchImage channel-аргумента нет. Для прозрачных файлов заранее выберите и проверьте самостоятельную политику alpha. Цветовые профили и многокадровые файлы также требуют отдельной обработки.

Соседние методы: autoLevelImage · contrastStretchImage · linearStretchImage. Для яркости, контраста и gamma: гамма, яркость и контраст; для двоичного документа: пороги.

• Imagick::normalizeImage
• Imagick 3.8.1 PHP-wrapper
• ImageMagick 7.1.1-46 enhance.c

PECL imagick 2, PECL imagick 3 · imagick

Imagick::contrastStretchImage(float $black_point, float $white_point, int $channel = Imagick::CHANNEL_DEFAULT): bool

Нужна явная политика: сколько редких тёмных и светлых значений позволить обрезать, сохраняя управляемую середину.

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

Первая строка получает ширину и высоту текущего изображения; звёздочка умножает их, знак = сохраняет число пикселей в $pixels. У 400×320 получится 128000. Во второй строке запятая отделяет нижний счётчик 1280 от верхней позиции 126720; это 1% снизу и 99% снизу, значит 1% сверху. Стрелка вызывает метод объекта; круглые скобки содержат аргументы, точка с запятой завершает команду. До изменения создайте $image = clone $source: присваивание без clone оставило бы два имени одного объекта.

$pixels = $image->getImageWidth() * $image->getImageHeight();
$image->contrastStretchImage($pixels * 0.01, $pixels * 0.99);

Это поясняющий фрагмент. Полная программа ниже загрузит переносимый вход, проверит возврат и сохранит PNG. Основы: объект и метод, копирование, аргумент вызова.

Сигнатура и параметры

Imagick::contrastStretchImage(float $black_point, float $white_point, int $channel = Imagick::CHANNEL_DEFAULT): bool

Метод выбирает уровни по накопленной гистограмме и растягивает между ними. В этой PHP-обвязке float передаются напрямую native-библиотеке. Они означают популяционные счётчики, не quantum-яркости и не проценты сами по себе. Для нижнего хвоста a и верхнего b при N пикселях запись contrastStretchImage(a×N,(1−b)×N).

Возвращаемое значение, версии и отказ

Возвращается bool: true при успехе. Метод меняет пиксели текущего объекта Imagick; $ok = $image->contrastStretchImage(...) сохранит флаг, не новую картинку. Доступность по PHP Manual: PECL imagick 2, PECL imagick 3. Обязательные параметры и default сохранены в сигнатуре выше.

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

Хотя у этих страниц нет отдельного описания ошибок, точная обвязка и preflight подтверждают ImagickException на пустом изображении и преобразование native-отказа в исключение. Чтение и запись могут отказать отдельно. В полном коде ! означает «вернулся false», throw создаёт отказ; clear освобождает native-ресурсы. Для сайта перехватите исключение и выдайте понятное сообщение без внутренних путей. True не обещает нужного качества, допустимых настроек или сохранения деталей.

Первый управляемый результат

<?php
declare(strict_types=1);

require __DIR__ . '/stretch-fixture.php';
$source = loadStretchSource();
$image = clone $source;
$pixels = $image->getImageWidth() * $image->getImageHeight();
if (!$image->contrastStretchImage($pixels * 0.01, $pixels * 0.99)) {
    throw new RuntimeException('Не удалось применить contrastStretchImage');
}
saveStretchComparison([$source, $image], 'contrast-stretch-basic.png');
$source->clear();
$image->clear();

contrast-stretch-basic.png

Практическая задача: Растянуть картинку, не испортив контрольные полосы макета

Для каталожного макета серые и цветные образцы должны остаться пригодными к сравнению. Применяем управляемые хвосты только к области картинки и считаем популяцию после вырезки: 352×184=64768.

CropImage получает ширину 352,высоту 184 и начало x=24,y=36; setImagePage сбрасывает виртуальное смещение вырезки. CompositeImage с COMPOSITE_OVER возвращает готовую область в(24,36). Переменная $region хранит отдельный объект; координаты задаёт макет, библиотека не узнаёт предмет сама. Границы и гистограмма определяются внутри вырезки.

Счётчик вычисляется у $region после crop, поэтому N=64768. Нижняя отсечка 647.68 и верхняя позиция 64120.32 допускают дробные float-счётчики; библиотека всё равно накапливает целые количества пикселей. Не округляйте их в яркость 0..255 и не берите прежнюю площадь исходника.

<?php
declare(strict_types=1);

require __DIR__ . '/stretch-fixture.php';
$source = loadStretchSource();
$image = clone $source;
$region = clone $source;
$region->cropImage(352, 184, 24, 36);
$region->setImagePage(0, 0, 0, 0);
$pixels = $region->getImageWidth() * $region->getImageHeight();
if (!$region->contrastStretchImage($pixels * 0.01, $pixels * 0.99)) {
    throw new RuntimeException('Не удалось применить contrastStretchImage');
}
if (!$image->compositeImage($region, Imagick::COMPOSITE_OVER, 24, 36)) {
    throw new RuntimeException('Не удалось вернуть область');
}
$region->clear();
saveStretchComparison([$source, $image], 'contrast-stretch-region.png');
$source->clear();
$image->clear();

contrast-stretch-region.png

Ошибки, ограничения и альтернативы

Числа 0.01 и 0.99 без умножения означают доли одного пикселя, а не 1% и 99%. При wrong white_point можно получить вырожденные границы или потерю почти всего диапазона. В точной C-реализации накопление сравнивается строго >; равные значения на гистограмме группируются. Для веб-настроек проверяйте конечность и 0≤black_point

Основные программы используют один непрозрачный sRGB PNG. На отдельном RGBA-образце нашей сборки default этих четырёх операций менял alpha; у трёх методов с channel явная маска RED|GREEN|BLUE сохранила её. У linearStretchImage channel-аргумента нет. Для прозрачных файлов заранее выберите и проверьте самостоятельную политику alpha. Цветовые профили и многокадровые файлы также требуют отдельной обработки.

Соседние методы: autoLevelImage · normalizeImage · linearStretchImage. Для яркости, контраста и gamma: гамма, яркость и контраст; для двоичного документа: пороги.

• Imagick::contrastStretchImage
• Imagick 3.8.1 PHP-wrapper
• ImageMagick 7.1.1-46 enhance.c

PECL imagick 2, PECL imagick 3 · imagick

Imagick::linearStretchImage(float $blackPoint, float $whitePoint): bool

Нужно задавать два хвоста одинаковым способом, например 1% снизу и 1% сверху для каталожных изображений разного размера.

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

Первая строка перемножает текущие ширину и высоту и сохраняет популяцию в $pixels. У 400×320 получается 128000. Во второй строке два аргумента равны 1280: 1% пикселей от тёмного края и 1% от светлого. Второй аргумент здесь не верхняя позиция 99%, как у contrastStretchImage. Стрелка вызывает метод объекта; круглые скобки содержат аргументы, точка с запятой завершает команду. До изменения создайте $image = clone $source: присваивание без clone оставило бы два имени одного объекта.

$pixels = $image->getImageWidth() * $image->getImageHeight();
$image->linearStretchImage($pixels * 0.01, $pixels * 0.01);

Это поясняющий фрагмент. Полная программа ниже загрузит переносимый вход, проверит возврат и сохранит PNG. Основы: объект и метод, копирование, аргумент вызова.

Сигнатура и параметры

Imagick::linearStretchImage(float $blackPoint, float $whitePoint): bool

Оба float — численные счётчики хвостов. Первый накопляется от тёмного края, второй от светлого. Для долей a и b: linearStretchImage(a×N,b×N). В точной реализации формируется гистограмма интенсивности, выбираются границы и выполняется LevelImage с gamma=1; вне границ значения насыщаются.

Возвращаемое значение, версии и отказ

Возвращается bool: true при успехе. Метод меняет пиксели текущего объекта Imagick; $ok = $image->linearStretchImage(...) сохранит флаг, не новую картинку. Доступность по PHP Manual: PECL imagick 2, PECL imagick 3. Обязательные параметры и default сохранены в сигнатуре выше.

Хотя у этих страниц нет отдельного описания ошибок, точная обвязка и preflight подтверждают ImagickException на пустом изображении и преобразование native-отказа в исключение. Чтение и запись могут отказать отдельно. В полном коде ! означает «вернулся false», throw создаёт отказ; clear освобождает native-ресурсы. Для сайта перехватите исключение и выдайте понятное сообщение без внутренних путей. True не обещает нужного качества, допустимых настроек или сохранения деталей.

Первый управляемый результат

<?php
declare(strict_types=1);

require __DIR__ . '/stretch-fixture.php';
$source = loadStretchSource();
$image = clone $source;
$pixels = $image->getImageWidth() * $image->getImageHeight();
if (!$image->linearStretchImage($pixels * 0.01, $pixels * 0.01)) {
    throw new RuntimeException('Не удалось применить linearStretchImage');
}
saveStretchComparison([$source, $image], 'linear-stretch-basic.png');
$source->clear();
$image->clear();

linear-stretch-basic.png

Практическая задача: Сохранить долю отсечки при двух размерах каталожного превью

Сервис делает полноразмерную картинку и уменьшенное превью. Одинаковый счётчик отсечки на 400×320 и 200×160 означал бы разные доли. Для каждой копии пересчитываем площадь после resize; уменьшенное превью увеличиваем обратно только для удобного просмотра рядом.

ResizeImage получает ширину, высоту, фильтр и коэффициент blur. FILTER_BOX при уменьшении агрегирует исходные значения; после уменьшения getImageWidth/getImageHeight возвращают 200 и 160. Площадь теперь 32000 пикселей; 1% — счётчик 320. Вторая операция FILTER_POINT увеличивает обработанный растр для сравнения без сглаживания. В исходной служебной задаче сохраните 200×160 как отдельное превью; увеличение здесь нужно только для равных по размеру панелей.

<?php
declare(strict_types=1);

require __DIR__ . '/stretch-fixture.php';
$source = loadStretchSource();
$image = clone $source;
$pixels = $image->getImageWidth() * $image->getImageHeight();
if (!$image->linearStretchImage($pixels * 0.01, $pixels * 0.01)) {
    throw new RuntimeException('Не удалось применить linearStretchImage');
}
$small = clone $source;
$small->resizeImage(200, 160, Imagick::FILTER_BOX, 1);
$smallPixels = $small->getImageWidth() * $small->getImageHeight();
if (!$small->linearStretchImage($smallPixels * 0.01, $smallPixels * 0.01)) {
    throw new RuntimeException('Не удалось применить linearStretchImage');
}
$small->resizeImage(400, 320, Imagick::FILTER_POINT, 1);
saveStretchComparison([$source, $image, $small], 'linear-stretch-two-sizes.png');
$source->clear();
$image->clear();
$small->clear();

linear-stretch-two-sizes.png

Ошибки, ограничения и альтернативы

В C используется накопление >=, поэтому граница при точном равенстве счётчика может отличаться от contrastStretchImage. Один выброс и счётчик ровно 1 среди ста пикселей ещё выбирают этот выброс; это видно в отдельной проверке. На ровной плашке текущий linearStretch вернул true и сделал чёрный при совпавших границах; uniform-вход следует распознать и пропустить по политике приложения. Аргументы не являются числами 0..255 и не проверяют качество сами.

Прикладная валидация: оба счётчика a и b должны быть конечными, a≥0, b≥0 и a+b<N. Это разумная политика приложения, а не обещание встроенной проверки Imagick. Отдельно проверьте ненулевой рабочий диапазон; даже корректные доли не создают детали на однотонном входе.

Основные программы используют один непрозрачный sRGB PNG. На отдельном RGBA-образце нашей сборки default этих четырёх операций менял alpha; у трёх методов с channel явная маска RED|GREEN|BLUE сохранила её. У linearStretchImage channel-аргумента нет. Для прозрачных файлов заранее выберите и проверьте самостоятельную политику alpha. Цветовые профили и многокадровые файлы также требуют отдельной обработки.

Соседние методы: autoLevelImage · normalizeImage · contrastStretchImage. Для яркости, контраста и gamma: гамма, яркость и контраст; для двоичного документа: пороги.

• Imagick::linearStretchImage
• Imagick 3.8.1 PHP-wrapper
• ImageMagick 7.1.1-46 enhance.c