PHPImagen BETA RC3 - Manejo de imágenes
Inicio::Historial de Cambios::Descárgalo::Comentarios::PHPPaging
IMPORTANTE: Para usuarios de PHP4

.: Descripción

PHPImagen es una herramienta que facilita ciertas tareas a la hora de trabajar con imágenes. La finalidad es simplificar el proceso usualmente tedioso de redimensionar y etiquetar con imágenes y/o texto las imágenes on the fly, además de cambiar su color. Esto quiere decir que el script genera automáticamente una imagen tras su ejecución, la que luego, según la decisión del usuario, serán enviada como imagen, como archivo adjunto descargable, o será guardada en el servidor.

El script requiere PHP >=5, la librería GD y opcionalmente la librería FreeType. La mayoria de webservers trae todas estas librerías instaladas ;-).

.: Modo de utilización

Utilizar PHPImagen es muy simple. Dado que la librería genera imágenes y no contenido HTML, el script en el que instanciemos el objeto Imagen no deberá tener ninguna otra salida al explorador. Caso contrario habrá error del lado del servidor PHP. Por lo tanto, todo lo que a continuación se explica deberá ser colocado en un archivo que exclusivamente genere imágenes.

Para este ejemplo, nuestro archivo que va a generar las imágenes se llama img.php. A lo largo de este pequeño tutorial, iremos armando el contenido de este archivo.
Archivos que conforman la librería
El único archivo necesario para la ejecución del script es el archivo PHPImagen.lib.php que puede ser descargado del área de descargas.
Inicio del script
Para usar la librería es necesario incluir primero el archivo PHPImagen.lib.php en nuestro script, para luego iniciar la clase:
//recibiremos el nombre de la imagen por URL
$imagen $_GET['file'];

include_once 
"PHPImagen.lib.php";
$imagen = new Imagen($imagen);
Veamos que el método constructor usado por nuestra clase tiene que recibir un parámetro, que viene a ser la imagen que queremos editar. Esta imagen puede debe ser de tipo JPEG (*.jpg), GIF (*.gif) o PNG (*.png), y puede estar alojada en cualquier directorio de nuestro servidor. La ruta relativa al script seberá ser indicada como parámetro del constructor.

El script puede abrir imágenes externas, pero para ello es necesario que nuestro servidor PHP permita la lectura de archivos remotos.
Ideas Generales
PHPImagen permite realizar tareas básicas con las imágenes. Estas tareas serán llamadas por medio de sus métodos correspondientes. El orden en que se llamen los métodos es fundamental. Así, si yo agrego una marca de agua, y luego redimensiono la imagen, pues la marca también será redimensionada. No pasará lo mismo si primero redimensiono la imagen y luego recién agrego la marca. Lo mismo con el texto.

Es posible llamar los métodos varias veces, así podremos utilizar más de una imagen para marcar nuestra imagen, o insertar textos en diferente posición y con diferente formato.

PHPImagen tiene 3 formas de enviar la imagen al navegador.
  • Como una imagen, esto quiere decir que usaremos el tag <img /> para mostrarla en el navegador.
  • Como un archivo descargable, por lo tanto usaremos un vínculo <a></a> estándar.
  • Guardar la imagen en el servidor.
La ejecución cualquiera de las dos primeras acciones significará el término de la ejecución del script, pues esos métodos envían cabeceras al navegador indicándole el tipo de contenido, y ya no se podrá hacer nada más con el script. En cambio, en la tercera acción, podremos utilizar el script en el que instanciamos el objeto (en este caso, img.php) para enviar otro tipo de salida al navegador. Incluso, se puede llamar alguno de los otros métodos para mostrar la imagen o descargarla.
EDICIÓN: Redimensionar la imagen
resize( [int $ancho] [, int $alto] [, bool $cut ] ) La nueva imagen tendrá las dimensiones que especifiquemos en ancho y alto en píxeles. Ambos parámetros son opcionales, y en caso de no especificarse se asumirán como default las medidas originales de la imagen. Si no se especifica ninguno, la imagen no sufrirá variación de tamaño alguna.

