Dessiner des graphiques vectoriels — formes, couleurs et styles de ligne

En bref

Cette recette dessine des primitives remplies et tracées en contour : rectangles, rectangles arrondis, cercles, ellipses et lignes. Pour chacune d’elles, tu règles la couleur de remplissage, la couleur de contour (tracé) et la largeur de ligne. Cette recette suit examples/06-colors-and-drawing.php.

Chaque primitive correspond à un objet de tracé ISO 32000-2. Un objet de tracé est une forme construite à partir de segments de droites et de courbes. Il se termine par un opérateur de peinture qui indique si la forme est tracée en contour, remplie, ou les deux.

Installation

composer require nextpdf/core:^3

Aucune extension optionnelle n’est requise. L’API de dessin et de couleur est stable depuis la version 1.0.0, et elle fonctionne sur la matrice de backport 8.1–8.4.

Vue d’ensemble conceptuelle

Règle l’état, puis dessine. setFillColor(), setDrawColor() et setLineWidth() mettent à jour l’état graphique. L’appel suivant à rect(), circle(), ellipse(), roundedRect() ou line() consomme cet état. Les méthodes de forme acceptent un argument de style : 'F' remplit, 'S' trace le contour (la valeur par défaut), et 'DF'/'FD' effectue les deux. En interne, un rectangle rempli est représenté par l’opérateur de construction de tracé re suivi de l’opérateur de peinture de remplissage. ISO 32000-2 §8.5.3 spécifie S pour tracer le contour et f pour le remplissage comme principaux opérateurs de peinture de tracé.

Les couleurs utilisées sont des couleurs de périphérique. setFillColor(r, g, b) sélectionne DeviceRGB. ISO 32000-2 §8.6.4.3 définit rg comme l’opérateur de couleur de non-tracé DeviceRGB et g comme l’équivalent DeviceGray. Avec un seul argument, setFillColor($v) définit un niveau de gris. La largeur de ligne vaut 1.0 par défaut, et le motif de tirets correspond par défaut à une ligne pleine (§8.4.3.6).

Surface de l’API

La surface de l’API est générée automatiquement à partir du PHPDoc. Cette recette utilise ces méthodes :

rect(float $x, float $y, float $w, float $h, string $style = 'S'): static
roundedRect(float $x, float $y, float $w, float $h, float $r, string $style = 'S'): static
circle(float $x, float $y, float $r, string $style = 'S'): static
ellipse(float $x, float $y, float $rx, float $ry, string $style = 'S'): static
line(float $x1, float $y1, float $x2, float $y2): static
setFillColor(int $r, int $g = -1, int $b = -1): static / setDrawColor(...)
setLineWidth(float $width): static

Exemple de code — Démarrage rapide

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->setFillColor(30, 58, 138);
$doc->rect(20, 30, 60, 40, 'F');          // filled rectangle

$doc->setDrawColor(217, 119, 6);
$doc->setLineWidth(1.0);
$doc->circle(140, 50, 20, 'S');           // stroked circle

$doc->setLineWidth(0.3);
$doc->line(20, 90, 190, 90);              // thin rule

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/vector.pdf');

Exemple de code — Production

Voici l’exemple complet, prêt pour le harnais de test. Il respecte NEXTPDF_COOKBOOK_OUTPUT et n’ajoute aucune entropie propre.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Colors and Drawing');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Colors and Drawing', newLine: true);
$doc->ln(5);

// --- Filled rectangles: set fill colour, then draw with style 'F' ---
$palette = [
    [30, 58, 138], [217, 119, 6], [30, 27, 75],
    [239, 66, 35], [21, 128, 61],
];
$x = 15.0;
$rowY = $doc->getY();
foreach ($palette as [$r, $g, $b]) {
    $doc->setFillColor($r, $g, $b);
    $doc->rect($x, $rowY, 30, 20, 'F');
    $x += 35.0;
}
$doc->ln(28);

// --- Outlined shapes: set draw colour + line width, draw with 'S' ---
$doc->setDrawColor(30, 58, 138);
$doc->setLineWidth(0.5);
$y = $doc->getY();
$doc->rect(15, $y, 30, 25, 'S');
$doc->roundedRect(55, $y, 30, 25, 5, 'S');
$doc->circle(110, $y + 12.5, 12.5, 'S');
$doc->ellipse(150, $y + 12.5, 18, 10, 'S');
$doc->ln(33);

// --- Lines at three widths ---
$y = $doc->getY();
$doc->setDrawColor(0);
$doc->setLineWidth(0.2);
$doc->line(15, $y, 195, $y);
$doc->setLineWidth(0.8);
$doc->line(15, $y + 5, 195, $y + 5);
$doc->setLineWidth(1.5);
$doc->line(15, $y + 12, 195, $y + 12);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/vector.pdf';
$doc->save($out);

echo "Created vector.pdf\n";

Cas limites et pièges

Le style trace le contour par défaut. Si tu omets l’argument de style, la forme est tracée en contour ('S'). Une forme qui paraît invisible est généralement dessinée sans couleur de tracé définie, ou remplie avec la couleur d’arrière-plan de la page. Passe 'F' pour la remplir.
L’état de couleur persiste. setFillColor() reste en vigueur jusqu’à ce que tu le changes. Réinitialise-le (par exemple, setFillColor(255)) avant le prochain bloc sans rapport, sinon la couleur sera réutilisée.
Niveau de gris ou surcharge RVB. setFillColor(128) est un niveau de gris. setFillColor(128, 0, 0) est du RVB. La variante à un seul argument n’est pas « rouge 128 ».
L’axe Y va de haut en bas dans l’API. Les utilitaires de dessin utilisent le coin supérieur gauche du document comme origine. Le moteur la convertit pour toi vers l’espace utilisateur PDF, dont l’origine est en bas à gauche.

Performances

Chaque primitive se traduit par quelques opérateurs de flux de contenu. Des milliers de formes par page restent largement sous le budget de 2000 ms / 64 Mo. Le coût croît linéairement avec le nombre de primitives. Aucune rastérisation n’intervient, donc la sortie reste vectorielle.

Notes de sécurité

Cette recette dessine uniquement la géométrie que ton code spécifie. Elle n’analyse aucune entrée et n’effectue aucun accès réseau. Vérifie les bornes de toutes les coordonnées issues de données non fiables. Une vérification des bornes empêche une valeur hostile de placer des marques loin en dehors de la page.

Conformité

Affirmation	Spécification	Clause
Un objet de tracé est constitué de lignes, de rectangles et de courbes de Bézier se terminant par un opérateur de peinture.	ISO 32000-2	§8.5
`S` trace le contour et `f` remplit un tracé.	ISO 32000-2	§8.5.3
`rg` définit la couleur de non-tracé DeviceRGB ; `g` définit DeviceGray.	ISO 32000-2	§8.6.4.3
La valeur initiale du motif de tirets est `[] 0`, une ligne pleine.	ISO 32000-2	§8.4.3.6

Profil de reproductibilité — structurel. Le dessin vectoriel n’a aucune entropie propre. Malgré cela, chaque document enregistré porte un /ID de trailer et des atomes de date. ISO 32000-2 §8.3.4 indique aussi que l’agencement exact des opérateurs d’état graphique n’a aucune signification sémantique, donc un normaliseur peut réordonner un état équivalent. L’affirmation correcte est l’égalité structurelle après normalisation par qpdf. Cette recette décrit comment NextPDF produit la structure. Elle n’affirme pas la conformité ISO 32000-2 comme une revendication générale.

Contexte commercial

Sans objet. Le dessin vectoriel est une fonctionnalité du cœur, sans verrou Premium.