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 uses 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{jpg: string, jpeg: string, gif: string, png: string, webp: string}
$dontCheckForExistingTempFile  : bool
This flag should always be FALSE. If set TRUE, imageMagickConvert will always write a new file to the tempdir! Used for debugging.
$filenamePrefix  : string
Filename prefix for images scaled in imageMagickConvert()
$IM_commands  : array<int, array{0: string, 1: string}>
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.
$scalecmd  : non-empty-string
ImageMagick scaling command; "-auto-orient -geometry" or "-auto-orient -sample". Used in makeText() and imageMagickConvert()
$allowedColorSpaceNames  : array<int, non-empty-string>
colorspace names allowed
$colorspace  : non-empty-string
defines the RGB colorspace to use
$im5fx_blurSteps  : non-empty-string
Used by v5_blur() to simulate 10 continuous steps of blurring
$im5fx_sharpenSteps  : non-empty-string
Used by v5_sharpen() to simulate 10 continuous steps of sharpening.
$imageFileExt  : array<int, non-empty-string>
Allowed file extensions perceived as images by TYPO3.
$jpegQuality  : int<1, 100>
$mayScaleUp  : bool
$pixelLimitGif  : int<1, max>
This is the limit for the number of pixels in an image before it will be rendered as JPG instead of GIF/PNG
$processorEnabled  : bool
Whether ImageMagick/GraphicsMagick is enabled or not
$webImageExt  : array<int, non-empty-string>
Web image extensions (can be shown by a webbrowser)
$webpQuality  : int<1, 101>

Methods

__construct()  : mixed
Reads configuration information from $GLOBALS['TYPO3_CONF_VARS']['GFX'] and sets some values in internal variables.
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.
convert()  : ImageProcessingResult|null
A simple call to migrate a file to a different web-based file format. Let's say you want to convert a PDF to a PNG, use this method.
getImageDimensions()  : ImageProcessingResult|array<string|int, mixed>|null
Gets the input image dimensions.
getImageFileExt()  : array<string|int, mixed>
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.
imageMagickConvert()  : array<string|int, mixed>|null
Converts $imagefile to another file in temp-dir of type $targetFileExtension.
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
isProcessingEnabled()  : bool
mask()  : mixed
This applies an image onto the $inputFile with an additional backgroundImage for the mask
randomName()  : string
Returns a random filename prefixed with "temp_" and then 32 char md5 hash (without extension).
resize()  : ImageProcessingResult|null
Converts $sourceFile to another file in temp-dir of type $targetFileExtension.
setImageFileExt()  : void
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.
webpSupportAvailable()  : bool
convert -list format returns all formats, ideally with a line like this: "WEBP P rw- WebP Image Format (libwepb v1.3.2, ENCODER ABI 0x020F)" only if we have "rw" included, TYPO3 can fully support to read and write webp images.
executeIdentifyCommandForImageFile()  : string|null
Internal function to execute an IM command fetching information on an image
getColorspaceFromConfiguration()  : string
Returns the recommended colorspace for a processor or the one set in the configuration
modifyImageMagickStripProfileParameters()  : string
Modifies the parameters for ImageMagick for stripping of profile information.

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{jpg: string, jpeg: string, gif: string, png: string, webp: string} $cmds = ['jpg' => '', 'jpeg' => '', 'gif' => '', 'png' => '', 'webp' => '']

$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

$filenamePrefix

Filename prefix for images scaled in imageMagickConvert()

public string $filenamePrefix = ''

$IM_commands

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

public array<int, array{0: string, 1: string}> $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 non-empty-string $scalecmd = '-auto-orient -geometry'

$allowedColorSpaceNames

colorspace names allowed

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

$colorspace

defines the RGB colorspace to use

protected non-empty-string $colorspace = 'RGB'

$im5fx_blurSteps

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

protected non-empty-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 non-empty-string $im5fx_sharpenSteps = '1x2,2x2,3x2,2x3,3x3,4x3,3x4,4x4,4x5,5x5'

$imageFileExt

Allowed file extensions perceived as images by TYPO3.

protected array<int, non-empty-string> $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<1, 100> $jpegQuality = 85

$mayScaleUp

protected bool $mayScaleUp = true

$pixelLimitGif

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

protected int<1, max> $pixelLimitGif = 10000

