VgtGd

Pliki źródłowe do prezentacji:

Na początku należy utworzyć obiekt klasy VgtGd i otworzyć plik:

<?php
require_once 'VgtGd/VgtGd.php';

$oPic1 = new VgtGd();
$oPic2 = new VgtGd();
$oPic1->open('images/vgtgd-examples-source1.jpg');
$oPic2->open('images/vgtgd-examples-source2.jpg');
?>

Funkcjonalności podstawowe znajdują się bezpośrednio w klasie VgtGd. Dodatkowe funkcje uzyskiwane są za pomocą klas efektów, które zostaną zaprezentowane dalej.

Obrót obrazka o wielokrotność 90 stopni można wykonać za pomocą metody roatate(). W parametrze przyjmuje ona wartości w zakresie 1-3 określające ilość 90-stopniowych obrotów zgodnie z ruchem wskazówek zegara.

<?php
$oPic1->rotate(1);
$oPic2->rotate(2);
?>

Skalowanie obrazka jest możliwe za pomocą metody scale(). Jeśli zostanie podany tylko jeden wymiar, a drugi pozostawiony, jako domyślny NULL, zostanie on automatycznie obliczony, aby zachować proporcje podczas skalowania. Jeśli jednak zostaną podane obydwa wymiary, docelowy obrazek będzie miał właśnie taki rozmiar niezależnie od tego, czy wpłynie to na proporcje:

<?php
$oPic1->scale(300, null, true);
$oPic2->scale(300, 300, true);
?>

Aby wyciąć fragment obrazka, należy skorzystać z metod cropMargins(), lub cropPoints(). Pierwsza pozwala określić, ile rzędów pikseli z każdej strony należy usunąć. Druga Przyjmuje współrzędne dwóch dowolnych punktów na obrazku i wycina obszar wyznaczony przez te punkty.

<?php
$oPic1->cropMargins(300, 200, 100, 50);
$oPic2->cropPoints(100, 100, 419, 299);
?>

Do tworzenia miniatur stworzone są dwie metody: thumbnail() i thumbnail2(). Pierwsza rozmiar przyjmowany w parametrach uznaje za maksymalny rozmiar, jakiego nie może przekroczyć miniatura. Jednak wysokość lub szerokość stworzonej miniatury może być mniejsza, jeśli proporcje obrazka źródłowego są inne niż tworzonej miniatury.

Poniższy kod:

<?php
$oPic1->thumbnail(200, 200);
$oPic2->thumbnail(200, 200);
?>

Da następujący rezultat:

Jeśli ważne jest, aby rozdzielczość miniatur była taka, jak podana w parametrach, można skorzystać z trzeciego parametru metody i określić kolor wypełnienia pustego obszaru:

<?php
$oPic1->thumbnail(200, 200, '#555555');
$oPic2->thumbnail(200, 200, '#555555');
?>

Druga możliwość, to skorzystanie z metody thumbnail2(), która utworzy miniaturę o wymaganym rozmiarze niezależnie od proporcji obrazka źródłowego. Jeśli proporcję są różne, fragmenty niemieszczące się w miniaturze zostaną usunięte:

<?php
$oPic1->thumbnail2(200, 200);
$oPic2->thumbnail2(200, 200);
?>

Możliwe jest także określenie umiejscowienia wycinanego obszaru dla miniatury w pionie i w poziomie na źródłowym obrazku. Decydują o tym trzeci i czwarty parametr przyjmujące wartości w zakresie [ -1 ; 1 ].

<?php
$oPic1->thumbnail2(200, 200, null, 1.0);
$oPic2->thumbnail2(200, 200, -0.9);
?>

Dodatkowe, bardziej złożone modyfikacje można realizować za pomocą dołączonych klas efektów. Możliwe jest także tworzenie własnych klas efektów i użycie ich w klasie VgtGd.

Aktualnie dostępne efekty, to: Blur, Desaturate, FlipHorizontal, FlipVertical, Gradient, InvertColors, Mosaic, PasteImage, Stamp, Text, Watermark

Jeśli efekt nie wymaga dodatkowej konfiguracji, najszybszy sposób użycia wygląda następująco:

<?php
$oPic1->getEffectsFactory()->useEffect('FlipHorizontal');
$oPic2->getEffectsFactory()->useEffect('FlipVertical', 120, 100, 400, 300);
?>

Nazwa efektu, to nazwa klasy i pliku z tą klasą znajdującego się w podkatalogu effects biblioteki VgtGd pozbawiona prefiksu "VgtGdFx".

Jeśli podano tylko nazwę efektu, nanoszony jest na cały obrazek, jednak możliwe jest ograniczenie obszaru za pomocą 4 kolejnych parametrów. Pierwsze dwa określają współrzędne punktu startowego, kolejne, to szerokość i wysokość obszaru działania efektu.

Efekty, które wymagają dodatkowych informacji, przy próbie użycia w powyższy sposób wyrzucą wyjątki informujące o błędnej konfiguracji. W tym przypadku należy pobrać referencję efektu z fabryki efektów, dokonać niezbędnej konfiguracji i dopiero nanieść na obrazek:

<?php
$oEfekt = $oPic1->getEffectsFactory()->getEffect('PasteImage');
$oEfekt->setImage($oPic2);
$oPic1->useEffect($oEfekt, 50, 100, 320, 200);

