Disegnare grafica vettoriale — forme, colori e stili di linea

In breve

Questa ricetta disegna primitive con riempimento e contorno: rettangoli, rettangoli arrotondati, cerchi, ellissi e linee. Per ciascuna imposta il colore di riempimento, il colore di contorno (tracciato) e lo spessore della linea. La ricetta segue examples/06-colors-and-drawing.php.

Ogni primitiva corrisponde, in ISO 32000-2, a un oggetto tracciato. Un oggetto tracciato è una forma costruita da segmenti di linea e di curva. Termina con un operatore di disegno che stabilisce se la forma viene tracciata, riempita o entrambe le cose.

Installazione

composer require nextpdf/core:^3

Non è richiesta alcuna estensione opzionale. L’API di disegno e colore è stabile dalla versione 1.0.0 e funziona nella matrice di backport 8.1–8.4.

Panoramica concettuale

Impostare prima lo stato, poi disegnare. setFillColor(), setDrawColor() e setLineWidth() aggiornano lo stato grafico. La chiamata successiva a rect(), circle(), ellipse(), roundedRect() o line() usa quello stato. I metodi delle forme accettano un argomento di stile: 'F' riempie, 'S' traccia (il valore predefinito) e 'DF'/'FD' eseguono entrambe le operazioni. Internamente, un rettangolo riempito è rappresentato dall’operatore di costruzione del tracciato re seguito dall’operatore di disegno di riempimento. ISO 32000-2 §8.5.3 specifica S per il tracciamento e f per il riempimento come principali operatori di disegno del tracciato.

I colori sono colori di dispositivo. setFillColor(r, g, b) seleziona DeviceRGB. ISO 32000-2 §8.6.4.3 definisce rg come operatore di colore DeviceRGB non di tracciamento e g come equivalente DeviceGray. Un setFillColor($v) con un solo argomento produce un livello di grigio. Lo spessore della linea ha valore predefinito 1.0 e il motivo del tratteggio, per impostazione predefinita, è una linea continua (§8.4.3.6).

Superficie dell’API

La superficie API è generata automaticamente da PHPDoc. Questa ricetta utilizza questi metodi:

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

Esempio di codice — Avvio rapido

<?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');

Esempio di codice — Produzione

Questo è l’esempio completo, pronto per l’harness. Rispetta NEXTPDF_COOKBOOK_OUTPUT e non aggiunge entropia propria.

<?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";

Casi limite e insidie

Lo stile predefinito è il tracciamento. Omettendo l’argomento di stile, la forma viene tracciata ('S'). Una forma che sembra invisibile di solito è disegnata senza un colore di contorno impostato, oppure è riempita con il colore di sfondo della pagina. Passare 'F' per riempirla.
Lo stato del colore persiste. setFillColor() rimane in vigore finché non viene modificato. Reimpostarlo (ad esempio, setFillColor(255)) prima del blocco successivo non correlato, altrimenti il colore si propaga.
Grigio e overload RGB. setFillColor(128) è un livello di grigio. setFillColor(128, 0, 0) è RGB. La chiamata con un solo argomento non significa «rosso 128».
Nell’API l’asse Y va dall’alto verso il basso. Gli helper di disegno usano l’origine in alto a sinistra del documento. Il motore la mappa automaticamente sullo spazio utente PDF con origine in basso a sinistra.

Prestazioni

Ogni primitiva è un piccolo gruppo di operatori del flusso di contenuto. Migliaia di forme per pagina rimangono ampiamente entro il budget di 2000 ms / 64 MB. Il costo cresce in modo lineare con il numero di primitive. Non avviene alcuna rasterizzazione, quindi l’output rimane vettoriale.

Note sulla sicurezza

Questa ricetta disegna solo la geometria specificata dal codice. Non analizza alcun input e non effettua alcun accesso di rete. Verificare l’intervallo di qualsiasi coordinata proveniente da dati non attendibili. Una verifica dell’intervallo impedisce a un valore ostile di spingere gli elementi grafici molto al di fuori della pagina.

Conformità

Dichiarazione	Specifica	Clausola
Un oggetto tracciato è composto da linee, rettangoli e curve di Bézier che terminano con un operatore di disegno.	ISO 32000-2	§8.5
`S` traccia e `f` riempie un tracciato.	ISO 32000-2	§8.5.3
`rg` imposta il colore non di tracciamento DeviceRGB; `g` imposta DeviceGray.	ISO 32000-2	§8.6.4.3
Il valore iniziale del motivo del tratteggio è `[] 0`, una linea continua.	ISO 32000-2	§8.4.3.6

Profilo di riproducibilità — strutturale. Il disegno vettoriale non ha alcuna entropia propria. Anche così, ogni documento salvato contiene un /ID nel trailer e atomi di data. ISO 32000-2 §8.3.4 afferma inoltre che la disposizione esatta degli operatori dello stato grafico non ha alcun significato semantico; pertanto un normalizzatore può riordinare uno stato equivalente. L’affermazione corretta è l’uguaglianza strutturale dopo la normalizzazione con qpdf. Questa ricetta descrive come NextPDF produce la struttura. Non dichiara la conformità a ISO 32000-2 come affermazione generalizzata.

Contesto commerciale

Non applicabile. Il disegno vettoriale è una funzionalità di Core senza alcuna limitazione Premium.