TYPO3 12.4 API: GraphicalFunctions

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

Properties

$addFrameSelection : bool: If set, the frame pointer is appended to the filenames.
$alternativeOutputKey : string: For debugging only.
$cmds : array<string|int, mixed>
$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<string|int, mixed>: 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<string|int, mixed>: 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<string|int, mixed>
$allowedColorSpaceNames : array<string|int, mixed>: colorspace names allowed
$colMap : array<string|int, mixed>: Array mapping HTML color names to RGB values.
$colorspace : string: defines the RGB colorspace to use
$csConvObj : CharsetConverter: Charset conversion object:
$gdlibExtensions : array<string|int, mixed>: 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<string|int, mixed>: Allowed file extensions perceived as images by TYPO3.
$jpegQuality : int
$mayScaleUp : bool
$OFFSET : array<string|int, mixed>
$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<string|int, mixed>: 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<string|int, mixed>: 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<string|int, mixed>: Calculates bounding box information for the TEXT GIFBUILDER object.
calcTextCordsForMap() : array<string|int, mixed>: Calculating the coordinates for a TEXT string on an image map. Used in an <area> tag
calcWordSpacing() : array<string|int, mixed>: Calculates the spacing and wordSpacing values
circleOffset() : array<string|int, mixed>: 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<string|int, mixed>: 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<string|int, mixed>|bool: Fetches the cached image dimensions from the cache. Does not check if the image file exists.
getImageDimensions() : array<string|int, mixed>|null: Gets the input image dimensions.
getImageScale() : array<string|int, mixed>: 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 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<string|int, mixed>|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<string|int, mixed>|null: Call the identify command
ImageTTFBBoxWrapper() : array<string|int, mixed>: Wrapper for ImageTTFBBox
ImageTTFTextWrapper() : mixed: Wrapper for ImageTTFText
ImageWrite() : bool: Writes the input GDlib image pointer to file
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<string|int, mixed>: 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<string|int, mixed>: Splitting a string for ImageTTFBBox up into an array where each part has its own configuration options.
txtPosition() : array<string|int, mixed>: 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<string|int, mixed>: Gets the word pairs used for automatic line breaks.
renderTTFText() : mixed: Renders a regular text and takes care of a possible line break automatically.

$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<string|int, mixed>
    $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'

$h


    public
        int
    $h
     = 0

$IM_commands

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


    public
        array<string|int, mixed>
    $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
     = ''

$map


    public
        string
    $map
     = ''

$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<string|int, mixed>
    $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

$w


    public
        int
    $w
     = 0

$workArea


    public
        array<string|int, mixed>
    $workArea
     = []

$allowedColorSpaceNames

colorspace names allowed


    protected
        array<string|int, mixed>
    $allowedColorSpaceNames
     = ['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<string|int, mixed>
    $colMap
     = ['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'

$csConvObj

Charset conversion object:


    protected
        CharsetConverter
    $csConvObj

$gdlibExtensions

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


    protected
        array<string|int, mixed>
    $gdlibExtensions
     = []

$im


    protected
        resource|GdImage
    $im

$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<string|int, mixed>
    $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

$OFFSET


    protected
        array<string|int, mixed>
    $OFFSET

$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<string|int, mixed>
    $webImageExt
     = ['gif', 'jpg', 'jpeg', 'png']

__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<string|int, mixed> $cords, array<string|int, mixed> $conf) : mixed

Parameters

$cords : array<string|int, mixed>: Coordinates for a polygon image map as created by ->calcTextCordsForMap()
$conf : array<string|int, mixed>: Configuration for "imgMap." property of a TEXT GIFBUILDER object.

Internal

adjust()

Implements the "ADJUST" GIFBUILDER object


    public
                    adjust(resource &$im, array<string|int, mixed> $conf) : mixed

Parameters

$im : resource: GDlib image pointer
$conf : array<string|int, mixed>: TypoScript array with configuration for the GIFBUILDER object.

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<string|int, mixed> $cords, array<string|int, mixed> $OFFSET) : array<string|int, mixed>

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

Parameters

$cords : array<string|int, mixed>: Integer coordinates in key 0/1
$OFFSET : array<string|int, mixed>: Offset values in key 0/1

Return values

array<string|int, mixed> —

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<string|int, mixed> $identifyResult) : bool

Parameters

$identifyResult : array<string|int, mixed>: Result of the getImageDimensions function

Return values

bool —

always TRUE

calcBBox()

Calculates bounding box information for the TEXT GIFBUILDER object.


    public
                    calcBBox(array<string|int, mixed> $conf) : array<string|int, mixed>

Parameters

$conf : array<string|int, mixed>: TypoScript array for the TEXT GIFBUILDER object

Internal

