GraphicalFunctions

class \TYPO3\CMS\Core\Imaging\GraphicalFunctions

Standard graphical functions

Class contains a bunch of cool functions for manipulating graphics with GDlib/Freetype and ImageMagick. VERY OFTEN used with gifbuilder that extends this class and provides a TypoScript API to using these functions

Table of Contents

Properties

$addFrameSelection  : bool
If set, the frame pointer is appended to the filenames.
$alternativeOutputKey  : string
For debugging only.
$cmds  : array
$dontCheckForExistingTempFile  : bool
This flag should always be FALSE. If set TRUE, imageMagickConvert will always write a new file to the tempdir! Used for debugging.
$dontCompress  : bool
Prevents imageMagickConvert() from compressing the gif-files with self::gifCompress()
$filenamePrefix  : string
Filename prefix for images scaled in imageMagickConvert()
$gifExtension  : string
This should be changed to 'png' if you want this class to read/make PNG-files instead!
$h  : int
$IM_commands  : array
All ImageMagick commands executed is stored in this array for tracking. Used by the Install Tools Image section
$imageMagickConvert_forceFileNameBody  : string
Forcing the output filename of imageMagickConvert() to this value. However after calling imageMagickConvert() it will be set blank again.
$map  : string
$scalecmd  : string
ImageMagick scaling command; "-auto-orient -geometry" or "-auto-orient -sample". Used in makeText() and imageMagickConvert()
$setup  : array
This holds the operational setup.
$truecolorColors  : int
16777216 Colors is the maximum value for PNG, JPEG truecolor images (24-bit, 8-bit / Channel)
$w  : int
$workArea  : array
$allowedColorSpaceNames  : array
colorspace names allowed
$colMap  : array
Array mapping HTML color names to RGB values.
$colorspace  : string
defines the RGB colorspace to use
$csConvObj  : CharsetConverter
Charset conversion object:
$gdlibExtensions  : array
File formats supported by gdlib. This variable get's filled in "init" method
$im  : resource|GdImage
$im5fx_blurSteps  : string
Used by v5_blur() to simulate 10 continuous steps of blurring
$im5fx_sharpenSteps  : string
Used by v5_sharpen() to simulate 10 continuous steps of sharpening.
$imageFileExt  : array
Allowed file extensions perceived as images by TYPO3.
$jpegQuality  : int
$mayScaleUp  : bool
$OFFSET  : array
$pixelLimitGif  : int
This is the limit for the number of pixels in an image before it will be rendered as JPG instead of GIF/PNG
$processorEffectsEnabled  : bool
Enable ImageMagick effects, disabled by default as IM5+ effects slow down the image generation
$processorEnabled  : bool
Whether ImageMagick/GraphicsMagick is enabled or not
$saveAlphaLayer  : bool
Preserve the alpha transparency layer of read PNG images
$webImageExt  : array
Web image extensions (can be shown by a webbrowser)

Methods

