imagecropauto — Funktion · PHP-Referenz

Signatur

imagecropauto(GdImage $image, int $mode = IMG_CROP_DEFAULT, float $threshold = 0.5, int $color = -1): GdImage|false

Beschreibung

imagecropauto() analysiert ein Bild und entfernt automatisch Ränder oder einfarbige Bereiche, ohne dass die Koordinaten des Zuschneidebereichs manuell angegeben werden müssen. Die Funktion wählt den relevanten Bildinhalt anhand des gewählten $mode-Parameters aus.

Folgende Modi stehen zur Verfügung: IMG_CROP_DEFAULT (versucht zunächst Schwellenwert-basiertes Zuschneiden, fällt auf Weiß zurück), IMG_CROP_TRANSPARENT (entfernt transparente Randbereiche), IMG_CROP_BLACK (entfernt schwarze Ränder), IMG_CROP_WHITE (entfernt weiße Ränder), IMG_CROP_SIDES (bestimmt die Schnittfarbe anhand der Ecken des Bildes) und IMG_CROP_THRESHOLD (nutzt eine eigene Farbe und einen Schwellenwert).

Das Original-Bild wird nicht verändert; stattdessen wird ein neues GdImage-Objekt zurückgegeben, das nur den zugeschnittenen Bereich enthält. Dies macht die Funktion ideal für die Vorverarbeitung von hochgeladenen Bildern, bei denen unerwünschte einfarbige Ränder entfernt werden sollen.

Der Modus IMG_CROP_THRESHOLD erfordert die Angabe von $threshold und $color, um präzise zu steuern, welche Farbbereiche als Rand interpretiert werden.

Parameter

Name	Typ	Default	Beschreibung
$image Pflicht	GdImage		Das Quell-Bild als `GdImage`-Objekt, z. B. erstellt mit `imagecreatefromjpeg()` oder `imagecreatetruecolor()`.
$mode	int	IMG_CROP_DEFAULT	Der Zuschneidemodus. Mögliche Werte: `IMG_CROP_DEFAULT`, `IMG_CROP_TRANSPARENT`, `IMG_CROP_BLACK`, `IMG_CROP_WHITE`, `IMG_CROP_SIDES` oder `IMG_CROP_THRESHOLD`.
$threshold	float	0.5	Nur relevant bei `IMG_CROP_THRESHOLD`. Gibt den prozentualen Toleranzwert (0.0–100.0) an, innerhalb dessen eine Farbe noch als Randfarbe gilt.
$color	int	-1	Nur relevant bei `IMG_CROP_THRESHOLD`. Die Referenzfarbe als RGB-Wert (z. B. via `imagecolorallocate()`) oder `-1` für den automatischen Standard.

Rückgabewert

Typ

GdImage|false

Beschreibung

Gibt ein neues GdImage-Objekt mit dem zugeschnittenen Bildinhalt zurück. Gibt false zurück, wenn das Zuschneiden fehlschlägt oder kein Randbereich erkannt wurde (d. h. das Bild bereits perfekt zugeschnitten ist).

Beispiele

Weiße Ränder automatisch entfernen

<?php
// Bild laden
$original = imagecreatefrompng('bild_mit_weissem_rand.png');

// Weiße Ränder automatisch entfernen
$cropped = imagecropauto($original, IMG_CROP_WHITE);

if ($cropped !== false) {
    // Zugeschnittenes Bild speichern
    imagepng($cropped, 'bild_ohne_rand.png');
    imagedestroy($cropped);
    echo 'Bild erfolgreich zugeschnitten.';
} else {
    echo 'Kein Rand erkannt oder Fehler beim Zuschneiden.';
}

imagedestroy($original);

Bild erfolgreich zugeschnitten.

Transparente Ränder entfernen (z. B. PNG mit Alphakanal)

<?php
// Transparentes PNG laden
$original = imagecreatefrompng('logo_mit_transparenz.png');

// Transparente Ränder abschneiden
$cropped = imagecropauto($original, IMG_CROP_TRANSPARENT);

if ($cropped !== false) {
    // Alphakanal im Ziel-Bild beibehalten
    imagesavealpha($cropped, true);
    imagepng($cropped, 'logo_zugeschnitten.png');
    imagedestroy($cropped);
    echo 'Logo ohne transparente Ränder gespeichert.';
} else {
    echo 'Keine transparenten Ränder gefunden.';
}

imagedestroy($original);

Logo ohne transparente Ränder gespeichert.

Zuschneiden mit benutzerdefiniertem Schwellenwert

<?php
$original = imagecreatefromjpeg('produkt_foto.jpg');

// Hellgraue Hintergrundbereiche als Rand erkennen (nahezu weißes Grau)
$refColor = imagecolorallocate($original, 240, 240, 240);

// Schwellenwert 15% Toleranz
$cropped = imagecropauto($original, IMG_CROP_THRESHOLD, 15.0, $refColor);

if ($cropped !== false) {
    imagejpeg($cropped, 'produkt_zugeschnitten.jpg', 90);
    imagedestroy($cropped);
    echo 'Produkt-Foto zugeschnitten.';
} else {
    echo 'Kein Randbereich erkannt.';
}

imagedestroy($original);

Produkt-Foto zugeschnitten.

// Wichtig · Fallstricke

Rückgabe false bei fehlendem Rand: Wenn das Bild keinen erkennbaren Rand des angegebenen Typs hat, gibt die Funktion false zurück. Das ist kein Fehler, sondern das erwartete Verhalten — der Aufrufer sollte dies explizit prüfen und ggf. das Originalbild weiterverwenden.

Speicherverwaltung: Das zurückgegebene GdImage-Objekt ist ein eigenständiges neues Bild. Es sollte nach der Verwendung mit imagedestroy() freigegeben werden, um Speicherlecks zu vermeiden.

Alphakanal bei PNG: Wenn transparente Ränder entfernt werden, muss nach dem Zuschneiden imagesavealpha($cropped, true) aufgerufen werden, damit der Alphakanal beim Speichern erhalten bleibt.

Ab PHP 8.0: Der Parameter $image erwartet ein GdImage-Objekt. In PHP 7.x und früher war dies noch eine Ressource vom Typ gd.

Siehe auch

imagecrop imagecreatefrompng imagecreatefromjpeg imagesavealpha imagedestroy imagecolorallocate