Return values

array<string|int, mixed> —

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<string|int, mixed> $cords, array<string|int, mixed> $offset, array<string|int, mixed> $conf) : array<string|int, mixed>

Parameters

$cords : array<string|int, mixed>: Coordinates (from BBOX array)
$offset : array<string|int, mixed>: Offset array
$conf : array<string|int, mixed>: Configuration for "imgMap." property of a TEXT GIFBUILDER object.

Internal

Return values

array<string|int, mixed>

calcWordSpacing()

Calculates the spacing and wordSpacing values


    public
                    calcWordSpacing(array<string|int, mixed> $conf[, int $scaleFactor = 1 ]) : array<string|int, mixed>

Parameters

$conf : array<string|int, mixed>: TypoScript array for the TEXT GIFBUILDER object
$scaleFactor : int = 1: TypoScript value from eg $conf['niceText.']['scaleFactor']

Internal

Return values

array<string|int, mixed> —

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<string|int, mixed>

access private

Parameters

$distance : int: Distance
$iterations : int: Iterations.

Return values

array<string|int, mixed>

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<string|int, mixed>

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<string|int, mixed> —

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<string|int, mixed> $conf, array<string|int, mixed> $workArea) : mixed

Parameters

$im : resource: GDlib image pointer, destination (bottom image)
$cpImg : resource: GDlib image pointer, source (top image)
$conf : array<string|int, mixed>: TypoScript array with the properties for the IMAGE GIFBUILDER object. Only used for the "tile" property value.
$workArea : array<string|int, mixed>: Work area

Internal

copyImageOntoImage()

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


    public
                    copyImageOntoImage(resource &$im, array<string|int, mixed> $conf, array<string|int, mixed> $workArea) : mixed

Parameters

$im : resource: GDlib image pointer
$conf : array<string|int, mixed>: TypoScript array with configuration for the GIFBUILDER object.
$workArea : array<string|int, mixed>: The current working area coordinates.

crop()

Implements the "CROP" GIFBUILDER object


    public
                    crop(resource &$im, array<string|int, mixed> $conf) : mixed

Parameters

$im : resource: GDlib image pointer
$conf : array<string|int, mixed>: TypoScript array with configuration for the GIFBUILDER object.

destroy()

Destroy internal image pointer, $this->im


    public
                    destroy() : mixed

fontResize()

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


    public
                    fontResize(array<string|int, mixed> $conf) : int

Parameters

$conf : array<string|int, mixed>: The TypoScript properties of the TEXT GIFBUILDER object

Internal

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<string|int, mixed>|bool

Parameters

$filePath : string: The absolute image file path

Return values

array<string|int, mixed>|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<string|int, mixed>|null

Parameters

$imageFile : string: The absolute image filepath

Return values

array<string|int, mixed>|null —

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

getImageScale()

Get numbers for scaling the image based on input.


    public
                    getImageScale(array<string|int, mixed> $info, string $w, string $h, array<string|int, mixed> $options) : array<string|int, mixed>

Notes by Benni in 2023 in order to understand this magic:

Relevant if an image should be

scaled
cropped
keep the aspect ratio while scaling?
use a target width or height
or rather have a minimum or maximum width and/or height

This method does a lot of magic:

$info contains [0] = width and [1] the width of an original image for example.
$w and $h are the width and height that are originally required the image to be like when scaled. They could contain a "c" for cropping information or "m" for "Ensure that even though $w and $h are given, one containing an $m that we keep the aspect ratio." "m" really allows to say $w="50c" that this might in a result with [0]=100 because $w would follow $h in order to keep aspect ratio. Obviously this only works properly if both m and c are working
$options contain "maxW" (never go beyond this width, even if scaling larger as this), same with "maxH" and "minW" and "minH"

The return values are a bit tricky to understand, so I added a few tests:

AFAICS "0" and "1" are always used as "these are the target width / height" which my image should be scaled to, or cropped down to. Notes: If you hand in $info[0] and $info[1] a "0", you will get "0" as return value back! but
"crs" if the image should be cropped (which is indicated by one of $w or $h contain the "c" at the end)
"cropH" and "cropV" is also set when one of the incoming $w or $h contains a "c". Notes: "cropH" and "cropV" are rather cryptic, and can't really be used outside of this context. They are then "magically calculated" outside of this function $offsetX = (int)(($data[0] - $data['origW']) * ($data['cropH'] + 100) / 200); $offsetY = (int)(($data[1] - $data['origH']) * ($data['cropV'] + 100) / 200);
"origW" / "origH" seems to be the values that were handed in as $w and $h, but they might be altered f.e. "origH" is set when $w is given and $options["maxH"]
When such a rearranging calculation was made ("maxH" reduces the original $w due to constraints), then the return value "max" is set.
When using the "c" argument, origH and origW seem to contain the values that you would expect when NOT doing a crop scenario whereas [0] and [1] contain the target width and height that could be larger than originally requested.

