Grafikler: yol + gölgeleme + dönüşüm ilkelleri

Bir bakışta

Graphics modülü, çizim niyetini Taşınabilir Belge Biçimi (PDF) grafik işleçlerine dönüştürür. Yolları, çizgi stillerini, renk uzaylarını, dönüşümleri, gölgelemeleri, desenleri, yarı tonları ve görüntü yüklemeyi kapsar.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Graphics, vektör ve raster çizim katmanıdır. ContentStream ve Writer modüllerinin bir PDF içine serileştirdiği işleç dizileri üretir. Bir içerik akışı, sayfa içeriğini Uluslararası Standardizasyon Örgütü (ISO) 32000-2 §8 uyarınca sıralı bir grafik işleçleri dizisi olarak kodlar. Modül bu işleçleri yayar; dosyayı yazmaz.

DrawingEngine, birincil uygulama programlama arabirimidir (API). Akıcı ve durum bilgili bir oluşturucudur. Her ayarlayıcı self döndürür, bir grafik durumu değişikliğini ya da bir yol boyama işlecini kaydeder ve getStream() ile okuduğunuz iç arabelleğe ekler. Motor, PDF grafik durumunu doğrudan modeller: çizgi genişliği, çizgi stili, kontur ve dolgu rengi, alfa ve karışım modu, gönye sınırı, yumuşak maske, kırpma, üst baskı, düzlük, yumuşaklık, işleme amacı, siyah üretimi ve alt renk kaldırma bileşenlerinin her biri belgelenmiş bir işlece eşlenir. Renk ayarlayıcıları bir Color değer nesnesini ya da açık bir ColorSpace değerini kabul eder; böylece aygıt tabanlı ve Uluslararası Aydınlatma Komisyonu (CIE) tabanlı uzaylar aynı çağrı biçimini kullanır.

Motorun yanında üç bileşen ailesi bulunur. İlki görüntü girdisidir. ImageLoader, bir dosyayı ya da bellekteki ikili veriyi çözerek bir ImageLoadResult oluşturur. ImageRegistry, çözülmüş görüntüleri bir MemoryReport ile yinelemeden arındırır ve izler; böylece büyük belgeler bir bellek bütçesi içinde kalır. Vektör içe aktarımı için SvgParser ve EpsParser, Ölçeklenebilir Vektör Grafikleri (SVG) ve Kapsüllenmiş PostScript (EPS) girdisini aynı işleç akışına çevirir; yerleşim için getBoundingBox() açığa çıkarılır. Üçüncü aile aygıt rengi doğruluğudur: gölgelemeler (ShadingManager, Type2/Type3 ve örgü aileleri), desenler (PatternFill), yarı tonlar (Type1/Type5/Type6/Type10/Type16), transfer işlevleri ve Uluslararası Renk Konsorsiyumu (ICC) tabanlı renk uzayları.

TransformEngine, koordinat dönüşümleri için odaklanmış bir yardımcıdır. Bir dönüşümü startTransform() ve stopTransform() ile sarmalar; bunlar q ve Q save/restore çiftini yayar. Adlandırılmış afin yardımcılar sunar: scale, translate, rotate, skew, mirrorH ve mirrorV. Her yardımcı isteğe bağlı bir eksen noktasını kabul eder. Dönüşüm matrisi, iç koordinat uzayını hedef koordinat uzayına eşler. Bu, ISO 32000-2 standardının gölgeleme tanım kümelerine uyguladığı modelin aynısıdır — §8.7.4.

Renk yönetimi, Mimari Karar Kaydı (ADR)-012 ilkesini izler: ICCBased ve CIE tabanlı renk uzayları, aygıt rengi yedeğine dayanmak yerine açık cs/CS içerik akışı işleçleri yayar. ICC profilleri, ISO 32000-2 §8.6.5.5 uyarınca doğru bileşen sayısıyla bir ICCBased akışına sarmalanır.

API yüzeyi

