Package: Zebra_Image
Project's homepage

Packages:

Classes:

Class: Zebra_Image

source file: /Zebra_Image.php

Class Overview



A compact, lightweight, object-oriented image manipulation library written in and for PHP, that provides methods   for performing several types of image manipulation operations. It doesn't require any external libraries other than   the GD2 extension (with which PHP usually comes precompiled with).


Author(s):



Version:


    

  • 2.2.2 (last revision: August 31, 2012)
    • 



Copyright:


    

  • (c) 2006 - 2012 Stefan Gabos
    • 








Properties







Methods












Class properties



integer $chmod_value 




Indicates the file system permissions to be set for newly created images.


Better is to leave this setting as it is.
If you know what you are doing, here is how you can calculate the permission levels:
  • 400 Owner Read
  • 200 Owner Write
  • 100 Owner Execute
  • 40 Group Read
  • 20 Group Write
  • 10 Group Execute
  • 4 Global Read
  • 2 Global Write
  • 1 Global Execute
   Default is 0755

Top






boolean $enlarge_smaller_images 




If set to FALSE, images having both width and height smaller than the required width and height, will be left   untouched (jpeg_quality and png_compression will still apply).


Available only for the resize() method
Default is TRUE

Top






integer $error 




In case of an error read this property's value to see the error's code.


Possible error codes are:
  • 1:  source file could not be found
  • 2:  source file is not readable
  • 3:  could not write target file
  • 4:  unsupported source file format
  • 5:  unsupported target file format
  • 6:  GD library version does not support target file format
  • 7:  GD library is not installed!
  • 8:  "chmod" command is disabled via configuration
   Default is 0 (no error).

Top






integer $jpeg_quality 




Indicates the quality of the output image (better quality means bigger file size).


Used only if the file at target_path is a JPG/JPEG image.
Range is 0 - 100
Default is 85

Top






integer $png_compression 




Indicates the compression level of the output image (lower compression means bigger file size).


Available only if PHP version is 5.1.2+, and only if the file at target_path is a PNG image. It will be   ignored otherwise.
Range is 0 - 9
Default is 9


Tags:





since:
2.2




Top






boolean $preserve_aspect_ratio 




Specifies whether, upon resizing, images should preserve their aspect ratio.


Available only for the resize() method
Default is TRUE

Top






boolean $preserve_time 




Indicates whether a target files should preserve the source file's date/time.


Default is TRUE


Tags:





since:
1.0.4




Top






boolean $sharpen_images 




Indicates whether the target image should have a "sharpen" filter applied to it.


Can be very useful when creating thumbnails and should be used only when creating thumbnails.
The sharpen filter relies on the "imageconvolution" PHP function which is available only for PHP version
5.1.0+, and will leave the images unaltered for older versions!
Default is FALSE


Tags:





since:
2.2




Top






string $source_path 




Path to an image file to apply the transformations to.


Supported file types are GIF, PNG and JPEG.

Top






string $target_path 




Path (including file name) to where to save the transformed image.


Can be a different than source_path - the type of the transformed image will be as indicated by the
file's extension (supported file types are GIF, PNG and JPEG).

Top






Class methods



constructor Zebra_Image()





void
Zebra_Image (
)



Constructor of the class.


Initializes the class and the default properties

Top






method apply_filter()





boolean
apply_filter (
string
$filter
, 
[
mixed
$arg1
= '']
, 
[
mixed
$arg2
= '']
, 
[
mixed
$arg3
= '']
, 
[
mixed
$arg4
= '']
)



Applies one or more filters to the image given as source_path and outputs it as the file specified as   target_path.


This method is available only if the imagefilter
function is available (available from PHP 5+), and will leave images unaltered otherwise.
  1.  // include the Zebra_Image library
    2. 

  2.  require 'path/to/Zebra_Image.php';
    3. 

  3.  
    4. 

  4.  // instantiate the class
    5. 

  5.  $img = new Zebra_Image();
    6. 

  6.  
    7. 

  7.  // a source image
    8. 

  8.  $img->source_path = 'path/to/source.ext';
    9. 

  9.  
    10. 

  10.  // path to where should the resulting image be saved
    11. 

  11.  // note that by simply setting a different extension to the file will
    12. 

  12.  // instruct the script to create an image of that particular type
    13. 

  13.  $img->target_path = 'path/to/target.ext';
    14. 

  14.  
    15. 

  15.  // apply the "grayscale" filter
    16. 

  16.  $img->apply_filter('grayscale');
    17. 

  17.  
    18. 

  18.  // apply the "contrast" filter
    19. 

  19.  $img->apply_filter('contrast', -20);
    20. 

