PurgeUnusedResources

Document manipulation, Optimisation

Description

Scans the selected page content layers and their transitive resource dependencies, then removes named resources that are not referenced in the applicable resource scope

The default options recurse into Form XObjects, tiling patterns, Type 3 glyphs, annotation appearances, and soft-mask groups, retain colour spaces referenced by images and other resources, remove deprecated /ProcSet arrays and empty resource categories, and collect indirect objects made unreachable by the cleanup

Syntax

Delphi

Function TPDFlib.PurgeUnusedResources(Const PageRange: WideString= '';
  Options: Integer= PDF_RESOURCE_PURGE_DEFAULT): Integer; Overload;

Function TPDFlib.PurgeUnusedResources(Const PageRange: WideString;
  Options: Integer; Out Stats: TPDFlibResourcePurgeStats): Integer; Overload;

Parameters

PageRange	A 1-based page range using the same syntax as the other page-range APIs, or an empty string for every page
Options	A bitwise combination of the resource purge option constants
Stats	Receives scan, safety, removal, and orphan-object counters

Options

PDF_RESOURCE_PURGE_RECURSE_FORMS	Scans referenced Form XObjects and respects their own or inherited resource scope
PDF_RESOURCE_PURGE_REMOVE_PROCSET	Removes deprecated `/ProcSet` arrays
PDF_RESOURCE_PURGE_REMOVE_EMPTY	Removes empty resource category dictionaries
PDF_RESOURCE_PURGE_AGGRESSIVE_UNKNOWN	Allows cleanup when a content stream contains an unknown operator
PDF_RESOURCE_PURGE_DRY_RUN	Reports removable named entries without mutating the document
PDF_RESOURCE_PURGE_GARBAGE_COLLECT	Collects indirect objects made unreachable after live cleanup
PDF_RESOURCE_PURGE_RECURSE_PATTERNS	Scans the content and independent resource scope of referenced tiling patterns
PDF_RESOURCE_PURGE_RECURSE_TYPE3	Scans every CharProc stream in referenced Type 3 fonts using the font resource scope
PDF_RESOURCE_PURGE_RECURSE_APPEARANCES	Scans normal, rollover, down, and named-state annotation appearance streams
PDF_RESOURCE_PURGE_RECURSE_SOFT_MASKS	Scans transparency group streams referenced by ExtGState soft-mask dictionaries
PDF_RESOURCE_PURGE_SCAN_IMAGE_DEPENDENCIES	Inspects image XObjects, explicit masks, soft-mask images, and alternate images for nested dependencies
PDF_RESOURCE_PURGE_RECURSE_DEPENDENCIES	Combines pattern, Type 3, appearance, soft-mask, and image dependency analysis
PDF_RESOURCE_PURGE_DEFAULT	Combines all dependency analysis, Form recursion, ProcSet removal, empty-category removal, and garbage collection

Return values

Live cleanup	The number of named resource entries removed
Dry run	The number of named resource entries that can be removed
0	No removable named entries, no selected pages, or no loaded document

Remarks

The scan recognises Font, XObject, ExtGState, ColorSpace, Pattern, Shading, and Properties references, including custom colour spaces in inline image dictionaries and indirect dependencies carried by resource objects

Dependency closure covers image and shading colour spaces, Indexed bases, Separation and DeviceN alternates, Pattern underlying spaces, ICCBased alternates, tiling-pattern content, all Type 3 CharProcs, annotation appearance states, ExtGState soft-mask groups, image masks, soft-mask images, and alternate images

PDF names are matched case-sensitively and all content layers of each selected page are combined before cleanup

Malformed streams and unknown operators preserve their complete resource scope unless PDF_RESOURCE_PURGE_AGGRESSIVE_UNKNOWN is set

Shared and inherited resource dictionaries are copied before mutation so cleanup remains local to the selected page, Form, pattern, Type 3 font, appearance, or soft-mask group

Repeated streams and dependency entries reuse cached parse results, while depth limits and active-stream tracking terminate malformed resource cycles

Cancellation is available through Abort from an OnProgress handler

Example

var
  Stats: TPDFlibResourcePurgeStats;
  Removed: Integer;
begin
  Removed:= PDF.PurgeUnusedResources('1-20',
    PDF_RESOURCE_PURGE_DEFAULT, Stats);
  PDF.SaveToFile('optimised.pdf');
end;