Docs For Class Image

Class Image

Description

Image wrapper class

This class is an OO wrapper for PHP's image handling functions. Note that this class requires the GD library to be installed in order to work correctly. Not all functions are available in all version of this library. But the class will automatically try a fall-back to an alternative function where possible.

Also note, that this class will NOT output any error messages unless a fatal error is encountered and instead will report error to the logs. This is a intended behaviour, as any output (e.g. an error message) from the script would result in a broken image file, when the image is directly put to the user's browser.

So when you are working with this class: in case you encounter an error and want to know the cause of it, please activate the program's logging feature via the administrator's menu, reproduce the error and see the logs for the entry that describes the problem.

The following image types are currently supported:

bmp
gif
jpeg
png

since: 2.8.7
access: public

Object
   |
   --Image

Variable Summary

int $aqua

int $black

int $blue

int $fuchsia

int $gray

int $green

int $grey

int $lime

int $maroon

int $navy

int $olive

int $purple

int $red

int $silver

int $teal

int $white

int $yellow

Method Summary

Image Image ([string $filename = null], [string $imageType = null])
bool applyFilter (int $filter, int $arg1, int $arg2, int $arg3)
bool blur (float $ammount)
bool brightness (float $ammount)
void clearCanvas ()
Object cloneObject ()
bool colorize (int $r, int $g, int $b)
float compareImage (Image|string $otherImage)
bool contrast (float $ammount)
bool copyPalette (Image|string|resource $sourceImage)
bool copyRegion (Image|string|resource $sourceImage, [int $sourceX = null], [int $sourceY = null], [int $width = null], [int $height = null], [int $destX = null], [int $destY = null], [float $opacity = null])
bool drawEllipse (int $x, int $y, int $width, [int $height = null], [int $color = null], [int $fillColor = null], [int $start = null], [int $end = null])
bool drawFormattedString (string $text, [int $x = null], [int $y = null], [int $color = null], [string $fontfile = null], [int $fontsize = 10], int $angle)
bool drawLine (int $x1, int $y1, int $x2, int $y2, [int $color = null])
bool drawPoint (int $x, int $y, [int $color = null])
bool drawPolygon (array $points, int $x, int $y, [int $color = null], [int $fillColor = null])
bool drawRectangle (int $x, int $y, int $width, [int $height = null], [int $color = null], [int $fillColor = null])
bool drawString (string $text, [int $x = null], [int $y = null], [int $color = null], [int $font = null], [bool $asVerticalString = false])
bool enableAlpha ([bool $isEnabled = true], [bool $saveAlpha = null])
bool enableAntialias ([bool $isEnabled = true])
bool enableInterlace ([bool $isInterlaced = true])
bool equals (object $anotherObject)
bool exists ()
array fill (int $fillColor, int $x, int $y, [int $borderColor = null])
bool flipX ()
bool flipY ()
int|bool(false) getBackgroundColor ()
int|bool(false) getColor (int $r, int $g, int $b, [float $opacity = null])
int|bool(false) getColorAt (int $x, int $y)
array|bool(false) getColorValues (int $color)
int|bool(false) getFontHeight (int $font)
int|bool(false) getFontWidth (int $font)
int|bool(false) getHeight ()
int|bool(false) getLineWidth ()
int|bool(false) getPaletteSize ()
string getPath ()
resource|bool(false) getResource ()
array getSize (string $filename)
int|bool(false) getTransparency ()
int|bool(false) getWidth ()
bool hasAlpha ()
bool isBroken ()
bool isInterlaced ()
bool isTruecolor ()
bool monochromatic (int $r, int $g, int $b)
bool multiply (int $r, int $g, int $b)
bool negate ()
string|bool(false) outputToFile (string $filename, [string $imageType = null])
bool outputToScreen ([string $imageType = null])
bool reduceColorDepth (int $ammount, [bool $dither = true])
bool replaceColor (int $replacedColor, int $newColor)
bool replaceIndexColor (int $replacedColor, array|int $newColor)
bool resize ([int $width = null], [int $height = null])
bool resizeCanvas ([int $width = null], [int $height = null], [int $paddingLeft = null], [int $paddingTop = null], [array $canvasColor = null])
bool resizeImage ([int $width = null], [int $height = null])
bool rotate (float $angle)
bool setBackgroundColor ([int $backgroundColor = null], [bool $replaceOldColor = true])
bool setBrush (string|Image|Brush|resource $brush)
bool setGamma (float $gamma)
bool setLineStyle ()
bool setLineWidth (int $width)
bool setTransparency ([int|array $transparency = null])
bool sharpen (float $ammount)
void toGrayscale ()
void toGreyscale ()
string toString ()
string|int uploadFile (string $fromId, string $toFilename, [string $imageType = null], [int $maxSize = null], [int $width = null], [int $height = null], [bool $keepAspectRatio = true], [array $backgroundColor = null])

Variables

int $aqua = null

aqua = #00ffff

color

final:
access: public

int $black = null

black = #000000

color

final:
access: public

int $blue = null

blue = #0000ff

color

final:
access: public

int $fuchsia = null

