Koordinat uzayını dönüştürme: döndürme, ölçekleme, eğme ve yansıtma

Bir bakışta

Çizim koordinat uzayını, seçtiğiniz bir pivot çevresinde dönüştürün. Bu tarif döndürme, ölçekleme, eğme ve yansıtma işlemlerini kapsar. Her dönüşüm, kaydedilmiş bir grafik durumu bloğunda yalıtılmış kalır; bu nedenle sonraki içeriği etkilemez. examples/21-transforms.php dosyasındaki akışı izler.

Kurulum

composer require nextpdf/core:^3

Bir Pro veya Enterprise paketine ihtiyacınız yoktur. Dönüşüm API’si Core ile birlikte gelir ve PHP 8.1’den 8.4’e kadar olan sürümlerde çalışır.

Kavramsal genel bakış

Taşınabilir Belge Biçimi (PDF) içeriği kullanıcı uzayında çizilir. Varsayılan olarak kullanıcı uzayının başlangıç noktası sayfanın sol alt köşesindedir ve bir birim 1/72 inçtir (ISO 32000-2 §8.3.2). Bir dönüşüm, geçerli dönüşüm matrisini (CTM), cm işleci aracılığıyla yeni bir matrisle çarpar (§8.3.4). Dönüşümler matris birleştirmesiyle bir araya gelir; bu nedenle sıra önemlidir.

NextPDF, başlangıç noktası sol üst köşe olan bir yazar koordinat sisteminde çalışmanıza olanak tanır. Dahili olarak bu sistemi, dönüşüm yöntemlerindeki toY() izdüşümü aracılığıyla doğal kullanıcı uzayına, yani başlangıç noktası sol alt köşe olan uzaya dönüştürür. Konumlar kullanıcı uzayı birimleriyle, yani 1 pt’nin 1/72 inç olduğu PDF noktalarıyla ifade edilir. Bir dönüşümü yerel kapsamda tutmak için onu startTransform() ile stopTransform() arasına alın. Bu yöntemler q (kaydet) ve Q (geri yükle) grafik durumu işleçlerini yazar (§8.4.2). Aralarında çizilen her şey dönüşümü devralır. stopTransform() çağrısından sonra çizilen her şey önceki CTM’ye geri döner. Her rotate()/scale()/skewX()/mirrorH() çağrısı açıkça belirtilmiş bir pivot alır; böylece dönüşüm sayfa başlangıç noktasına değil, beklediğiniz yere sabitlenir.

API yüzeyi

API yüzeyi PHPDoc’tan üretilir. Ana giriş noktaları \NextPDF\Core\Concerns\HasTransforms trait’inden gelir:

Document::startTransform(): static — q işlecini yazar ve bir durum bloğu açar
Document::stopTransform(): static — Q işlecini yazar ve bloğu kapatır
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

Kod örneği — Hızlı başlangıç

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

Kod örneği — Üretim

Bu bağımsız program, tarif kitabı koşum düzeneği altında çalışır. examples/21-transforms.php dosyasının ölçekleme bölümünü yansıtır. Her dönüşüm, açıkça belirtilmiş bir pivotla kaydedilmiş bir grafik durumu bloğunun içinde kalır. Renk ve çizgi durumu en sonda sıfırlanır; böylece sonraki bir sayfaya hiçbir şey sızmaz.

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

Beklenen STDOUT:

Wrote transforms.pdf

Tam örnek, dört dönüşüm ailesinin tamamını kapsar: döndürme, ölçekleme, eğme ve yansıtma. Örneği php examples/21-transforms.php ile çalıştırın; examples/output/21-transforms.pdf dosyasını yazar.

Sınır durumları ve tuzaklar

Bloğu her zaman eşleyin. Her startTransform() çağrısının eşleşen bir stopTransform() çağrısı olmalıdır. Dengesiz bir q/Q sayısı, sayfanın geri kalanı için grafik durumunu bozar (ISO 32000-2 §8.4.2). NextPDF derinliği izler; ancak tarif düzeyindeki sözleşme bire bir eşleşme olarak kalır.
Sıra değişmeli değildir. Dönüşümler matris birleştirmesiyle bir araya gelir; bu nedenle önce rotate() sonra scale() uygulamak, önce scale() sonra rotate() uygulamakla aynı değildir. Bunları tek bir blok içinde, amaçladığınız sırada uygulayın.
Pivot varsayılan olarak başlangıç noktasıdır. Pivotu atlarsanız, dönüşüm şeklin değil, sayfa başlangıç noktasının çevresinde döner. Bu genellikle istediğiniz şey değildir; bu nedenle pivotu açıkça geçirin.
Y ekseni yazar uzayındadır. Pivot y değeri, yazar uzayının sol üst köşesinden olan uzaklıktır ve NextPDF bunu doğal kullanıcı uzayına yansıtır. Ham PDF koordinatlarını yazar API’siyle karıştırmak, yansıtılmış bir sonuç üretir.
Durum sızıntısı. Bir dönüşüm bloğu içinde ayarlanan renk, yazı tipi ve çizgi genişliği stopTransform() çağrısından sonra da kalıcıdır; çünkü bu API yüzeyinde Q yalnızca CTM’yi geri yükler. Sonraki bir bölüm bu değerleri devralmamalıysa, üretim örneğinde olduğu gibi onları açıkça sıfırlayın.

Performans

Bir dönüşüm, bir cm işleciyle birlikte q/Q çiftini yazar. Her parça yalnızca birkaç bayttır ve ölçülebilir bir çalışma zamanı maliyeti eklemez; bu nedenle tarif 1500 ms / 96 MB bütçesi içinde kalır. Yeniden üretilebilirlik profili yapısaldır. Çıktı, çalıştırmalar arasında kararlı olmayan art bilgi /ID dizisi ve oluşturma meta verileri içerir; bu nedenle karşılaştırmadan önce bunları normalleştirmeniz gerekir. Dönüşüm akışının kendisi belirlenimcidir.

Güvenlik notları

Veri ikametgâhı ve kişisel olarak tanımlanabilir bilgi (PII) önlemleri. Geçerli değil. Bu tarif geometrik ilkel öğeler ve kısa etiketler çizer. Hiçbir harici veya kişisel veri işlemez.
Güvenli telemetri ve günlük temizleme. Tarif tek bir sabit ilerleme satırı yazar. Hiçbir belge içeriğini günlüğe kaydetmez.
Tehdit modeli. Geçerli değil. Girdi ayrıştırması, şifreleme veya güven sınırı yoktur. Bir dönüşüm yalnızca içerik akışı yayımıdır.
Federal Bilgi İşleme Standartları (FIPS) modu davranışı. Geçerli değil. Hiçbir şifreleme işlemi yoktur.

Uygunluk

Beyan	Belirtim	Madde
Bir dönüşüm, `cm` işleciyle CTM’ye bir matris ekler.	ISO 32000-2	§8.3.4
Dönüşümler matris birleştirmesiyle bir araya gelir ve sıra önemlidir.	ISO 32000-2	§8.3.4
`q` grafik durumunu kaydeder ve `Q` geri yükler; böylece dönüşüm kapsam içine alınır.	ISO 32000-2	§8.4.2
Varsayılan kullanıcı uzayının başlangıç noktası sol alt köşedir; bir birim 1/72 inçtir.	ISO 32000-2	§8.3.2

Bu tarif, alıntılanan ISO 32000-2 grafik durumu ve dönüşüm maddelerini izler. Genel ISO 32000-2 uygunluğu iddiasında bulunmaz; bu tarifin uyguladığı tek maddeler, alıntılanan maddelerdir.