Podręcznik użytkownika CodeIgniter wersja 2.2.1


Klasa manipulowania plikiem graficznym

Klasa manipulowania plikiem graficznym pozwala na wykonywanie następujących czynności:

Wspierane są trzy podstawowe biblioteki: GD/GD2, NetPBM i ImageMagick

Uwaga: Tworzenie znaków wodnych jest dostępne tylko za pomocą biblioteki GD/GD2. Dodatkowo, pomimo tego że inne biblioteki są wspierane, to biblioteka GD jest wymagana do obliczania właściwości pliku graficznego. Samo przetwarzanie pliku graficznego odbywać się jednak będzie za pomocą biblioteki, która została określona.

Inicjalizowanie klasy

Tak jak większość innych klas w CodeIgniterze, klasa Image jest inicjalizowana w Twoim kontrolerze poprzez funkcję $this->load->library:

$this->load->library('image_lib');

Po załadowaniu, obiekt klasy Image będzie dostępny poprzez wywołanie: $this->image_lib

Przetwarzanie pliku graficznego

Niezależnie od typu przetwarzania, które chciałbyś przeprowadzić (zmiana rozmiaru, przycinanie, obracanie, dołączenie znaku wodnego), główny proces jest zawsze taki sam. Musisz ustawić preferencje odnoszące się do czynności jaką chcesz wykonać i wywołać jedną z czterech dostępnych funkcji przetwarzania. Dla przykładu, aby utworzyć miniaturę pliku graficznego, możesz zrobic tak:

$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();

Powyższy kod, mówi funkcji image_resize aby szukała pliku o nazwie mypic.jpg w folderze source_image. następnie ma stworzyć miniaturę o wymiarach 75 na 50 pikseli, za pomocą biblioteki GD2. W związku z tym, że opcja maintain_ratio jest włączona, miniatura będzie miała jak najbardziej zbliżoną szerokość i wysokość do docelowego rozmiaru pliku, przy jednoczesnym zachowaniu oryginalnych proporcji. Miniatura będzie miała nazwę mypic_thumb.jpg

Uwaga: Aby umożliwić klasie Image przeprowadzenie jakichkolwiek procesów, folder w którym znajdują się pliki graficzne musi mieć uprawnienia do zapisu.

Uwaga: Przetwarzanie plików graficznych może wymagać sporej ilości pamięci przy niektórych operacjach. Jeśli doświadczasz błędów związanych z brakiem pamięci podczas przetwarzania plików graficznych, możesz ograniczyć ich maksymalną wielkość i/lub dostosować wielkość limitu pamięci PHP.

Funkcje przetwarzania

Dostępne są cztery funkcje przetwarzania:

Te funkcje zwracają wartość TRUE (boolean) w przypadku sukcesu i wartość FALSE w przypadku niepowodzenia. Dodatkowo w przypadku niepowodzenia, możesz zwrócić wiadomość błędu za pomocą tej funkcji:

echo $this->image_lib->display_errors();

Dobrą praktyką jest używanie funkcji przetwarzania w warunku i wyświetlanie błędów w przypadku niepowodzenia, w ten sposób:

if ( ! $this->image_lib->resize())
{
    echo $this->image_lib->display_errors();
}

Uwaga: Opcjonalnie możesz określić formatowanie HTML, jakie ma zostać dołączone do błędów, poprzez określenie otwierającego/zamykającego tagu w funkcji:

$this->image_lib->display_errors('<p>', '</p>');

Preferencje

Poniżej przedstawione preferencje pozwalają na dopasowanie przetwarzania pliku graficznego do Twoich potrzeb.

Zauważ, że nie wszystkie preferencje są dostępne dla wszystkich funkcji. Dla przykładu, ustawienie osi x/y jest dostępne tylko dla przycinania pliku graficznego. Tak samo, opcja szerokości i wysokości nie ma wpływu na przycinanie pliku graficznego. Kolumna "dostępności" określa, która funkcja wspiera daną preferencję.

Legenda dostępności:

Preferencja Domyślna wartość Opcje Opis Dostępność
image_library GD2 GD, GD2, ImageMagick, NetPBM Ustawia bibliotekę, która zostanie użyta. R, C, X, W
library_path Brak Brak Ustawia ścieżkę serwerową do biblioteki ImageMagick lub NetPBM. Jeśli używasz którejkolwiek z tych bibliotek, musisz określić ścieżkę. R, C, X
source_image Brak Brak Ustawia źródłową nazwę/ścieżkę. Ścieżka musi być ścieżką relatywną lub absolutną, nie adresem URL. R, C, S, W
dynamic_output FALSE TRUE/FALSE (boolean) Określa, czy nowy plik graficzny powinien być zapisany na dysku, czy wygenerowany dynamicznie. Uwaga: Jeśli wybierzesz opcję "dynamiczną", na raz może zostać wyświetlony tylko jeden plik graficzny i nie może zostać umieszczony na stronie. Wysyłane są po prostu dane pliku graficznego razem z odpowiednimi nagłówkami bezpośrednio do przeglądarki. R, C, X, W
quality 90% 1 - 100% Ustawia jakość pliku graficznego. Im wyższa jakość, tym większy rozmiar pliku. R, C, X, W
new_image Brak Brak Ustawia docelową nazwę/ścieżkę pliku graficznego. Będziesz używał tego ustawienia podczas tworzenia kopii pliku graficznego. Ścieżka musi być ścieżką relatywną lub absolutną, nie adresem URL. R, C, X, W
width Brak Brak Ustawia szerokość dla pliku graficznego. R, C
height Brak Brak Ustawia wysokość dla pliku graficznego. R, C
create_thumb FALSE TRUE/FALSE (boolean) Informuje funkcję przetwarzania, czy ma być tworzona miniatura. R
thumb_marker _thumb Brak Określa wskaźnik miniatury. Będzie on dołączony do nazwy pliku zaraz przed rozszerzeniem pliku. Tak więc, mypic.jpg będzie teraz mypic_thumb.jpg R
maintain_ratio TRUE TRUE/FALSE (boolean) Określa, czy utrzymac oryginalne proporcje podczas zmiany rozmiaru, czy dostosować się do "twardych" wartości. R, C
master_dim auto auto, width, height Określa co użyć jako główną oś podczas zmiany rozmiaru lub tworzenia miniatury. Dla przykładu, powiedzmy że chcesz zmienić rozmiar pliku graficznego do 100 na 75 pikseli. Jeśli źródłowy plik graficzny nie pozwala na idealną zmianę do tych rozmiarów, to to ustawienie określa, która oś powinna zostać użyta do zastosowania z "twardymi" wartościami. Ustawienie "auto" powoduje ustawienie osi automatycznie na podstawie tego, czy plik graficzny jest wyższy niż szerszy lub na odwrót. R
rotation_angle Brak 90, 180, 270, vrt, hor Określa kąt rotacji podczas obrotu pliku graficznego. Zwróć uwagę, że PHP wykonuje rotację w przeciwnym do ruchu wskazówek zegara kierunku. Dlatego rotacja o 90 stopni w prawo, musi zostać określona jako 270. X
x_axis Brak Brak Ustawia koordynat X w pikselach dla przycięcia pliku graficznego. Dla przykładu, ustawienie wartości 30, przytnie plik graficzny o 30 pikseli od lewej strony. C
y_axis Brak Brak Ustawia koordynat Y w pikselach dla przycięcia pliku graficznego. Dla przykładu, ustawienie wartości 30, przytnie plik graficzny o 30 pikseli od góry. C

Ustawianie preferencji w pliku konfiguracyjnym

Jeśli nie chcesz ustawiać preferencji za pośrednictwem powyższej metody, możesz zamiast tego umieścić je w pliku konfiguracyjnym. Wystarczy, że stworzysz plik o nazwie image_lib.php, który będzie zawierał tablicę $config. Jeśli zachowasz ten plik w config/image_lib.php, będzie on używany automatycznie. Jeśli Twoje ustawienia preferencji znajdują się w pliku konfiguracyjnym, NIE będziesz musiał korzystać z funkcji $this->image_lib->initialize().

$this->image_lib->resize()

Funkcja pozwala na zmianę rozmiaru oryginalnego pliku graficznego, stworzenie kopii (z lub bez zmiany rozmiaru) lub utworzenie miniatury.

Z praktycznego punktu widzenia nie ma różnicy między tworzeniem kopii pliku, a tworzeniem miniatury, za wyjątkiem tego, że miniatura otrzyma wskaźnik jako część nazwy (np. mypic_thumb.jpg).

Wszystkie wymienione preferencje z powyższej tabeli są dostępne dla tej funkcji, z wyjątkiem tych trzech: rotation_angle, x_axis i y_axis.

