Класс манипуляций с изображениями
Класс Image Manipulation позволяет вам выполнять следующие действия:
- Масштабирование изображения
- Создание миниатюр
- Обрезка изображения
- Вращение изображения
- Наложение ватермарка
Поддерживаются все три основных библиотеки: GD/GD2, NetPBM и ImageMagick
Примечание: Наложение ватермарков доступно только при использовании библиотеки GD/GD2. К тому же, даже если поддерживаются другие библиотеки, GD требуется для определения свойств изображения. Однако, обработка изображения будет осуществляться с той библиотекой, которую вы укажете.
Инициализация класса
Как и большинство других классов CodeIgniter, класс для работы с изображениями инициализируется в вашем контроллере посредством функции $this->load->library:
$this->load->library('image_lib');
После загрузки библиотека готова к использованию. Объект класса доступен как $this->image_lib
Обработка изображений
Вне зависимости от типа обработки, которую вы собираетесь выполнять (масштабирование, обрезка, вращение или наложение ватермарка), основные действия идентичны. Вы будете устанавливать некоторые параметры, соответствующие действию, которые вы собираетесь выполнить, и затем вызывать одну из четырех функций. Например, для создания миниатюры изображения:
$config['image_library'] = 'gd2';
$config['source_image'] = '/path/to/image/mypic.jpg';
$config['create_thumb'] = TRUE;
$config['maintain_ratio'] = TRUE;
$config['width'] = 75;
$config['height'] = 50;
$this->load->library('image_lib', $config);
$this->image_lib->resize();
Код выше говорит функции image_resize искать изображение mypic.jpg, находящееся в директории source_image, затем создать миниатюру размером 75 на 50 пикселей, используя GD2 image_library. Так как включена опция maintain_ratio, пропорции миниатюры будет как можно ближе к оригинальной ширине и высоте. Миниатюра будет называться mypic_thumb.jpg
Примечание: Для того, чтобы класс изображений смог делать что-либо, директория, содержащая изображения, должна иметь права на запись.
Примечание: Обработка изображений могут потребовать значительное количество памяти для некоторых операций. Если вы переживаете из-за ошибок памяти при обработки изображений, вы можете ограничить их максимальный размер, и (или) увеличить ограничения памяти для PHP.
Функции обработки
Доступны четыре функции для обработки изображений:
- $this->image_lib->resize()
- $this->image_lib->crop()
- $this->image_lib->rotate()
- $this->image_lib->watermark()
- $this->image_lib->clear()
Эти функции возвращают булево TRUE при успехе или FALSE при неудаче. Если у них что-то не получается, вы можете получить сообщения об ошибках с этой функцией:
echo $this->image_lib->display_errors();
Хорошей практикой является использование функции в условии, показывающее ошибки при неудаче, к примеру так:
if ( ! $this->image_lib->resize())
{
echo $this->image_lib->display_errors();
}
Примечание: При желании вы можете указать форматирование HTML, которое будет применено к ошибкам, передав открывающий и закрывающий тег функции, например так:
$this->image_lib->display_errors('<p>', '</p>');
Параметры
Параметры, описанные ниже, позволяют вам приспосабливать обработку изображений к вашим потребностям.
Заметим, что не все параметры доступны для каждой функции. Например, оси X и Y нужны только для обрезки изображения. Аналогично, ширина и высота никак не влияют на обрезку. Столбец «применяемость» отображает, к какой функции применим указанный параметр.
Легенда:
- R - Масштабирование (Resizing)
- C - Обрезка (Cropping)
- X - Вращение (Rotation)
- W - Наложение ватермарка (Watermarking)
| Параметр | Значение по умолчанию | Опции | Описание | Применяемость |
|---|---|---|---|---|
| image_library | GD2 | GD, GD2, ImageMagick, NetPBM | Указывает на библиотеку, которая будет использована. | R, C, X, W |
| library_path | Нет | Нет | Устанавливает серверный путь к вашей библиотеке NetPBM или ImageMagick. Если вы используете какую-либо из них, или обе, укажите путь к ним. | R, C, X |
| source_image | Нет | Нет | Устанавливает путь и имя источника. Путь может быть относительным или абсолютным, но не URL. | R, C, S, W |
| dynamic_output | FALSE | TRUE/FALSE (boolean) | Определяет, должен ли новый файл изображения быть записанным на диск, или только сгенерирован динамически. Примечание: если вы указали динамеческий способ, отображается только одно изображение. Оно просто отправляется в стандартный вывод, непосредственно в браузер, вместе с заголовками изображения. | R, C, X, W |
| quality | 90% | 1 - 100% | Устанавливает качество изображения. Высокое качество провоцирует большие размеры файлов. | R, C, X, W |
| new_image | Нет | Нет | Устанавливает путь и имя файла назначения. Вы будете использовать этот параметр для создания копии. Путь может быть относительным или абсолютным, но не URL. | R, C, X, W |
| width | Нет | Нет | Устанавливает ширину изображения. | R, C |
| height | Нет | Нет | Устанавливает высоту изображения. | R, C |
| create_thumb | FALSE | TRUE/FALSE (boolean) | Указывает на создание миниатюры. | R |
| thumb_marker | _thumb | Нет | Указывает на индикатор миниатюры. Он будет добавлен перед расширением, так что из mypic.jpg получится mypic_thumb.jpg | R |
| maintain_ratio | TRUE | TRUE/FALSE (boolean) | Указывает сохранять ли оригинальное соотношение сторон при масштабировании или использовать жесткие значения. | R, C |
| master_dim | auto | auto, width, height | Указывает, что использовать в качестве ведущей оси при масштабировании или создания миниатюр. Например, давайте предположим, что вы хотите масштабировать изображение до размера 100 на 75 пикселей. Если источник изображения не позволяет выполнить четкое масштабирование в указанные размеры, эта настройка определит ось, которая должна быть использована в качестве жесткого значения. Режим «auto» автоматически устанавливает ось, в зависимости от того, шире изображение или выше. | R |
| rotation_angle | Нет | 90, 180, 270, vrt, hor | Указывает угол вращения. Помните, что PHP вращает против часовой стрелки, поэтому, к примеру, вращение на 90 градусов по часовой стрелке должно указываться как на 270. | X |
| x_axis | Нет | Нет | Устанавливает координату X в пикселях для обрезки изображений. Например, установка в 30 обрежет изображение на 30 пикселей слева. | C |
| y_axis | Нет | Нет | Устанавливает координату Y в пикселях для обрезки изображения. Например, установка в 30 обрежет изображение на 30 пикселей сверху. | C |
Установка параметров в конфигурационном файле
Если вы предпочитаете не устанавливать параметры, используя методы, описанные выше, вы можете поместить их в конфигурационный файл. Просто создайте новый файл image_lib.php, добавьте в него массив $config. Затем сохраните файл в config/image_lib.php и тогда он будет использован автоматически. Вы не должны использовать инициализирующую функцию $this->image_lib->initialize, если вы сохранили ваши настройки в конфигурационном файле.
$this->image_lib->resize()
Функция масштабирования изображения позволит вам изменить размер оригинального изображения, создать копию (с масштабированием или без него), или создать миниатюру.
Практически нет различия между созданием копии и созданием миниатюры, за исключением того, что миниатюра имеет маркер, как часть имени (например, mypic_thumb.jpg).
Все параметры, перечисленные в таблице выше, доступны для этой функции, за исключением трех: rotation_angle, x_axis и y_axis.
Создание миниатюры
Функция масштабирования создает файл миниатюры (и сохраняет оригинал), если вы установите парамер в TRUE:
$config['create_thumb'] = TRUE;
Этот единственный параметр определяет, создавать миниатюру или нет.
Создание копии
Функция масштабирования создаст копию изображения (и сохранит оригинал), если вы установите путь и (или) укажете новое имя файла в этом пераметре:
$config['new_image'] = '/path/to/new_image.jpg';
Замечания насчет этого параметра:
- Если указано только имя нового изображения, оно будет помещено в ту же директорию, где находится оригинальное
- Если указывать только путь, новое изображение будет размещено в новом месте, с тем же именем, что и оригинальное.
- Если указать и путь и имя файла, новое изображение будет размещено по новому пути и с новым именем.
Масштабирование оригинального изображения
Если не использован ни один из параметров, указанных выше (create_thumb и new_image), функция масштабирования будет обрабатывать оригинальное изображение.
$this->image_lib->crop()
Функция обрезки работает почти идентично функции масштабирования, за исключением того, что она требует указания осей X и Y в пикселях, уточняющих где нужно обрезать:
$config['x_axis'] = '100';
$config['y_axis'] = '40';
Все перечисленные в таблице параметры применимы к этой функции, за исключением: rotation_angle, width, height, create_thumb и new_image.
Вот пример, показывающий как вы можете обрезать изображение:
$config['image_library'] = 'imagemagick';
$config['library_path'] = '/usr/X11R6/bin/';
$config['source_image'] = '/path/to/image/mypic.jpg';
$config['x_axis'] = '100';
$config['y_axis'] = '60';
$this->image_lib->initialize($config);
if ( ! $this->image_lib->crop())
{
echo $this->image_lib->display_errors();
}
Примечание: Без визуального интерфейса достаточно сложно обрезать изображения, поэтому эта функция не очень полезна, если вы не планируете создать такой интерфейс. Мы сделали именно это для фотогалереи, модуля ExpressionEngine, CMS, которую мы разрабатываем. Мы добавили JavaScript UI, который позволяет выбирать фрагмент изображения для обрезки.
$this->image_lib->rotate()
Функция вращения изображения требует, чтобы угол вращения был установлен через этот параметр:
$config['rotation_angle'] = '90';
Есть пять опций вращения:
- 90 - вращает на 90 градусов против часовой стрелки.
- 180 - вращает на 180 градусов против часовой стрелки.
- 270 - вращает на 270 градусов против часовой стрелки.
- hor - зеркалирует изображение по горизонтали.
- vrt - зеркалирует изображение по вертикали.
Вот пример, показывающий вам как вы можете вращать изображение:
$config['image_library'] = 'netpbm';
$config['library_path'] = '/usr/bin/';
$config['source_image'] = '/path/to/image/mypic.jpg';
$config['rotation_angle'] = 'hor';
$this->image_lib->initialize($config);
if ( ! $this->image_lib->rotate())
{
echo $this->image_lib->display_errors();
}
$this->image_lib->clear()
Функция очистки сбрасывает все значения, использованные при обработке изображения. Вы можете использовать эту функцию, если вы обрабатываете изображения в цикле.
$this->image_lib->clear();
Наложение ватермарков (водяных знаков)
Функция наложения ватермарков требует библиотеку GD/GD2.
Два типа ватермарков
Есть два типа ватермарков, которые вы можете использовать:
- Текст: Сообщение будет сгенерировано используя текст, с шрифтом True Type, который вы указали, или используя родной вывод текста, который предоставляет GD. Если вы используете True Type, ваша инсталляция GD должна быть скомпилирована с поддержкой True Type (чаще всего так, но не всегда).
- Наложение: Ватермарк генерируется наложением изображения, обычно прозрачный PNG или GIF.
Наложение ватермарка
Также как и с другими функциями (масштабирование, обрезка и вращение), основной процесс для наложения ватермарка заключается в указании параметров, и затем вызове функции. Вот пример:
$config['source_image'] = '/path/to/image/mypic.jpg';
$config['wm_text'] = 'Copyright 2006 - John Doe';
$config['wm_type'] = 'text';
$config['wm_font_path'] = './system/fonts/texb.ttf';
$config['wm_font_size'] = '16';
$config['wm_font_color'] = 'ffffff';
$config['wm_vrt_alignment'] = 'bottom';
$config['wm_hor_alignment'] = 'center';
$config['wm_padding'] = '20';
$this->image_lib->initialize($config);
$this->image_lib->watermark();
Пример выше использует 16-пиксельный шрифт True Type, чтобы создать текст "Copyright 2006 - John Doe". Ватермарк будет размещен внизу по центру изображения, в 20 пикселях от нижней границы изображения.
Примечание: Чтобы класс изображений смог обрабатывать что-либо, файл изображения должен иметь разрешения на запись.
Параметры наложения ватермарков
Эта таблица показывает парамеры, которые доступны для обоих типов наложения ватермарков (текст и изображение)
| Параметр | Значение по умолчанию | Опции | Описание |
|---|---|---|---|
| wm_type | text | text, overlay | Устанавливает тип ватермарка (текст или накладываемое изображение). |
| source_image | Нет | Нет | Указывает путь к исходному изображению. Путь может быть абсолютным или относительным серверным путем, но не URL. |
| dynamic_output | FALSE | TRUE/FALSE (boolean) | Определяет, следует ли сохранять изображение на диск или только сгенерировать динамечески. |
| quality | 90% | 1 - 100% | Устанавливает качество изображения. Большее качество провоцирует больший размер файлов. |
| padding | Нет | Число | Отступ от края изображения, в пикселях. |
| wm_vrt_alignment | bottom | top, middle, bottom | Устанавливает вертикальное выравнивание для ватермарка. |
| wm_hor_alignment | center | left, center, right | Устанавливает горизонтальное выравнивание для ватермарка. |
| wm_hor_offset | Нет | Нет | Вы можете указать горизонтальное смещение (в пикселях), чтобы применить его к позиции ватермарка. Обычно смещение будет перемещать ватермарк направо, если вы только не указали горизонтальное выравнивание "right" (тогда будет смещение в обратную сторону, налево). |
| wm_vrt_offset | Нет | Нет | Вы можете указать вертикальное смещение (в пикселях), чтобы применить его к позиции ватермарка. Обычно смещение будет перемещать ватермарк вниз, если вы только не указали вертикальное выравнивание "bottom" (тогда будет смещение в обратную сторону, вверх). |
Параметры текста
Эта таблица показывает, какие параметры доступны для текстовых ватермарков.
| Параметр | Значение по умолчанию | Опции | Описание |
|---|---|---|---|
| wm_text | Нет | Нет | Текст, который должен быть на ватермарке. Обычно это уведомление о копирайте или копилефте. |
| wm_font_path | Нет | Нет | Серверный путь к шрифту True Type, который нужно использовать. Если вы не использовали эту опцию, будет применен родной некрасивый шрифт GD. |
| wm_font_size | 16 | Нет | Размер текста. Примечание: если вы не используете шрифты True Type, номер устанавливается в диапазоне от 1 до 5. Иначе вы можете указать любое правильное значение в пикселях для шрифта, который вы используете. |
| wm_font_color | ffffff | Нет | Цвет шрифта, указанный в шестнадцатеричном представлении. Обратите внимание, необходимо использовать все шесть цифр (например 993300). |
| wm_shadow_color | Нет | Нет | Цвет тени, указанный в шестнадцатеричном значении. Если вы оставите это поле пустым, тени не будет. Обратите внимание, необходимо использовать все шесть цифр (например 993300). |
| wm_shadow_distance | 3 | Нет | Дистанция в пикселях от шрифта, на которую должна отдаляться тень. |
Параметры накладываемого изображения
В этой таблице показаны параметры, которые доступны для ватермаркинга наложением изображения.
| Параметр | Значение по умолчанию | Опции | Описание |
|---|---|---|---|
| wm_overlay_path | Нет | Нет | Серверный путь к изображению, которое следует использовать в качестве ватермарка. Требуется только при использовании этого метода. |
| wm_opacity | 50 | 1 - 100 | Прозрачность изображения. Вы можете указать прозрачность вашего изображения, используемого в качестве ватермарка. Это ослабит водяной знак, и он будет меньше скрывать детали под ним. Обычно устанавливают прозрачность в 50%. |
| wm_x_transp | 4 | Число | Если изображение ватермарка в формате PNG или GIF, вы можете уточнить цвет «прозрачности». Эта настрока (вместе со следующей) позволит вам указывать цвет. Это работает с указанием координат X и Y пикселя (отсчитывая слева сверху), откуда будет взят цвет. |
| wm_y_transp | 4 | Число | Вторая часть предыдущей настройки, позиция Y пикселя. |