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<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.

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<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'

$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 = ''

$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

$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'

$gdlibExtensions

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

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

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<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
Tags
see
makeText()
see
calcTextCordsForMap()

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.

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<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
Tags
see
txtPosition()
see
GifBuilder::start()
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
Tags
see
makeText()
see
calcTextCordsForMap()
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
Tags
see
calcBBox()
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.

Tags
see
makeOutline()
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.

Tags
see
GifBuilder::make()
see
maskImageOntoImage()

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.

Tags
see
GifBuilder::make()

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
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<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

Tags
see
imageMagickConvert()
see
ContentObjectRenderer::getImgResource()
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
Tags
todo

in this method:

  • use real values for "cropH" and "cropV"
  • clean up "max" value to use a better naming, same as "crs"
  • we might just replace "0" and "1" with "width" and "height" for the sake of having it in place for the future.

see
imageMagickConvert()
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

Tags
throws
RuntimeException

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

  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

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.

Tags
see
getImageScale()
see
ContentObjectRenderer::getImgResource()
see
maskImageOntoImage()
see
copyImageOntoImage()
see
scale()
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)

Tags
see
maskImageOntoImage()
see
scale()
see
output()
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
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<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.

Tags
see
GifBuilder::make()

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.

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<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.

Tags
see
GifBuilder::make()

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.

Tags
see
GifBuilder::make()
see
makeShadow()

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.

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<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.

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

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.

Tags
see
GifBuilder::make()

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.

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<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
Tags
see
copyGifOntoGif()
see
makeBox()
see
crop()
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

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

GDlib image pointer

$conf : array<string|int, mixed>

TypoScript array with configuration for the GIFBUILDER object.

Tags
see
GifBuilder::make()

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
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<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
Tags
see
makeText()
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)

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

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


        
On this page

Search results