Tworzenie miniatury

Funkcja zmiany rozmiaru utworzy plik miniatury (i zachowa plik oryginalny) jeśli ustawisz tą preferencję na wartość TRUE:

$config['create_thumb'] = TRUE;

To ustawienie decyduje o tym, czy miniatura zostanie stworzona.

Tworzenie kopii

Funkcja zmiany rozmiaru stworzy kopię pliku graficznego (i zachowa plik oryginalny) jeśli ustawisz ścieżkę i/lub nową nazwę pliku za pomocą tego ustawienia:

$config['new_image'] = '/path/to/new_image.jpg';

Uwagi dotyczące tej preferencji:

Zmiana rozmiaru oryginalnego pliku graficznego

Jeśli żaden z powyższych parametrów nie zotanie użyty (create_thumb i new_image), to funkcja zmiany rozmiaru będzie odnosiła się do oryginalnego pliku.

$this->image_lib->crop()

Funkcja przycinania działa prawie identycznie jak funkcja zmiany rozmiaru, z tym wyjątkiem, że wymaga ustawienia preferencji dla osi X i Y (w pikselach), które określą w którym miejscu przyciąć obraz:

$config['x_axis'] = '100';
$config['y_axis'] = '40';

Wszystkie wymienione preferencje z powyższej tabeli są dostępne dla tej funkcji, za wyjątkiem tych: rotation_angle, width, height, create_thumb, new_image.

Oto przykład pokazujący w jaki sposób możesz przyciąć obraz:

$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();
}

Uwaga: Bez graficznego interfejsu trudno jest przyciąć obraz, więc ta funkcja nie jest zbyt przydatna, o ile nie chcesz zbudować właśnie takiego interfejsu. Tak własnie zrobiliśmy, używając tej funkcji dla galerii w module CMS ExpressionEngine. Dodaliśmy interfejs JavaScript, który pozwala na zaznaczenie obszaru, który ma zostać przycięty.

$this->image_lib->rotate()

Funkcja obrotu pliku graficznego wymaga ustawienia kąta rotacji:

$config['rotation_angle'] = '90';

Mamy 5 opcji obrotu:

  1. 90 - obrót w przeciwną stronę do ruchu wskazówek zegara o 90 stopni.
  2. 180 - obrót w przeciwną stronę do ruchu wskazówek zegara o 180 stopni.
  3. 270 - obrót w przeciwną stronę do ruchu wskazówek zegara o 270 stopni.
  4. hor - poziomy obrót obrazu.
  5. vrt - pionowy obrót obrazu.

Oto przykład pokazujący w jaki sposób możesz obrócić obraz:

$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()

Funkcja clear, resetuje wszystkie wartości użyte podczas przetwarzania pliku graficznego. Wywołanie tej funkcji będzie potrzebne w przypadku przetwarzania plików graficznych w pętli.

$this->image_lib->clear();

 

Dołączanie znaków wodnych

Ta funkcja wymaga biblioteki GD/GD2.

Dwa rodzaje znaków wodnych

Są dwa rodzaje znaków wodnych, których możesz używać:

Tworzenie znaku wodnego

Tak jak w przypadku innych funkcji (zmiany wielkości, przycinania i obracania), głównym procesem nakładania znaku wodnego jest ustawianie preferencji, które odpowiadać będą akcjom, które chcemy wykonać, a na końcu wywołanie samej metody. Oto przykład:

$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();

Powyższy przykład używa czcionki True Type o wielkości 16 pikseli i tworzy napis "Copyright 2006 - John Doe". Znak wodny będzie umiejscowiony na środku, w odległości 20 pikseli od dołu obrazu.

Uwaga: Aby klasa manipulowania plikiem graficznym mogła wykonać przetwarzanie, dany plik musi mieć prawa do "zapisu". Dla przykładu, 777.

Preferencje znaku wodnego

Ta tabela przedstawia dostępne preferencje dla obu typów znakow wodnych (tekstowego i graficznego)

