Linearize a PDF

Linearization, also known as Fast Web View, restructures a PDF so a web browser can display the first page before the whole file finishes downloading.

How it works

A standard PDF stores its objects in an order optimized for the complete file, so a viewer usually needs the whole document before it can render a page. Linearization reorganizes the file so the objects for the first page come first, followed by a hint structure that locates the remaining objects.

If a web server supports HTTP byte-range requests, a viewer can request the first page immediately and stream the rest of the document on demand.

Linearize a PDF

This procedure linearizes a document as part of optimization, using the Optimizer with the Web profile. Before you start, Initialize the Pdftools SDK license.

Open the input document

Load the input PDF from the file system into a read-only Document.

.NET

// Open input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);

Java

// Open input document
FileStream inStr = new FileStream(inPath, FileStream.Mode.READ_ONLY);
Document inDoc = Document.open(inStr);

Python

# Open input document
in_stream = io.FileIO(input_path, 'rb')
input_document = Document.open(in_stream)

Enable linearization in the output options

Create an OutputOptions object and set Linearize to true. By default, linearization is off.

.NET

// Write the output in linearized form (Fast Web View)
var outputOptions = new OutputOptions();
outputOptions.Linearize = true;

Java

// Write the output in linearized form (Fast Web View)
OutputOptions outputOptions = new OutputOptions();
outputOptions.setLinearize(true);

Python

# Write the output in linearized form (Fast Web View)
output_options = OutputOptions()
output_options.linearize = True

Write the linearized document

Pass the output options to an operation that writes a PDF. This example optimizes the document with the Web profile and applies the output options to produce a linearized result.

.NET

// Create the output stream
using var outStr = File.Create(outPath);

// Optimize the document and write it in linearized form
var optimizer = new Optimizer();
var profile = new Profiles.Web();
using var outDoc = optimizer.OptimizeDocument(inDoc, outStr, profile, outputOptions);

Java

// Create the output stream
FileStream outStr = new FileStream(outPath, FileStream.Mode.READ_WRITE_NEW);

// Optimize the document and write it in linearized form
Optimizer optimizer = new Optimizer();
Web profile = new Web();
Document outDoc = optimizer.optimizeDocument(inDoc, outStr, profile, outputOptions);

Python

# Create the output stream
with io.FileIO(output_path, 'wb+') as output_stream:

    # Optimize the document and write it in linearized form
    optimizer = Optimizer()
    profile = Web()
    optimizer.optimize_document(input_document, output_stream, profile, output_options)

tip

This example uses the Web optimization profile. However, linearization is independent of the selected optimization profile. As Linearize is a property of OutputOptions, you can also apply it during PDF/A conversion or signing. For the available profiles, review Optimization profiles.

The preceding snippets are excerpts, not complete programs. Before you run Pdftools SDK, install the package for your language and set up a license key. For setup steps, review Getting started with Pdftools SDK.

Operations that support linearization

The Linearize property of the OutputOptions object controls linearization. Enable it for operations that write a PDF and accept output options:

• Document optimization (Optimizer.OptimizeDocument)
• PDF/A conversion (Converter.Convert)
• Signing (Signer)

Linearization isn’t compatible with preserving existing digital signatures because signature preservation uses an incremental update.

Setting Linearize does not affect image-to-PDF conversion or OCR.

When to use linearization

Linearize a PDF when you serve large documents over the web and want the first page to appear before the whole file downloads. The benefit depends on the delivery path:

• Large documents served over HTTP. A linearized file lets a capable viewer display the first page while the rest streams in the background.
• Byte-range streaming. The benefit applies only when the web server supports HTTP byte-range requests and the viewer fetches pages on demand. Without range requests, the viewer still downloads the whole file.

Linearization adds processing time and a small amount of overhead to the file structure. For small documents, or documents accessed from local storage rather than streamed over the web, the benefit is minimal.