El tercer parámetro cut indica si se debe o no forzar que la nueva imagen tenga las medidas indicadas. Su valor por default es false; esto quiere decir que la nueva imagen usará las nuevas medidas como medidas máximas, pero conservará su aspect ratio. Por lo tanto, la nueva imagen no necesariamente medirá lo que se especifique. Esto es útil, por ejemplo, para mostrar thumbnails en una tabla, evitando así que se descuadre nuestro código, ya que la imagen nunca sobrepasará las medidas especificadas.

Si el parámetro cut es puesto en true, las medidas indicadas serán las medidas que adopte la imagen generada. Para esto, la imagen es redimensionada totalmente en una de sus dimensiones, adoptando la medida especificada. En la otra dimensión, se corta los excesos hasta que la imagen adopte el tamaño deseado. Así, si queremos mostrar thumbnails por ejemplo, todos los thumbnails serán de la misma medida, sin importar el ratio de la imagen original.

BETA RC2: Al redimensionar archivos GIF y PNG, estos conservarán su transparencia.

En nuestro img.php queremos primero (¡!) redimensionar las imágenes. Lo haremos así:
//Recibiremos las nuevas medidas por la URL
$nuevo_ancho $_GET['ancho'];
$nuevo_alto $_GET['alto'];
$cut = (isset($_GET['cut'])) ? true false;

$imagen->resize($nuevo_ancho$nuevo_alto$cut);
Es necesario indicar llamar un método significa ejecutar la acción inmediatamente, por lo tanto, los cambios sufridos en la imagen son ya irreversibles. Sin embargo, la imagen original no sufre alteración ninguna durante el proceso (:-D)
EDICIÓN: Recolorear la imagen - Escala de grises
grayscale( ) La nueva imagen tendrá el mismo aspecto, pero en escala de grises. Aplicar esta función disminuye la calidad de la imagen, ya que la deja como una imagen de 256 colores.

En nuestro archivo img.php convertiremos la imagen a escala de grises:
//Pero especificaremos si se desea hacerlo en la URL
if(isset($_GET['gris']))
    