You can also apply multiple filters at once. In this case, the method requires a single argument, an array of   arrays, containing the filters and associated arguments, where applicable:
  1.  // create a sepia effect
    2. 

  2.  // note how we're applying multiple filters at once
    3. 

  3.  // each filter is in its own array
    4. 

  4.  $img->apply_filter(array(
    5. 

  5.  
    6. 

  6.      // first we apply the "grayscale" filter
    7. 

  7.      array('grayscale'),
    8. 

  8.  
    9. 

  9.      // then we apply the "colorize" filter with 90, 60, 40 as
    10. 

  10.      // the values for red, green and blue
    11. 

  11.      array('colorize', 90, 60, 40),
    12. 

  12.  
    13. 

  13.  ));
    14. 



Tags:





return:

Returns TRUE on success or FALSE on error.
If imagefilter is not                               available the method will return FALSE without setting an error code.
If the requested filter doesn't exist, or invalid arguments are passed, the method                               will trigger a warning.
If FALSE is returned and you are sure that                               imagefilter exists and that                               the requested filter is valid, check the error property to see the error code.





since:
2.2.2





Parameters:





string
$filter

The (case-insensitive) name of the filter to apply. Can be one of the following:
  • brightness       -   changes the brightness of the image; use arg1
to set the level of brightness; the range of brightness
is -255 to 255;
  • colorize         -   adds (subtracts) specified RGB values to each pixel;
use arg1, arg2 and arg3 in the
form of red, green, blue and arg4 for the alpha
channel. the range for each color is -255 to 255 and
0 to 127 for alpha; alpha support is available only
for PHP 5.2.5+;
  • contrast         -   changes the contrast of the image; use arg1
to set the level of contrast; the range of contrast
is -100 to 100;
  • gausian_blur     -   blurs the image using the Gaussian method;
  • grayscale        -   converts the image into grayscale;
  • edgedetect       -   uses edge detection to highlight the edges in the image;
  • emboss           -   embosses the image;
  • mean_removal     -   uses mean removal to achieve a "sketchy" effect;
  • negate           -   reverses all the colors of the image;
  • pixelate         -   applies pixelation effect to the image, use arg1
to set the block size and arg2 to set the
pixelation effect mode; this filter is available
only for PHP 5.3.0+;
  • selective_blur   -   blurs the image;
  • smooth           -   makes the image smoother. Use arg1 to set the
level of smoothness. applies a 9-cell convolution matrix
where center pixel has the weight of arg1 and
others weight of 1.0. the result is normalized by dividing
the sum with arg1 + 8.0 (sum of the matrix).
any float is accepted;





mixed
$arg1
Used by the following filters: 
  • brightness       -   sets the brightness level (-255 to 255)
  • contrast         -   sets the contrast level (-100 to 100)
  • colorize         -   sets the value of the red component (-255 to 255)
  • smooth           -   sets the smoothness level
  • pixelate         -   sets the block size, in pixels





mixed
$arg2
Used by the following filters: 
  • colorize         -   sets the value of the green component (-255 to 255)
  • pixelate         -   whether to use advanced pixelation effect or not (defaults to FALSE).





mixed
$arg3
Used by the following filters: 
  • colorize         -   sets the value of the blue component (-255 to 255)





mixed
$arg4
Used by the following filters: 
  • colorize         -   alpha channel; a value between 0 and 127. 0 indicates
completely opaque while 127 indicates completely
transparent.





Top






method crop()





boolean
crop (
integer
$start_x
, 
integer
$start_y
, 
integer
$end_x
, 
integer
$end_y
)



Crops a portion of the image given as source_path and outputs it as the file specified as target_path.


  1.  // include the Zebra_Image library
    2. 

  2.  require 'path/to/Zebra_Image.php';
    3. 

  3.  
    4. 

  4.  // instantiate the class
    5. 

  5.  $img = new Zebra_Image();
    6. 

  6.  
    7. 

  7.  // a source image
    8. 

  8.  $img->source_path = 'path/to/source.ext';
    9. 

  9.  
    10. 

  10.  // path to where should the resulting image be saved
    11. 

  11.  // note that by simply setting a different extension to the file will
    12. 

  12.  // instruct the script to create an image of that particular type
    13. 

  13.  $img->target_path = 'path/to/target.ext';
    14. 

  14.  
    15. 

  15.  // crop a rectangle of 100x100 pixels, starting from the top-left corner
    16. 

  16.  $img->crop(0, 0, 100, 100);
    17. 



Tags:





return:

Returns TRUE on success or FALSE on error.
If FALSE is returned, check the error property to see the error code.





since:
1.0.4





Parameters:





integer
$start_x
x coordinate to start cropping from




integer
$start_y
y coordinate to start cropping from




integer
$end_x
x coordinate where to end the cropping




integer
$end_y
y coordinate where to end the cropping




Top






method flip_both()





boolean
flip_both (
)