fuchsia = #ff00ff

color

final:
access: public

int $gray = null

gray = #808080

color

final:
access: public

int $green = null

green = #008000

color

final:
access: public

int $grey = null

grey = #808080

color

final:
access: public

int $lime = null

lime = #00ff00

color

final:
access: public

int $maroon = null

maroon = #800000

color

final:
access: public

int $navy = null

navy = #008080

color

final:
access: public

int $olive = null

olive = #808000

color

final:
access: public

int $purple = null

purple = #800080

color

final:
access: public

int $red = null

red = #ff0000

color

final:
access: public

int $silver = null

silver = #c0c0c0

color

final:
access: public

int $teal = null

teal = #008080

color

final:
access: public

int $white = null

white = #ffffff

color

final:
access: public

int $yellow = null

yellow = #ffff00

color

final:
access: public

Methods

create a new instance of this class

Image Image (

[string $filename = null], [string $imageType = null]

)

List of parameters:

Name	Type	Description
$filename	string	name of the source file
$imageType	string	type of the image

Description:

The argument $filename determines wich file to take the input from. If $filename is not provided, an empty truecolor image with white background and a dimension of 300x200px is created.

The argument $imageType can be on of the following.

bmp
gif
jpeg
png

If no image type is set, the function will try to determine the correct type of the file automatically, 1st by checking the file extension and in case this did not work 2nd by checking the file header. If all this fails it writes an entry to the logs and creates an error image instead.

NOTE: it DOES NOT produces an error message, as this would result in a broken image, if the image was printed!

To check wether or not an image is broken, use

if ($myImage->isBroken() === true) {
// handle broken image
}

apply a filter

bool applyFilter (

int $filter, int $arg1, int $arg2, int $arg3

)

List of parameters:

Name	Type	Description
$filter	int	a constant (see list)
$arg1	int	depends on filter
$arg2	int	depends on filter
$arg3	int	depends on filter

Description:

This is an OO-style alias of PHP's imagefilter() function. See the PHP manual for a full description.

$filter can be (among others) one of the following:

IMG_FILTER_BRIGHTNESS (see also: Image::brightness())
IMG_FILTER_CONTRAST (see also: Image::contrast())
IMG_FILTER_COLORIZE (see also: Image::colorize())
IMG_FILTER_EDGEDETECT
IMG_FILTER_EMBOSS
IMG_FILTER_GAUSSIAN_BLUR (see also: Image::blur(), Image::sharpen())
IMG_FILTER_GRAYSCALE (see also: Image::toGrayscale())
IMG_FILTER_SELECTIVE_BLUR
IMG_FILTER_MEAN_REMOVAL
IMG_FILTER_NEGATE (see also: Image::negate())
IMG_FILTER_SMOOTH (see also: Image::blur(), Image::sharpen())

Note: this is only available with PHP 5. If you are using PHP 4, check with the alternative functions named above.

Returns bool(true) on success and bool(false) on error.

blur the image

bool blur (

float $ammount

)

List of parameters:

Name	Type	Description
$ammount	float	effect strength

Description:

This makes the image look smoother. The argument $ammount is any float 0.0 through 1.0, which translates to 0% through 100%.

access: public

brighten / darken the image

bool brightness (

float $ammount

)

List of parameters:

Name	Type	Description
$ammount	float	effect strength

Description:

Adds or removes white from the image.

The argument $ammount is a float between -1.0 and 1.0. Which you might translate to -100% through 100%.

This has the same effect as calling Image::colorize($r, $g, $b), with $r, $b, $g being identical values.

Returns bool(true) on success and bool(false) on error.

access: public

This function produces a new image

void clearCanvas ()

Description:

The old image is deleted and replaced by a new one. Be warned: all previous changes to the image will be lost!

access: public

clone this object

Object cloneObject ()

Description:

Creates a copy of this object. You are encouraged to reimplement this for each subclass.

access: public

Redefinition of: Object::cloneObject()

colorize the image

bool colorize (

int $r, int $g, int $b

)

List of parameters:

Name	Type	Description
$r	int	red value
$g	int	green value
$b	int	blue value

Description:

This adds the specified color to the image, shaded in the color provided.

The arguments $r, $g, $b can be any integer of -255 through 255.

Returns bool(true) on success and bool(false) on error.

access: public

compare this image to another

float compareImage (

Image|string $otherImage

)

List of parameters:

Name	Type	Description
$otherImage	Image\|string	filename or image object

Description:

This function compare the image to another image on a pixel by pixel basis. It returns the difference between booth images in percent.

The result is returned as a float value, where 0.0 translates to 0% (images are exactly the same) and 1.0 translates to 100% (images are totally different).

On error the function returns bool(false).

I would suggest to consider two images equal, if the difference is not greater than 1% (or in other words, if the images are 99% the same). Images with less than 10% difference should be similar. E.g. one has sharper edges, or one is lighter than the other. Any value higher than 10% should indicate that both images are different.

WARNING: since this function compares every pixel it is very slow for large images. It's use is suggested for testing and debugging issues only.

since: 2.9.9
access: public

