Code Igniter User Guide Version 1.5.2

Classe Manipulação de Imagem

Esta classe do Code Igniter lhe permite executar as seguintes ações:

Todas essas principais bibliotecas de imagens são suportadas: GD/GD2, NetPBM, e ImageMagick

Nota: A Marca-d'água está apenas disponível na biblioteca GD/GD2. Além disto, mesmo que as outras bibliotecas sejam suportadas, a GD é exigida para que o script calcule as propriedades da imagem. O processamento da imagem, no entando, será executado pela biblioteca que você especificar.

Inicializando a Classe

Como a maioria das classes no Code Igniter, a classe Manipulação de Imagem é inicializada em seu controller usando a função $this->load_library:

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

Uma vez carregada, estará pronta para usar. O objeto desta biblioteca que você usará para chamar todas as funções é: $this->image_lib

Processando uma Imagem

Não importa qual o tipo de processamento você queria executar (redimensionar, cortar, rotacionar ou aplicar marca-d'água), o processo geral é idêntico. Você configurará algumas preferências correspndentes à ação desejada, e então chamará uma das quatro funções disponíveis. Por exemplo, para criar uma miniatura da imagem, use isto:

$config['image_library'] = 'GD';
$config['source_image'] = '/caminho/para/imagens/minha_imagem.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();

O código acima diz à função image_resize procurar uma imagem chamada minha_imagem.jpg localizada no diretório especificado, e então criar uma miniatur que terá 75x50 pixels, usando a bilioteca image_library GD2. Uma vez que a opção maintain_ratio está habilitada, a miniatura será terá as mais próximas largura e altura possíveis enquanto preservará a proporção original. A miniatura será chamda minha_imagem_thumb.jpg

Note: Para que a classe tenha permissão para executar qualquer processo, o diretório contendo os arquivos das imagens deve ter permissão 777.

Funções de Processamento

Há quatro funções de processamento disponíveis:

Essas funções retornam TRUE booleano se tudo der certo e FALSE se algo falhar. Se houver falha, você pode recuperar a mensagem de erro usando esta função:

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

Uma boa prática é usar a função de processamento condicionalmente, mostrando um erro se houver falha, como desta maneira:

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

Nota: Você pode opcionalmente especificar qual formatação do HTML será aplicada aos erros, submentendo as tags de abertura/fechamento na função, como desta maneira:

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

Preferências

As 14 preferências disponíveis descriatas abaixo permitem que você ajuste o processamento de imagens às suas necessidades.

Note que nem todas as preferências estão disponíveis para todas as funções. Por exemplo, as preferências dos eixos x/y estão apenas disponíveis para cortar imagens. Da mesma forma, as preferências de largura e altura não tem efeito quando estiver cortando uma imagem. A coluna "disponibilidade" indica quais funções suportam uma dada preferência.

Legenda de Disponibilidade:

Preferência Valor Default Opções Descrição Disponibilidade
image_library GD2 GD, GD2, ImageMagick, NetPBM Configurar qual biblioteca deve ser usada. R, C, X, W
library_path None None Configura o caminho, no servidor, para as bibliotecas ImageMagick ou NetPBM. Se usar uma dessas bibliotecas você deve fornecer o caminho. R, C, X
source_image None None Configura o caminho/nome da imagem original. O caminho do servidor deve ser absoluto ou relatico e não uma URL. R, C, S, W
dynamic_output FALSE TRUE/FALSE (boolean) Determina quando uma nova imagem deve ser escrita no disco ou gerada dinamicamente. Nota: Se você escolher a opção dinâmica, apenas uma imagem pode ser mostrada de cada vez, e ela não pode ser posicionada na página. Esta preferência simplismente dá saída automaticamente da imagem bruta (raw) no seu browser, junto com os cabeçalhos da imagem. R, C, X, W
quality 90% 1 - 100% Configurar a qualidade da imagem. Quanto maior a qualidade, maior será o arquivo. R, C, X, W
new_image Nenhum Nenhum Configura o nome/caminho de destino da imagem. Você usará esta preferência quando criar uma cópia de uma imagem. O caminho do servidor deve ser absoluto ou relativo e não uma URL. R
width Nenhum Nenhum Configura a largura da imagem final. R
height Nenhum Nenhum Configura a altura da imagem final. R
create_thumb FALSE TRUE/FALSE (boolean) Cria uma miniatura da imagem. R
thumb_marker _thumb Nenhum Especifica o sufixo da miniatura. Ele será inserido antes da extensão do aquivo, portanto, minhaimagem.jpg virará minhaimagem_thumb.jpg R
maintain_ratio TRUE TRUE/FALSE (boolean) Especifica se deve manter a proporção da imagem original ou então usar valores forçados. R
master_dim auto auto, width, height Especifica o que usar como eixo mestre ao redimensionar uma imagem ou criar miniaturas. Por exemplo, digamos que você quer redimensionar uma imagem para 100 x 75 pixels. Se a imagem original não permitir o redimensionamento ideal para essas dimensões, esta preferência determina qual eixo deverá ser usado como valor forçado. "auto" escolhe o eixo automaticamente baseado na condição se a imagem é mais alta do que larga, ou vice-versa. R
rotation_angle Nenhum 90, 180, 270, vrt, hor Especifica o ângulo de rotação ao rotacionar imagens. Note que o PHP rotcionar em sentido anti-horário, portanto uma rotação de 90 graus para a direita deve ser especificada como 270 graus. X
x_axis Nenhum Nenhum Configura a coordenada X, em pixels, para o corte da imagem. Por exemplo, um valor igual a 30 irá cortar a imagem 30 pixels vindo da esquerda. C
y_axis Nenhum Nenhum Configura a coordenada Y, em pixels, para o corte da imagem. Por exemplo, um valor igual a 30 irá cortar a imagem 30 pixels vindo de cima. C

Configurando as preferências em um arquivo

Se desejar não configurar as preferências do jeito mostrado acima, pode colocá=las num arquivo de configuração. simplesmente crie um arquivo chamado image_lib.php, e adicionar a array $config a ele. Salve-o em: config/image_lib.php e ele será usado automaticamente. Você NÃO precisará usar a função $this->image_lib->initialize se salvar suas preferências em um arquivo.

$this->image_lib->resize()

A função de redimensionamento de imagnes lhe permite alterar o tamanho da imagem original, criar uma cópia (com ou sem redimensionamento) ou criar uma miniatura.

Na prática, não há diferença entre criar uma cópia ou criar uma miniatura, exceto pelo fato que a minatura irá conter o sufixo em seu nome (ex.:, minhaimagem_thumb.jpg).

Todas as preferências listas na tabela acima estão disponíveis para essa função, exceto estas três: rotation, x_axis, and y_axis.

Criando uma Miniatura

A função resizing irá um arquivo da miniatura (e preservar a imagem original) se você configurar as preferências para TRUE:

$config['create_thumb'] = TRUE;

Esta preferência determina quando uma miniatura é criada ou não.

Criando uma Cópia

A função resizing, irá criar uma cópia do arquivo ogirinal (e irá preservá-lo) se você configurar o caminho e/ou um novo nome de arquivo usando esta preferência:

$config['new_image'] = '/caminho/para/nova_imagem.jpg';

Notas acerca desta preferência:

Redimensionando a Imagem Original

Se nenhuma das duas preferências listadas acima (create_thumb, e new_image) for usada, a função resizing irá se voltar à imagem original no processamento.

$this->image_lib->crop()

A função cropping trabalhar praticamente de forma idêntica à redising, exceto por requerer que você configure as preferências para os eixos X e Y (em pixels), especificando onde cortar, como desta maneira:

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

Todas as preferências listas na tabela acima estão disponíveis para esta função, exceto estas: rotation, width, height, create_thumb, new_image.

Aqui vai um exemplo mostrando como você poderia cortar uma imagem:

$config['image_library'] = 'imagemagick';
$config['library_path'] = '/usr/X11R6/bin/';
$config['source_image'] = '/caminho/para/minhaimagem.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();
}