Sınıf	Anahtar yöntemler	Rol
`DrawingEngine`	`getStream()`, `reset()`, `setLineWidth()`, `setLineStyle()`, `setDrawColor()`, `setFillColor()`, `setAlpha()`, `setSoftMask()`, `clip()`, `setOverprint()`, `setRenderingIntent()`, `line()`, `rect()`, `circle()`, `ellipse()`, `polygon()`, `linearGradient()`	Durum bilgili yol + grafik durumu işleci oluşturucusu
`TransformEngine`	`startTransform()`, `stopTransform()`, `scale()`, `translate()`, `rotate()`, `skew()`, `mirrorH()`, `mirrorV()`, `getStream()`	Afin koordinat dönüşümleri
`ImageLoader`	`load(string $filePath)`, `loadFromString(string $data, string $mimeType)`	Görüntüleri şuna çözer: `ImageLoadResult`
`ImageRegistry`	`load()`, `loadFromString()`, `getMetadata()`, `memoryUsage()`, `reset()`	Bellek raporlaması yapan, yinelemeden arındıran görüntü önbelleği
`SvgParser`	`parse()`, `parseFile()`	SVG girdisini işleç akışına çevirir
`EpsParser`	`parse()`, `parseFile()`, `getBoundingBox()`	EPS girdisini işleç akışına çevirir
`ShadingManager`	gölgeleme kaydı + sözlük yayımı	Eksenel, ışınsal ve örgü gölgelemeleri
`Halftone` (soyut)	`halftoneType()`, `toDict()`, `hasStream()`, `getStream()`	Type `1/5/6/10/16` yarı ton ekranları

Tam PHPDoc tablosunu oluşturmak için composer docs:generate-api-php -- --module=Graphics komutunu çalıştırın.

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

Kaynak: examples/06-colors-and-drawing.php.

<?php

declare(strict_types=1);

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

use NextPDF\Graphics\Color;
use NextPDF\Graphics\DrawingEngine;
use NextPDF\Graphics\LineStyle;

$engine = new DrawingEngine();

$engine
    ->setLineWidth(1.5)
    ->setDrawColor(Color::rgb(0, 51, 102))
    ->setFillColor(Color::rgb(230, 240, 250))
    ->rect(20.0, 20.0, 160.0, 80.0)
    ->line(20.0, 110.0, 180.0, 110.0, new LineStyle(dash: [3.0, 2.0]));

$contentStreamBytes = $engine->getStream();

Kod örneği — üretim

Bu örnek, bellek raporlaması yapan bir görüntü kayıt defteriyle bir dönüşüm bloğunu birbirine bağlar. examples/07-images.php ve examples/21-transforms.php içinde kullanılan yapıyı yansıtır.

<?php

declare(strict_types=1);

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

use NextPDF\Graphics\DrawingEngine;
use NextPDF\Graphics\ImageRegistry;
use NextPDF\Graphics\TransformEngine;

$registry = new ImageRegistry();
$image = $registry->load('/srv/assets/logo.png');

$report = $registry->memoryUsage();
if ($report->bytes > 32 * 1024 * 1024) {
    // Decoded image cache exceeded the budget — reset before the next page.
    $registry->reset();
}

$transform = new TransformEngine();
$transform
    ->startTransform()
    ->translate(40.0, 700.0)
    ->scale(0.5, 0.5)
    ->stopTransform();

$engine = new DrawingEngine();
$engine->reset();
$page = $transform->getStream() . $engine->getStream();

Sınır durumları ve tuzaklar

DrawingEngine durum bilgisi tutar. Önceki grafik durumunun sonraki akışa sızmaması için bağımsız sayfalar arasında reset() çağırın.
TransformEngine, eşleşen bir startTransform()/stopTransform() çifti gerektirir. Dengelenmemiş bir blok, askıda kalan bir q bırakır ve Writer içinde aşağı akıştaki save/restore yığınını bozar.
setSoftMask(), setOverprint(), setBlackGeneration() ve setUnderColorRemoval() genişletilmiş grafik durumu işaretleyicileri yazar. Bu özellikleri reddeden bir profil altında etkisiz kalırlar. Görsel sonuca güvenmeden önce profil korumasını denetleyin.
ImageRegistry içeriğe göre yinelemeden arındırır. Aynı baytlara sahip iki yol tek bir nesneyi paylaşır. Her load() çağrısı başına bir PDF görüntüsü olduğunu varsaymayın.
EpsParser::getBoundingBox(), sayfa kutusunu değil, ayrıştırılan sınırlayıcı kutuyu döndürür. EPS, hedef dikdörtgeni aşarsa kendi kırpmanızı uygulayın.
Siyah nokta telafisi tavsiye niteliğindedir ve işaretleyici tabanlıdır. Pikselleri kendi başına dönüştürmez.

Doğrulama ve hata işleme

Üretici tarafındaki iki değişiklik geriye dönük uyumsuzdur. Her ikisi de daha önce sessizce gerçekleşen bozulmayı, çağrı yerinde açık bir hataya dönüştürür.

Girdi doğrulaması artık özel durum fırlatıyor (geçiş notu). Çizim girdisi işleç akışına ulaşmadan önce doğrulanır ve hatalı biçimli değerler InvalidArgumentException ile reddedilir. NaN, Infinity ya da aralık dışı değerler geçiren çağıranlar daha önce sessizce bozuk işleçler üretiyordu; aynı girdi artık özel durum fırlatır. Doğrulanan kısıtlamalar şunlardır:

