Technisch artikel

Fast Web View in PDF: wat linearisatie verandert

Open een PDF van 200 pagina's via een link en de browser blijft vaak leeg totdat het grootste deel van het bestand binnen is. Fast Web View is de Adobe Acrobat-naam voor een gelineariseerde PDF (ISO 32000-1 Bijlage F): pagina één en een kleine index staan vooraan, dus een viewer tekent pagina één vroeg en haalt latere pagina's op met een HTTP Range request. Zowel HotPDF als PDFium Component kan gelineariseerde bestanden schrijven vanuit Delphi

Dit is geen apart bestandsformaat. Een gelineariseerde PDF is een gewone PDF die elke conforme reader zonder speciale afhandeling opent; het verschil zit in de volgorde van de bytes en in twee extra structuren, het linearisatieparameterwoordenboek en de hintstroom. Twee voorwaarden bepalen of een reader ooit het voordeel merkt. Het bestand moet gelineariseerd zijn en dat blijven, wat een toegevoegde bewerking stilletjes ongedaan maakt, en de webserver moet byte-range-verzoeken beantwoorden met 206 Partial Content. Op een lokale schijf, waar zoeken naar het einde van een bestand niets kost, gedraagt een gelineariseerde PDF zich exact zoals elke andere, dus Fast Web View is puur een netwerkoptimalisatie die zich pas laat betalen bij grote documenten die rechtstreeks vanaf een URL worden geopend

Wat herschikt een gelineariseerde PDF?

Een gelineariseerde PDF verzamelt alles wat pagina één nodig heeft in een aaneengesloten blok nabij het begin van het bestand, vóór elke andere pagina. In een gewone PDF kunnen objecten in willekeurige volgorde staan, want de kruisverwijzingstabel aan het einde mapt elk objectnummer op zijn byte-offset: een reader zoekt naar de staart, leest de startxref-aanwijzer, laadt de tabel en kan dan alles vinden (de uitleg van de PDF-bestandsstructuur loopt door die header-, body-, xref- en trailer-opzet heen). Het ontwerp is uitstekend op schijf en slecht over een netwerk, waar de staart precies het deel is dat het laatst aankomt. Om pagina één te tekenen heeft een conventionele reader het paginaobject, zijn contentstream en de fonts en afbeeldingen die het gebruikt nodig, en in een ongeordend bestand kan elk daarvan in de laatste megabyte zitten

Linearisatie herschikt de volgorde. Na de header komen het linearisatiewoordenboek en een kleine kruisverwijzingssectie voor de eerste pagina, daarna de objecten op documentniveau zoals de catalog, de primaire hintstroom en de eerste pagina met al zijn resources. De resterende pagina's volgen één voor één, daarna de objecten die latere pagina's delen, en allerlaatst de hoofdtabel met kruisverwijzingen. Een reader die de optimalisatie negeert begint nog steeds achteraan en vindt elk object via de hoofdtabel, en daarom blijft een gelineariseerd bestand volledig compatibel met oudere software. Objectnummering ziet er in een hex-editor daardoor achterstevoren uit: het voorste blok draagt de hoogste nummers, terwijl alles erachter vanaf 1 wordt genummerd

Bytelayout van een gewone PDF naast een gelineariseerde PDF die Fast Web View mogelijk maakt
Een gelineariseerd bestand zet het linearisatiewoordenboek, de eerste-paginaxref en de hintstroom vóór alles anders, terwijl een gewone PDF zijn enige index aan de staart van het bestand houdt

Het linearisatiewoordenboek en de hinttabellen

Het eerste object na de %PDF-header is het linearisatieparameterwoordenboek, en Bijlage F eist dat het binnen de eerste 1024 bytes staat zodat een streaming reader het in het openingspakket vindt. Tabel F.1 somt zijn ingangen op: /L is de lengte van het hele bestand in bytes, /H de offset en lengte van de primaire hintstroom, /O het objectnummer van de eerste pagina, /E de offset waar de eerste pagina eindigt, /N het aantal pagina's en /T de offset van de eerste ingang in de hoofdtabel met kruisverwijzingen. De /L-ingang weegt zwaarder dan hij lijkt. Wanneer hij niet overeenkomt met de echte bestandsgrootte, zegt Tabel F.1 tegen de reader het document als een gewone PDF te behandelen en elke hint erin te negeren