Parameters

$info : array<string|int, mixed>: Current image information: Width, Height etc.
$w : string: "required" width
$h : string: "required" height
$options : array<string|int, mixed>: Options: Keys are like "maxW", "maxH", "minW", "minH"

Internal

Return values

array<string|int, mixed> —

keys "0" and "1" explain the target width and height that should be adopted, but can be null

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

getTextScalFactor()

Calculates and returns the niceText.scaleFactor


    public
                    getTextScalFactor(array<string|int, mixed> $conf) : int

Parameters

$conf : array<string|int, mixed>: TypoScript array for the TEXT GIFBUILDER object

Internal

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 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 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<string|int, mixed> $color) : string

Parameters

$color : array<string|int, mixed>: 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

Create a blank TRUE-COLOR image
Copy the destination image onto that one
Then do the actual operation; Copying the source (top image) onto that
... and return the result pointer.
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

Internal

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<string|int, mixed> $options = [] ][, bool $mustCreate = false ]) : array<string|int, mixed>|null

Parameters

$imagefile : string: The absolute 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<string|int, mixed> = []: 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.

Return values

array<string|int, mixed>|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<string|int, mixed>|null

Parameters

$imagefile : string: The relative to public web path image filepath

Return values

array<string|int, mixed>|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<string|int, mixed> $splitRendering[, int $sF = 1 ]) : array<string|int, mixed>

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<string|int, mixed>: Split-rendering configuration
$sF : int = 1: Scale factor

Return values

array<string|int, mixed> —

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<string|int, mixed> $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<string|int, mixed>: 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 absolute file path to write to
$quality : int = 0: The image quality (for JPEGs)

Return values

bool —

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

IMparams()

Creating ImageMagick parameters from TypoScript property


    public
                    IMparams(string $setup) : string

Parameters

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

Internal

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<string|int, mixed> $conf, array<string|int, mixed> $workArea) : mixed

Parameters

$im : resource: GDlib image pointer
$conf : array<string|int, mixed>: TypoScript array with configuration for the GIFBUILDER object.
$workArea : array<string|int, mixed>: The current working area coordinates.

makeEffect()

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


    public
                    makeEffect(resource &$im, array<string|int, mixed> $conf) : mixed

Parameters

$im : resource: GDlib image pointer
$conf : array<string|int, mixed>: TypoScript array with configuration for the GIFBUILDER object.

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<string|int, mixed> $conf, array<string|int, mixed> $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<string|int, mixed>: TypoScript array with configuration for the GIFBUILDER object.
$workArea : array<string|int, mixed>: The current working area coordinates.

makeEmboss()

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


    public
                    makeEmboss(resource &$im, array<string|int, mixed> $conf, array<string|int, mixed> $workArea, array<string|int, mixed> $txtConf) : mixed

Parameters

$im : resource: GDlib image pointer
$conf : array<string|int, mixed>: TypoScript array with configuration for the GIFBUILDER object.
$workArea : array<string|int, mixed>: The current working area coordinates.
$txtConf : array<string|int, mixed>: TypoScript array with configuration for the associated TEXT GIFBUILDER object.

makeOutline()

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


    public
                    makeOutline(resource &$im, array<string|int, mixed> $conf, array<string|int, mixed> $workArea, array<string|int, mixed> $txtConf) : mixed

Parameters

$im : resource: GDlib image pointer
$conf : array<string|int, mixed>: TypoScript array with configuration for the GIFBUILDER object.
$workArea : array<string|int, mixed>: The current working area coordinates.
$txtConf : array<string|int, mixed>: TypoScript array with configuration for the associated TEXT GIFBUILDER object.

makeShadow()

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


    public
                    makeShadow(resource &$im, array<string|int, mixed> $conf, array<string|int, mixed> $workArea, array<string|int, mixed> $txtConf) : mixed

Parameters

$im : resource: GDlib image pointer
$conf : array<string|int, mixed>: TypoScript array with configuration for the GIFBUILDER object.
$workArea : array<string|int, mixed>: The current working area coordinates.
$txtConf : array<string|int, mixed>: TypoScript array with configuration for the associated TEXT GIFBUILDER object.

makeText()

Implements the "TEXT" GIFBUILDER object


    public
                    makeText(resource &$im, array<string|int, mixed> $conf, array<string|int, mixed> $workArea) : mixed

Parameters

$im : resource: GDlib image pointer
$conf : array<string|int, mixed>: TypoScript array with configuration for the GIFBUILDER object.
$workArea : array<string|int, mixed>: The current working area coordinates.

