Optimizing documents
editPdfOptimizer works in two steps: CreatePlan lists the changes the options ask for without making them, and Apply makes those that are enabled:
var document = PdfDocument.Open(file);
var plan = PdfOptimizer.CreatePlan(document, new PdfOptimizationOptions
{
RemoveMetadata = true,
RemoveJavaScript = true,
RemoveAttachments = true,
RemovePageThumbnails = true,
RemoveComments = true,
RemoveBookmarks = true,
PruneUnusedResources = true,
PruneUnreachableObjects = true,
});
// Inspect the plan, and leave out what must be kept
var json = plan.ToJson(indented: true);
foreach (var action in plan.Actions.Where(action => action.Kind == PdfOptimizationActionKind.RemoveBookmarks))
{
action.IsEnabled = false;
}
var applied = PdfOptimizer.Apply(plan);
var optimized = document.ToByteArray();The plan is a list of PdfOptimizationAction: the kind of change, a description, and the page, object or resource it concerns. Show it to a user, log it, or keep it with ToJson; set IsEnabled to false to leave an action out. Apply returns the actions that changed the document. The changes are made to the document: save it to write them.
What can be planned
Every option of PdfOptimizationOptions is off by default:
| Option | Changes |
|---|---|
| RemoveMetadata | The document information dictionary and the XMP metadata |
| RemoveJavaScript | The scripts of the document, and the actions that run scripts: of the document, its pages, annotations and fields |
| RemoveAttachments | The embedded files and the file attachment annotations |
| RemovePageThumbnails | The thumbnail images of the pages |
| RemoveComments | The markup annotations (notes, highlights, stamps, drawings...) and their pop-ups; links and widgets are kept |
| RemoveOpenAction | The action run when the document is opened |
| RemoveXfa | The XFA form; the AcroForm fields are kept |
| RemoveFormFields | The interactive form and the widgets of its fields. To keep the values on the pages, flatten the form instead |
| RemoveBookmarks | The outline |
| FlattenOptionalContent | The layers: the content hidden in the default configuration is removed, the visible content is kept as ordinary content |
| PruneUnusedResources | The fonts, images, graphics states... of the pages that their content does not use |
| PruneUnreachableObjects | The objects that nothing refers to |
| CompressStreams | The streams without filter, compressed with FlateDecode when it makes them smaller |
| MaxImageResolution | The images shown at a higher resolution than this one, resampled to it |
- A full save writes only the objects that can be reached and compresses the streams (CompressStreams): pruning the unreachable objects and compressing the streams matter for an incremental save, which writes the objects removed as free entries and the streams as they are.
- The unused resources are removed from the resource dictionaries that only pages use, by the names of their content. A dictionary that a form, a pattern or an annotation shares with the pages is kept as it is, and so are the resources of a page whose content cannot be read.
- The resolution of an image is the highest of its placements on the pages. The images of 8 bits per component in gray or RGB (device or ICC-based color spaces) are resampled; the others (CMYK, indexed, masks, decode arrays) are kept. A JPEG image is compressed as JPEG again, the others without loss. A resampled image is stored in sRGB.
- The optional content is evaluated with the default configuration of the document, without its visibility expressions. The hidden content still changes the graphics state (a transformation, a clipping, a color): only its painting is removed. The layers of the document are removed only when the optional content of every page was flattened: not when a page action is disabled, or when visible text continues hidden text on the same line, whose position would change.
- The default color spaces (
DefaultGray,DefaultRGB,DefaultCMYK) are always kept: the content uses them without naming them.
Signed documents
Any change to a signed document invalidates its signatures. HasSignatures tells whether the document has signed fields, and InvalidatesSignatures whether the plan changes it: Apply then throws InvalidOperationException, unless the plan was created with AllowSignatureInvalidation.
Repair harmless issues
PdfSaveSanitizer repairs issues that are harmless but that some readers handle badly, with one incremental update that keeps the bytes of the file:
var result = PdfSaveSanitizer.Sanitize(data);
var repaired = result.Output;| PdfSanitizerRepairKind | Repair |
|---|---|
| DanglingOutlineRoot | The outline entry of the catalog refers to something that is not an outline: it is removed |
| EmptyOutlineRoot | The outline has no item: it is removed |
| DegenerateCropBox | The crop box of a page has no area inside the media box: it is removed, so the page shows its media box |
| CropBoxOutsideMediaBox | The crop box extends outside the media box: it becomes its intersection with the media box, which is what readers show |
A file without these issues is returned as it is, byte for byte (HasChanges is false). A damaged file, whose cross-reference information the reader rebuilt, cannot be updated incrementally: Sanitize throws InvalidOperationException when it needs repairs.