De hintstroom is wat een sprong naar pagina 40 goedkoop maakt. Hij bevat een page offset hinttabel, die voor elke pagina vastlegt waar zijn objecten beginnen en hoeveel bytes ze beslaan, en een shared object hinttabel die hetzelfde doet voor fonts, logo's en andere resources die op meerdere pagina's worden gebruikt. Een reader die pagina 40 wil, zoekt zijn bytebereik op, vraagt exact die plak op en rendert zodra die aankomt, en haalt elke shared object die hij nog niet heeft op dezelfde manier binnen. Twee details laten zelfgebakken linearizers struikelen. Hint-offsets zijn logisch, berekend alsof de hintstroom zelf afwezig was, dus een writer die fysieke offsets opslaat stuurt elk later range-verzoek evenveel mis als de grootte van het hintobject. En een writer die bij het verzamelen van de resources de /Parent-link van een pagina volgt, loopt terug door de paginaboom en sleept het hele document mee naar de eerste-paginasectie. Beide bestanden beweren nog steeds gelineariseerd te zijn. Geen van beide laadt sneller

Waarom heeft Fast Web View de hulp van de server nodig?

Fast Web View werkt alleen wanneer de server op verzoek willekeurige plakken van het bestand levert. De reader stuurt HTTP-verzoeken met een Range-header en verwacht 206 Partial Content terug; als de server nooit Accept-Ranges: bytes adverteert, of een proxy of CDN ervoor range-verzoeken laat uitmonden in volledige overdrachten, kan de reader pagina 40 niet zelf ophalen en downloadt hij het hele bestand. De structuur in de PDF is dan correct en volledig verspild, en dit is de fout die het vaakst ten onrechte wordt gediagnosticeerd als kapotte linearisatie. Vraag voordat u een document herbouwt de eerste kilobyte op van de exacte URL die de viewer opent, bijvoorbeeld met curl -r 0-1023, en bevestig dat de status 206 is. Statische file hosts krijgen dit doorgaans standaard goed, terwijl application endpoints die PDF's door hun eigen handler sturen dat vaak niet doen

Linearisatiehinttabellen die een HTTP range-verzoek aandrijven dat 206 Partial Content teruggeeft voor één pagina van een Fast Web View-PDF
Hinttabellen geven de reader het bytebereik van elke pagina, dus een host die ranges ondersteunt levert pagina 40 met één partiéle respons; zonder byte-serving wordt weer het hele bestand gedownload

Hoe controleert u of een PDF Fast Web View heeft?

Controleer de bytes in plaats van de tool te vertrouwen die het bestand produceerde, en controleer beide helften van de voorwaarde: het bestand verklaart zichzelf gelineariseerd, en die verklaring matcht nog steeds met het bestand op schijf. Drie controles dekken vrijwel elk geval, van een snelle blik op een desktop tot een geautomatiseerde poort in een publicatiepijplijn:

  • Adobe Acrobat or Reader: open File > Properties; the Description tab shows Fast Web View: Yes or No in its lower-right corner. Acrobat reports Yes only when the structure is present and current, so a file edited after linearization shows No
  • qpdf on the command line: qpdf --check-linearization validates the hint tables against the real object positions, and qpdf --show-linearization dumps the dictionary and every hint table entry
  • The first kilobyte of the file: open it in a text or hex editor and look for an object containing /Linearized 1 within the first 1024 bytes; when it is there, compare its /L value with the file size reported by the operating system
# Toetst het linearisatiewoordenboek en de hinttabellen aan de layout
qpdf --check-linearization report-web.pdf

# Dumpt /L, /H, /O, /E, /N, /T en elke hinttabelingang
qpdf --show-linearization report-web.pdf