Preferencja Domyślna wartość Opcje Opis
wm_type text text, overlay Ustawia typ znaku wodnego.
source_image Brak Brak Ustawia nazwę/ścieżkę pliku źródłowego. Ścieżka musi być ścieżką relatywną lub absolutną, nie adresem URL.
dynamic_output FALSE TRUE/FALSE (boolean) Określa, czy nowy plik graficzny powinien zostać zapisany na dysku, czy dynamicznie zwrócony. Uwaga: Jeśli wybierzesz opcję "dynamiczną", na raz może zostać wyświetlony tylko jeden plik graficzny i nie może zostać umieszczony na stronie. Wysyłane są po prostu dane pliku graficznego razem z odpowiednimi nagłówkami bezpośrednio do przeglądarki.
quality 90% 1 - 100% Ustawia jakość pliku graficznego. Im wyższa jakość, tym większy rozmiar pliku.
padding Brak Numer Odstęp w pikselach, który będzie zastosowany do znaku wodnego, aby ustawić go z dala od krawędzi pliku graficznego.
wm_vrt_alignment bottom top, middle, bottom Ustawia wyrównanie w pionie dla znaku wodnego.
wm_hor_alignment center left, center, right Ustawia wyrównanie w poziomie dla znaku wodnego.
wm_hor_offset Brak Brak Możesz ustawić przesunięcie poziome (w pikselach), które ma być zastosowane dla pozycji znaku wodnego. Normalnie, przesunięcie porusza znak w prawą stronę, chyba że wyrównanie jest ustawione na wartość "right" - wtedy przesunięcie następuje w lewą stronę.
wm_vrt_offset Brak Brak Możesz ustawić przesunięcie pionowe (w pikselach), które ma być zastosowane dla pozycji znaku wodnego. Normalnie, przesunięcie porusza znak w dół, chyba że wyrównanie jest ustawione na wartość "bottom" - wtedy przesunięcie następuje w górę.

Preferencje dla tekstowego znaku wodnego

Ta tabela przedstawia preferencje, które są dostępne dla tekstowego typu znaku wodnego.

Preferencje Domyślna Wartość Opcje Opis
wm_text Brak Brak Tekst który chciałbyś przedstawić jako znak wodny. Zazwyczaj będzie to nota o prawach autorskich.
wm_font_path Brak Brak Ścieżka serwerowa do czcionki True Type, której chciałbyć użyć. Jeśli nie skorzystasz z tej opcji, zostanie użyta natywna czcionka biblioteki GD.
wm_font_size 16 Brak Rozmiar tekstu. Uwaga: Jeśli nie używasz powyższej opcji True Type, wartość jest ustawiana z przedziału 1 - 5. W innym przypadku możesz używać poprawnego rozmiaru w pikselach dla danego fontu.
wm_font_color ffffff Brak Kolor czcionki w hexach. Zauważ, że musisz użyć pełnej 6 znakowej wartości (np. 993300), a nie trzyznakowej, skróconej wersji (np. fff).
wm_shadow_color Brak Brak Kolor dla cienia czcionki w hexach. Jeśli zostawisz to pole puste, cień dla czcionki nie zostanie użyty. auważ, że musisz użyć pełnej 6 znakowej wartości (np. 993300), a nie trzyznakowej, skróconej wersji (np. fff).
wm_shadow_distance 3 Brak Dystans (w pikselach) od czcionki do miejsca w którym cien dla niej powinien się rozpoczynać.

Preferencje dla graficznego znaku wodnego

Ta tabela zawiera preferencje, które są dostępne dla graficznego typu znaku wodnego.

Preferencja Domyślna wartość Opcje Opis
wm_overlay_path Brak Brak Ścieżka serwerowa do pliku graficznego, który ma zostać użyty jako znak wodny. Wymagane tylko w przypadku używania znaku graficznego.
wm_opacity 50 1 - 100 Przeźroczystość obrazu. Możesz określić przeźroczystość dla Twojego obrazu znaku wodnego. Pozwala na to, aby znak wodny nie przysłaniał całkowicie oryginalnego obrazu. Zwyczajowo używana jest przeźroczystość na poziomie 50%.
wm_x_transp 4 Numer Jeśli Twój obraz jest typu PNG lub GIF, możesz określić który kolor na obrazie będzie "przeźroczysty". To ustawienie (w połączeniu kolejnym) pozwala na określenie takiego koloru. Działa to na zasadzie określenia koordynatów ("X" i "Y" - mierzonych od lewej górnej strony) dla piksela, który będzie odpowiadał kolorowi, który ma być przeźroczysty.
wm_y_transp 4 Numer W połączeniu z poprzednim ustawieniem, pozwala na określenie koordynatow dla piksela, który będzei reprezentował kolor, który ma się stać przeźroczysty.