add / remove contrast from the image

bool contrast (

float $ammount

)

List of parameters:

Name	Type	Description
$ammount	float	effect strength

Description:

Adds or removes grey from the image.

The argument $ammount is a float between -1.0 and 1.0. Which you might translate to -100% through 100%.

Returns bool(true) on success and bool(false) on error.

access: public

copy palette

bool copyPalette (

Image|string|resource $sourceImage

)

List of parameters:

Name	Type	Description
$sourceImage	Image\|string\|resource	the image to copy the palette from

Description:

This copies the palette from the source image to this image.

The argument $sourceImage can be another Image object, a filename, or an image resource.

Returns bool(true) on success and bool(false) on error.

access: public

copy one portion of an image to another

bool copyRegion (

Image|string|resource $sourceImage, [int $sourceX = null], [int $sourceY = null], [int $width = null], [int $height = null], [int $destX = null], [int $destY = null], [float $opacity = null]

)

List of parameters:

Name	Type	Description
$sourceImage	Image\|string\|resource	filename or image resource
$sourceX	int	horizontal position in pixel
$sourceY	int	vertical position in pixel
$width	int	horizontal dimension in pixel
$height	int	vertical dimension in pixel
$destX	int	horizontal position in pixel
$destY	int	vertical position in pixel
$opacity	float	alpha value in percent

Description:

This is an OO-style alias of PHP's imagecopymerge() function. See the PHP manual for a full description.

The argument $sourceImage can be another Image object, a filename, or an image resource.

If $width and / or $height is NULL or not provided, then they are set to cover the full size of the image.

If $sourceX and / or $sourceY is NULL or not provided, then they are set to 0 (the upper left corner).

If $destX and / or $destY is NULL or not provided, then they are set to the same values as $sourceX and $sourceY.

The $opacity parameter is available for truecolor images only. It is a float between 0.0 (completely opaque) and 1.0 (completely transparent). You may translate this to 0% through 100% opacity. Note that opacity only applies when alpha blending has has not been disabled and the underlying function is available.

To copy the whole source image to the current image, just write:

$image->copyRegion($anotherImage);
// $image now is a copy of $anotherImage

Returns bool(true) on success and bool(false) on error.

access: public

draw an ellipse

bool drawEllipse (

int $x, int $y, int $width, [int $height = null], [int $color = null], [int $fillColor = null], [int $start = null], [int $end = null]

)

List of parameters:

Name	Type	Description
$x	int	horizontal position
$y	int	vertical position
$width	int	horizontal dimension in pixel
$height	int	vertical dimension in pixel
$color	int	the color of the contour line
$fillColor	int	the color to flood fill the ellipse with
$start	int	angle in degrees (start)
$end	int	angle in degrees (end)

Description:

This draws an ellipse at position ($x px, $y px).

With the dimensions $width px to $height px. Note that you can set $width = $height to create a circle. Setting $height = NULL does the same.

The $color is an integer value, that you can get via the function Image::getColor().

In addition you may also use on of the predefined colors: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow.

Example:

$image = new Image();
$image->drawEllipse(20, 20, 30, null, $image->black);

The same applies to $fillColor. When provided, a filled object is created. You can create object that are not filled, by setting this to NULL.

Setting $start and $end will create an arcus, that starts at $start degrees and goes to $end degrees. Both values can be NULLed. Note that $start and $end can also be negative.

access: public

draw a formatted text string with a true-type font

bool drawFormattedString (

string $text, [int $x = null], [int $y = null], [int $color = null], [string $fontfile = null], [int $fontsize = 10], int $angle

)

List of parameters:

Name	Type	Description
$text	string	the text to draw
$x	int	horizontal position
$y	int	vertical position
$color	int	the text color
$fontfile	string	path and name of a true-type (*.ttf) font
$fontsize	int	size
$angle	int	rotation 0 through 360 degrees

Description:

This is the same as Image::drawString() except, that it allows some true-type font of your choosing to be used, accepts a custom font size and allows to freely choose an angle of rotation.

The rotation is performed anticlockwise. To create a text that flows straight up, set $angle to 90.

The default font is 'tahoma'. The path to the font file needs to start with a '/' sign.

Note that $fontfile my also be just the name of font, like 'tahoma', 'arial', or 'helvetica'. If the name instead of the file is provided, this function will try to use a true-type font of the same name, which is installed on the current system. Of course this requires that the font actually IS installed on the system.

access: public

draw a line

bool drawLine (

int $x1, int $y1, int $x2, int $y2, [int $color = null]

)

List of parameters:

Name	Type	Description
$x1	int	horizontal position (start)
$y1	int	vertical position (start)
$x2	int	horizontal position (end)
$y2	int	vertical position (end)
$color	int	the line color

Description:

This draws a straight line at position ($x px, $y px).

The line has the color set by the argument $color. This defaults to black.

access: public

draw a point (aka paint a pixel)

bool drawPoint (

int $x, int $y, [int $color = null]

)

List of parameters:

Name	Type	Description
$x	int	horizontal position (left value)
$y	int	vertical position (top value)
$color	int	the point color

Description:

This paints the pixel at position ($x px, $y px) with a $color. This color defaults to black.

access: public

draw a polygon

bool drawPolygon (

array $points, int $x, int $y, [int $color = null], [int $fillColor = null]

)

List of parameters:

Name	Type	Description
$points	array	a list of vertices
$x	int	horicontal position
$y	int	vertical position
$color	int	color of contour line
$fillColor	int	inner color

Description:

This draws a polygon at position ($x px, $y px).

$points is a two dimensional array of the vertices. Example:

$points = array(
0 => array( 10, 0 ),
1 => array( 20, 10 ),
2 => array( 0, 10 )
);
$image = new Image();
$image->drawPolygon($points);
$image->outputToScreen();

(The code above will output a triangle.)

The $color is an integer value, that you can get via the function Image::getColor().

In addition you may also use on of the predefined colors: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow.

Example:

$image = new Image();
$image->drawPolygon($points, $image->black);

The same applies to $fillColor. When provided, a filled object is created. You can create object that are not filled, by setting this to NULL.

access: public

draw a rectangle

bool drawRectangle (

int $x, int $y, int $width, [int $height = null], [int $color = null], [int $fillColor = null]

)

List of parameters:

Name	Type	Description
$x	int	horicontal position in pixel
$y	int	vertical position in pixel
$width	int	horizontal dimension in pixel
$height	int	vertical dimension in pixel
$color	int	color of contour line
$fillColor	int	inner color

Description:

This draws a rectangle at position ($x px, $y px).

With the dimensions $width px to $height px. Note that you can set $width = $height to create a square. Setting $height = NULL does the same.

The $color is an integer value, that you can get via the function Image::getColor().

In addition you may also use on of the predefined colors: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow.

Example:

$image = new Image();
$image->drawRectangle(10, 10, 30, null, $image->black);

The same applies to $fillColor. When provided, a filled object is created. You can create object that are not filled, by setting this to NULL.

access: public

draw a text string

bool drawString (

string $text, [int $x = null], [int $y = null], [int $color = null], [int $font = null], [bool $asVerticalString = false]

)

List of parameters:

Name	Type	Description
$text	string	the text to draw
$x	int	horizontal position
$y	int	vertical position
$color	int	the text color
$font	int	font size (1 through 5)
$asVerticalString	bool	switch between horizontal and vertical print

Description:

This draws a text string at position ($x px, $y px).

The string has the color set by the argument $color. This defaults to black.

The $color is an integer value, that you can get via the function Image::getColor().

In addition you may also use on of the predefined colors: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow.

Example:

$image = new Image();
$image->drawString('Hello World!', 0, 0, $image->black);

The argument $font determines the font type and size. The values 1-5 are used for a predefined system font. Where 1 is the smallest font-size and 5 is the largest. The font itself belongs to the sans-serif family. Note that you can load custom fonts using the PHP function imageloadfont(). The argument $font defaults to 2, which is a 10px font.

The argument $asVerticalString is used to switch from printing text horizontal to vertical. Note that vertical strings are rotated 90° left (anticlockwise). This means they will start at ($x px, $y px) upwards, so you should make sure, there is enough space for the string on your image above the starting point.

All arguments except $text may be skipped by assigning the NULL value.

access: public

enable / disable alpha blending

bool enableAlpha (

[bool $isEnabled = true], [bool $saveAlpha = null]

)

List of parameters:

Name	Type	Description
$isEnabled	bool	on / off
$saveAlpha	bool	on / off

Description:

Enables alpha blending if set to bool(true) and disables it when set to bool(false).

Works only with truecolor images.

If $saveAlpha is true and the output is a PNG image, the alpha channel information will get saved with the file, otherwise not. Note that this setting only affects PNG images.

You should be aware, that IE 6.0 and other older browsers do not support alpha channels in PNG images by default.

Returns bool(true) on success and bool(false) on error.

access: public

enable / disable antialiasing

bool enableAntialias (

[bool $isEnabled = true]

)

List of parameters:

Name	Type	Description
$isEnabled	bool	on / off

Description:

Enables antialiasing if set to bool(true) and disables it when set to bool(false).

Works only with truecolor images.

Returns bool(true) on success and bool(false) on error.

access: public

switch interlacing on / off

bool enableInterlace (

[bool $isInterlaced = true]

)

List of parameters:

Name	Type	Description
$isInterlaced	bool	on / off

Description:

If $isInterlaced is true, interlacing is set to on, otherwise set to off.

If the image is a JPEG, this setting will set the output to be a progressive image.

Returns bool(true) on success and bool(false) on error.

access: public

compare with another object

bool equals (

object $anotherObject

)

List of parameters:

Name	Type	Description
$anotherObject	object	any object or var you want to compare

Description:

Returns bool(true) if this object and $anotherObject are the booth object which have an image resource that is the same, or $anotherObject is an image resource and identical to the one of this object.

Retunrs bool(false) otherwise.

access: public

Redefinition of: Object::equals()

return true, if the image exists

bool exists ()

Description:

access: public

fill with a color