De qpdf-controle is degene die de moeite waard is om in een pipeline in te bouwen, want hij toetst de hinttabellen af tegen de werkelijke objectposities; een controle die alleen bevestigt dat het woordenboek bestaat, verklaart ook een bestand in orde waarvan de offsets naar de verkeerde bytes wijzen. Vanuit Delphi meldt THotPDF.IsLoadedLinearized in HotPDF of een geladen document zichzelf gelineariseerd verklaart, door de eerste 1024 bytes te scannen op /Linearized voor de parsing. PDFium Component beantwoordt dezelfde vraag via de class function TPdf.InspectAvailability, waarvan het veld Linearization plnLinearized, plnNotLinearized of plnUnknown teruggeeft zonder het document überhaupt te laden. Beide vlaggen rapporteren wat het bestand verklaart; de /L-vergelijking vertelt u of die verklaring nog steeds matcht met de bytes op schijf:

uses
  System.SysUtils, System.Classes, System.Math, System.StrUtils, PDFium;

type
  TFastWebView = (fwvNo, fwvStale, fwvYes);

// Uw eigen helper: PDFium beslist of het bestand gelineariseerd is,
// en de /L-vergelijking vangt bewerkingen die daarna zijn toegevoegd
function FastWebViewState(const FileName: string): TFastWebView;
var
  Stream: TFileStream;
  Head: AnsiString;
  Text: string;
  P, Q: Integer;
begin
  Result := fwvNo;
  Stream := TFileStream.Create(FileName, fmOpenRead or fmShareDenyWrite);
  try
    if TPdf.InspectAvailability(Stream).Linearization <> plnLinearized then
      Exit;
    SetLength(Head, Min(Stream.Size, 1024));   // Bijlage F: eerste 1024 bytes
    Stream.Position := 0;
    if Length(Head) > 0 then
      Stream.ReadBuffer(Head[1], Length(Head));
    Text := string(Head);
    P := Pos('/Linearized', Text);
    if P = 0 then
      Exit;
    P := PosEx('/L ', Text, P + Length('/Linearized'));
    if P = 0 then
      Exit;
    Inc(P, 3);
    Q := P;
    while (Q <= Length(Text)) and CharInSet(Text[Q], ['0'..'9']) do
      Inc(Q);
    if StrToInt64Def(Copy(Text, P, Q - P), -1) = Stream.Size then
      Result := fwvYes
    else
      Result := fwvStale;   // een keer gelineariseerd, daarna gewijzigd
  finally
    Stream.Free;
  end;
end;

Fast Web View aanzetten in Acrobat, qpdf en Delphi

Elke tool die het hele bestand in Bijlage F-volgorde herschrijft, kan Fast Web View aanzetten, en het belangrijkste is dat die als laatste draait. Zet in Acrobat Save As optimizes for Fast Web View aan onder Preferences > Documents en gebruik daarna File > Save As in plaats van Save, want een kale Save kan een incrementele update toevoegen. Op een server of in een buildscript herschrijft qpdf --linearize in.pdf out.pdf elke PDF naar gelineariseerde vorm en laat de invoer onaangetast. Delphi-code heeft twee routes, afhankelijk van of u het document genereert of ontvangt. HotPDF schrijft gelineariseerde uitvoer direct wanneer THotPDF.LinearizeOutput True is; zet dat samen met de andere uitvoeropties vóór BeginDoc, en de Bijlage F-layout wordt berekend en weggeschreven binnen EndDoc:

qpdf --linearize report-final.pdf report-web.pdf
var
  PDF: THotPDF;
begin
  PDF := THotPDF.Create(nil);
  try
    PDF.AutoLaunch := False;       // opent geen viewer na EndDoc
    PDF.FileName := 'catalog-web.pdf';
    PDF.LinearizeOutput := True;   // vóór BeginDoc zetten
    PDF.BeginDoc;                  // pagina 1 bestaat na BeginDoc
    PDF.CurrentPage.TextOut(72, 72, 0, 'Spring catalog');
    PDF.AddPage;
    PDF.CurrentPage.TextOut(72, 72, 0, 'Price list');
    PDF.EndDoc;                    // hier wordt de gelineariseerde layout geschreven
  finally
    PDF.Free;
  end;
end;