maskImageOntoImage()

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


    public
                    maskImageOntoImage(resource &$im, array<string|int, mixed> $conf, array<string|int, mixed> $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<string|int, mixed>: TypoScript array with configuration for the GIFBUILDER object.
$workArea : array<string|int, mixed>: The current working area coordinates.

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<string|int, mixed> $conf, array<string|int, mixed> $workArea, array<string|int, mixed> $BB) : array<string|int, mixed>

Parameters

$conf : array<string|int, mixed>: TypoScript configuration for a GIFBUILDER object
$workArea : array<string|int, mixed>: Workarea definition
$BB : array<string|int, mixed>: BB (Bounding box) array. Not just used for TEXT objects but also for others

Internal

Return values

array<string|int, mixed> —

[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 absolute filename to write to

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<string|int, mixed> $conf) : mixed

Parameters

$im : resource: GDlib image pointer
$conf : array<string|int, mixed>: TypoScript array with configuration for the GIFBUILDER object.

setImageFileExt()


    public
                    setImageFileExt(array<string|int, mixed> $imageFileExt) : void

Parameters

$imageFileExt : array<string|int, mixed>

Internal

Only used for ext:install, not part of TYPO3 Core API.

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

Internal

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<string|int, mixed> $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<string|int, mixed>: Array
$sF : int = 1: Scale factor

Internal

splitString()

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


    public
                    splitString(string $string, array<string|int, mixed> $splitRendering, int $fontSize, string $fontFile) : array<string|int, mixed>

Parameters

$string : string: UTF-8 string
$splitRendering : array<string|int, mixed>: Split-rendering configuration from GIFBUILDER TEXT object.
$fontSize : int: Current fontsize
$fontFile : string: Current font file

Return values

array<string|int, mixed> —

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<string|int, mixed> $conf, array<string|int, mixed> $workArea, array<string|int, mixed> $BB) : array<string|int, mixed>

Parameters

$conf : array<string|int, mixed>: TypoScript array for the TEXT GIFBUILDER object
$workArea : array<string|int, mixed>: Work area definition
$BB : array<string|int, mixed>: Bounding box information, was set in \TYPO3\CMS\Frontend\Imaging\GifBuilder::start()

Internal

Return values

array<string|int, mixed> —

[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<string|int, mixed> $colArr[, bool $closest = false ]) : int

Parameters

$img : resource: Image resource
$colArr : array<string|int, mixed>: 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)

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)

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: Absolute image file 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: Absolute image file path

Return values

string —

the status hash (an SHA1 hash)

getBreakSpace()

Gets the break space for each new line.


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

Parameters

$conf : array<string|int, mixed>: TypoScript configuration for the currently rendered object
$boundingBox : array<string|int, mixed>|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<string|int, mixed> $conf) : int

Parameters

$text : string
$conf : array<string|int, mixed>

Return values

int

getWordPairsForLineBreak()

Gets the word pairs used for automatic line breaks.


    protected
                    getWordPairsForLineBreak(string $string) : array<string|int, mixed>

Parameters

$string : string

Return values

array<string|int, mixed>

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<string|int, mixed> $splitRendering, array<string|int, mixed> $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<string|int, mixed>: Split-rendering configuration
$conf : array<string|int, mixed>: The configuration
$sF : int = 1: Scale factor

GraphicalFunctions

Table of Contents

Properties

Methods

Properties

$addFrameSelection

$alternativeOutputKey

$cmds

$dontCheckForExistingTempFile

$dontCompress

$filenamePrefix

$gifExtension

$h

$IM_commands

$imageMagickConvert_forceFileNameBody

$map

$scalecmd

$setup

$truecolorColors

$w

$workArea

$allowedColorSpaceNames

$colMap

$colorspace

$csConvObj

$gdlibExtensions

$im

$im5fx_blurSteps

$im5fx_sharpenSteps

$imageFileExt

$jpegQuality

$mayScaleUp

$OFFSET

$pixelLimitGif

$processorEffectsEnabled

$processorEnabled

$saveAlphaLayer

$webImageExt

Methods

__construct()

addToMap()

Parameters

Tags

adjust()

Parameters

Tags

applyImageMagickToPHPGif()

Parameters

applyOffset()

Parameters

Return values

autolevels()

Parameters

cacheImageDimensions()

Parameters

Return values

calcBBox()

Parameters

Tags

Return values

calcTextCordsForMap()

Parameters

Tags

Return values

calcWordSpacing()

Parameters

Tags

Return values

circleOffset()

Parameters

Tags

Return values

combineExec()

Parameters

Return values

convertColor()

Parameters

Return values

copyGifOntoGif()

Parameters