De coördinatenruimte transformeren: roteren, schalen, schuintrekken en spiegelen

In een oogopslag

Transformeer de tekencoördinatenruimte rond een door u gekozen draaipunt. Dit recipe behandelt rotatie, schaling, schuintrekken en spiegelen. Elke transformatie blijft geïsoleerd binnen een opgeslagen graphics-state-blok, zodat ze latere inhoud niet beïnvloedt. Het voorbeeld volgt examples/21-transforms.php.

Installeren

composer require nextpdf/core:^3

U hebt geen Pro- of Enterprise-pakket nodig. De API voor transformaties wordt met Core meegeleverd en werkt met PHP 8.1 tot en met 8.4.

Conceptueel overzicht

Inhoud in Portable Document Format (PDF) wordt getekend in de user space. Standaard ligt de oorsprong van de user space linksonder op de pagina en is één eenheid gelijk aan 1/72 inch (ISO 32000-2 §8.3.2). Een transformatie vermenigvuldigt de current transformation matrix (CTM) via de cm-operator met een nieuwe matrix (§8.3.4). Transformaties worden samengesteld door matrixconcatenatie, dus de volgorde is van belang.

Met NextPDF werkt u in een auteurscoördinatensysteem met de oorsprong linksboven. NextPDF zet dit intern om naar de native user space met oorsprong linksonder via de toY()-projectie in de transformatiemethoden. Posities gebruiken eenheden van de user space: PDF-punten, waarbij 1 pt gelijk is aan 1/72 in. Plaats een transformatie tussen startTransform() en stopTransform() om deze lokaal te houden. Deze methoden geven de graphics-state-operatoren q (opslaan) en Q (herstellen) uit (§8.4.2). Alles wat ertussen wordt getekend, erft de transformatie. Alles na stopTransform() keert terug naar de vorige CTM. Elke aanroep van rotate()/scale()/skewX()/mirrorH() krijgt een expliciet draaipunt mee, zodat de transformatie verankert waar u verwacht in plaats van bij de paginaoorsprong.

API-oppervlak

Het API-oppervlak wordt uit PHPDoc gegenereerd. De belangrijkste ingangspunten komen uit de trait \NextPDF\Core\Concerns\HasTransforms:

Document::startTransform(): static — geeft q uit en opent een state-blok
Document::stopTransform(): static — geeft Q uit en sluit het blok
Document::rotate(float $angle, float $x = 0, float $y = 0): static
Document::scale(float $sx, float $sy, float $x = 0, float $y = 0): static
Document::skewX(float $angle, float $x = 0, float $y = 0): static / skewY(...)
Document::mirrorH(float $x = 0): static / mirrorV(float $y = 0): static
Document::translateCtm(float $dx, float $dy): static

Codevoorbeeld — Snelstart

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Coordinate Transforms');
$doc->addPage();

$cx = 60.0;
$cy = 60.0;

// Rotate 30° around (cx, cy). The transform is scoped to this block.
$doc->startTransform();
$doc->rotate(30, $cx, $cy);
$doc->setFont('helvetica', '', 14);
$doc->text($cx, $cy, 'Rotated 30 degrees');
$doc->stopTransform();

// Back to the untransformed CTM — this text is upright.
$doc->setFont('helvetica', '', 10);
$doc->text($cx, $cy + 20, 'Not rotated');

$doc->save(__DIR__ . '/transforms.pdf');

echo "Created: transforms.pdf\n";

Codevoorbeeld — Productie

Dit op zichzelf staande programma draait onder de cookbook-harness. Het komt overeen met de schaalsectie van examples/21-transforms.php. Elke transformatie blijft in een opgeslagen graphics-state-blok met een expliciet draaipunt. De kleur- en lijnstatus worden aan het einde teruggezet, zodat niets doorlekt naar een latere pagina.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Coordinate Transforms');
$doc->addPage();

$doc->setFont('helvetica', 'B', 13);
$doc->cell(0, 8, 'Scaling a reference square at 0.5x, 1.0x, 1.5x, 2.0x', newLine: true);
$doc->ln(6);

$scaleBaseY   = $doc->getY();
$scaleFactors = [0.5, 1.0, 1.5, 2.0];

$doc->setDrawColor(30, 58, 138);
$doc->setLineWidth(0.4);

