Transformasi ruang koordinat: putar, ubah skala, miringkan, dan cerminkan

Gambaran singkat

Transformasikan ruang koordinat gambar di sekitar pivot pilihan Anda. Resep ini mencakup rotasi, penskalaan, kemiringan, dan pencerminan. Setiap transformasi tetap terisolasi di dalam blok status grafis yang disimpan, sehingga tidak memengaruhi konten berikutnya. Resep ini mengikuti examples/21-transforms.php.

Instalasi

composer require nextpdf/core:^3

Anda tidak memerlukan paket Pro atau Enterprise. API transformasi sudah disertakan dalam Core dan berjalan pada PHP 8.1 hingga 8.4.

Tinjauan konseptual

Konten Portable Document Format (PDF) digambar dalam ruang pengguna. Secara baku, ruang pengguna memiliki titik asal di kiri bawah halaman, dan satu unit sama dengan 1/72 inci (ISO 32000-2 §8.3.2). Transformasi mengalikan matriks transformasi saat ini (CTM) dengan matriks baru melalui operator cm (§8.3.4). Transformasi disusun melalui penggabungan matriks, sehingga urutannya penting.

NextPDF memungkinkan Anda bekerja dalam sistem koordinat penulis dengan titik asal di kiri atas. Secara internal, sistem tersebut dikonversi ke ruang pengguna native yang bertitik asal di kiri bawah melalui proyeksi toY() di dalam metode transformasi. Posisi menggunakan unit ruang pengguna: titik PDF, dengan 1 pt sama dengan 1/72 inci. Agar transformasi tetap lokal, bungkus di antara startTransform() dan stopTransform(). Metode ini mengeluarkan operator status grafis q (simpan) dan Q (pulihkan) (§8.4.2). Apa pun yang digambar di antara keduanya mewarisi transformasi tersebut. Apa pun setelah stopTransform() kembali ke CTM sebelumnya. Setiap pemanggilan rotate()/scale()/skewX()/mirrorH() menerima pivot eksplisit, sehingga transformasi berlabuh di lokasi yang Anda harapkan, bukan di titik asal halaman.

Permukaan API

Permukaan API dihasilkan dari PHPDoc. Titik masuk utamanya berasal dari trait \NextPDF\Core\Concerns\HasTransforms:

Document::startTransform(): static — mengeluarkan q dan membuka blok status grafis
Document::stopTransform(): static — mengeluarkan Q dan menutup blok status grafis
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

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Program mandiri ini berjalan di bawah harness cookbook. Program ini mengikuti bagian penskalaan dari examples/21-transforms.php. Setiap transformasi tetap berada di dalam blok status grafis yang disimpan dengan pivot eksplisit. Status warna dan garis disetel ulang di bagian akhir, sehingga tidak ada yang bocor ke halaman berikutnya.

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

STDOUT yang diharapkan:

Wrote transforms.pdf

Contoh lengkap ini mencakup keempat keluarga transformasi: rotasi, penskalaan, kemiringan, dan pencerminan. Jalankan dengan php examples/21-transforms.php; perintah ini menulis examples/output/21-transforms.pdf.

Kasus tepi & jebakan

Selalu pasangkan bloknya. Setiap startTransform() harus memiliki stopTransform() yang berpasangan. Jumlah q/Q yang tidak seimbang akan merusak status grafis untuk sisa halaman (ISO 32000-2 §8.4.2). NextPDF melacak kedalamannya, tetapi kontrak pada tingkat resep tetap satu lawan satu.
Urutan tidak komutatif. Transformasi disusun melalui penggabungan matriks, sehingga rotate() lalu scale() tidak sama dengan scale() lalu rotate(). Terapkan keduanya di dalam satu blok dengan urutan yang Anda inginkan.
Secara baku, pivot berada di titik asal. Jika Anda menghilangkan pivot, transformasi berpusat di sekitar titik asal halaman, bukan di sekitar bentuknya. Hal itu biasanya bukan yang Anda inginkan, jadi berikan pivot secara eksplisit.
Sumbu Y berada di ruang penulis. Pivot y adalah jarak dari kiri atas dalam ruang penulis, dan NextPDF memproyeksikannya ke ruang pengguna native. Mencampur koordinat PDF mentah dengan API penulis menghasilkan output yang tercermin.
Kebocoran status. Warna, fon, dan lebar garis yang disetel di dalam blok transformasi tetap bertahan setelah stopTransform(), karena pada permukaan API ini Q hanya memulihkan CTM. Setel ulang nilai-nilai ini secara eksplisit jika bagian berikutnya tidak boleh mewarisinya, seperti yang dilakukan contoh produksi.

Performa

Transformasi mengeluarkan satu operator cm ditambah pasangan q/Q. Setiap bagian hanya berukuran beberapa byte dan tidak menambah biaya runtime yang terukur, sehingga resep tetap berada dalam anggaran 1500 ms / 96 MB. Profil reproduktibilitasnya bersifat struktural. Keluarannya berisi larik trailer /ID dan metadata pembuatan yang tidak stabil antar-running, sehingga Anda harus menormalkannya sebelum membandingkan. Aliran transformasi itu sendiri bersifat deterministik.

Catatan keamanan

Residensi data & mitigasi Informasi Pengenal Pribadi (PII). Tidak berlaku. Resep ini menggambar primitif geometris dan label pendek. Resep ini tidak memproses data eksternal atau pribadi.
Telemetri aman & pembersihan log. Resep ini menulis satu baris progres tetap. Resep ini tidak mencatat konten dokumen apa pun.
Model ancaman. Tidak berlaku. Tidak ada penguraian masukan, tidak ada kriptografi, dan tidak ada batas kepercayaan. Transformasi adalah emisi aliran konten murni.
Perilaku mode Federal Information Processing Standards (FIPS). Tidak berlaku. Tidak ada operasi kriptografis.

Kesesuaian

Pernyataan	Spesifikasi	Klausa
Transformasi menggabungkan matriks ke CTM dengan operator `cm`.	ISO 32000-2	§8.3.4
Transformasi disusun melalui penggabungan matriks, dan urutannya berpengaruh.	ISO 32000-2	§8.3.4
`q` menyimpan dan `Q` memulihkan status grafis, yang membatasi cakupan transformasi.	ISO 32000-2	§8.4.2
Titik asal ruang pengguna baku berada di kiri bawah; satu unit adalah 1/72 inci.	ISO 32000-2	§8.3.2

Resep ini mengikuti klausa status grafis dan transformasi ISO 32000-2 yang dikutip. Resep ini tidak mengklaim kesesuaian ISO 32000-2 secara menyeluruh; klausa yang dikutip adalah satu-satunya yang dijalankan resep ini.