Voor bestanden die al bestaan biedt PDFium Component TPdf.SaveAsLinearized. Die draait de gewone PDFium-opslag naar een tussentijdse store, zodat paginabewerkingen en formuliervelden hetzelfde pad volgen als elke andere opslag, en herschikt die uitvoer vervolgens volgens Bijlage F voordat uw doel wordt weggeschreven. De methode heeft dezelfde TSaveOption- en TPdfVersion-parameters als SaveAs, weigert saIncremental en elke versie onder PDF 1.2, en zijn overload met bestandsnaam schrijft naar een tijdelijk bestand dat het doel pas vervangt nadat de opslag geslaagd is. Omdat de writer het bestand vanuit de huidige revisie herbouwt, is het ook de manier om Fast Web View te herstellen op een bestand dat toegevoegde bewerkingen heeft opgelopen. Versleutelde invoer heeft saRemoveSecurity nodig: objecten hernummeren maakt de per-object-sleutels van de standaard security handler ongeldig (ISO 32000-1 §7.6.2), dus de webkopie wordt zonder versleuteling geschreven

var
  Pdf: TPdf;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := 'manual-rev3.pdf';   // bevat toegevoegde bewerkingen
    Pdf.Active := True;
    if not Pdf.SaveAsLinearized('manual-web.pdf', saNoIncremental) then
      raise Exception.Create('Linearized save failed');
  finally
    Pdf.Free;
  end;
end;

Incrementele updates zetten Fast Web View stilletjes uit

Een incrementele update is de meest voorkomende reden dat een correct gelineariseerd bestand later Fast Web View verliest. Wanneer een tool een handtekening toevoegt, een formulierveld invult of een sticky note plakt via een incrementele opslag, laat hij de oorspronkelijke bytes onaangeroerd en voegt de gewijzigde objecten, een nieuwe kruisverwijzingssectie en een nieuwe trailer achteraan toe. Het linearisatiewoordenboek vooraan beschrijft nog steeds de oude layout, zijn /L matcht niet langer met de bestandsgrootte, en een conforme reader behandelt het document weer als een gewone PDF, ook al zit de gelineariseerde structuur nog intact in het eerste deel van het bestand. HotPDF voegt precies dit soort revisie toe via BeginIncrementalUpdate en SaveIncrementalUpdate, wat het juiste gereedschap is zolang een document nog verandert en de verkeerde laatste stap voor een bestand dat naar een webserver gaat:

// Voegt een revisie toe: snel, houdt de eerdere bytes intact,
// en laat het resultaat zonder Fast Web View achter
PDF.BeginIncrementalUpdate('report.pdf');
PDF.AddPage;
PDF.CurrentPage.TextOut(72, 760, 0, 'Addendum');
PDF.SaveIncrementalUpdate('report-rev2.pdf');
Incrementele updates stapelen revisies op die het linearisatiewoordenboek ontregelen totdat één definitieve herschrijving Fast Web View herstelt
Elke incrementele opslag stapelt nog een revisie achter het verouderde woordenboek vooraan; eindigen met een volledige herschrijving en pas op het laatst herlineariseren houdt Fast Web View intact

De werkbare regel is om incrementeel te bewerken zolang een document in beweging is, één keer te lineariseren als allerlaatste stap, en Fast Web View achterwege te laten voor bestanden die worden gemaild of gedownload voordat iemand ze opent, want ze hebben niets aan de grotere voorgeladen index. Ondertekende documenten dwingen een echte keuze af: een volledige herschrijving verandert de bytes die de /ByteRange van elke handtekening dekt, en ondertekenen daarna voegt een update toe die de /L-mismatch meteen terugbrengt, dus voor contracten houdt u de handtekening en accepteert u volledige downloads. De schrijfkant van Bijlage F, inclusief hoe offsets convergeren voordat de eerste byte wordt geschreven en waarom gelineariseerde uitvoer objectstreams opgeeft, staat in gelineariseerde PDF's schrijven met HotPDF-hinttabellen en Fast Web View-linearisatie met PDFium Component in Delphi. LinearizeOutput en IsLoadedLinearized worden meegeleverd met de HotPDF Delphi Component, terwijl SaveAsLinearized en InspectAvailability deel uitmaken van PDFium Component for Delphi, C++Builder and Lazarus