Signatur
Beschreibung
imageaffine() wendet eine affine Transformationsmatrix auf ein GD-Bild an und gibt das transformierte Ergebnis als neues GdImage-Objekt zurück. Affine Transformationen umfassen Operationen wie Translation (Verschiebung), Rotation, Skalierung, Scherung und beliebige Kombinationen davon, die in einer 2×3-Matrix codiert sind.
Die Transformationsmatrix wird als Array mit genau 6 Gleitkommazahlen übergeben, die den Einträgen einer 2×3-Transformationsmatrix entsprechen: [a0, a1, a2, a3, a4, a5]. Diese repräsentieren die Matrix: x' = a0*x + a2*y + a4 und y' = a1*x + a3*y + a5.
Mit dem optionalen Parameter clip kann ein rechteckiger Bereich des Quellbilds angegeben werden, auf den die Transformation beschränkt wird. Das Array muss die Schlüssel x, y, width und height enthalten. Wird null übergeben, wird das gesamte Bild transformiert.
Für häufige Sonderfälle wie Rotation oder Skalierung kann imageaffinematrixget() genutzt werden, um die passende Transformationsmatrix komfortabel zu berechnen. Mehrere Matrizen lassen sich mit imageaffinematrixconcat() kombinieren.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | GdImage | Das Quell-GdImage-Objekt, das transformiert werden soll. Wird typischerweise durch Funktionen wie imagecreatefromjpeg(), imagecreatetruecolor() o. Ä. erzeugt. |
|
| $affine Pflicht | array | Transformationsmatrix als numerisch indiziertes Array mit genau 6 Gleitkommazahlen [a0, a1, a2, a3, a4, a5], die die affine 2×3-Matrix beschreiben. |
|
| $clip | array|null | null | Optionaler Ausschnitt des Quellbilds, auf den die Transformation angewendet wird. Erwartet ein assoziatives Array mit den Schlüsseln x, y, width und height (alle als Integer). Bei null wird das gesamte Bild verwendet. |
Rückgabewert
GdImage-Objekt mit dem transformierten Bild zurück. Im Fehlerfall (z. B. ungültige Matrix) wird false zurückgegeben.Beispiele
Bild um 30 Grad rotieren mit imageaffine
<?php
// Originalbild laden
$src = imagecreatetruecolor(200, 200);
$blau = imagecolorallocate($src, 0, 0, 255);
imagefilledrectangle($src, 40, 40, 160, 160, $blau);
// Rotationsmatrix für 30 Grad berechnen
$matrix = imageaffinematrixget(IMG_AFFINE_ROTATE, 30);
// Affine Transformation anwenden
$rotiert = imageaffine($src, $matrix);
if ($rotiert !== false) {
// Transformiertes Bild als PNG ausgeben
header('Content-Type: image/png');
imagepng($rotiert);
imagedestroy($rotiert);
}
imagedestroy($src);Bild skalieren und auf einen Ausschnitt beschränken
<?php
// Quellbild erstellen
$src = imagecreatefrompng('beispiel.png');
// Skalierungsmatrix (Faktor 1.5 in X und Y)
$matrix = imageaffinematrixget(IMG_AFFINE_SCALE, ['x' => 1.5, 'y' => 1.5]);
// Nur den mittleren Bereich des Bildes transformieren
$clip = [
'x' => 50,
'y' => 50,
'width' => 100,
'height' => 100,
];
$skaliert = imageaffine($src, $matrix, $clip);
if ($skaliert !== false) {
header('Content-Type: image/png');
imagepng($skaliert);
imagedestroy($skaliert);
}
imagedestroy($src);Eigene Transformationsmatrix manuell definieren (Scherung)
<?php
$src = imagecreatetruecolor(150, 150);
$farbe = imagecolorallocate($src, 255, 100, 0);
imagefilledellipse($src, 75, 75, 100, 100, $farbe);
// Manuelle Scherungsmatrix: x-Richtung um 0.3 scheren
// [a0, a1, a2, a3, a4, a5]
// x' = 1*x + 0.3*y + 0
// y' = 0*x + 1*y + 0
$matrix = [1.0, 0.0, 0.3, 1.0, 0.0, 0.0];
$geschert = imageaffine($src, $matrix);
if ($geschert !== false) {
header('Content-Type: image/png');
imagepng($geschert);
imagedestroy($geschert);
}
imagedestroy($src);// Wichtig · Fallstricke
Speicherverwaltung: Das von imageaffine() zurückgegebene GdImage-Objekt belegt eigenen Speicher. Ab PHP 8.0 wird der Speicher durch den Destruktor des Objekts automatisch freigegeben; bei älteren PHP-Versionen sollte imagedestroy() explizit aufgerufen werden.
Matrixformat: Das Array affine muss genau 6 Elemente enthalten (Indizes 0–5). Fehlerhafte oder unvollständige Arrays führen zur Rückgabe von false. Zur komfortablen Erzeugung gängiger Matrizen empfiehlt sich imageaffinematrixget() mit den Konstanten IMG_AFFINE_TRANSLATE, IMG_AFFINE_SCALE, IMG_AFFINE_ROTATE, IMG_AFFINE_SHEAR_HORIZONTAL oder IMG_AFFINE_SHEAR_VERTICAL.
Bildgröße: Die Größe des zurückgegebenen Bilds hängt von der Transformation ab und kann sich vom Quellbild unterscheiden – insbesondere bei Rotationen, die das Bild vergrößern können.