Nota: Sem uma interface visual, é difícil cortar imagens, por isto esta função não é muito útil a menos que você queria contruir tal interface. E foi exatamente isto que fizemos para o módulo galeria de fotos do ExpressionEngine, o CMS que desenvolvemos. Adicionamos uma Javascript UI que permite que as áreas de corte sejam selecionadas.

$this->image_lib->rotate()

A função de rotação requer que o ângulo de rotação seja configurado via sua preferência:

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

Há 5 opções de rotação:

  1. 90 - rotaciona 90 graus em sentido anti-horário.
  2. 180 - rotaciona 180 graus em sentido anti-horário.
  3. 270 - rotaciona 270 graus em sentido anti-horário.
  4. hor - gira a imagem horizontalmente.
  5. vrt - gira a imagem verticalmente.

Aqui vai um exemplo mostrando como você poderia rotacionar uma imagem:

$config['image_library'] = 'netpbm';
$config['library_path'] = '/usr/bin/';
$config['source_image'] = '/caminho/para/minhaimagem.jpg';
$config['rotation_angle'] = 'hor';

$this->image_lib->initialize($config);

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

 

Marca-d'água

A funcionalidade de Marca-d'água requer a biblioteca GD/GD2.

Dois tipos de Marca-d'água

Há dois tipos de marca-d'água que você pode usar:

Colocando uma marca-d'água numa imagem

Assim como as outras funções (resizing, cropping, e rotating) o processo geral para aplicar a marca-d'água envolve configurar as preferências correspondentes à açào que se deseja executar, e então chamar a função watermark. Aqui vai um exemplo:

$config['source_image'] = 'caminho/para/minhaimagem.jpg';
$config['wm_text'] = 'Copyright 2006 - Fulano de Tal';
$config['wm_type'] = 'text';
$config['wm_font_path'] = './system/fonts/texb.ttf';
$config['wm_font_size'] = '16';
$config['wm_text_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();

O exemplo acima usa uma fonte True Type em corpo 16 para criar o texto "Copyright 2006 - Fulano de Tal". A marca-d'água será posicionada centralizada no rodapé da imagem, 20 pixels acima da borda inferior.

Nota: Para que a classe tenha permissão para executar qualquer coisa, o arquivo da imagem deve ter permissão 777.

Preferências da Marca-d'água

Esta tabela mostra as preferências disponíveis para ambos os tipos de marca-d'água (texto ou overlay)

Preferência Valor Default Opções Descrição
wm_type text type, overlay Configura o tipo de marca-d'água a usar.
source_image Nenhum Nenhum Configura o nome/caminho da imagem original. O caminho no servidor deve ser absoluto ou relativo e não uma URL.
dynamic_output FALSE TRUE/FALSE (boolean) Determina quando uma nova imagem deve ser escrita no disco ou gerada dinamicamente. Nota: Se você escolher a opção dinâmica, apenas uma imagem pode ser mostrada de cada vez, e ela não pode ser posicionada na página. Esta preferência simplesmente dá saída automaticamente da imagem bruta (raw) no seu browser, junto com os cabeçalhos da imagem.
quality 90% 1 - 100% Configurar a qualidade da imagem. Quanto maior a qualidade, maior será o arquivo.
padding Nenhum Um número O montante de padding, em pixels, que será aplicado à marca-d'água para distanciá-la da borda da imagem.
wm_vrt_alignment bottom top, middle, bottom Configura o alinhamento vertical para a imagem de marca-d'água.
wm_hor_alignment center left, center, right Configura o alinhamento horizontal para a imagem de marca-d'água.
wm_vrt_offset Nenhum Nenhum Você pode especificar um offset vertical (em pixels) para a posiçào da marca-d'água. O offset normalmente move a marca-d'água para a direita, exceto se vc tiver configurado o alinhamento como "right". Dessa forma o valor de offset moverá a marca-d'água na direção esquerda da imagem.
wm_hor_offset Nenhum Nenhum Você pode especificar um offset horizontal (em pixels) para a posiçào da marca-d'água. O offset normalmente move a marca-d'água para baixo, exceto se vc tiver configurado o alinhamento como "bottom". Dessa forma o valor de offset moverá a marca-d'água para cima.

Preferências de Texto

Esta tabela mostra das preferências de texto disponíveis para o tipo de marca-d'água usando texto.

Preferência Valor Default Opções Descrição
wm_text Nenhum Nenhum O texto que você quer usar como marca-d'água. Tipicamente uma frase de copyright.
wm_font_path Nenhum Nenhum O caminho no servidor para a fonte True Type que você gostaria de usar. O Code Igniter inclui uma fonte no diretório system/fonts. Se você não quiser usar esta opçào, a fonte nativa da GD será usada no lugar.
wm_font_size 16 Nenhum O corpo do texto. Nota: Se você não estiver usando a opção da fonte True Type acima, o número deve estar na escala de 1 a 5. Do contrário, você pode usar qualquer valor válido em pixels para a fonte.
wm_font_color ffffff Nenhum A cor da fonte, especificada em hexa decimal. Note que você deve usar os 6 caracteres (ex.:, 993300), e não a versão abreviada de 3.
wm_shadow_color Nenhum Nenhum A cor da sombra, espeficida em hexa decimal. Se deixa este valor vazio, a sombra não será usada. Note que você deve usar os 6 caracteres (ex.:, 993300), e não a versão abreviada de 3.
wm_shadow_distance 3 Nenhum A distância (em pixels) da distância entre a fonte e a sombra.

Preferências de Overlay

Esta tabela mostra das preferências disponíveis para o tipo de marca-d'água usando overlay.

Preferência Valor Default Opções Descrição
wm_overlay_path Nenhum Nenhum O caminho no servidor da imagem que você deseja usar como marca-d'água. Obrigatória apenas para o método overlay.
wm_opacity 50 1 - 100 Opacidade (transparência) da imagem usada como marca-d'água. Permite que esta fique translúcida, mostrando os detalhes da imagem onde está aplicada. A opacidade de 50% é típica.
wm_x_transp 4 Um número Se a sua imagem de marca-d'ágia for PNG ou GIF, você pode especificar uma cor na imagem que deverá ser transparente. Esta preferência (junto com a próxima) lhe permitirá especificar tal cor. Isto funciona especificando as coordenadas "X" e "Y" (medidas a partir do canto superior esquerdo) dentro da imagem que corresponde àquela cor que você quer tornar transparente.
wm_y_transp 4 Um número Junto com a configuração anterior, permite que você especifique a coordenada para a representação em pixel daquela cor que quer transparente.