array fill (

int $fillColor, int $x, int $y, [int $borderColor = null]

)

List of parameters:

Name	Type	Description
$fillColor	int	the filled area will get this color
$x	int	horicontal position
$y	int	vertical position
$borderColor	int	flood fill will stop at this color

Description:

This does a flood fill at position ($x px, $y px).

The $fillColor is an integer value, that you can get via the function Image::getColor().

In addition you may also use on of the predefined colors: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow.

Example:

$image = new Image();
$image->fill($image->white);

If $borderColor is defined, flood fill will stop at the this color, otherwise it will stop at any color that is different from pixel ($x px, $y px).

access: public

flip the image horizontally

bool flipX ()

Description:

Returns bool(true) on success and bool(false) on error.

access: public

flip the image vertically

bool flipY ()

Description:

Returns bool(true) on success and bool(false) on error.

access: public

get current background color

int|bool(false) getBackgroundColor ()

Description:

Returns the current background color as an integer or bool(false) on error.

get a color for the current index

int|bool(false) getColor (

int $r, int $g, int $b, [float $opacity = null]

)

List of parameters:

Name	Type	Description
$r	int	red value
$g	int	green value
$b	int	blue value
$opacity	float	alpha value

Description:

This is an OO-style alias of PHP's imagecolorallocate() function. See the PHP manual for a full description.

The $opacity parameter is available as of PHP 4.3.2. It is a float between 0.0 (completely opaque) and 1.0 (completely transparent). You may translate this to 0% through 100% opacity. Note that opacity only applies when alpha blending has has not been disabled and the underlying function is available.

If the current palette already has the specified color, the existing color will be returned. Otherwise the new color will get appended to the palette.

Returns bool(false) on error.

access: public

get color at pixel ($x,$y)

int|bool(false) getColorAt (

int $x, int $y

)

List of parameters:

Name	Type	Description
$x	int	horicontal position
$y	int	vertical position

Description:

This is an OO-style alias of PHP's imagecolorat() function. See the PHP manual for a full description.

This function returns bool(false) on error.

access: public

get color values (red,green,blue,alpha)

array|bool(false) getColorValues (

int $color

)

List of parameters:

Name	Type	Description
$color	int	a color resource

Description:

This is an OO-style alias of PHP's imagecolorsforindex() function. See the PHP manual for a full description.

Example:

$image = new Image();
print_r($image->getColorValues($image->white));

Will output:

Array
(
[red] => 255
[green] => 255
[blue] => 255
[alpha] => 0
)

access: public

get font width

int|bool(false) getFontHeight (

int $font

)

List of parameters:

Name	Type	Description
$font	int	a font resource

Description:

This is an OO-style alias of PHP's imagefontheight() function. See the PHP manual for a full description.

The argument $font determines the font type. The values 1-5 are used for a predefined system font. Where 1 is the smallest font-size and 5 is the largest. The font itself belongs to the sans-serif family. Note that you can load custom fonts using the PHP function imageloadfont().

This function is usefull to calculate how much space a string is going to take on the picture when using this font.

access: public

get font width

int|bool(false) getFontWidth (

int $font

)

List of parameters:

Name	Type	Description
$font	int	a font resource

Description:

This is an OO-style alias of PHP's imagefontheight() function. See the PHP manual for a full description.

This function is usefull to calculate how much space a string is going to take on the picture when using this font.

access: public

get image height

int|bool(false) getHeight ()

Description:

Returns the image's vertical dimension in pixel or bool(false) on error.

access: public

get current line width

int|bool(false) getLineWidth ()

Description:

Returns the current line width in pixel as an integer value.

Returns bool(false) on error.

access: public

get number of colors in palette

int|bool(false) getPaletteSize ()

Description:

Returns bool(false) on error.

For palette images the number of colors is the number of colors used in the current image. For truecolor images the maximum number of colors is returned, which is always 16 million.

Note that if you reduce the color depth using $image->reduceColorDepth($number), This function may NOT return $number, but instead the number of colors that are actually used in the image, which may be less then $number.

access: public

get filename

string getPath ()

Description:

access: public

get the image resource

resource|bool(false) getResource ()

Description:

This returns the image resource of the object, or bool(false) on error.

access: public

get image info

array getSize (

string $filename

)

List of parameters:

Name	Type	Description
$filename	string	relative file path

Description:

This is an OO-style alias of PHP's getimagesize() function. See the PHP manual for a full description.

The following two lines are equal:

$imgInfo = Image::getSize('foo.png');
$imgInfo = getimagesize('foo.png');

Just choose the style that you prefer.

access: public

get current transparency color

int|bool(false) getTransparency ()

Description:

Returns bool(false) on error.

access: public

get image width

int|bool(false) getWidth ()

Description:

Returns the image's horizontal dimension in pixel or bool(false) on error.

access: public

Check if image has alpha channel

bool hasAlpha ()

Description:

This returns bool(true) if alpha channel is turned on for the current image. Returns bool(false) otherwise.

Compatibility note: This function has been renamed in version 2.8.8 from "hasAlphaChannel()" to "hasAlpha()".

access: public

return true, if the image is broken

