DeduplicateSimilarImages

Image handling, Optimisation

Description

Finds perceptually similar indirect image XObjects, redirects their references to a deterministic canonical image, and optionally removes the duplicate objects

Candidates must have the same semantic image dictionary after excluding encoded-container fields, then pass a 64-bit difference-hash threshold and a 64 × 64 decoded colour-sample comparison

Syntax

Function TPDFlib.DeduplicateSimilarImages(
  MaxHashDistance, MaxMeanError, MaxChannelError,
  Options: Integer): Integer; Overload;

Function TPDFlib.DeduplicateSimilarImages(
  MaxHashDistance, MaxMeanError, MaxChannelError,
  Options: Integer;
  Out Stats: TPDFlibImageSimilarityDedupStats): Integer; Overload;

Parameters

MaxHashDistance	Maximum Hamming distance from 0 to 7 between the two 64-bit difference hashes
MaxMeanError	Maximum mean absolute channel difference from 0 to 255 across the decoded samples
MaxChannelError	Maximum absolute difference from 0 to 255 for any sampled colour channel
Options	`PDF_RESOURCE_DEDUP_DRY_RUN`, `PDF_RESOURCE_DEDUP_GARBAGE_COLLECT`, both flags, or 0
Stats	Receives decoding, candidate, comparison, accepted-error, reference, payload, and object-collection counters

Return values

Positive value	The number of similar image objects consolidated or reported by a dry run
0	No acceptable pair was found, no document is loaded, or a threshold or option is invalid

Remarks

The lowest object number and generation in each accepted group becomes the canonical image

/Length, /Filter, and /DecodeParms describe encoded storage and may differ, while dimensions, colour space, bit depth, masks, decode arrays, interpolation, optional content, metadata, and other semantic dictionary entries must match

Images that cannot be decoded are skipped and counted in DecodeFailures

The hash is split into eight indexed bands, which bounds the candidate search for the supported distance range before decoded samples are compared

This is an intentionally approximate visual operation because it samples a fixed 64 × 64 grid, so differences smaller than the sampling grid can be missed even when every threshold is zero

Use DeduplicateResources when byte-exact proof is required, and use a dry run plus GetSimilarImageDeduplicationReportJSON before choosing thresholds for unfamiliar content

Example

var
  Stats: TPDFlibImageSimilarityDedupStats;
  Merged: Integer;
begin
  Merged:= PDF.DeduplicateSimilarImages(2, 3, 12,
    PDF_RESOURCE_DEDUP_GARBAGE_COLLECT, Stats);
  PDF.SaveToFile('optimised.pdf');
end;