Flips both horizontally and vertically the image given as source_path and outputs the resulted image as   target_path


  1.  // include the Zebra_Image library
    2. 

  2.  require 'path/to/Zebra_Image.php';
    3. 

  3.  
    4. 

  4.  // instantiate the class
    5. 

  5.  $img = new Zebra_Image();
    6. 

  6.  
    7. 

  7.  // a source image
    8. 

  8.  $img->source_path = 'path/to/source.ext';
    9. 

  9.  
    10. 

  10.  // path to where should the resulting image be saved
    11. 

  11.  // note that by simply setting a different extension to the file will
    12. 

  12.  // instruct the script to create an image of that particular type
    13. 

  13.  $img->target_path = 'path/to/target.ext';
    14. 

  14.  
    15. 

  15.  // flip the image both horizontally and vertically
    16. 

  16.  $img->flip_both();
    17. 



Tags:





return:

Returns TRUE on success or FALSE on error.
If FALSE is returned, check the error property to see the error code.





since:
2.1




Top






method flip_horizontal()





boolean
flip_horizontal (
)



Flips horizontally the image given as source_path and outputs the resulted image as target_path


  1.  // include the Zebra_Image library
    2. 

  2.  require 'path/to/Zebra_Image.php';
    3. 

  3.  
    4. 

  4.  // instantiate the class
    5. 

  5.  $img = new Zebra_Image();
    6. 

  6.  
    7. 

  7.  // a source image
    8. 

  8.  $img->source_path = 'path/to/source.ext';
    9. 

  9.  
    10. 

  10.  // path to where should the resulting image be saved
    11. 

  11.  // note that by simply setting a different extension to the file will
    12. 

  12.  // instruct the script to create an image of that particular type
    13. 

  13.  $img->target_path = 'path/to/target.ext';
    14. 

  14.  
    15. 

  15.  // flip the image horizontally
    16. 

  16.  $img->flip_horizontal();
    17. 



Tags:





return:

Returns TRUE on success or FALSE on error.
If FALSE is returned, check the error property to see the error code.





Top






method flip_vertical()





boolean
flip_vertical (
)



Flips vertically the image given as source_path and outputs the resulted image as target_path


  1.  // include the Zebra_Image library
    2. 

  2.  require 'path/to/Zebra_Image.php';
    3. 

  3.  
    4. 

  4.  // instantiate the class
    5. 

  5.  $img = new Zebra_Image();
    6. 

  6.  
    7. 

  7.  // a source image
    8. 

  8.  $img->source_path = 'path/to/source.ext';
    9. 

  9.  
    10. 

  10.  // path to where should the resulting image be saved
    11. 

  11.  // note that by simply setting a different extension to the file will
    12. 

  12.  // instruct the script to create an image of that particular type
    13. 

  13.  $img->target_path = 'path/to/target.ext';
    14. 

  14.  
    15. 

  15.  // flip the image vertically
    16. 

  16.  $img->flip_vertical();
    17. 



Tags:





return:

Returns TRUE on success or FALSE on error.
If FALSE is returned, check the error property to see the error code.





Top






method resize()





boolean
resize (
[
integer
$width
= 0]
, 
[
integer
$height
= 0]
, 
[
int
$method
= ZEBRA_IMAGE_CROP_CENTER]
, 
[
hexadecimal
$background_color
= '#FFFFFF']
)



Resizes the image given as source_path and outputs the resulted image as target_path.


  1.  // include the Zebra_Image library
    2. 

  2.  require 'path/to/Zebra_Image.php';
    3. 

  3.  
    4. 

  4.  // instantiate the class
    5. 

  5.  $img = new Zebra_Image();
    6. 

  6.  
    7. 

  7.  // a source image
    8. 

  8.  $img->source_path = 'path/to/source.ext';
    9. 

  9.  
    10. 

  10.  // path to where should the resulting image be saved
    11. 

  11.  // note that by simply setting a different extension to the file will
    12. 

  12.  // instruct the script to create an image of that particular type
    13. 

  13.  $img->target_path = 'path/to/target.ext';
    14. 

  14.  
    15. 

  15.  // apply a "sharpen" filter to the resulting images
    16. 

  16.  $img->sharpen_images = true;
    17. 

  17.  
    18. 

  18.  // resize the image to exactly 150x150 pixels, without altering aspect ratio, by using the CROP_CENTER method
    19. 

  19.  $img->resize(150, 150, ZEBRA_IMAGE_CROP_CENTER);
    20. 



Tags:





return:

Returns TRUE on success or FALSE on error.
If FALSE is returned, check the error property to see what went                                           wrong






Parameters:





integer
$width