foreach ($scaleFactors as $idx => $factor) {
    $cx = 25.0 + $idx * 45;
    $cy = $scaleBaseY + 5;

    $doc->startTransform();
    $doc->scale($factor, $factor, $cx, $cy);   // scale about (cx, cy)

    $doc->setFillColor(220, 230, 241);
    $doc->rect($cx, $cy, 15, 15, 'DF');
    $doc->line($cx, $cy, $cx + 15, $cy + 15);

    $doc->stopTransform();                      // CTM restored here

    // Drawn AFTER the block — at the original scale, untransformed.
    $doc->setFont('helvetica', '', 8);
    $doc->setTextColor(0);
    $doc->text($cx, $scaleBaseY + 38, sprintf('%.1fx', $factor));
}

// Explicit state reset so nothing carries into the next section.
$doc->setTextColor(0);
$doc->setFillColor(255);
$doc->setDrawColor(0);

// The harness sets NEXTPDF_COOKBOOK_OUTPUT and runs this script twice under
// the structural profile (the transform stream itself is deterministic).
$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false && $out !== '' ? $out : __DIR__ . '/transforms.pdf');

echo "Wrote transforms.pdf\n";

Verwachte STDOUT:

Wrote transforms.pdf

Het volledige voorbeeld behandelt alle vier de transformatiefamilies: rotatie, schaling, schuintrekken en spiegelen. Voer het uit met php examples/21-transforms.php; het schrijft examples/output/21-transforms.pdf.

Randgevallen en valkuilen

Gebruik blokken altijd per paar. Elke startTransform() moet een bijbehorende stopTransform() hebben. Een ongebalanceerd aantal q/Q beschadigt de graphics state voor de rest van de pagina (ISO 32000-2 §8.4.2). NextPDF houdt de diepte bij, maar het contract op recipe-niveau blijft een-op-een.
De volgorde is niet commutatief. Transformaties worden samengesteld door matrixconcatenatie, dus rotate() gevolgd door scale() is niet hetzelfde als scale() gevolgd door rotate(). Pas ze binnen één blok toe in de door u bedoelde volgorde.
Het draaipunt is standaard de oorsprong. Als u het draaipunt weglaat, draait de transformatie rond de paginaoorsprong en niet rond de vorm. Dat is meestal niet wat u wilt, dus geef het draaipunt expliciet door.
De Y-as bevindt zich in de auteursruimte. Het draaipunt y is de afstand vanaf de linkerbovenhoek in de auteursruimte, en NextPDF projecteert het naar de native user space. Het mengen van ruwe PDF-coördinaten met de auteurs-API levert een gespiegeld resultaat op.
Statuslek. Kleur, lettertype en lijndikte die binnen een transformatieblok worden ingesteld, blijven behouden na stopTransform(), omdat Q in dit API-oppervlak alleen de CTM herstelt. Zet deze waarden expliciet terug als een latere sectie ze niet mag erven, zoals het productievoorbeeld doet.

Prestaties

Een transformatie geeft één cm-operator uit plus het q/Q-paar. Elk onderdeel is slechts enkele bytes groot en voegt geen meetbare runtimekosten toe, zodat het recipe binnen het budget van 1500 ms / 96 MB blijft. Het reproduceerbaarheidsprofiel is structureel. De uitvoer bevat een trailer-/ID-array en aanmaakmetadata die tussen uitvoeringen niet stabiel zijn, dus u moet deze normaliseren voordat u vergelijkt. De transform-stream zelf is deterministisch.

Beveiligingsnotities

Datalocatie en maatregelen voor Personally Identifiable Information (PII). Niet van toepassing. Dit recipe tekent geometrische primitieven en korte labels. Het verwerkt geen externe of persoonlijke gegevens.
Veilige telemetrie en logopschoning. Het recipe schrijft één vaste voortgangsregel. Het logt geen documentinhoud.
Dreigingsmodel. Niet van toepassing. Er is geen invoerparsing, geen cryptografie en geen vertrouwensgrens. Een transformatie is zuivere content-stream-uitvoer.
Gedrag in Federal Information Processing Standards (FIPS)-modus. Niet van toepassing. Er is geen cryptografische bewerking.

Conformiteit

Bewering	Specificatie	Clausule
Een transformatie concateneert een matrix op de CTM met de `cm`-operator.	ISO 32000-2	§8.3.4
Transformaties worden samengesteld door matrixconcatenatie, en de volgorde is van betekenis.	ISO 32000-2	§8.3.4
`q` slaat de graphics state op en `Q` herstelt deze, waardoor de transformatie wordt afgebakend.	ISO 32000-2	§8.4.2
De standaardoorsprong van de user space ligt linksonder; één eenheid is 1/72 inch.	ISO 32000-2	§8.3.2

Dit recipe volgt de aangehaalde ISO 32000-2-clausules over graphics state en transformatie. Het claimt geen volledige ISO 32000-2-conformiteit; de aangehaalde clausules zijn de enige die dit recipe gebruikt.