$processorEnabled

Whether ImageMagick/GraphicsMagick is enabled or not

protected bool $processorEnabled

$webImageExt

Web image extensions (can be shown by a webbrowser)

protected array<int, non-empty-string> $webImageExt = ['gif', 'jpg', 'jpeg', 'png', 'webp']

$webpQuality

protected int<1, 101> $webpQuality = 85

Methods

__construct()

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

public __construct() : 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

convert()

A simple call to migrate a file to a different web-based file format. Let's say you want to convert a PDF to a PNG, use this method.

public convert(string $sourceFile[, string $targetFileExtension = 'web' ]) : ImageProcessingResult|null

If you want to also resize it, try "resize" instead.

Parameters
$sourceFile : string
$targetFileExtension : string = 'web'
Tags
see
resize()
Return values
ImageProcessingResult|null

getImageDimensions()

Gets the input image dimensions.

public getImageDimensions(string $imageFile[, bool $useResultObject = false ]) : ImageProcessingResult|array<string|int, mixed>|null
Parameters
$imageFile : string

The absolute image filepath

$useResultObject : bool = false
Tags
see
imageMagickConvert()
see
ContentObjectRenderer::getImgResource()
Return values
ImageProcessingResult|array<string|int, mixed>|null

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

getImageFileExt()

public getImageFileExt() : array<string|int, mixed>
Internal

Not part of TYPO3 Core API.

Return values
array<string|int, mixed>

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

imageMagickConvert()

Converts $imagefile to another file in temp-dir of type $targetFileExtension.

public imageMagickConvert(string $imagefile[, string $targetFileExtension = '' ][, 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

$targetFileExtension : string = ''

New image file extension. If $targetFileExtension is NOT set, the new imagefile will be of the original format. If set to = '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
ContentObjectRenderer::getImgResource()
see
GifBuilder::maskImageOntoImage()
see
GifBuilder::copyImageOntoImage()
see
GifBuilder::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.

isProcessingEnabled()

public isProcessingEnabled() : bool
Internal
Return values
bool

mask()

This applies an image onto the $inputFile with an additional backgroundImage for the mask

public mask(string $inputFile, string $outputFile, string $maskImage, string $maskBackgroundImage, string $params, array<string|int, mixed> $options) : mixed
Parameters
$inputFile : string
$outputFile : string
$maskImage : string
$maskBackgroundImage : string
$params : string
$options : array<string|int, mixed>
Internal

until API is finalized

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

resize()

Converts $sourceFile to another file in temp-dir of type $targetFileExtension.

public resize(string $sourceFile, string $targetFileExtension[, int|string $width = '' ][, int|string $height = '' ][, string $additionalParameters = '' ][, array<string|int, mixed> $options = [] ][, bool $forceCreation = false ]) : ImageProcessingResult|null
Parameters
$sourceFile : string

The absolute image filepath

$targetFileExtension : string

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

$width : int|string = ''

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

$height : int|string = ''

Height. See $width

$additionalParameters : string = ''

Additional ImageMagick parameters.

$options : array<string|int, mixed> = []

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

$forceCreation : 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.

Internal

until imageMagickConvert() is marked as deprecated.

Tags
see
ContentObjectRenderer::getImgResource()
see
maskImageOntoImage()
see
copyImageOntoImage()
see
GifBuilder::scale()
Return values
ImageProcessingResult|null

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.

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, e.g. " -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"

webpSupportAvailable()

convert -list format returns all formats, ideally with a line like this: "WEBP P rw- WebP Image Format (libwepb v1.3.2, ENCODER ABI 0x020F)" only if we have "rw" included, TYPO3 can fully support to read and write webp images.

public webpSupportAvailable() : bool
Internal
Return values
bool

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.

getColorspaceFromConfiguration()

Returns the recommended colorspace for a processor or the one set in the configuration

protected getColorspaceFromConfiguration() : string
Return values
string

modifyImageMagickStripProfileParameters()

Modifies the parameters for ImageMagick for stripping of profile information.

protected modifyImageMagickStripProfileParameters(string $parameters, array<string|int, mixed> $options) : string

Strips profile information of image to save some space ideally

Parameters
$parameters : string

The parameters to be modified (if required)

$options : array<string|int, mixed>
Return values
string

        
On this page

Search results