The width to resize the image to.
If set to 0, the width will be automatically adjusted, depending                                           on the value of the height argument so that the image preserves                                           its aspect ratio.
If preserve_aspect_ratio is set to TRUE and both this and the                                           height arguments are values greater than 0, the image will                                           be resized to the exact required width and height and the aspect ratio                                           will be preserved - (also see the description for the method                                           argument below on how can this be done).
If preserve_aspect_ratio is set to FALSE, the image will be                                           resized to the required width and the aspect ratio will be ignored.
If both width and height are set to 0, a copy of                                           the source image will be created (jpeg_quality and                                           png_compression will still apply).
If either width or height are set to 0, the script                                           will consider the value of the preserve_aspect_ratio to bet set                                           to TRUE regardless of its actual value!





integer
$height

The height to resize the image to.
If set to 0, the height will be automatically adjusted, depending                                           on the value of the width argument so that the image preserves                                           its aspect ratio.
If preserve_aspect_ratio is set to TRUE and both this and the                                           width arguments are values greater than 0, the image will                                           be resized to the exact required width and height and the aspect ratio                                           will be preserved - (also see the description for the method                                           argument below on how can this be done).
If preserve_aspect_ratio is set to FALSE, the image will be                                           resized to the required height and the aspect ratio will be ignored.
If both width and height are set to 0, a copy of                                           the source image will be created (jpeg_quality and                                           png_compression will still apply).
If either height or width are set to 0, the script                                           will consider the value of the preserve_aspect_ratio to bet set                                           to TRUE regardless of its actual value!





int
$method

(Optional) Method to use when resizing images to exact width and height                                           while preserving aspect ratio.
If the preserve_aspect_ratio property is set to TRUE and both the                                           width and height arguments are values greater than 0,                                           the image will be resized to the exact given width and height and the                                           aspect ratio will be preserved by using on of the following methods:
  • ZEBRA_IMAGE_BOXED - the image will be scalled so that it will
fit in a box with the given width and height (both width/height will
be smaller or equal to the required width/height) and then it will
be centered both horizontally and vertically. The blank area will be
filled with the color specified by the bgcolor argument. (the
blank area will be filled only if the image is not transparent!)
 
  • ZEBRA_IMAGE_NOT_BOXED - the image will be scalled so that it
could fit in a box with the given width and height but will
not be enclosed in a box with given width and height. The new width/
height will be both smaller or equal to the required width/height
 
  • ZEBRA_IMAGE_CROP_TOPLEFT
  • ZEBRA_IMAGE_CROP_TOPCENTER
  • ZEBRA_IMAGE_CROP_TOPRIGHT
  • ZEBRA_IMAGE_CROP_MIDDLELEFT
  • ZEBRA_IMAGE_CROP_CENTER
  • ZEBRA_IMAGE_CROP_MIDDLERIGHT
  • ZEBRA_IMAGE_CROP_BOTTOMLEFT
  • ZEBRA_IMAGE_CROP_BOTTOMCENTER
  • ZEBRA_IMAGE_CROP_BOTTOMRIGHT
                                           For the methods involving crop, first the image is scaled so that both                                           its sides are equal or greater than the respective sizes of the bounding                                           box; next, a region of required width and height will be cropped from                                           indicated region of the resulted image.
Default is ZEBRA_IMAGE_CROP_CENTER





hexadecimal
$background_color

(Optional) The hexadecimal color (like "#FFFFFF" or "#FFF") of the                                           blank area. See the method argument.
When set to -1 the script will preserve transparency for transparent GIF                                           and PNG images. For non-transparent images the background will be white                                           in this case.
Default is #FFFFFF.





Top






method rotate()





boolean
rotate (
double
$angle
, 
[
mixed
$background_color
= -1]
)



Rotates the image given as source_path and outputs the resulted image as target_path.


  1.  // include the Zebra_Image library
    2. 

  2.  require 'path/to/Zebra_Image.php';
    3. 

  3.  
    4. 

  4.  // instantiate the class
    5. 

  5.  $img = new Zebra_Image();
    6. 

  6.  
    7. 

  7.  // a source image
    8. 

  8.  $img->source_path = 'path/to/source.ext';
    9. 

  9.  
    10. 

  10.  // path to where should the resulting image be saved
    11. 

  11.  // note that by simply setting a different extension to the file will
    12. 

  12.  // instruct the script to create an image of that particular type
    13. 

  13.  $img->target_path = 'path/to/target.ext';
    14. 

  14.  
    15. 

  15.  // rotate the image 45 degrees, clockwise
    16. 

  16.  $img->rotate(45);
    17. 



Tags:





return:

Returns TRUE on success or FALSE on error.
If FALSE is returned, check the error property to see the error                                           code.






Parameters:





double
$angle

Angle by which to rotate the image clockwise.
Between 0 and 360.





mixed
$background_color

(Optional) The hexadecimal color (like "#FFFFFF" or "#FFF") of the                                           uncovered zone after the rotation.
When set to -1 the script will preserve transparency for transparent GIF                                           and PNG images. For non-transparent images the background will be white                                           in this case.
Default is -1.





Top