Renk alfası sonlu ve [0, 1] aralığında olmalıdır.
Geçerli dönüşüm matrisi (CTM) işlenenleri, şablon boyutları, geçiş köşe koordinatları ve örgü yaması koordinatları sonlu olmalıdır — NaN ya da Infinity olamaz.
Bir geçiş yaması kenar bayrağı {0, 1, 2, 3} değerlerinden biri olmalıdır.
Type 2/3/4 işlev parametreleri ve yarı ton parametreleri sınır denetiminden geçirilir.
Renklendirici adları kaçışlanır.
İsteğe bağlı içerik grubu (OCG) katman adı boş olmamalıdır.

Yükseltmeden önce, koordinatları ya da alfayı yukarı akış verilerinden hesaplayan çağrı yerlerini denetleyin: önceden kabul edilen bir değer artık kesin bir hatadır.

ICCBased /N varsayılan olarak hatada kapalı davranır. Düz PDF çıktısı, /N bileşen sayısı {1, 3, 4} dışında olan bir ICCBased renk uzayını reddeder ve bildirilen /N değerini gömülü profil ve /Alternate uzayıyla bağdaştırır. Bu, ICCBased akışı için ISO 32000-2 §8.6.5.5 kuralını izler; bu akış, /N değerini bir /Alternate uzayıyla birlikte taşır. N = 6 içeren bir hekzakrom profili gibi N kanallı bir ICC profili, yalnızca bir PDF/A ya da PDF/X profili etkin olduğunda, IccConformancePolicy::ProfileGated ile etkinleştirilerek korunur. Bu, bileşen sayısı üzerinde yapısal bir kapıdır; bir PDF/A ya da PDF/X sertifikasyon iddiası değildir.

Performans

İşleç yayımı, çizim çağrılarının sayısıyla doğrusaldır: bir arabelleğe O(n) ekleme yapılır, yeniden akış olmaz. Görüntü çözme maliyeti, kayıt defterinden değil, codec ve piksel sayısından kaynaklanır. Kayıt defterinin içerik karmasına dayalı yinelemeden arındırması, büyük belgeler için temel kaldıraçtır: yeniden kullanılan varlıklar bir çözme ve bir PDF nesnesi kadar maliyetlidir. Bu modülün referans iş yükü için performance_budget değeri 1500 ms duvar süresi ve 64 MB tepe bellek tüketimidir. Çözülmüş görüntü ayak izini gözlemlemek için ImageRegistry::memoryUsage(), sayfa grupları arasında bunu serbest bırakmak için reset() kullanın.

Güvenlik notları

SvgParser ve EpsParser güvenilmeyen vektör girdilerini işler. Her ikisini de düşmanca veri ayrıştırıcıları olarak ele alın. parse() çağrılmadan önce girdi boyutu sınırlarını uygulayın. Kaynak kullanıcı tarafından sağlandığında çıkarmayı kısıtlı bir işçi sürecinde çalıştırın. EPS, bir PostScript lehçesidir. Ayrıştırıcı yalnızca kısıtlı bir alt kümeyi çevirir ve genel bir yorumlayıcı çalıştırmaz; yine de girdi boyutunu ve ayrıştırma süresini sınırlamalısınız. Görüntü yükleyiciler üçüncü taraf codec’lerini çözer. Çalışma zamanı görüntü uzantılarını güncel tutun ve çözülen boyutları sınırlayın. Güven sınırı ve işçi yalıtımı yönergesi için /modules/core/security/ içindeki motor tehdit modeline bakın.

Uygunluk

Modül, ISO 32000-2 §8 ile tutarlı PDF grafik işleci yapıları, §8.6.5.5 uyarınca ICCBased renk uzayı sözlükleri ve Domain, Function, Matrix ve BBox değerleri için §8.7.4 uyarınca gölgeleme sözlükleri yayar. Bunlar uygulama düzeyindeki gerçeklerdir: src/Graphics/ işleç ve sözlük biçimlerini üretir; tests/Unit/Graphics/ ve ayrıca tests/Golden/PdfWriter/PdfWriterShadingGoldenBaselineSmokeTest ve PdfWriterExtGStateGoldenSmokeTest temelleri bunları sınar. Bunlar uçtan uca PDF 2.0 ya da PDF/X uygunluğu beyanı değildir. Tam belge uygunluğu, /modules/core/conformance/ içinde açıklanan oracle ve golden takımları tarafından ayrıca doğrulanır. ICC OutputIntents için profil davranışı yalnızca bu modül tarafından değil, ADR-011 ve ADR-012 tarafından belirlenir.