imagefilledarc — Funktion · PHP-Referenz

Signatur

imagefilledarc(GdImage $image, int $center_x, int $center_y, int $width, int $height, int $start_angle, int $end_angle, int $color, int $style): bool

Beschreibung

imagefilledarc() zeichnet einen Bogenabschnitt einer Ellipse (oder eines Kreises, wenn $width === $height) auf das angegebene Bild und füllt ihn gemäß dem gewählten Stil. Der Bogen wird durch Mittelpunkt, Breite, Höhe sowie Start- und Endwinkel definiert, wobei 0° rechts liegt und die Winkel im Uhrzeigersinn zunehmen.

Der Parameter $style bestimmt, wie der Bogen ausgefüllt wird. Er kann eine Kombination (bitweise ODER) der Konstanten IMG_ARC_PIE, IMG_ARC_CHORD, IMG_ARC_NOFILL und IMG_ARC_EDGED sein. Damit lassen sich Tortenstücke, Segmente mit gerader Sehne oder reine Umrisse realisieren.

Typische Einsatzbereiche sind Tortendiagramme, Fortschrittsanzeigen in Kreisform oder dekorative grafische Elemente. Die Funktion arbeitet mit dem GD-Bildressourcen-Typ GdImage (ab PHP 8.0 Objekt, davor resource).

Farben und Stile müssen vorab mit imagecolorallocate() bzw. den IMG_ARC_*-Konstanten definiert werden. Sonderwerte wie IMG_COLOR_TRANSPARENT funktionieren ebenfalls als Füllfarbe.

Parameter

Name	Typ	Beschreibung
$image Pflicht	GdImage	Ein gültiges GD-Bildobjekt, wie es von Funktionen wie `imagecreatetruecolor()` oder `imagecreatefromjpeg()` zurückgegeben wird.
$center_x Pflicht	int	X-Koordinate des Mittelpunkts des Bogens in Pixeln (von links).
$center_y Pflicht	int	Y-Koordinate des Mittelpunkts des Bogens in Pixeln (von oben).
$width Pflicht	int	Gesamtbreite der Ellipse in Pixeln. Gleicher Wert wie `$height` ergibt einen Kreis.
$height Pflicht	int	Gesamthöhe der Ellipse in Pixeln.
$start_angle Pflicht	int	Startwinkel des Bogens in Grad (0° = rechts, Uhrzeigersinn). Negative Winkel werden unterstützt.
$end_angle Pflicht	int	Endwinkel des Bogens in Grad (0° = rechts, Uhrzeigersinn).
$color Pflicht	int	Füllfarbe als Farbbezeichner, erstellt mit `imagecolorallocate()` oder `imagecolorallocatealpha()`.
$style Pflicht	int	Füll- und Zeichenstil als bitweise Kombination der Konstanten: `IMG_ARC_PIE` (Tortenstück), `IMG_ARC_CHORD` (Sehne statt Radien), `IMG_ARC_NOFILL` (nur Umriss), `IMG_ARC_EDGED` (Radien bei `IMG_ARC_NOFILL`).

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültiges Bild-Objekt).

Beispiele

Einfaches Tortenstück (Pie-Segment)

<?php
// Bild erstellen
$image = imagecreatetruecolor(200, 200);

// Farben definieren
$white  = imagecolorallocate($image, 255, 255, 255);
$red    = imagecolorallocate($image, 220,  50,  50);
$border = imagecolorallocate($image,   0,   0,   0);

// Hintergrund weiß füllen
imagefill($image, 0, 0, $white);

// Ausgefülltes Tortenstück: 0° bis 120° (ein Drittel des Kreises)
imagefilledarc($image, 100, 100, 160, 160, 0, 120, $red, IMG_ARC_PIE);

// Bild als PNG ausgeben
header('Content-Type: image/png');
imagepng($image);
imagedestroy($image);

Tortendiagramm mit mehreren Segmenten

<?php
$image = imagecreatetruecolor(300, 300);
$bg    = imagecolorallocate($image, 240, 240, 240);
imagefill($image, 0, 0, $bg);

$cx = 150; $cy = 150; $diam = 250;

// Daten: Anteile in Prozent
$data = [
    ['value' => 40, 'color' => [230,  60,  60]],
    ['value' => 30, 'color' => [  60, 180,  60]],
    ['value' => 20, 'color' => [  60,  60, 220]],
    ['value' => 10, 'color' => [220, 180,   0]],
];

$startAngle = 0;
foreach ($data as $slice) {
    $endAngle = $startAngle + (int)round($slice['value'] * 360 / 100);
    [$r, $g, $b] = $slice['color'];
    $color = imagecolorallocate($image, $r, $g, $b);
    imagefilledarc($image, $cx, $cy, $diam, $diam, $startAngle, $endAngle, $color, IMG_ARC_PIE);
    $startAngle = $endAngle;
}

header('Content-Type: image/png');
imagepng($image);
imagedestroy($image);

Nur Bogenumriss mit Radien (NOFILL + EDGED)

<?php
$image = imagecreatetruecolor(200, 200);
$white = imagecolorallocate($image, 255, 255, 255);
$blue  = imagecolorallocate($image,   0,   0, 200);
imagefill($image, 0, 0, $white);

// Nur Umriss zeichnen: Bogen von 45° bis 270° mit Radien
imagefilledarc($image, 100, 100, 160, 160, 45, 270, $blue, IMG_ARC_NOFILL | IMG_ARC_EDGED);

header('Content-Type: image/png');
imagepng($image);
imagedestroy($image);

// Wichtig · Fallstricke

Winkelrichtung: Die Winkel werden im Uhrzeigersinn gemessen (abweichend von der mathematischen Konvention). 0° liegt rechts (3-Uhr-Position), 90° unten, 180° links, 270° oben.

Stil-Kombination: IMG_ARC_NOFILL | IMG_ARC_EDGED zeichnet nur den Umriss des Tortenstücks (Bogen + zwei Radien), ohne zu füllen — ideal für Vorschau oder overlay-Grafiken.

PHP 8.0: Ab PHP 8.0 erwartet die Funktion ein GdImage-Objekt statt einer alten resource. Code, der is_resource() auf das Bild prüft, muss angepasst werden.

Sonderstil IMG_ARC_CHORD: Dieser Stil verbindet Start- und Endpunkt des Bogens mit einer geraden Linie (Sehne) statt mit Radien. Kann mit IMG_ARC_NOFILL kombiniert werden.

Siehe auch

imagearc imageellipse imagefilledellipse imagecolorallocate imagecreatetruecolor