bool isBroken ()

Description:

Returns bool(true) if the image type was not recognized. Returns bool(false) otherwise.

access: public

Check if image is interlaced

bool isInterlaced ()

Description:

This returns bool(true) if interlacing is turned on for the current image. Returns bool(false) otherwise.

access: public

check if image is truecolor

bool isTruecolor ()

Description:

Returns bool(true) if the image is truecolor and bool(false) otherwise.

Truecolor images are e.g. JPEG images while GIF is not. Some functions won't work with non-truecolor images.

access: public

create a monochromatic image

bool monochromatic (

int $r, int $g, int $b

)

List of parameters:

Name	Type	Description
$r	int	red value
$g	int	green value
$b	int	blue value

Description:

This produces a monochromatic version of the image, shaded in the color provided.

The arguments $r, $g, $b can be any integer of 0 through 255.

Returns bool(true) on success and bool(false) on error.

access: public

multiply the palette values with a color

bool multiply (

int $r, int $g, int $b

)

List of parameters:

Name	Type	Description
$r	int	red value
$g	int	green value
$b	int	blue value

Description:

The color provided multiplies with each color in the palette. For example, this is usefull to filter colors.

Extract the green channel of an image:

$image->multiply(0, 255, 0);

Removing some red from an image will remove a red stitch and shift the colors towards a cold turquoise:

$image->multiply(200, 255, 255);

Shifting cold blue colors towards warm orange colors:

$image->multiply(255, 200, 150);

The arguments $r, $g, $b can be any integer of 0 through 255.

Returns bool(true) on success and bool(false) on error.

access: public

procude negative image

bool negate ()

Description:

This function negates all colors.

Returns bool(true) on success and bool(false) on error.

access: public

output image to a file

string|bool(false) outputToFile (

string $filename, [string $imageType = null]

)

List of parameters:

Name	Type	Description
$filename	string	name of the output file
$imageType	string	can be on of "png", "jpg", "gif", "bmp"

Description:

Returns the name of the output file on success and bool(false) on error.

You may leave off the file extension. If so the function will determine the correct extension by itself and append it automatically to the argument $filename.

If the file already exists, it will get replaced.

The optional argument $imageType can be used to set a prefered image type.

If no prefered image type is set, or the prefered image type is not available, then this function will automatically try to create a PNG image. If PNG is not available it will automatically try fall back to another type. PNG will fall back to JPEG, JPEG to GIF, GIF to BMP. Only if nothing of the above worked, it will give up and returns bool(false). Otherwise bool(true) is returned.

access: public

output image to browser

bool outputToScreen (

[string $imageType = null]

)

List of parameters:

Name	Type	Description
$imageType	string	can be on of "png", "jpg", "gif", "bmp"

Description:

Returns bool(true) on success and bool(false) on error.

The optional argument $imageType can be used to set a prefered image type.

If no prefered image type is set, or the prefered image type is not available, then this function will automatically try to create a PNG image. If PNG is not available it will automatically fall back. PNG will fall back to JPEG, JPEG to GIF, GIF to BMP. If nothing of the above worked it gives up and returns bool(false).

access: public

reduce color depth to value

bool reduceColorDepth (

int $ammount, [bool $dither = true]

)

List of parameters:

Name	Type	Description
$ammount	int	effect strength
$dither	bool	on / off

Description:

Returns bool(true) on success and bool(false) on error.

Reduces the color depth of the current image to $ammount colors. The argument $ammount is an integer 2 through 256.

The argument $dither triggers whether or not dithering is used while reducing the colors for the current image.

access: public

replace a color

bool replaceColor (

int $replacedColor, int $newColor

)

List of parameters:

Name	Type	Description
$replacedColor	int	index of replaced color
$newColor	int	index of the new color

Description:

This replaces the replaced color by a new color.

To be more technical, this is done by setting the replaced color as transparent, setting the new color as background and merging the results to a new image. Then reseting transparency and background color to the previously set values.

This may take some time - if you prefer a more performant solution, see Image::replaceIndexColor() instead.

Returns bool(true) on success and bool(false) on error.

see: Image::replaceIndexColor()
access: public

replace one palette color by another

bool replaceIndexColor (

int $replacedColor, array|int $newColor

)

List of parameters:

Name	Type	Description
$replacedColor	int	index of replaced color
$newColor	array\|int	the color that should be assigned

Description:

This replaces the palette color with the index $replacedColor by the color with the index $newColor. Note that $newColor can also be an associative array with the keys 'red', 'green' and 'blue'.

Returns bool(true) on success and bool(false) on error.

Note that this only works on palette (non-truecolor) images and thus returns false if the image is truecolor. Also note, that all images are converted to truecolor by default.

Examples:

$image->replaceIndexColor(0, $image->blue);
$array = $image->getColorValues($image->red);
$image->replaceIndexColor(1, $array);
$image->replaceIndexColor(2, array('red'=>0,'green'=>255,'blue'=>100));

access: public

Resize the image

bool resize (

[int $width = null], [int $height = null]

)

List of parameters:

Name	Type	Description
$width	int	horizontal dimension in pixel
$height	int	vertical dimension in pixel

Description:

This resizes the image to $width x $height.

You may set either $width or $height to NULL to get a proportional resize.

Returns bool(false) on error.

IMPORTANT NOTE: this function resets some settings. E.g. transparency, color depth a.s.o. will be lost.

access: public

Resize the canvas

bool resizeCanvas (

[int $width = null], [int $height = null], [int $paddingLeft = null], [int $paddingTop = null], [array $canvasColor = null]

)

List of parameters:

Name	Type	Description
$width	int	horizontal dimension in pixel
$height	int	vertical dimension in pixel
$paddingLeft	int	horizontal offset
$paddingTop	int	vertical offset
$canvasColor	array	array of red, green, yellow values (0 through 255) to identify the canvas color, defaults to background color

Description:

This resizes the canvas to $width x $height.

You may set either $width or $height to NULL to get a proportional resize. If $width or $height is smaller than the current value, the parts of the image that do not fit will get cut.

The $paddingLeft and $paddingTop parameters set left and top padding for the canvas. Setting both to 0 will position the left-top corner of the original image at the point (0, 0) on the new image. If the original image was bigger than the new, the parts at the right and the bottom the are outside the canvas will get cut. Note that you may use negative numbers here. Still you may not completely move the image outside the canvas.

If $left and/or $top are not provided, the image will get copied to the center of the canvas.

Examples:

// original image is 300x200px
// this will return true, but does nothing at all
$image->resizeCanvas(300);
// resize to 150x100px
$image->resizeCanvas(150);
// same effect
$image->resizeCanvas(null, 100);
// cut 20px off the top
// the image is centered horizontally
$image->resizeCanvas(null, null, null, -20);
// cut 50px off the left
// the image is centered vertically
$image->resizeCanvas(null, null, -50);
// cut 50px off the right
// the image is centered vertically
$image->resizeCanvas(null, null, 50);
// combination of all
$image->resizeCanvas(200, 100, 10, -5);
// these will return false
$image->resizeCanvas(0);
$image->resizeCanvas(-1);
// padding value out of range
$image->resizeCanvas(null, null, 301);
$image->resizeCanvas(null, null, 300);
$image->resizeCanvas(null, null, null, -200);

Returns bool(false) on error.

since: 2.8.8
access: public

Resize the image

bool resizeImage (

[int $width = null], [int $height = null]

)

List of parameters:

Name	Type	Description
$width	int	horizontal dimension in pixel
$height	int	vertical dimension in pixel

Description:

alias of Image::resize()

see: Image::resize()
since: 2.8.8
access: public

Rotate the image

bool rotate (

float $angle

)

List of parameters:

Name	Type	Description
$angle	float	angle of rotation in degree

Description:

This rotates the image anticlockwise by $angle degrees.

This function became available with PHP 4.3.

access: public

set current background color

bool setBackgroundColor (

[int $backgroundColor = null], [bool $replaceOldColor = true]

)

List of parameters:

Name	Type	Description
$backgroundColor	int	index of new background color
$replaceOldColor	bool

Description:

If you don't specify a background color, than the color is reset.

By default the background color will be set to the transparent color of the image if it has any. Otherwise it defaults to white.

If the argument $replaceOldColor is set to true, it will replace the all pixel of the previous background color with the new one. It it is set to false, the new background color will get appended and all pixel of the old color will remain as is.

Returns bool(true) on success and bool(false) on error.

access: public

set current brush

bool setBrush (

string|Image|Brush|resource $brush

)

List of parameters:

Name	Type	Description
$brush	string\|Image\|Brush\|resource	a brush resource

Description:

Sets the brush used by imageline(), imagepolygon() et cetera to the image $brush.

The argument $brush can be a filename of the image that you want to use as the brush to use, or another image object. In addition $brush may also be an image resource.

Returns bool(true) on success and bool(false) on error.

access: public

set gamma correction

bool setGamma (

float $gamma

)

List of parameters:

Name	Type	Description
$gamma	float	effect strength

Description:

Gamma can be any positive float 0.1 trough 10.0 The base is always 1.0 (100%). So e.g. calling setGamma(0.1) sets the gamma of the image to 10% and calling setGamma(2.0) sets the gamma to 200%. To reset the gamma value call setGamma(1.0).

This function only works on truecolor images.

Returns bool(true) on success and bool(false) on error.

access: public

set line style

bool setLineStyle ()

Description:

This is an OO-style alias of PHP's imagesetstyle() function. See the PHP manual for details.

Example:

$r = $image->red;
$w = $image->white;
// dotted line
$image->setLineStyle($r, $w);
// 3px dashed line
$image->setLineStyle($r, $r, $r, $w, $w, $w);

To reset the line style, call this function with no arguments.

access: public

set line width

bool setLineWidth (

int $width

)

List of parameters:

Name	Type	Description
$width	int	size in pixel

Description:

Sets the line width of the current brush to $width. The setting will apply to whatever you draw, until you call this function again.

Returns bool(true) on success and bool(false) on error.

access: public

set transparency to a color