__construct()  : mixed
Reads configuration information from $GLOBALS['TYPO3_CONF_VARS']['GFX'] and sets some values in internal variables.
addToMap()  : mixed
Adds an <area> tag to the internal variable $this->map which is used to accumulate the content for an ImageMap
adjust()  : mixed
Implements the "ADJUST" GIFBUILDER object
applyImageMagickToPHPGif()  : mixed
Applies an ImageMagick parameter to a GDlib image pointer resource by writing the resource to file, performing an IM operation upon it and reading back the result into the ImagePointer.
applyOffset()  : array
Applies offset value to coordinated in $cords.
autolevels()  : mixed
Apply auto-levels to input image pointer
cacheImageDimensions()  : bool
Caches the result of the getImageDimensions function into the database. Does not check if the file exists.
calcBBox()  : array
Calculates bounding box information for the TEXT GIFBUILDER object.
calcTextCordsForMap()  : array
Calculating the coordinates for a TEXT string on an image map. Used in an <area> tag
calcWordSpacing()  : array
Calculates the spacing and wordSpacing values
circleOffset()  : array
Creates some offset values in an array used to simulate a circularly applied outline around TEXT
combineExec()  : string
Executes an ImageMagick "combine" (or composite in newer times) on four filenames - $input, $overlay and $mask as input files and $output as the output filename (written to) Can be used for many things, mostly scaling and effects.
convertColor()  : array
Converts a "HTML-color" TypoScript datatype to RGB-values.
copyGifOntoGif()  : mixed
Copies two GDlib image pointers onto each other, using TypoScript configuration from $conf and the input $workArea definition.
copyImageOntoImage()  : mixed
Implements the "IMAGE" GIFBUILDER object, when the "mask" property is FALSE (using only $conf['file'])
crop()  : mixed
Implements the "CROP" GIFBUILDER object
destroy()  : mixed
Destroy internal image pointer, $this->im
fontResize()  : int
Function that finds the right fontsize that will render the textstring within a certain width
getCachedImageDimensions()  : array|bool
Fetches the cached image dimensions from the cache. Does not check if the image file exists.
getImageDimensions()  : array|null
Gets the input image dimensions.
getImageScale()  : array
Get numbers for scaling the image based on input
getTemporaryImageWithText()  : mixed
Creates error image based on gfx/notfound_thumb.png Requires GD lib enabled, otherwise it will exit with the three textstrings outputted as text. Outputs the image stream to browser and exits!
getTextScalFactor()  : int
Calculates and returns the niceText.scaleFactor
gif_or_jpg()  : string
Returns an image extension for an output image based on the number of pixels of the output and the file extension of the original file.
gifCompress()  : string
Compressing a GIF file if not already LZW compressed.
hexColor()  : string
Returns the HEX color value for an RGB color array
imagecopyresized()  : mixed
Alternative function for using the similar PHP function imagecopyresized(). Used for GD2 only.
imageCreateFromFile()  : resource
Creates a new GDlib image resource based on the input image filename.
imageMagickConvert()  : array|null
Converts $imagefile to another file in temp-dir of type $newExt (extension).
imageMagickExec()  : string
Executes an ImageMagick "convert" on two filenames, $input and $output using $params before them.
imageMagickIdentify()  : array|null
Call the identify command
ImageTTFBBoxWrapper()  : array
Wrapper for ImageTTFBBox
ImageTTFTextWrapper()  : mixed
Wrapper for ImageTTFText
ImageWrite()  : bool
Writes the input GDlib image pointer to file
imgTag()  : string
Returns Image Tag for input image information array.
IMparams()  : string
Creating ImageMagick parameters from TypoScript property
IMreduceColors()  : string
Reduce colors in image using IM and create a palette based image if possible (<=256 colors)
inputLevels()  : mixed
Apply input levels to input image pointer (increasing contrast)
makeBox()  : mixed
Implements the "BOX" GIFBUILDER object
makeEffect()  : mixed
Implements the "EFFECT" GIFBUILDER object The operation involves ImageMagick for applying effects
makeEllipse()  : mixed
Implements the "Ellipse" GIFBUILDER object Example Typoscript: file = GIFBUILDER file { XY = 200,200 format = jpg quality = 100 10 = ELLIPSE 10.dimensions = 100,100,50,50 10.color = red
makeEmboss()  : mixed
Implements the "EMBOSS" GIFBUILDER object / property for the TEXT object
makeOutline()  : mixed
Implements the "OUTLINE" GIFBUILDER object / property for the TEXT object
makeShadow()  : mixed
Implements the "SHADOW" GIFBUILDER object / property for the TEXT object The operation involves ImageMagick for combining.
makeText()  : mixed
Implements the "TEXT" GIFBUILDER object
maskImageOntoImage()  : mixed
Implements the "IMAGE" GIFBUILDER object, when the "mask" property is TRUE.
objPosition()  : array
Create an array with object position/boundaries based on input TypoScript configuration (such as the "align" property is used), the work area definition and $BB array
output()  : string
Writing the internal image pointer, $this->im, to file based on the extension of the input filename Used in GIFBUILDER Uses $this->setup['reduceColors'] for gif/png images and $this->setup['quality'] for jpg images to reduce size/quality if needed.
outputLevels()  : mixed
Apply output levels to input image pointer (decreasing contrast)
randomName()  : string
Returns a random filename prefixed with "temp_" and then 32 char md5 hash (without extension).
readPngGif()  : string|null
Returns filename of the png/gif version of the input file (which can be png or gif).
scale()  : mixed
Implements the "SCALE" GIFBUILDER object
setImageFileExt()  : void
setWorkArea()  : mixed
Implements the "WORKAREA" GIFBUILDER object when setting it Setting internal working area boundaries (->workArea)
SpacedImageTTFText()  : mixed
Printing text onto an image like the PHP function imageTTFText does but in addition it offers options for spacing of letters and words.
splitString()  : array
Splitting a string for ImageTTFBBox up into an array where each part has its own configuration options.
txtPosition()  : array
Calculates text position for printing the text onto the image based on configuration like alignment and workarea.
unifyColors()  : int
Unifies all colors given in the colArr color array to the first color in the array.
v5_blur()  : string
Returns the IM command for blurring with ImageMagick 5.
v5_sharpen()  : string
Returns the IM command for sharpening with ImageMagick 5 Uses $this->im5fx_sharpenSteps for translation of the factor to an actual command.
compensateFontSizeiBasedOnFreetypeDpi()  : float
Function to compensate for DPI resolution.
executeIdentifyCommandForImageFile()  : string|null
Internal function to execute an IM command fetching information on an image
generateCacheKeyForImageFile()  : string
Creates the key for the image dimensions cache for an image file.
generateStatusHashForImageFile()  : string
Creates the status hash to check whether a file has been changed.
getBreakSpace()  : int
Gets the break space for each new line.
getRenderedTextWidth()  : int
Gets the rendered text width
getWordPairsForLineBreak()  : array
Gets the word pairs used for automatic line breaks.
renderTTFText()  : mixed
Renders a regular text and takes care of a possible line break automatically.

Properties

$addFrameSelection

If set, the frame pointer is appended to the filenames.

public bool $addFrameSelection = true

$alternativeOutputKey

For debugging only.

public string $alternativeOutputKey = ''

Filenames will not be based on mtime and only filename (not path) will be used. This key is also included in the hash of the filename...

$cmds

public array $cmds = ['jpg' => '', 'jpeg' => '', 'gif' => '', 'png' => '']

$dontCheckForExistingTempFile

This flag should always be FALSE. If set TRUE, imageMagickConvert will always write a new file to the tempdir! Used for debugging.

public bool $dontCheckForExistingTempFile = false

$dontCompress

Prevents imageMagickConvert() from compressing the gif-files with self::gifCompress()

public bool $dontCompress = false

$filenamePrefix

Filename prefix for images scaled in imageMagickConvert()

public string $filenamePrefix = ''

$gifExtension

This should be changed to 'png' if you want this class to read/make PNG-files instead!

public string $gifExtension = 'gif'

$IM_commands

All ImageMagick commands executed is stored in this array for tracking. Used by the Install Tools Image section

public array $IM_commands = []

$imageMagickConvert_forceFileNameBody

Forcing the output filename of imageMagickConvert() to this value. However after calling imageMagickConvert() it will be set blank again.

public string $imageMagickConvert_forceFileNameBody = ''

$scalecmd

ImageMagick scaling command; "-auto-orient -geometry" or "-auto-orient -sample". Used in makeText() and imageMagickConvert()

public string $scalecmd = '-auto-orient -geometry'

$setup

This holds the operational setup.

public array $setup = []

Basically this is a TypoScript array with properties.

$truecolorColors

16777216 Colors is the maximum value for PNG, JPEG truecolor images (24-bit, 8-bit / Channel)

public int $truecolorColors = 16777215

$allowedColorSpaceNames

colorspace names allowed

protected array $allowedColorSpaceNames = ['CMY', 'CMYK', 'Gray', 'HCL', 'HSB', 'HSL', 'HWB', 'Lab', '…
Show the full value['CMY', 'CMYK', 'Gray', 'HCL', 'HSB', 'HSL', 'HWB', 'Lab', 'LCH', 'LMS', 'Log', 'Luv', 'OHTA', 'Rec601Luma', 'Rec601YCbCr', 'Rec709Luma', 'Rec709YCbCr', 'RGB', 'sRGB', 'Transparent', 'XYZ', 'YCbCr', 'YCC', 'YIQ', 'YCbCr', 'YUV']

$colMap

Array mapping HTML color names to RGB values.

protected array $colMap = ['aqua' => [0, 255, 255], 'black' => [0, 0, 0], 'blue' => [0…
Show the full value['aqua' => [0, 255, 255], 'black' => [0, 0, 0], 'blue' => [0, 0, 255], 'fuchsia' => [255, 0, 255], 'gray' => [128, 128, 128], 'green' => [0, 128, 0], 'lime' => [0, 255, 0], 'maroon' => [128, 0, 0], 'navy' => [0, 0, 128], 'olive' => [128, 128, 0], 'purple' => [128, 0, 128], 'red' => [255, 0, 0], 'silver' => [192, 192, 192], 'teal' => [0, 128, 128], 'yellow' => [255, 255, 0], 'white' => [255, 255, 255]]

$colorspace

defines the RGB colorspace to use

protected string $colorspace = 'RGB'

$gdlibExtensions

File formats supported by gdlib. This variable get's filled in "init" method

protected array $gdlibExtensions = []

$im5fx_blurSteps

Used by v5_blur() to simulate 10 continuous steps of blurring

protected string $im5fx_blurSteps = '1x2,2x2,3x2,4x3,5x3,5x4,6x4,7x5,8x5,9x5'

$im5fx_sharpenSteps

Used by v5_sharpen() to simulate 10 continuous steps of sharpening.

protected string $im5fx_sharpenSteps = '1x2,2x2,3x2,2x3,3x3,4x3,3x4,4x4,4x5,5x5'

$imageFileExt

Allowed file extensions perceived as images by TYPO3.

protected array $imageFileExt = ['gif', 'jpg', 'jpeg', 'png', 'tif', 'bmp', 'tga', 'pcx', 'ai', 'pdf', 'webp']

List should be set to 'gif,png,jpeg,jpg' if IM is not available.

$jpegQuality

protected int $jpegQuality = 85

$mayScaleUp

protected bool $mayScaleUp = true

$pixelLimitGif

This is the limit for the number of pixels in an image before it will be rendered as JPG instead of GIF/PNG

protected int $pixelLimitGif = 10000

$processorEffectsEnabled

Enable ImageMagick effects, disabled by default as IM5+ effects slow down the image generation

protected bool $processorEffectsEnabled = false

$processorEnabled

Whether ImageMagick/GraphicsMagick is enabled or not

protected bool $processorEnabled

$saveAlphaLayer

Preserve the alpha transparency layer of read PNG images

protected bool $saveAlphaLayer = false

$webImageExt

Web image extensions (can be shown by a webbrowser)

protected array $webImageExt = ['gif', 'jpg', 'jpeg', 'png']

Methods

__construct()

Reads configuration information from $GLOBALS['TYPO3_CONF_VARS']['GFX'] and sets some values in internal variables.

public __construct() : mixed

addToMap()

Adds an <area> tag to the internal variable $this->map which is used to accumulate the content for an ImageMap

public addToMap(array $cords, array $conf) : mixed

Parameters

$cords : array

Coordinates for a polygon image map as created by ->calcTextCordsForMap()

$conf : array

Configuration for "imgMap." property of a TEXT GIFBUILDER object.

Tags

see
makeText()
see
calcTextCordsForMap()

adjust()

Implements the "ADJUST" GIFBUILDER object

public adjust(resource &$im, array $conf) : mixed

Parameters

$im : resource

GDlib image pointer

$conf : array

TypoScript array with configuration for the GIFBUILDER object.

Tags

see
GifBuilder::make()
see
autoLevels()
see
outputLevels()
see
inputLevels()

applyImageMagickToPHPGif()

Applies an ImageMagick parameter to a GDlib image pointer resource by writing the resource to file, performing an IM operation upon it and reading back the result into the ImagePointer.

public applyImageMagickToPHPGif(resource &$im, string $command) : mixed

Parameters

$im : resource

The image pointer (reference)

$command : string

The ImageMagick parameters. Like effects, scaling etc.

applyOffset()

Applies offset value to coordinated in $cords.

public applyOffset(array $cords, array $OFFSET) : array

Basically the value of key 0/1 of $OFFSET is added to keys 0/1 of $cords

Parameters

$cords : array

Integer coordinates in key 0/1

$OFFSET : array

Offset values in key 0/1

Return values

array —

Modified $cords array

autolevels()

Apply auto-levels to input image pointer

public autolevels(resource &$im) : mixed

Parameters

$im : resource

GDlib Image Pointer

cacheImageDimensions()

Caches the result of the getImageDimensions function into the database. Does not check if the file exists.

public cacheImageDimensions(array $identifyResult) : bool

Parameters

$identifyResult : array

Result of the getImageDimensions function

Return values

bool —

always TRUE

calcBBox()

Calculates bounding box information for the TEXT GIFBUILDER object.

public calcBBox(array $conf) : array

Parameters

$conf : array

TypoScript array for the TEXT GIFBUILDER object

Tags

see
txtPosition()
see
GifBuilder::start()

Return values

array —

Array with three keys [0]/[1] being x/y and [2] being the bounding box array

calcTextCordsForMap()

Calculating the coordinates for a TEXT string on an image map. Used in an <area> tag

public calcTextCordsForMap(array $cords, array $offset, array $conf) : array

Parameters

$cords : array

Coordinates (from BBOX array)

$offset : array

Offset array

$conf : array

Configuration for "imgMap." property of a TEXT GIFBUILDER object.

Tags

see
makeText()
see
calcTextCordsForMap()

Return values

array

calcWordSpacing()

Calculates the spacing and wordSpacing values

public calcWordSpacing(array $conf[, int $scaleFactor = 1 ]) : array

Parameters

$conf : array

TypoScript array for the TEXT GIFBUILDER object

$scaleFactor : int = 1

TypoScript value from eg $conf['niceText.']['scaleFactor']

Tags

see
calcBBox()

Return values

array —

Array with two keys [0]/[1] being array($spacing,$wordSpacing)

circleOffset()

Creates some offset values in an array used to simulate a circularly applied outline around TEXT

public circleOffset(int $distance, int $iterations) : array

access private

Parameters

$distance : int

Distance

$iterations : int

Iterations.

Tags

see
makeOutline()

Return values

array

combineExec()

Executes an ImageMagick "combine" (or composite in newer times) on four filenames - $input, $overlay and $mask as input files and $output as the output filename (written to) Can be used for many things, mostly scaling and effects.

public combineExec(string $input, string $overlay, string $mask, string $output) : string

Parameters

$input : string

The relative to public web path image filepath, bottom file

$overlay : string

The relative to public web path image filepath, overlay file (top)

$mask : string

The relative to public web path image filepath, the mask file (grayscale)

$output : string

The relative to public web path image filepath, output filename (written to)

Return values

string

convertColor()

Converts a "HTML-color" TypoScript datatype to RGB-values.

public convertColor(string $string) : array

Default is 0,0,0

Parameters

$string : string

"HTML-color" data type string, eg. 'red', '#ffeedd' or '255,0,255'. You can also add a modifying operator afterwards. There are two options: "255,0,255 : 20" - will add 20 to values, result is "255,20,255". Or "255,0,255 : *1.23" which will multiply all RGB values with 1.23

Return values

array —

RGB values in key 0/1/2 of the array

copyGifOntoGif()

Copies two GDlib image pointers onto each other, using TypoScript configuration from $conf and the input $workArea definition.

public copyGifOntoGif(resource &$im, resource $cpImg, array $conf, array $workArea) : mixed

Parameters

$im : resource

GDlib image pointer, destination (bottom image)

$cpImg : resource

GDlib image pointer, source (top image)

$conf : array

TypoScript array with the properties for the IMAGE GIFBUILDER object. Only used for the "tile" property value.

$workArea : array

Work area

copyImageOntoImage()

Implements the "IMAGE" GIFBUILDER object, when the "mask" property is FALSE (using only $conf['file'])

public copyImageOntoImage(resource &$im, array $conf, array $workArea) : mixed

Parameters

$im : resource

GDlib image pointer

$conf : array

TypoScript array with configuration for the GIFBUILDER object.

$workArea : array

The current working area coordinates.

Tags

see
GifBuilder::make()
see
maskImageOntoImage()

crop()

Implements the "CROP" GIFBUILDER object

public crop(resource &$im, array $conf) : mixed

Parameters

$im : resource

GDlib image pointer

$conf : array

TypoScript array with configuration for the GIFBUILDER object.

Tags

see
GifBuilder::make()

fontResize()

Function that finds the right fontsize that will render the textstring within a certain width

public fontResize(array $conf) : int

Parameters

$conf : array

The TypoScript properties of the TEXT GIFBUILDER object

Tags

see
GifBuilder::start()

Return values

int —

The new fontSize

getCachedImageDimensions()

Fetches the cached image dimensions from the cache. Does not check if the image file exists.

public getCachedImageDimensions(string $filePath) : array|bool

Parameters

$filePath : string

Image file path, relative to public web path

Return values

array|bool —

an array where [0]/[1] is w/h, [2] is extension and [3] is the file name, or FALSE for a cache miss

getImageDimensions()

Gets the input image dimensions.

public getImageDimensions(string $imageFile) : array|null

Parameters

$imageFile : string

The image filepath

Tags

see
imageMagickConvert()
see
ContentObjectRenderer::getImgResource()

Return values

array|null —

Returns an array where [0]/[1] is w/h, [2] is extension and [3] is the filename.

getImageScale()

Get numbers for scaling the image based on input

public getImageScale(array $info, string $w, string $h, array $options) : array

Parameters

$info : array

Current image information: Width, Height etc.

$w : string

"required" width

$h : string

"required" height

$options : array

Options: Keys are like "maxW", "maxH", "minW", "minH

Tags

see
imageMagickConvert()

Return values

array

getTemporaryImageWithText()

Creates error image based on gfx/notfound_thumb.png Requires GD lib enabled, otherwise it will exit with the three textstrings outputted as text. Outputs the image stream to browser and exits!

public getTemporaryImageWithText(string $filename, string $textline1, string $textline2, string $textline3) : mixed

Parameters

$filename : string

Name of the file

$textline1 : string

Text line 1

$textline2 : string

Text line 2

$textline3 : string

Text line 3

Tags

throws
RuntimeException

getTextScalFactor()

Calculates and returns the niceText.scaleFactor

public getTextScalFactor(array $conf) : int

Parameters

$conf : array

TypoScript array for the TEXT GIFBUILDER object

Return values

int —

TypoScript value from eg $conf['niceText.']['scaleFactor']

gif_or_jpg()

Returns an image extension for an output image based on the number of pixels of the output and the file extension of the original file.

public gif_or_jpg(string $type, int $w, int $h) : string

For example: If the number of pixels exceeds $this->pixelLimitGif (normally 10000) then it will be a "jpg" string in return.

Parameters

$type : string

The file extension, lowercase.

$w : int

The width of the output image.

$h : int

The height of the output image.

Return values

string —

The filename, either "jpg" or "gif"/"png" (whatever $this->gifExtension is set to.)

gifCompress()

Compressing a GIF file if not already LZW compressed.

public static gifCompress(string $theFile, string $type) : string

This function is a workaround for the fact that ImageMagick and/or GD does not compress GIF-files to their minimum size (that is RLE or no compression used)

The function takes a file-reference, $theFile, and saves it again through GD or ImageMagick in order to compress the file GIF: If $type is not set, the compression is done with ImageMagick (provided that $GLOBALS['TYPO3_CONF_VARS']['GFX']['processor_path_lzw'] is pointing to the path of a lzw-enabled version of 'convert') else with GD (should be RLE-enabled!) If $type is set to either 'IM' or 'GD' the compression is done with ImageMagick and GD respectively PNG: No changes.

$theFile is expected to be a valid GIF-file! The function returns a code for the operation.

Parameters

$theFile : string

Filepath

$type : string

See description of function

Return values

string —

Returns "GD" if GD was used, otherwise "IM" if ImageMagick was used. If nothing done at all, it returns empty string.

hexColor()

Returns the HEX color value for an RGB color array

public hexColor(array $color) : string

Parameters

$color : array

RGB color array

Return values

string —

HEX color value

imagecopyresized()

Alternative function for using the similar PHP function imagecopyresized(). Used for GD2 only.

public imagecopyresized(resource &$dstImg, resource $srcImg, int $dstX, int $dstY, int $srcX, int $srcY, int $dstWidth, int $dstHeight, int $srcWidth, int $srcHeight) : mixed

OK, the reason for this stupid fix is the following story: GD1.x was capable of copying two images together and combining their palettes! GD2 is apparently not. With GD2 only the palette of the dest-image is used which mostly results in totally black images when trying to copy a color-ful image onto the destination. The GD2-fix is to

  1. Create a blank TRUE-COLOR image
  2. Copy the destination image onto that one
  3. Then do the actual operation; Copying the source (top image) onto that
  4. ... and return the result pointer.
  5. Reduce colors (if we do not, the result may become strange!) It works, but the resulting images is now a true-color PNG which may be very large. So, why not use 'imagetruecolortopalette ($im, TRUE, 256)' - well because it does NOT WORK! So simple is that.

Parameters

$dstImg : resource

Destination image

$srcImg : resource

Source image

$dstX : int

Destination x-coordinate

$dstY : int

Destination y-coordinate

$srcX : int

Source x-coordinate

$srcY : int

Source y-coordinate

$dstWidth : int

Destination width

$dstHeight : int

Destination height

$srcWidth : int

Source width

$srcHeight : int

Source height

imageCreateFromFile()

Creates a new GDlib image resource based on the input image filename.

public imageCreateFromFile(string $sourceImg) : resource

If it fails creating an image from the input file a blank gray image with the dimensions of the input image will be created instead.

Parameters

$sourceImg : string

Image filename

Return values

resource —

Image Resource pointer

imageMagickConvert()

Converts $imagefile to another file in temp-dir of type $newExt (extension).

public imageMagickConvert(string $imagefile[, string $newExt = '' ][, string $w = '' ][, string $h = '' ][, string $params = '' ][, string $frame = '' ][, array $options = [] ][, bool $mustCreate = false ]) : array|null

Parameters

$imagefile : string

The image filepath

$newExt : string = ''

New extension, eg. "gif", "png", "jpg", "tif". If $newExt is NOT set, the new imagefile will be of the original format. If newExt = 'WEB' then one of the web-formats is applied.

$w : string = ''

Width. $w / $h is optional. If only one is given the image is scaled proportionally. If an 'm' exists in the $w or $h and if both are present the $w and $h is regarded as the Maximum w/h and the proportions will be kept

$h : string = ''

Height. See $w

$params : string = ''

Additional ImageMagick parameters.

$frame : string = ''

Refers to which frame-number to select in the image. '' or 0 will select the first frame, 1 will select the next and so on...

$options : array = []

An array with options passed to getImageScale (see this function).

$mustCreate : bool = false

If set, then another image than the input imagefile MUST be returned. Otherwise you can risk that the input image is good enough regarding measures etc and is of course not rendered to a new, temporary file in typo3temp/. But this option will force it to.

Tags

see
getImageScale()
see
ContentObjectRenderer::getImgResource()
see
maskImageOntoImage()
see
copyImageOntoImage()
see
scale()

Return values

array|null —

[0]/[1] is w/h, [2] is file extension and [3] is the filename.

imageMagickExec()

Executes an ImageMagick "convert" on two filenames, $input and $output using $params before them.

public imageMagickExec(string $input, string $output, string $params[, int $frame = 0 ]) : string

Can be used for many things, mostly scaling and effects.

Parameters

$input : string

The relative to public web path image filepath, input file (read from)

$output : string

The relative to public web path image filepath, output filename (written to)

$params : string

ImageMagick parameters

$frame : int = 0

Optional, refers to which frame-number to select in the image. '' or 0

Return values

string —

The result of a call to PHP function "exec()

imageMagickIdentify()

Call the identify command

public imageMagickIdentify(string $imagefile) : array|null

Parameters

$imagefile : string

The relative to public web path image filepath

Return values

array|null —

Returns an array where [0]/[1] is w/h, [2] is extension, [3] is the filename and [4] the real image type identified by ImageMagick.

ImageTTFBBoxWrapper()

Wrapper for ImageTTFBBox

public ImageTTFBBoxWrapper(int $fontSize, int $angle, string $fontFile, string $string, array $splitRendering[, int $sF = 1 ]) : array

Parameters

$fontSize : int

(See argument for PHP function ImageTTFBBox())

$angle : int

(See argument for PHP function ImageTTFBBox())

$fontFile : string

(See argument for PHP function ImageTTFBBox())

$string : string

(See argument for PHP function ImageTTFBBox())

$splitRendering : array

Split-rendering configuration

$sF : int = 1

Scale factor

Return values

array —

Information array.

ImageTTFTextWrapper()

Wrapper for ImageTTFText

public ImageTTFTextWrapper(resource $im, int $fontSize, int $angle, int $x, int $y, int $color, string $fontFile, string $string, array $splitRendering[, int $sF = 1 ]) : mixed

Parameters

$im : resource

(See argument for PHP function imageTTFtext())

$fontSize : int

(See argument for PHP function imageTTFtext())

$angle : int

(See argument for PHP function imageTTFtext())

$x : int

(See argument for PHP function imageTTFtext())

$y : int

(See argument for PHP function imageTTFtext())

$color : int

(See argument for PHP function imageTTFtext())

$fontFile : string

(See argument for PHP function imageTTFtext())

$string : string

(See argument for PHP function imageTTFtext()). UTF-8 string, possibly with entities in.

$splitRendering : array

Split-rendering configuration

$sF : int = 1

Scale factor

ImageWrite()

Writes the input GDlib image pointer to file

public ImageWrite(resource $destImg, string $theImage[, int $quality = 0 ]) : bool

Parameters

$destImg : resource

The GDlib image resource pointer

$theImage : string

The filename to write to

$quality : int = 0

The image quality (for JPEGs)

Tags

see
maskImageOntoImage()
see
scale()
see
output()

Return values

bool —

The output of either imageGif, imagePng or imageJpeg based on the filename to write

imgTag()

Returns Image Tag for input image information array.

public imgTag(array $imgInfo) : string

Parameters

$imgInfo : array

Image information array, key 0/1 is width/height and key 3 is the src value

Return values

string —

Image tag for the input image information array.

IMparams()

Creating ImageMagick parameters from TypoScript property

public IMparams(string $setup) : string

Parameters

$setup : string

A string with effect keywords=value pairs separated by "|

Tags

see
makeEffect()

Return values

string —

ImageMagick prepared parameters.

IMreduceColors()

Reduce colors in image using IM and create a palette based image if possible (<=256 colors)

public IMreduceColors(string $file, int $cols) : string

Parameters

$file : string

Image file to reduce

$cols : int

Number of colors to reduce the image to.

Return values

string —

Reduced file

inputLevels()

Apply input levels to input image pointer (increasing contrast)

public inputLevels(resource &$im, int $low, int $high) : mixed

Parameters

$im : resource

GDlib Image Pointer

$low : int

The "low" value (close to 0)

$high : int

The "high" value (close to 255)

makeBox()

Implements the "BOX" GIFBUILDER object

public makeBox(resource &$im, array $conf, array $workArea) : mixed

Parameters

$im : resource

GDlib image pointer

$conf : array

TypoScript array with configuration for the GIFBUILDER object.

$workArea : array

The current working area coordinates.

Tags

see
GifBuilder::make()

makeEffect()

Implements the "EFFECT" GIFBUILDER object The operation involves ImageMagick for applying effects

public makeEffect(resource &$im, array $conf) : mixed

Parameters

$im : resource

GDlib image pointer

$conf : array

TypoScript array with configuration for the GIFBUILDER object.

Tags

see
GifBuilder::make()
see
applyImageMagickToPHPGif()

makeEllipse()

Implements the "Ellipse" GIFBUILDER object Example Typoscript: file = GIFBUILDER file { XY = 200,200 format = jpg quality = 100 10 = ELLIPSE 10.dimensions = 100,100,50,50 10.color = red

public makeEllipse(resource &$im, array $conf, array $workArea) : mixed

$workArea = X,Y $conf['dimensions'] = offset x, offset y, width of ellipse, height of ellipse

Parameters

$im : resource

GDlib image pointer

$conf : array

TypoScript array with configuration for the GIFBUILDER object.

$workArea : array

The current working area coordinates.

Tags

see
GifBuilder::make()

makeEmboss()

Implements the "EMBOSS" GIFBUILDER object / property for the TEXT object

public makeEmboss(resource &$im, array $conf, array $workArea, array $txtConf) : mixed

Parameters

$im : resource

GDlib image pointer

$conf : array

TypoScript array with configuration for the GIFBUILDER object.

$workArea : array

The current working area coordinates.

$txtConf : array

TypoScript array with configuration for the associated TEXT GIFBUILDER object.

Tags

see
GifBuilder::make()
see
makeShadow()

makeOutline()

Implements the "OUTLINE" GIFBUILDER object / property for the TEXT object

public makeOutline(resource &$im, array $conf, array $workArea, array $txtConf) : mixed

Parameters

$im : resource

GDlib image pointer

$conf : array

TypoScript array with configuration for the GIFBUILDER object.

$workArea : array

The current working area coordinates.

$txtConf : array

TypoScript array with configuration for the associated TEXT GIFBUILDER object.

Tags

see
GifBuilder::make()
see
makeText()

makeShadow()

Implements the "SHADOW" GIFBUILDER object / property for the TEXT object The operation involves ImageMagick for combining.

public makeShadow(resource &$im, array $conf, array $workArea, array $txtConf) : mixed

Parameters

$im : resource

GDlib image pointer

$conf : array

TypoScript array with configuration for the GIFBUILDER object.

$workArea : array

The current working area coordinates.

$txtConf : array

TypoScript array with configuration for the associated TEXT GIFBUILDER object.

Tags

see
GifBuilder::make()
see
makeText()
see
makeEmboss()

makeText()

Implements the "TEXT" GIFBUILDER object

public makeText(resource &$im, array $conf, array $workArea) : mixed

Parameters

$im : resource

GDlib image pointer

$conf : array

TypoScript array with configuration for the GIFBUILDER object.

$workArea : array

The current working area coordinates.

Tags

see
GifBuilder::make()

maskImageOntoImage()

Implements the "IMAGE" GIFBUILDER object, when the "mask" property is TRUE.

public maskImageOntoImage(resource &$im, array $conf, array $workArea) : mixed

It reads the two images defined by $conf['file'] and $conf['mask'] and copies the $conf['file'] onto the input image pointer image using the $conf['mask'] as a grayscale mask The operation involves ImageMagick for combining.

Parameters

$im : resource

GDlib image pointer

$conf : array

TypoScript array with configuration for the GIFBUILDER object.

$workArea : array

The current working area coordinates.

Tags

see
GifBuilder::make()

objPosition()

Create an array with object position/boundaries based on input TypoScript configuration (such as the "align" property is used), the work area definition and $BB array

public objPosition(array $conf, array $workArea, array $BB) : array

Parameters

$conf : array

TypoScript configuration for a GIFBUILDER object

$workArea : array

Workarea definition

$BB : array

BB (Bounding box) array. Not just used for TEXT objects but also for others

Tags

see
copyGifOntoGif()
see
makeBox()
see
crop()

Return values

array —

[0]=x, [1]=y, [2]=w, [3]=h

output()

Writing the internal image pointer, $this->im, to file based on the extension of the input filename Used in GIFBUILDER Uses $this->setup['reduceColors'] for gif/png images and $this->setup['quality'] for jpg images to reduce size/quality if needed.

public output(string $file) : string

Parameters

$file : string

The filename to write to.

Tags

see
GifBuilder::gifBuild()

Return values

string —

Returns input filename

outputLevels()

Apply output levels to input image pointer (decreasing contrast)

public outputLevels(resource &$im, int $low, int $high[, bool $swap = false ]) : mixed

Parameters

$im : resource

GDlib Image Pointer

$low : int

The "low" value (close to 0)

$high : int

The "high" value (close to 255)

$swap : bool = false

If swap, then low and high are swapped. (Useful for negated masks...)

randomName()

Returns a random filename prefixed with "temp_" and then 32 char md5 hash (without extension).

public randomName() : string

Used by functions in this class to create truly temporary files for the on-the-fly processing. These files will most likely be deleted right away.

Return values

string

readPngGif()

Returns filename of the png/gif version of the input file (which can be png or gif).

public static readPngGif(string $theFile[, bool $output_png = false ]) : string|null

If input file type does not match the wanted output type a conversion is made and temp-filename returned.

Parameters

$theFile : string

Filepath of image file

$output_png : bool = false

If TRUE, then input file is converted to PNG, otherwise to GIF

Return values

string|null —

If the new image file exists, its filepath is returned

scale()

Implements the "SCALE" GIFBUILDER object

public scale(resource &$im, array $conf) : mixed

Parameters

$im : resource

GDlib image pointer

$conf : array

TypoScript array with configuration for the GIFBUILDER object.

Tags

see
GifBuilder::make()

setImageFileExt()

public setImageFileExt(array $imageFileExt) : void

Parameters

$imageFileExt : array

setWorkArea()

Implements the "WORKAREA" GIFBUILDER object when setting it Setting internal working area boundaries (->workArea)

public setWorkArea(string $workArea) : mixed

Parameters

$workArea : string

Working area dimensions, comma separated

Tags

see
GifBuilder::make()

SpacedImageTTFText()

Printing text onto an image like the PHP function imageTTFText does but in addition it offers options for spacing of letters and words.

public SpacedImageTTFText(resource &$im, int $fontSize, int $angle, int $x, int $y, int $Fcolor, string $fontFile, string $text, int $spacing, int $wordSpacing, array $splitRenderingConf[, int $sF = 1 ]) : mixed

Spacing is done by printing one char at a time and this means that the spacing is rather uneven and probably not very nice. See

Parameters

$im : resource

(See argument for PHP function imageTTFtext())

$fontSize : int

(See argument for PHP function imageTTFtext())

$angle : int

(See argument for PHP function imageTTFtext())

$x : int

(See argument for PHP function imageTTFtext())

$y : int

(See argument for PHP function imageTTFtext())

$Fcolor : int

(See argument for PHP function imageTTFtext())

$fontFile : string

(See argument for PHP function imageTTFtext())

$text : string

(See argument for PHP function imageTTFtext()). UTF-8 string, possibly with entities in.

$spacing : int

The spacing of letters in pixels

$wordSpacing : int

The spacing of words in pixels

$splitRenderingConf : array

Array

$sF : int = 1

Scale factor

splitString()

Splitting a string for ImageTTFBBox up into an array where each part has its own configuration options.

public splitString(string $string, array $splitRendering, int $fontSize, string $fontFile) : array

Parameters

$string : string

UTF-8 string

$splitRendering : array

Split-rendering configuration from GIFBUILDER TEXT object.

$fontSize : int

Current fontsize

$fontFile : string

Current font file

Return values

array —

Array with input string splitted according to configuration

txtPosition()

Calculates text position for printing the text onto the image based on configuration like alignment and workarea.

public txtPosition(array $conf, array $workArea, array $BB) : array

Parameters

$conf : array

TypoScript array for the TEXT GIFBUILDER object

$workArea : array

Work area definition

$BB : array

Bounding box information, was set in \TYPO3\CMS\Frontend\Imaging\GifBuilder::start()

Tags

see
makeText()

Return values

array —

[0]=x, [1]=y, [2]=w, [3]=h

unifyColors()

Unifies all colors given in the colArr color array to the first color in the array.

public unifyColors(resource &$img, array $colArr[, bool $closest = false ]) : int

Parameters

$img : resource

Image resource

$colArr : array

Array containing RGB color arrays

$closest : bool = false

Return values

int —

The index of the unified color

v5_blur()

Returns the IM command for blurring with ImageMagick 5.

public v5_blur(int $factor) : string

Uses $this->im5fx_blurSteps for translation of the factor to an actual command.

Parameters

$factor : int

The blurring factor, 0-100 (effectively in 10 steps)

Tags

see
makeText()
see
IMparams()
see
v5_sharpen()

Return values

string —

The blurring command, eg. " -blur 3x4

v5_sharpen()

Returns the IM command for sharpening with ImageMagick 5 Uses $this->im5fx_sharpenSteps for translation of the factor to an actual command.

public v5_sharpen(int $factor) : string

Parameters

$factor : int

The sharpening factor, 0-100 (effectively in 10 steps)

Tags

see
makeText()
see
IMparams()
see
v5_blur()

Return values

string —

The sharpening command, eg. " -sharpen 3x4

compensateFontSizeiBasedOnFreetypeDpi()

Function to compensate for DPI resolution.

protected compensateFontSizeiBasedOnFreetypeDpi(float $fontSize) : float

FreeType 2 always has 96 dpi, so it is hard-coded at this place.

Parameters

$fontSize : float

font size for freetype function call

Return values

float —

compensated font size based on 96 dpi

executeIdentifyCommandForImageFile()

Internal function to execute an IM command fetching information on an image

protected executeIdentifyCommandForImageFile(string $imageFile) : string|null

Parameters

$imageFile : string

the absolute path to the image

Return values

string|null —

the raw result of the identify command.

generateCacheKeyForImageFile()

Creates the key for the image dimensions cache for an image file.

protected generateCacheKeyForImageFile(string $filePath) : string

This method does not check if the image file actually exists.

Parameters

$filePath : string

Image file path, relative to public web path

Return values

string —

the hash key (an SHA1 hash), will not be empty

generateStatusHashForImageFile()

Creates the status hash to check whether a file has been changed.

protected generateStatusHashForImageFile(string $filePath) : string

Parameters

$filePath : string

Image file path, relative to public web path

Return values

string —

the status hash (an SHA1 hash)

getBreakSpace()

Gets the break space for each new line.

protected getBreakSpace(array $conf[, array|null $boundingBox = null ]) : int

Parameters

$conf : array

TypoScript configuration for the currently rendered object

$boundingBox : array|null = null

The bounding box the the currently rendered object

Return values

int —

The break space

getRenderedTextWidth()

Gets the rendered text width

protected getRenderedTextWidth(string $text, array $conf) : int

Parameters

$text : string
$conf : array

Return values

int

getWordPairsForLineBreak()

Gets the word pairs used for automatic line breaks.

protected getWordPairsForLineBreak(string $string) : array

Parameters

$string : string

Return values

array

renderTTFText()

Renders a regular text and takes care of a possible line break automatically.

protected renderTTFText(resource &$im, int $fontSize, int $angle, int $x, int $y, int $color, string $fontFile, string $string, array $splitRendering, array $conf[, int $sF = 1 ]) : mixed

Parameters

$im : resource

(See argument for PHP function imageTTFtext())

$fontSize : int

(See argument for PHP function imageTTFtext())

$angle : int

(See argument for PHP function imageTTFtext())

$x : int

(See argument for PHP function imageTTFtext())

$y : int

(See argument for PHP function imageTTFtext())

$color : int

(See argument for PHP function imageTTFtext())

$fontFile : string

(See argument for PHP function imageTTFtext())

$string : string

(See argument for PHP function imageTTFtext()). UTF-8 string, possibly with entities in.

$splitRendering : array

Split-rendering configuration

$conf : array

The configuration

$sF : int = 1

Scale factor

On this page