$imagen->grayscale();
EDICIÓN: Recolorear la imagen - Asignar un color
colorize( string $color [, bool $exact ] ) Esta función dará a la imagen la tonalidad del color que pasemos como $color. Este parámetro debe indicar el color en formato RGB (R,G,B, r,g,b o r g b) o hexadecimal (#xxx, xxx, #xxxxxx o xxxxxx). Si el color no tiene ese formato válido, se genera una imagen de error.

El parámetro $exact sirve para indicar si la imagen debe perder su coloración original primero y luego recién ser coloreada, lo que significa que la nueva imagen ç tendrá diferentes tonalidades del color que especifiquemos; o agregar el color manteniendo la paleta anterior, lo que resultará en una imagen con cierta tonalidad del color que especifiquemos, pero que mantiene su aspecto original. En el primer caso, su valor debe ser true, y para el segundo, su valor es false. El valor por default es false.

BETA RC2: A partir de la versión BETA RC2, estas funciones tratarán primero de utilizar la función php imagefilter(), disponible a partir de PHP5. Esta función permite aplicar filtros a la imagen, obteniendo mejores resultados. Aquellos usuarios con versiones de PHP <5 o GD <2 usarán el método de cambio de color de la versión BETA RC1

Para nuestro archivo img.php, haremos que si no se ha definido que la imagen vaya en escala de grises, lo haga con una nueva coloración amarillenta:
if(isset($_GET['gris']))
    
$imagen->grayscale();
else {
    
$exact = (isset($_GET['exact'])) ? true false;    
    
$imagen->colorize("#F1D94B",$exact);
}
EDICIÓN: "Watermark" la imagen (Marcas de agua)
watermark( string $watermark [, int $posx] [, int $posy ] [, int $loop ] ) PHPImagen permite agregar fácilmente marcas de agua a nuestras imágenes. Esto no es más que una imagen $watermark sobrepuesta a la imagen original. La url de la imagen debe ser indicada como primer parámetro y debe estar en formato *.jpg, *.gif o *.png. Cualquier otro tipo de archivo que indiquemos provocará error. Lo más usado son las imágenes PNG, por lo niveles de transparencia que presentan.

$posx y $posy indicarán la posición de la marca. Su valor por default es 0. Su valor debe ser un entero. Si es positivo, se cuenta hacia abajo y/o hacia la derecha a partir de la esquina superior izquierda. Si es negativo, se calcula hacia arriba y/o hacia la izquierda desde la esquina inferior derecha. Si en vez de indicar un entero se indica false, la marca toma una posición central en relación a la imagen original.

$posx hace referencia al eje horizontal, $posy al eje vertical.

El cuarto parámetro $loop indicará si la marca insertada debe ser única o debe repetirse en sentido horizontal y/o vertical a lo largo de toda la imagen. Debe ser un entero entre 1 y 3:
  • 1: La marca debe repetirse horizontalmente
  • 2: La marca debe repetirse verticalmente
  • 3: La marca debe repetirse horizontal y verticalmente
Las marcas se repetirán respetando la posición indicada en $posx y $posy.

Nuestro img.php ha de añadir las marcas de agua en el centro verticalmente, y harán un loop horizontal. La marca base para el loop se ubicará en la posición 0, osea al borde de la imagen
$imagen->watermark("wm.png",null,false,1);
Esta función puede ser llamada varias veces, permitiendo así agregar distintas marcas en una misma imagen.

NOTAR QUE como en el caso de img.php estamos insertando las marcas después de redimensionar la imagen, la marca tendrá siempre las mismas dimensiones.
EDICIÓN: "Textmark" la imagen (Escribir sobre la imagen)
textmark( string $text, string $color, int $size [, string $font ]
          [, int $rotation] [, int $posx] [, int $posy ] )
Tal vez es una de las características más saltantes de PHPImagen. Podemos escrbir muchas cosas sobre nuestra imagen, y darle formato a cada texto.

El texto es pasado por el parámetro $text. Puede contener cualquier caracter, pero dependiendo de la condifuración del servidor, puede haber algún problema al utilizar caracteres muy extraños.

El color del texto es definido en $color. Hay varias formas de indicarlo. Por ejemplo, si yo quiero poner el color rosado podré definir el parámetro $color de varias formas. Puedo pasar el color en forma hexadecimal, osea en HTML estándar (#FF2A7F). También es posible indicarlo en formato RGB (255,42,127). Ver la demostración más abajo para ver todos los formatos aceptados.

$size indica el tamaño del texto. Si definimos una fuente específica en $font, el valor de $size es interpretado como píxeles. Si no se define $font, $size es tomado como puntos (similar a HTML).

$font indica si se debe usar una fuente TTF alojada en el servidor o se debe usar la fuente por default. El contenido de este parámetro debe ser la dirección de la fuente TTF que deseamos utilizar.

$rotation sólo tendrá efecto si se utiliza una fuente personalizada. Indica el grado de rotación que debe tener el texto, considerando como eje de rotación al punto inferior izquierdo del texto, desde donde se comienza a escribir. Debe ser indicado en grados de -180 a 180.

$posx y $posy indican la posición desde donde se debe comenzar a escribir. Nótese que si se define una fuente personalizada, el punto de referencia será la esquina inferior izquierda del texto. Si se usa la fuente predeterminada, el punto referencial es la esquina superior izquierda del texto. ¿Por qué? Caprichos del PHP. Las reglas son las mismas que para las marcas de agua.

A mí me gustan más las cosas prácticas. Sigamos con nuestro img.php. Quiero escribir 2 textos. Veamos:
/*
TEXTO 1: Imagen v1.0

CARACTERÍSTICAS:
    Color: #ff0 -> Amarillo
    Tamaño: 15px
    Fuente: font2.ttf
    Rotación: 90º en sentido antihorario (+90)
    Posición en eje horizontal: a 15px del borde izquierdo de la imagen
    Posición en eje vertical: a 17px del borde inferior de la imagen 

Para el color AMARILLO podré poner:

#ff0
#ffff00
ff0
ffff00
255,255,0
255.255.0
255 255 0

*/
$imagen->textmark("Imagen v1.0","#ff0",15,"font2.ttf",90,15,-17);

/*
TEXTO 2: MyOkram.INFO

CARACTERÍSTICAS:
    Color: #fff -> Blanco
    Tamaño: 3pt
    Fuente: Por default
    Rotación: -
    Posición en eje horizontal: a 5px del border izquierdo de la imagen
    Posición en eje vertical: a 15px del border inferior de la imagen 

Para el color BLANCO podré poner:

#fff
#ffffff
fff
ffffff
255,255,255
255.255.255
255 255 255

*/
$imagen->textmark("MyOkram.INFO","255 255 255",3,null,null,5,-15);
Enviando el resultado al navegador: Guardar al servidor
doSave( string $destino [, int $quality ] ) Teóricamente, este método no envía salida alguna al navegador. Lo que hace es guardar la imagen modificada en el servidor. En consecuencia, este método, a diferencia de los dos siguientes, NO termina la ejecución del script. El parámetro $destino

El parámetro $quality indica la calidad que debe tener la imagen. Debe ser un entero entre 1 y 100. Tenga en cuenta que a mayor calidad, mayor el tamaño del archivo enviado. El valor por default es 75.
$imagen->doSave("path/nombre_de_archivo",90);
Note que la extensión del archivo será definida por el script, de acuerdo al contenido generado. Por lo tanto, es mejor no colocar al nombre de archivo una extensión. Si lo hace, el script comprobará que la extensión es la correcta. Si no lo es, conservará todo el nombre y le agregará la nueva extensión correspondiente.
Enviando el resultado al navegador: Imprimir como imagen
doPrint( [ int $quality ] ) Envía la imagen modificada al navegador, indicándole que el contenido es una imagen y que debe mostrarla como tal. En consecuencia, este método termina la ejecución del script.

El parámetro $quality indica la calidad que debe tener la imagen. Debe ser un entero entre 1 y 100. Tenga en cuenta que a mayor calidad, mayor el tamaño del archivo enviado. El valor por default es 75.
$imagen->doPrint();
Enviando el resultado al navegador: Enviar como descargable
doDownload( [ int $quality ] ) Envía la imagen modificada al navegador, indicándole que el contenido es un archivo descargable y que debe tratarlo como tal. En consecuencia, este método termina la ejecución del script.

El parámetro $quality indica la calidad que debe tener la imagen. Debe ser un entero entre 1 y 100. Tenga en cuenta que a mayor calidad, mayor el tamaño del archivo enviado. El valor por default es 75.

En nuestro img.php, daremos la opción de mostrar la imagen o descargarla. Esto lo haremos por la URL.
//Por la URL recibiremos el parámetro download
if(isset($_GET['download']))
    
$imagen->doDownload();
else
    
$imagen->doPrint();
Pero... quiero ver un ejemplo!
Bien, aqui tienes una serie de Ejemplos del funcionamiento de PHPImagen. Todos se basan en el script img.php que hemos ido creando en este tutorial.
Get PHPImagen at SourceForge.net. Fast, secure and Free Open Source software downloads
Esta web está alojada en SourceForge
Diseño y Programación por MyOkram ©2008
PHPeru.net es parte de MyOkram.com ©2008