bool setTransparency (

[int|array $transparency = null]

)

List of parameters:

Name	Type	Description
$transparency	int\|array	new transparent color

Description:

Returns bool(true) on success and bool(false) on error.

The $transparency color is an integer value, that you can get via the function Image::getColor().

In addition you may also use on of the predefined colors: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow.

Example:

$image = new Image();
$image->setTransparency($image->white);

If $transparency is not set, the current background color will be used instead.

access: public

sharpen the image

bool sharpen (

float $ammount

)

List of parameters:

Name	Type	Description
$ammount	float	effect strength

Description:

This sharpens the image. The argument $ammount is any float 0.0 through 1.0, which translates to 0% through 100%.

access: public

convert a colored image to grayscale

void toGrayscale ()

Description:

This converts the palette colors to gray values.

see: Image::toGrayscale()
access: public

alias of Image::toGrayscale()

void toGreyscale ()

Description:

see: Image::toGrayscale()
access: public

get a string representation of this object

string toString ()

Description:

This function is intended to be called when the object is used in a string context.

access: public

Redefinition of: Object::toString()

upload an image file

string|int uploadFile (

string $fromId, string $toFilename, [string $imageType = null], [int $maxSize = null], [int $width = null], [int $height = null], [bool $keepAspectRatio = true], [array $backgroundColor = null]

)

List of parameters:

Name	Type	Description
$fromId	string	identifier of the form-field from which the file has been sent
$toFilename	string	the path and filename to output the file to
$imageType	string	prefered type of the output file
$maxSize	int	maximum size of uploaded files in byte
$width	int	horizontal dimension of the output image in pixel
$height	int	vertical dimension of the output image in pixel
$keepAspectRatio	bool	vertical dimension of the output image in pixel
$backgroundColor	array	array of red, green, yellow values (0 through 255) to identify the background color, defaults to white

Description:

The purpose of this method is to handle an uploaded image.

The image is taken from the $_FILES array at the index provided by the argument $fromId ($_FILES[$fromId]). The argument is case-insensitive.

The method converts the image to the type given by the argument $imageType, which currently can be "gif", "png" or "jpg".

The image is resized to the dimensions given by the arguments $width x $height. If you set one of these to NULL, the other one will be determined automatically. If you leave booth to NULL, the image will not be resized at all.

The argument $keepAspectRatio triggers how the image is resized. If it is false, the image will be stretched or compressed to the dimensions of the output image. If it is true, will be resized proportionally and the canvas will expanded to the size of the output instead, if necessary.

When using the setting true (which is the default), you may provide a background color for the canvas using the argument $backgroundColor. To do so, provide an array with the red, green and yellow values. Example: array(255, 255, 255) is "white".

The converted and resized image is then copied to the path given by the argument $toFilename.

The method returns the name of the output file on success and an integer constant on error.

Possible error codes returned by this method are:

file upload failed => value of $_FILES[$fromId]['error']
uploaded file exceeds maximum file size => UPLOAD_ERR_SIZE
uploaded file is not a recognized image => UPLOAD_ERR_FILE_TYPE
unable to write to target directory => UPLOAD_ERR_INVALID_TARGET
misc. (unexpected) errors => UPLOAD_ERR_OTHER

You may leave off the file extension. If so the function will determine the correct extension by itself and append it automatically to the argument $filename.

If the file already exists, it will get replaced.

The optional argument $imageType can be used to set a prefered image type.

Example of usage:

HTML-Code:

<form method="POST" action="%PHP_SELF%" enctype="multipart/form-data">
...
Upload image: <input type="file" name="my_image" />
...
</form>

PHP-Code:

// get data from form field 'my_image'
$id = 'my_image';
// output to directory 'foo/bar/' using filename 'image'
// (extension will be determined automatically)
$file = 'foo/bar/image';
// output as png image
$type = 'png';
// limit upload to 150 kbyte
$size = 150000;
// resize to 150px x 200px
$width = 150;
$height = 200;
// leave aspect-ratio untouched
$ratio = true;
// set background color to gray
$color = array(80, 80, 80);
// call method
$result = Image::uploadFile($id, $file, $type, $size, $width, $height, $ratio, $color);
// check for errors
if (is_string($result)) {
print "The image was successfully uploaded to: ".$result;
} else {
switch ($result)
{
case UPLOAD_ERR_SIZE:
case UPLOAD_ERR_INI_SIZE:
case UPLOAD_ERR_FORM_SIZE:
die( "File too big!" );
break;
case UPLOAD_ERR_NO_FILE:
die( "No file has been uploaded!" );
break;
case UPLOAD_ERR_INVALID_TARGET:
die( "Unable to write to file: ".$file );
break;
case UPLOAD_ERR_FILE_TYPE:
die( "The file is not a recognized image!" );
break;
default:
die( "Some unexpected error occured!" );
break;
}
}

since: 2.8.9
access: public

inherited from base classes

Inherited From Object

Documentation generated on Sat, 03 Jan 2009 22:22:28 +0100 by phpDocumentor 1.4.0

yana author: Thomas Meyer Homepage: www.yanaframework.net