WideImage

# Class: WideImage_Image Source Location: /Image.php
### Class Overview
Base class for images #### Author(s): | ### Variables $canvas $handle $handleReleased $sdata | ### Methods __construct __destruct addNoise allocateColor applyConvolution applyFilter applyMask asGrayscale asNegative asPalette asString asTrueColor autoCrop copy copyNoAlpha copyTo copyTransparencyFrom correctGamma crop destroy fill flip getCanvas getChannels getClosestColor getColorAt getColorRGB getExactColor getHandle getHeight getMask getOperation getRGBAt getTransparentColor getTransparentColorRGB getWidth isTransparent isTrueColor isValid merge mirror output releaseHandle resize resizeCanvas resizeDown resizeUp rotate roundCorners saveToFile setColorAt setRGBAt setTransparentColor unsharp writeHeader __call __sleep __toString __wakeup
### Child classes: WideImage_PaletteImage WideImage_TrueColorImage A class for truecolor image objects
### Class Details [line 44] Base class for images #### Tags:
abstract: |
[ Top ] ### Class Variables #### $canvas = null [line 62] Canvas object #### Tags:
access: | protected
Type: | WideImage_Canvas
[ Top ] #### $handle = null [line 50] Holds the image resource #### Tags:
access: | protected
Type: | resource
[ Top ] #### $handleReleased = false [line 56] Flag that determines if WideImage should call imagedestroy() upon object destruction #### Tags:
access: | protected
Type: | bool
[ Top ] #### $sdata = null [line 67] #### Tags:
access: | protected
Type: | string
[ Top ] ### Class Methods ### constructor __construct [line 74]
`WideImage_Image __construct( resource $handle)`
The base class constructor Overridden in child classes as: WideImage_TrueColorImage::__construct() Creates the object #### Parameters:
resource | $handle | Image handle (GD2 resource)
[ Top ] ### destructor __destruct [line 85]
`void __destruct( )`
Cleanup Destroys the handle via WideImage_Image::destroy() when called by the GC. [ Top ] ### method addNoise [line 813]
`WideImage_Image addNoise( int $amount, string $type)`
Adds noise to the image #### Tags:
return: | Image with noise added
author: | Tomasz Kapusta
#### Parameters:
int | $amount | Number of noise pixels to add
string | $type | Type of noise 'salt&pepper', 'color' or 'mono'
[ Top ] ### method allocateColor [line 248]
`int allocateColor( mixed $R, [int $G = null], [int $B = null])`
Allocate a color by RGB values. #### Tags:
return: | Image color index
#### Parameters:
mixed | $R | Red-component value or an RGB array (with red, green, blue keys)
int | $G | If $R is int, this is the green component
int | $B | If $R is int, this is the blue component
[ Top ] ### method applyConvolution [line 677]
`WideImage_Image applyConvolution( array $matrix, float $div, float $offset)`
Applies convolution matrix with imageconvolution() #### Parameters:
array | $matrix |
float | $div |
float | $offset |
[ Top ] ### method applyFilter [line 664]
`WideImage_Image applyFilter( int $filter, [int $arg1 = null], [int $arg2 = null], [int $arg3 = null], [int $arg4 = null])`
Applies a filter #### Parameters:
int | $filter | One of the IMG_FILTER_* constants
int | $arg1 |
int | $arg2 |
int | $arg3 |
int | $arg4 |
[ Top ] ### method applyMask [line 649]
`WideImage_Image applyMask( WideImage_Image $mask, [mixed $left = 0], [mixed $top = 0])`
Returns an image with applied mask A mask is a grayscale image, where the shade determines the alpha channel. Black is fully transparent and white is fully opaque. #### Tags:
return: | The resulting image
#### Parameters:
WideImage_Image | $mask | The mask image, greyscale
mixed | $left | Left coordinate, smart coordinate
mixed | $top | Top coordinate, smart coordinate
[ Top ] ### method asGrayscale [line 754]
`WideImage_Image asGrayscale( )`
Returns a grayscale copy of the image #### Tags:
return: | grayscale copy
[ Top ] ### method asNegative [line 744]
`WideImage_Image asNegative( )`
Returns a negative of the image This operation differs from calling WideImage_Image::applyFilter(IMG_FILTER_NEGATIVE), because it's 8-bit and transparency safe. This means it will return an 8-bit image, if the source image is 8-bit. If that 8-bit image has a palette transparency, the resulting image will keep transparency. #### Tags:
return: | negative of the image
[ Top ] ### method asPalette [line 919]
`WideImage_Image asPalette( [int $nColors = 255], [bool $dither = null], [bool $matchPalette = true])`
Returns a palette copy (8bit) of the image #### Tags:
abstract: |
Overridden in child classes as: WideImage_PaletteImage::asPalette() (non-PHPdoc) WideImage_TrueColorImage::asPalette() #### Parameters:
int | $nColors | Number of colors in the resulting image, more than 0, less or equal to 255
bool | $dither | Use dithering or not
bool | $matchPalette | Set to true to use imagecolormatch() to match the resulting palette more closely to the original image
[ Top ] ### method asString [line 175]
`string asString( string $format)`
Returns binary string with image data in format specified by $format Additional parameters may be passed to the function. See WideImage_Image::saveToFile() for more details. #### Tags:
return: | The binary image data in specified format
#### Parameters:
string | $format | The format of the image
[ Top ] ### method asTrueColor [line 909]
`WideImage_TrueColorImage asTrueColor( )`
Returns a true-color copy of the image #### Tags:
abstract: |
Overridden in child classes as: WideImage_PaletteImage::asTrueColor() (non-PHPdoc) WideImage_TrueColorImage::asTrueColor() (non-PHPdoc) [ Top ] ### method autoCrop [line 730]
`WideImage_Image autoCrop( [int $margin = 0], [int $rgb_threshold = 0], [int $pixel_cutoff = 1], [int $base_color = null])`
Performs an auto-crop on the image The image is auto-cropped from each of four sides. All sides are scanned for pixels that differ from $base_color for more than $rgb_threshold in absolute RGB difference. If more than $pixel_cutoff differentiating pixels are found, that line is considered to be the crop line for the side. If the line isn't different enough, the algorithm procedes to the next line towards the other edge of the image. When the crop rectangle is found, it's enlarged by the $margin value on each of the four sides. #### Tags:
return: | The cropped image
#### Parameters:
int | $margin | Margin for the crop rectangle, can be negative.
int | $rgb_threshold | RGB difference which still counts as "same color".
int | $pixel_cutoff | How many pixels need to be different to mark a cut line.
int | $base_color | The base color index. If none specified (or null given), left-top pixel is used.
[ Top ] ### method copy [line 850]
`WideImage_Image copy( )`
Returns a copy of the image object #### Tags:
return: | The copy
[ Top ] ### method copyNoAlpha [line 940]
`WideImage_Image copyNoAlpha( )`
Returns an image without an alpha channel #### Tags:
abstract: |
Overridden in child classes as: WideImage_PaletteImage::copyNoAlpha() (non-PHPdoc) WideImage_TrueColorImage::copyNoAlpha() (non-PHPdoc) [ Top ] ### method copyTo [line 865]
`void copyTo( WideImage_Image $dest, [int $left = 0], [int $top = 0])`
Copies this image onto another image #### Parameters:
WideImage_Image | $dest |
int | $left |
int | $top |
[ Top ] ### method copyTransparencyFrom [line 401]
`void copyTransparencyFrom( object $sourceImage, [bool $fill = true])`
Copies transparency information from $sourceImage. Optionally fills the image with the transparent color at (0, 0). #### Parameters:
object | $sourceImage |
bool | $fill | True if you want to fill the image with transparent color
[ Top ] ### method correctGamma [line 799]
`WideImage_Image correctGamma( float $inputGamma, float $outputGamma)`
Corrects gamma on the image #### Tags:
return: | Image with corrected gamma
#### Parameters:
float | $inputGamma |
float | $outputGamma |
[ Top ] ### method crop [line 707]
`WideImage_Image crop( [mixed $left = 0], [mixed $top = 0], [mixed $width = '100%'], [mixed $height = '100%'])`
Returns a cropped rectangular portion of the image If the rectangle specifies area that is out of bounds, it's limited to the current image bounds. Examples: $cropped = $img->crop(10, 10, 150, 200); // crops a 150x200 rect at (10, 10) $cropped = $img->crop(-100, -50, 100, 50); // crops a 100x50 rect at the right-bottom of the image $cropped = $img->crop('25%', '25%', '50%', '50%'); // crops a 50%x50% rect from the center of the image This operation supports alignment notation in left/top coordinates. Example: $cropped = $img->crop("right", "bottom", 100, 200); // crops a 100x200 rect from right bottom $cropped = $img->crop("center", "middle", 50, 30); // crops a 50x30 from the center of the image #### Tags:
return: | The cropped image
#### Parameters:
mixed | $left | Left-coordinate of the crop rect, smart coordinate
mixed | $top | Top-coordinate of the crop rect, smart coordinate
mixed | $width | Width of the crop rect, smart coordinate
mixed | $height | Height of the crop rect, smart coordinate
[ Top ] ### method destroy [line 96]
`void destroy( )`
This method destroy the image handle, and releases the image resource. After this is called, the object doesn't hold a valid image any more. No operation should be called after that. [ Top ] ### method fill [line 430]
`void fill( int $x, int $y, int $color)`
Fill the image at ($x, $y) with color index $color #### Parameters:
int | $x |
int | $y |
int | $color |
[ Top ] ### method flip [line 787]
`WideImage_Image flip( )`
Returns a flipped (mirrored over horizontal line) copy of the image #### Tags:
return: | Flipped copy
[ Top ] ### method getCanvas [line 890]
`WideImage_Canvas getCanvas( )`
Returns the canvas object The Canvas object can be used to draw text and shapes on the image Examples: $img = WideImage::load('pic.jpg); $canvas = $img->getCanvas(); $canvas->useFont('arial.ttf', 15, $img->allocateColor(200, 220, 255)); $canvas->writeText(10, 50, "Hello world!"); $canvas->filledRectangle(10, 10, 80, 40, $img->allocateColor(255, 127, 255)); $canvas->line(60, 80, 30, 100, $img->allocateColor(255, 0, 0)); $img->saveToFile('new.png'); #### Tags:
return: | The Canvas object
[ Top ] ### method getChannels [line 933]
`WideImage_Image getChannels( )`
Retrieve an image with selected channels Examples: $channels = $img->getChannels('red', 'blue'); $channels = $img->getChannels('alpha', 'green'); $channels = $img->getChannels(array('green', 'blue')); #### Tags:
abstract: |
Overridden in child classes as: WideImage_PaletteImage::getChannels() (non-PHPdoc) WideImage_TrueColorImage::getChannels() [ Top ] ### method getClosestColor [line 369]
`int getClosestColor( mixed $R, [int $G = null], [int $B = null])`
Returns closest color index that matches the given RGB value. Uses PHP's imagecolorclosest() #### Tags:
return: | Color index
#### Parameters:
mixed | $R | Red or RGBA array
int | $G | Green component (or null if $R is an RGB array)
int | $B | Blue component (or null if $R is an RGB array)
[ Top ] ### method getColorAt [line 343]
`int getColorAt( int $x, int $y)`
Returns an index of the color at $x, $y #### Tags:
return: | Color index for a pixel at $x, $y
#### Parameters:
int | $x |
int | $y |
[ Top ] ### method getColorRGB [line 331]
`mixed getColorRGB( int $colorIndex)`
Returns a color's RGB #### Tags:
return: | RGBA array for a color with index $colorIndex
#### Parameters:
int | $colorIndex | Color index
[ Top ] ### method getExactColor [line 386]
`int getExactColor( mixed $R, [int $G = null], [int $B = null])`
Returns the color index that exactly matches the given RGB value. Uses PHP's imagecolorexact() #### Tags:
return: | Color index
#### Parameters:
mixed | $R | Red or RGBA array
int | $G | Green component (or null if $R is an RGB array)
int | $B | Blue component (or null if $R is an RGB array)
[ Top ] ### method getHandle [line 109]
`resource getHandle( )`
Returns the GD image resource #### Tags:
return: | GD image resource
[ Top ] ### method getHeight [line 235]
`int getHeight( )`
#### Tags:
return: | Image height
[ Top ] ### method getMask [line 457]
`WideImage_Image getMask( )`
Returns the image's mask Mask is a greyscale image where the shade defines the alpha channel (black = transparent, white = opaque). For opaque images (JPEG), the result will be white. For images with single-color transparency (GIF, 8-bit PNG), the areas with the transparent color will be black. For images with alpha channel transparenct, the result will be alpha channel. #### Tags:
return: | An image mask
[ Top ] ### method getOperation [line 441]
`object getOperation( string $name)`
Used internally to create Operation objects #### Tags:
access: | protected
#### Parameters:
string | $name |
[ Top ] ### method getRGBAt [line 305]
`array getRGBAt( int $x, int $y)`
Returns a RGBA array for pixel at $x, $y #### Tags:
return: | RGB array
#### Parameters:
int | $x |
int | $y |
[ Top ] ### method getTransparentColor [line 267]
`int getTransparentColor( )`
#### Tags:
return: | Transparent color index
[ Top ] ### method getTransparentColorRGB [line 287]
`mixed getTransparentColorRGB( )`
Returns a RGB array of the transparent color or null if none. #### Tags:
return: | Transparent color RGBA array
[ Top ] ### method getWidth [line 227]
`int getWidth( )`
#### Tags:
return: | Image width
[ Top ] ### method isTransparent [line 259]
`bool isTransparent( )`
#### Tags:
return: | True if the image is transparent, false otherwise
[ Top ] ### method isTrueColor [line 902]
`bool isTrueColor( )`
Returns true if the image is true-color, false otherwise #### Tags:
abstract: |
Overridden in child classes as: WideImage_PaletteImage::isTrueColor() (non-PHPdoc) WideImage_TrueColorImage::isTrueColor() [ Top ] ### method isValid [line 117]
`bool isValid( )`
#### Tags:
return: | True, if the image object holds a valid GD image, false otherwise
[ Top ] ### method merge [line 554]
`WideImage_Image merge( WideImage_Image $overlay, [mixed $left = 0], [mixed $top = 0], [int $pct = 100])`
This method lays the overlay (watermark) on the image. Hint: if the overlay is a truecolor image with alpha channel, you should leave $pct at 100. This operation supports alignment notation in coordinates: $watermark = WideImage::load('logo.gif'); $base = WideImage::load('picture.jpg'); $result = $base->merge($watermark, "right - 10", "bottom - 10", 50); // applies a logo aligned to bottom-right corner with a 10 pixel margin #### Tags:
return: | The merged image
#### Parameters:
WideImage_Image | $overlay | The overlay image
mixed | $left | Left position of the overlay, smart coordinate
mixed | $top | Top position of the overlay, smart coordinate
int | $pct | The opacity of the overlay
[ Top ] ### method mirror [line 764]
`WideImage_Image mirror( )`
Returns a mirrored copy of the image #### Tags:
return: | Mirrored copy
[ Top ] ### method output [line 214]
`void output( string $format)`
Outputs the image to browser Sets headers Content-length and Content-type, and echoes the image in the specified format. All other headers (such as Content-disposition) must be added manually. Example: WideImage::load('image1.png')->resize(100, 100)->output('gif'); #### Parameters:
string | $format | Image format
[ Top ] ### method releaseHandle [line 125]
`void releaseHandle( )`
Releases the handle [ Top ] ### method resize [line 487]
`WideImage_Image resize( [mixed $width = null], [mixed $height = null], [string $fit = 'inside'], [string $scale = 'any'])`
Resize the image to given dimensions. $width and $height are both smart coordinates. This means that you can pass any of these values in: positive or negative integer (100, -20, ...) positive or negative percent string (30%, -15%, ...) complex coordinate (50% - 20, 15 + 30%, ...) If $width is null, it's calculated proportionally from $height, and vice versa. Example (resize to half-size): $smaller = $image->resize('50%'); $smaller = $image->resize('100', '100', 'inside', 'down'); is the same as $smaller = $image->resizeDown(100, 100, 'inside'); #### Tags:
return: | The resized image
#### Parameters:
mixed | $width | The new width (smart coordinate), or null.
mixed | $height | The new height (smart coordinate), or null.
string | $fit | 'inside', 'outside', 'fill'
string | $scale | 'down', 'up', 'any'
[ Top ] ### method resizeCanvas [line 595]
`WideImage_Image resizeCanvas( mixed $width, mixed $height, mixed $pos_x, mixed $pos_y, [int $bg_color = null], [string $scale = 'any'], [bool $merge = false])`
Resizes the canvas of the image, but doesn't scale the content of the image This operation creates an empty canvas with dimensions $width x $height, filled with background color $bg_color and draws the original image onto it at position [$pos_x, $pos_y]. Arguments $width, $height, $pos_x and $pos_y are all smart coordinates. $width and $height are relative to the current image size, $pos_x and $pos_y are relative to the newly calculated canvas size. This can be confusing, but it makes sense. See the example below. The example below loads a 100x150 image and then resizes its canvas to 200% x 100%+20 (which evaluates to 200x170). The image is placed at position [10, center+20], which evaluates to [10, 30]. $image = WideImage::load('someimage.jpg'); // 100x150 $white = $image->allocateColor(255, 255, 255); $image->resizeCanvas('200%', '100% + 20', 10, 'center+20', $white); The parameter $merge defines whether the original image should be merged onto the new canvas. This means it blends transparent color and alpha colors into the background color. If set to false, the original image is just copied over, preserving the transparency/alpha information. You can set the $scale parameter to limit when to resize the canvas. For example, if you want to resize the canvas only if the image is smaller than the new size, but leave the image intact if it's larger, set it to 'up'. Likewise, if you want to shrink the canvas, but don't want to change images that are already smaller, set it to 'down'. #### Tags:
return: | The resulting image with resized canvas
#### Parameters:
mixed | $width | Width of the new canvas (smart coordinate, relative to current image width)
mixed | $height | Height of the new canvas (smart coordinate, relative to current image height)
mixed | $pos_x | x-position of the image (smart coordinate, relative to the new width)
mixed | $pos_y | y-position of the image (smart coordinate, relative to the new height)
int | $bg_color | Background color (created with allocateColor or allocateColorAlpha), defaults to null (tries to use a transparent color)
string | $scale | Possible values: 'up' (enlarge only), 'down' (downsize only), 'any' (resize precisely to $width x $height). Defaults to 'any'.
bool | $merge | Merge the original image (flatten alpha channel and transparency) or copy it over (preserve). Defaults to false.
[ Top ] ### method resizeDown [line 501]
`WideImage_Image resizeDown( [int $width = null], [int $height = null], [string $fit = 'inside'])`
Same as WideImage_Image::resize(), but the image is only applied if it is larger then the given dimensions. Otherwise, the resulting image retains the source's dimensions. #### Tags:
return: | resized image
#### Parameters:
int | $width | New width, smart coordinate
int | $height | New height, smart coordinate
string | $fit | 'inside', 'outside', 'fill'
[ Top ] ### method resizeUp [line 515]
`WideImage_Image resizeUp( [int $width = null], [int $height = null], [string $fit = 'inside'])`
Same as WideImage_Image::resize(), but the image is only applied if it is smaller then the given dimensions. Otherwise, the resulting image retains the source's dimensions. #### Tags:
return: | resized image
#### Parameters:
int | $width | New width, smart coordinate
int | $height | New height, smart coordinate
string | $fit | 'inside', 'outside', 'fill'
[ Top ] ### method rotate [line 530]
`WideImage_Image rotate( int $angle, [int $bgColor = null], [bool $ignoreTransparent = true])`
Rotate the image for angle $angle clockwise. Preserves transparency. Has issues when saving to a BMP. #### Tags:
return: | The rotated image
#### Parameters:
int | $angle | Angle in degrees, clock-wise
int | $bgColor | color of the new background
bool | $ignoreTransparent |
[ Top ] ### method roundCorners [line 633]
`WideImage_Image roundCorners( int $radius, [int $color = null], [int $smoothness = 2], [int $corners = 255])`
Returns an image with round corners You can either set the corners' color or set them transparent. Note on $smoothness: 1 means jagged edges, 2 is much better, more than 4 doesn't noticeably improve the quality. Rendering becomes increasingly slower if you increase smoothness. Example: $nice = $ugly->roundCorners(20, $ugly->allocateColor(255, 0, 0), 2); Use $corners parameter to specify which corners to draw rounded. Possible values are WideImage::SIDE_TOP_LEFT, WideImage::SIDE_TOP, WideImage::SIDE_TOP_RIGHT, WideImage::SIDE_RIGHT, WideImage::SIDE_BOTTOM_RIGHT, WideImage::SIDE_BOTTOM, WideImage::SIDE_BOTTOM_LEFT, WideImage::SIDE_LEFT, and WideImage::SIDE_ALL. You can specify any combination of corners with a + operation, see example below. Example: $white = $image->allocateColor(255, 255, 255); $diagonal_corners = $image->roundCorners(15, $white, 2, WideImage::SIDE_TOP_LEFT + WideImage::SIDE_BOTTOM_RIGHT); $right_corners = $image->roundCorners(15, $white, 2, WideImage::SIDE_RIGHT); #### Tags:
return: | The resulting image with round corners
#### Parameters:
int | $radius | Radius of the corners
int | $color | The color of corners. If null, corners are rendered transparent (slower than using a solid color).
int | $smoothness | Specify the level of smoothness. Suggested values from 1 to 4.
int | $corners | Specify which corners to draw (defaults to WideImage::SIDE_ALL = all corners)
[ Top ] ### method saveToFile [line 157]
`void saveToFile( string $uri)`
Saves an image to a file The file type is recognized from the $uri. If you save to a GIF8, truecolor images are automatically converted to palette. This method supports additional parameters: quality (for jpeg images) and compression quality and filters (for png images). See http://www.php.net/imagejpeg and http://www.php.net/imagepng for details. Examples: // save to a GIF $image->saveToFile('image.gif'); // save to a PNG with compression=7 and no filters $image->saveToFile('image.png', 7, PNG_NO_FILTER); // save to a JPEG with quality=80 $image->saveToFile('image.jpg', 80); // save to a JPEG with default quality=100 $image->saveToFile('image.jpg'); #### Parameters:
string | $uri | File location
[ Top ] ### method setColorAt [line 355]
`void setColorAt( int $x, int $y, int $color)`
Set the color index $color to a pixel at $x, $y #### Parameters:
int | $x |
int | $y |
int | $color | Color index
[ Top ] ### method setRGBAt [line 320]
`void setRGBAt( int $x, int $y, array $color)`
Writes a pixel at the designated coordinates Takes an associative array of colours and uses getExactColor() to retrieve the exact index color to write to the image with. #### Parameters:
int | $x |
int | $y |
array | $color |
[ Top ] ### method setTransparentColor [line 277]
`void setTransparentColor( int $color)`
Sets the current transparent color index. Only makes sense for palette images (8-bit). #### Parameters:
int | $color | Transparent color index
[ Top ] ### method unsharp [line 777]
`WideImage_Image unsharp( float $amount, float $radius, float $threshold)`
Applies the unsharp filter #### Tags:
return: | Unsharpened copy of the image
#### Parameters:
float | $amount |
float | $radius |
float | $threshold |
[ Top ] ### method writeHeader [line 196]
`void writeHeader( $name $name, $data $data)`
Output a header to browser. #### Tags:
access: | protected
#### Parameters:
$name | $name | Name of the header
$data | $data | Data
[ Top ] ### method __call [line 825]
`WideImage_Image __call( string $name, array $args)`
Used internally to execute operations #### Parameters:
string | $name |
array | $args |
[ Top ] ### method __sleep [line 947]
`array __sleep( )`
Returns an array of serializable protected variables. Called automatically upon serialize(). [ Top ] ### method __toString [line 837]
`string __toString( )`
Returns an image in GIF or PNG format [ Top ] ### method __wakeup [line 956]
`void __wakeup( )`
Restores an image from serialization. Called automatically upon unserialize(). [ Top ] Documentation generated on Sat, 19 Feb 2011 12:55:42 +0100 by phpDocumentor 1.4.3