$oEfekt = $oPic2->getEffectsFactory()->getEffect('Watermark');
$oEfekt->setImage('images/watermark.png');
$oPic2->useEffect($oEfekt);
?>

Możliwe jest także wielokrotne użycie różnych efektów na jednym pliku:

<?php
$oFxText = $oPic2->getEffectsFactory()->getEffect('Text');
$oFxText->setColor('#FFFF00');
$oFxText->setSize(5);

//blur
$oFx = $oPic2->getEffectsFactory()->getEffect('Blur');
$oFx->setStrength(5);
$oPic2->useEffect($oFx, 10, 10, 200, 200);
$oFxText->setText('Blur');
$oPic2->useEffect($oFxText, 10, 10);

//invert colors
$oPic2->getEffectsFactory()->useEffect('InvertColors', 130, 150, 200, 200);
$oFxText->setText('InvertColors');
$oPic2->useEffect($oFxText, 130, 150);

//desaturate
$oPic2->getEffectsFactory()->useEffect('Desaturate', 280, 50, 200, 200);
$oFxText->setText('Desaturate');
$oPic2->useEffect($oFxText, 280, 50);

//mosaic
$oFx = $oPic2->getEffectsFactory()->getEffect('Mosaic');
$oFx->setPixelSize(8);
$oPic2->useEffect($oFx, 410, 210, 200, 200);
$oFxText->setText('Mosaic');
$oPic2->useEffect($oFxText, 410, 210);
?>

Możliwe jest tworzenie własnych klas efektów. Jedyne wymagania, jakie muszą spełnić to implementacja interface'u VgtGdEffectInterface, który zawiera jedną metodę:

public function paint($oImage, $iX, $iY, $iWidth, $iHeight);

Poniżej prosty przykład własnego efektu i jego użycia:

<?php
class Cenzura
    implements VgtGdEffectInterface
    {
    public function paint($oImage, $iX = null, $iY = null, $iWidth = null, $iHeight = null)
        {
        $iX = is_null($iX) ? 0 : (int)$iX;
        $iY = is_null($iY) ? 0 : (int)$iY;
        $iWidth = is_null($iWidth) ? $oImage->getWidth() : (int)$iWidth;
        $iHeight = is_null($iHeight) ? $oImage->getHeight() : (int)$iHeight;
        $rImage = $oImage->exportImage();
        $iKolor = imagecolorallocate($rImage, 0, 0, 0);
        imagefilledrectangle($rImage, $iX, $iY, $iX + $iWidth - 1, $iY + $iHeight - 1, $iKolor);
        }
    }

$oEfekt = new Cenzura();
$oPic1->useEffect($oEfekt, 180, 30, 200, 300);
?>

Po dokonaniu obróbki obrazka możliwe jest jego zapisanie i/lub wyświetlenie. Zapis odbywa się za pomocą metody save(), której opcjonalny parametr pozwala określić stopień kompresji w przypadku typu obrazka ustawionego na 'jpg'. Wyświetlenie można uzyskać za pomocą metody display(), jednak należy pamiętać, aby przed jej wywołaniem nie było wyświetlonych żadnych znaków, gdyż metoda musi wysłać odpowiednie nagłówki informujące o typie przesyłanych danych.

Zarówno przed wyświetleniem jak i zapisaniem obrazka można zmienić jego typ za pomocą metody setType(). Aktualnie obsługiwane typy, to: gif, jpg, png.

Biblioteka GD potrafi znacznie zużywać zasoby i z tego powodu często można zetknąć się z problemem przekroczenia limitu pamięci:

Fatal error: Allowed memory size of 16777216 bytes exhausted (tried to allocate 10240 bytes)

Biblioteka VgtGd zapobiega tym problemom poprzez ciągłe monitorowanie zużycia pamięci. Podczas tworzenia obiektu limit dostępnej pamięci jest ustawiany na 50% wartości "memory_limit" ustawionej w konfiguracji php. W każdej chwili można ten limit sprawdzić za pomocą metody getMemoryLimit(), a także zmienić metodą setMemoryLimit(). Jeśli jakakolwiek operacja może potencjalnie przekroczyć wyznaczony limit pamięci, zostanie wyrzucony wyjątek VgtGdMemoryLimitExceededException. Nie zalecane jest ustawianie limitu pamięci blisko rzeczywistego limitu ustawionego w konfiguracji php na serwerze, gdyż wszystkie obliczenia monitorujące są szacunkowe. Nie jest to dokładna ilość zużytej pamięci, a jedynie przybliżona.

Wszystkie obiekty będące instancjami klasy VgtGd dzielą jeden wspólny limit pamięci. Przestawienie limitu dla któregokolwiek obiektu oznacza zmianę współdzielonego limitu dla wszystkich instancji tej klasy. W przypadku ustawienia limitu np. na 8 MB i wykorzystanie przez jeden z obiektów 3 MB pamięci pozostałe obiekty mogą już użyć tylko 5 MB.

Sprawdzenie, ile pamięci jest aktualnie "zarezerwowane" przez obiekty można wykonać za pomocą metody getMemoryUsage().

Biblioteka jest dostępna do ściągnięcia na stronie downloadu. Jeśli masz jakiekolwiek sugestie, czy znalazłeś błąd, który należałoby poprawić, chętnie się o tym dowiem. :) Adres, na który można wysyłać maile, znajduje się na stronie http://vgtworld.pl