Aynı rapor üretecisinin aynı veriden, bir koşu arayla ürettiği iki PDF, nadiren bayt bayt eşleşir. İkili bir diff cross-reference tablosunu, nesne numaralarını ve çoğu zaman font programlarını aydınlatır; iki dosya da tamamen aynı sayfaları basar. Render edilmiş pikselleri karşılaştırmak çare gibi görünür, ta biri bir kapak sayfası ekleyene dek: o andan itibaren her sayfa, karşılığından bir konum sonra durur ve sayfa sayfa bir piksel kontrolü tüm belgeyi değişmiş bildirir. Otomatikleştirmeye değer bir karşılaştırma iki farklı soruyu yanıtlamak zorundadır — dosyanın içinde ne değişti ve bir okuyucu onu görecek mi — ve bir dosyadaki hangi sayfanın diğerindeki hangi sayfaya karşılık geldiğini bilmek zorundadır
Aynı görünen iki PDF neden bayt bayt farklıdır?
Bayt kirliliğinin çoğu, okuyucunun hiç görmediği kayıt tutmadan gelir. Nesne numaraları, yazıcının nesneleri tesadüfen hangi sırada salıverdiyse o sırayla dağıtılır. Birçok üretici font alt kümelerini, glifler ilk kullanıldıkları sırada kurar; hafifçe farklı bir gezinme, aynı görünür metin için farklı glif kodları ve dolayısıyla farklı içerik akışı baytları üretir. Cross-reference ofsetleri, dosyada önde olan herhangi bir şey uzunluk değiştirdiğinde kayar — ki bu neredeyse hep olur
Nesne numaraları iki dosya arasında kimlik olarak bu yüzden işe yaramaz. HotPDFteki THPDFDocComparison, her nesneyi, belge kataloğundan genişlik öncelikli bir yürüyüşte ona ilk ulaşan yolla adlandırır. Sözlük anahtarları bayt sırasında, dizi ögeleri indeksle ziyaret edilir; yürüyüş böylece belirlenimlidir: ilk sayfadaki bir font kaynağı, her üreticinin ona verdiği nesne numarası ne olursa olsun tipik olarak her iki dosyada $Catalog/Pages/Kids[0]/Resources/Font/F1 gibi bir şeye dönüşür. Anahtardaki alışılmadık baytlar #xx olarak kaçırılır ve MaxPathBytesi aşan bir yol kısaltılıp tam yolun bir özetiyle tamamlanır; önek paylaşan iki uzun yol böylece birbirinden ayrı kalır
Sonra her nesne, kendi içeriği üzerinden bir SHA-256 imzası alır. Bir dolaylı referans yalnızca orada bir referans durduğunu katar, işaret ettiği nesne numarasını asla; hedef kendi imzası için kuyruğa girer. Bir dosyadaki her nesneyi yeniden numaralandırmak bu yüzden hiçbir fark üretmez. Bir font sözlüğü değiştiğinde rapor, sayfayı, kaynak sözlüğünü ve üzerindeki sayfa ağacını işaretlemek yerine o fontun yolunu objectChanged olarak adlandırır. İmzası uyan ama yolu kaymış bir nesne (diyelim sayfa, sayfa ağacının başka bir dalına kaymış) objectMoved olarak görünür; gerisi objectInserted ya da objectDeleteddir
Katalogdan hiçbir yolun ulaşmadığı nesneler de imzalanır; nesne ile üretim numarasını taşıyan $Unreachable[42:0] gibi sentetik bir yol altında. Yetim içerik, hiçbir görüntüleyici onu asla göstermeyecek olsa bile iki dosya arasındaki gerçek bir farktır. Akış verisi, akıştan doğrudan 64 KBlik parçalarla hash edilir ve akış konumu sonrasında geri konur; iki büyük dosyayı karşılaştırmak her akışın bir kopyasını bellekte tutmak demek değildir
Bir belgeye kapak girdiğinde sayfaları hizalamak
1. sayfayı 1. ile, 2. sayfayı 2. ile eşlemek ancak bir şey araya girene kadar doğrudur. Öne yeni bir kapak geldiğinde konumsal eşleme her sayfayı değişmiş bildirir; teknik olarak doğrudur ve gözden geçirene hiçbir şey söylemez
Sayfalara bakan her mod önce onları hizalar. Her sayfa, çıkarılan metninden bir imza alır; çıkarılabilir metni olmayan sayfalar, sayfa sözlüğünün ve içerik akışının imzasına düşer. İmzaları tam eşleşen sayfalar eşleşir ve karşılaştırma, o eşleşmelerin ikinci dosyadaki konumlarına göre sıralanmış en uzun artan alt dizisini alır. O alt dizideki eşleşmeler bir ekleme ya da silmeyle birlikte yalnızca kaymıştır. Dışında kalanlar gerçekten yeniden sıralanmıştır ve pageMoved olarak bildirilir. Hiç eşleşmeyenler sırayla pageChanged olarak eşleştirilir; artan kısım pageInserted ya da pageDeleted olur. Tek bir yeni kapak sayfalı 400 sayfalık bir kılavuz için sayfa düzeyi girdiler, konumsal eşlemenin 400 değişiklik ürettiği yerde tek bir pageInsertede iner. Nesne geçişi yol ile çalıştığı için kaymış sayfa nesneleri tipik olarak orada yine objectMoved olarak görünür ve type alanına süzmek onları gerçek düzenlemelerden ayırır
Hizalanmış eşleşmeler yapısal modlarda bir kontrol daha alır. Sayfa sözlüğü /Contents, /Resources ve /Parentsiz ikinci kez imzalanır; imza farklıysa eşleşme, ayrıntısı page metadata changed olan bir pageChanged olarak bildirilir. Bu, metni aynı ama /MediaBoxı ya da /Rotatei kaymış bir sayfayı yakalar; metin temelli hizalama tek başına öyle bir değişikliği eşleştirip geçiştirirdi
Yapısal bir karşılaştırma koşturmak ve kararı okumak
Karşılaştırma, iki yüklenmiş THotPDF örneği ve bir mod alır, raporu AnsiString olarak bir JSON döndürür. cmStructural nesne ve sayfa yürüyüşünü koşturur, cmRenderedImage piksel geçişini, cmFull ikisini birden; cmPageCount, cmPageText ve cmObjectCount duman testleri için daha hafif kontrollerdir. Compare öntanımlı sınırları ve seçenekleri kullanır; CompareWithLimits ile CompareWithOptions sizinkileri alır
uses
Classes, SysUtils, HPDFDoc, HPDFDocCompare;
function CompareFiles(const BaselineFile, CandidateFile: string): AnsiString;
var
DocA, DocB: THotPDF;
begin
Result := '';
DocA := THotPDF.Create(nil);
DocB := THotPDF.Create(nil);
try
if (DocA.LoadFromFile(BaselineFile) <= 0) or
(DocB.LoadFromFile(CandidateFile) <= 0) then
raise Exception.Create('Could not load one of the files');
Result := THPDFDocComparison.Compare(DocA, DocB, cmStructural);
with TFileStream.Create('diff.json', fmCreate) do
try
if Result <> '' then
WriteBuffer(Result[1], Length(Result));
finally
Free;
end;
finally
DocB.Free;
DocA.Free;
end;
end;
Rapor, tek bir booleanın bulanıklaştıracağı üç üst düzey olguyu taşır. identical yalnızca hiçbir fark kaydedilmemişse ve karşılaştırma tamamlanmışsa doğrudur. comparisonComplete tamamlanıp tamamlanmadığını söyler. differencesTruncated listenin kırpılıp kırpılmadığını söyler; differenceCount gerçek toplamı, reportedDifferenceCount fiilen listelenen sayıyı tutar. Bir gezinme bir limite çarptığında differences dizisindeki bir comparisonBudget girdisi, sayfa yürüyüşünün mi nesne yürüyüşünün mü kırpıldığını söyler
comparisonCompletei false yapan birkaç şey vardır: kırpılmış bir sayfa ya da nesne gezinmesi, dosyalardan birinde çözülmeyen bir dolaylı referans, MaxDifferencesin izin verdiğinden fazla fark, yapısı (ya da cmPageTextte metni) okunamayan bir sayfa ve eksik bir piksel geçişi. Hepsi identicali de false zorlar; API, erken durmuş bir yürüyüşten eşitlik bildirmez. Bir CI kapısı bu yüzden iki tür başarısızlığı ayırt etmek zorundadır:
uses
SysUtils, HPDFJobJSON;
// Yalnızca farksız tamamlanmış bir karşılaştırma için True döndürür;
// aksi halde sebebi yazar. Kapının kendisi sizin kodunuzdur
function DiffGatePasses(const Report: AnsiString): Boolean;
var
Parser: THPDFJSONParser;
Root, Diffs, Item: THPDFJSONValue;
I: Integer;
begin
Parser := THPDFJSONParser.Create(Report);
try
Root := Parser.Parse;
finally
Parser.Free;
end;
try
Result := Root.GetBool('identical');
if Result then
Exit;
if not Root.GetBool('comparisonComplete') then
Writeln('INCOMPLETE: a limit or unreadable input stopped the comparison');
Writeln(Format('%d difference(s), %d listed',
[Root.GetInt('differenceCount'), Root.GetInt('reportedDifferenceCount')]));
Diffs := Root.GetArr('differences');
if Diffs <> nil then
for I := 0 to Diffs.ItemCount - 1 do
begin
Item := Diffs.Item(I);
Writeln(Item.GetStr('type'), ' ', Item.GetStr('detail'), ' ',
Item.GetStr('pathA'), ' -> ', Item.GetStr('pathB'));
end;
finally
Root.Free;
end;
end;
"Eksik"i kendi derleme sonucu olarak değerlendirin. Onu "farklı"a eşleyen bir iş, gerçekte bozuk bir girdi ya da fazla düşük kurulmuş bir sınır olan şey için mühendisleri bir gerileme avına yollar; onu "aynı"ya eşleyen bir iş ise kırpılmış bir yürüyüşü bir sürümden geçirir
Üretmediğiniz dosyalarda yürüyüşü ne sınırlı tutar?
THPDFStructuralCompareLimits.Default gerçek dünya belgelerine göre boyutlanmıştır: 250.000 nesne, 2.000.000 izlenen referans, 250.000 sayfa, 128 yuvalanma derinliği, 10.000 listelenen fark, tek bir akıştan 64 MB ve tüm akışlardan toplam 512 MB, dize ya da name değeri başına 1 MB, yol başına 4.096 bayt ve serileştirilmiş rapor üzerinde 16 MB tavan. Sıfır ya da negatif bir alan öntanımlısına düşer; yarı dolu bir kayıt asla sınırsız olana dönüşmez. Kayıt ayrıca karşılaştırmanın iş birimleri arasında — sayfalar render edilirken dâhil — kontrol ettiği bir CancellationToken ve bir Checkpoint olayı taşır
uses
SysUtils, HPDFDoc, HPDFDocCompare, HPDFTypes;
function CompareForRelease(DocA, DocB: THotPDF;
Token: THPDFCancellationToken): AnsiString;
var
Limits: THPDFStructuralCompareLimits;
Options: THPDFRenderedCompareOptions;
begin
Limits := THPDFStructuralCompareLimits.Default;
Limits.MaxDifferences := 200; // listeyi kısa tutar; differenceCount yine de tümünü sayar
Limits.MaxTotalStreamBytes := 128 * 1024 * 1024;
Limits.CancellationToken := Token; // başka bir thread Token.Cancel çağırabilir
Options := THPDFRenderedCompareOptions.Default;
Options.DPI := 150; // öntanımlı 72
Options.ColorSpace := rccLuminance; // parlaklığı karşılaştır, yalnızca renk tonu kaymalarını yok say
Options.ColorTolerance := 2; // 1-2 düzeylik sapmalar sayılmaz
Options.MinimumSimilarity := 0.9995;
Options.MaxChangedPixelRatio := 0.0005;
Options.GenerateHeatmaps := True;
Options.HeatmapDirectory := 'diff-overlays';
try
Result := THPDFDocComparison.CompareWithOptions(DocA, DocB, cmFull,
Limits, Options);
except
on EHPDFOperationCancelled do
Result := ''; // iptal edildi: rapor yok
end;
end;
İptal, kısmi bir rapor döndürmek yerine çağrıdan EHPDFOperationCancelled fırlatır. İptal edilmiş bir karşılaştırmanın geri verecek raporu yoktur ve exception bunu söyleme biçimidir. Render seçenekleri sınırlarla aynı normalizasyonu alır: DPI 2.400e, ColorTolerance 0-255e, TileSize 8-1.024e kelepirlenir; 0-1 dışında (ya da NaN) bir benzerlik ya da oran eşiği sessizce öntanımlıya döner
Piksel geçişi, hiçbir şey render etmeden önce her sayfanın bitmap boyutunu sayfa boyutlarından ve istenen DPIden tahmin eder ve gerçek bitmapi sonrasında bir kez daha MaxPixelsPerPagele kontrol eder; sahte geometrili bir sayfa tahmini aşamaz. Maliyet DPIın karesiyle büyür. US Letter sayfalı, 612 × 792 pointlik bir belgede öntanımlı 72 DPIde her sayfa çifti kabaca 0,97 milyon piksel eder ve öntanımlı 500 milyonluk MaxTotalPixels 500 çiftten fazlasını kapsar. 300 DPIde tek bir çift kabaca 16,8 milyon pikseldir ve bütçe 29 çiftten sonra tükenir. Geçiş sonra bir renderBudget girdisi kaydeder, o sayfayı budgetExceeded işaretler ve durur; renderComparisonComplete false kalır
Ne kadar benzer, yeterince benzerdir?
Öntanımlı seçeneklerle piksel geçişi tam eşleşme ister: ColorTolerance 0, MinimumSimilarity 1.0 ve MaxChangedPixelRatio 0. Öntanımlıda katı kalmak, gevşetme kararını açık tutar: birisi onu yazmak zorundadır ve bir iş hattı eşikleri, yalnızca kendi renderlarında anti-aliasing gürültüsünün neye benzediğini gördükten sonra gevşetmelidir
Piksel başına, rccRGB modundaki delta kırmızı, yeşil ve mavi kanallar arasındaki en büyük farktır; rccLuminance modunda Rec. 709 parlaklığındaki farktır. Delta ColorTolerancei aştığında bir piksel değişmiş sayılır. Benzerlik sayısı, tüm sayfanın parlaklığı üzerinden bir kere hesaplanan yapısal benzerlik (SSIM) skorudur. Bir çift yalnızca değişmiş piksel oranı MaxChangedPixelRatioya eşit ya da onun altındayken ve benzerlik MinimumSimilarityye eşit ya da üstündeyken similardır. İki kapı vardır; çünkü barkoddaki birkaç yüz fena yanlış piksel ile bütün sayfaya yayılan soluk bir renk tonu farklı başarısızlıklardır ve her iş akışı onları farklı tolere eder. Eşik kontrolleri yuvarlanmamış değerlerle yapılır; JSONdaki altı ondalık, raporları koşturmadan koşturmaya kararlı tutar
Değişen pikseller, öntanımlı 64 piksellik sabit bir döşeme ızgarasında, dört kenar komşusuyla birleştirilerek bölgelere toplanır. changedRegionsdeki her bölge sınırlayıcı kutusunu, değişen piksel sayısını ve en büyük deltasını verir. En fazla MaxChangedRegions (öntanımlı 256) listelenir; changedRegionCount yine de gerçek sayıyı bildirir ve liste kırpıldığında changedRegionsTruncated kurulur ve piksel geçişi eksik sayılır. GenerateHeatmaps açıkkende değişen pikseli olan her sayfa, HeatmapDirectoryde page-000003-diff.png gibi adlanan bir PNG alır: birinci dosyadaki sayfa, değişen pikseller sarıdan (eşikten azıcık ötede) kırmızıya (maksimum delta) tonlanmış olarak; yolu raporda overlayPath olarak görünür
Başarısızlıklar bildirilir, asla yutulmaz. Renderer exceptionı, eksik bir bitmap ya da geçersiz bir sayfa boyutu, mesajıyla birlikte bir renderError girdisi olur; sayfa girdisi error durumunu alır ve renderComparisonComplete false olur. Piksel boyutları farklı iki render, sizeMismatch durumu ve her iki boyutu listeleyen bir renderedImageSize farkı alır. Kimse karşılaştıramadığı bir sayfa asla eşit sayılmaz
Her modun bir işlem hattındaki (pipeline) yeri
Piksel geçişi sayfaları katı biçimde indeksle eşler: sayfa i sayfa iye, kısa belgeye kadar. Sayfa hizalaması, cmPageCount ile cmRenderedImage dışındaki her modda koşar. Araya bir kapak girdiğinde cmRenderedImage tek başına sonrasındaki her sayfayı işaretler; cmFull ise o konumsal piksel sonuçların yanı sıra hizalamayı yapısal yarısından verir. Önce yapısal kararı okuyun ve piksel sonuçlarına yalnızca sayfa listeleri hizalıyken güvenin
Her derlemede cmStructural koşturun. Ucuzdur, yolu, sayfa indeksini ve ilgili nesne numaralarını adlandırır ve beklenmedik bir objectChanged, onu üreten kodu doğrudan gösterir. cmFullü heatmaplerle sürüm adayları için ve bir iyileştirme geçişinin gerçekten kayıpsız olduğunu denetlemek için — görselleri bakacak biri varken — tutun. cmPageText, yalnızca söylemin önemli olduğu belgelere uyar. İşaretleme düzeyinde inceleme başka bir seçenektir: PDF sayfalarını SVGye dışa aktarma, sıradan diff araçlarının okuyabileceği bir metin görünümü verir ve preflight rapor otomasyonundaki kontroller, hiçbir karşılaştırma modunun yanıtlamaya çalışmadığı uyum sorularını kapsar
Karşılaştırma, preflight ve render, aynı yüklenmiş THotPDF belgesinde çalışır; tek bir yükleme üçüne de hizmet edebilir. Bileşenin Delphi ve C++Builder geliştiricileri için kapsadığı her şey HotPDF Delphi PDF bileşeni sayfasındadır