TL;DR: When a compressed PDF looks blurry, debug embedded image resolution before changing compression settings. Keep the archival PDF unchanged, own the watermark template, and generate a separate external-sharing derivative. Test four boundaries: source pixels, placed size, downsampling policy, and final rendered output. A 2400-pixel-wide scan placed at 8 inches is 300 pixels per inch; at 16 inches it is 150. Geometry often explains the blur before any codec does.
| Choice | Template owner | Archive behavior | Best fit | Main risk |
|---|---|---|---|---|
| Owned sharing template | Your team | Preserve source; create derivative | Regulated documents with stable disclosure rules | You maintain layout tests |
| Processor-owned template | External processor | Accept rendered derivative | Fast, low-sensitivity experiments | Resampling rules may be harder to inspect |
Recommendation: own the sharing template and treat the watermarked file as a derivative, never the archival master. This puts page geometry, watermark placement, and image policy in one versioned change.
Why does a compressed PDF look fuzzy after watermarking?
A PDF page is a coordinate system, not a promise that every embedded image has enough pixels for every display size. The useful diagnostic is effective pixel density: image pixels divided by physical placement size. Compression changes representation; downsampling discards pixels. Tuning compression teaches nothing if an image was already reduced upstream.
The watermark stage may trigger a full-page render and rebuild. A vector watermark added as page content can remain independent of existing raster images. A pipeline that rasterizes the entire page first creates a new image at a chosen resolution, so text, signatures, and fine statement lines inherit that ceiling. Same thumbnail. Very different architecture.
Start there.
Do not debug by file size alone. A small file can contain adequate vector content, while a large file can contain an under-resolved scan. Inspect objects and geometry, then render representative pages under target viewing conditions.
The two criteria that decide template ownership
First is control over transformation boundaries. An owned template can declare the master immutable, keep the watermark as separate page content, and permit resampling only for selected images. Account statements, signed authorizations, and supporting scans do not tolerate the same loss. One global setting is config bloat disguised as simplicity.
Second is reproducibility. A useful job record captures the source digest, template version, placement dimensions, source pixel dimensions, resampling decision, and output digest. Six fields beat thirty undocumented defaults.
The trade-off is maintenance. Template owners must test rotation, crop boxes, transparency, font availability, and watermark contrast. A processor-owned template moves that work elsewhere, but also moves the evidence needed to explain why a 1200-pixel signature softened on a wide placement. For regulated sharing, the evidence wins.
A 4-test TypeScript preflight
Keep preflight boring. It should consume metadata from a standards-aware PDF inspector, not pretend that searching raw bytes is PDF parsing. This calculation decides policy after inspection reports each raster image's dimensions and placed bounds.
interface PlacedImage {
objectId: string;
pixelWidth: number;
pixelHeight: number;
widthPoints: number;
heightPoints: number;
}
interface ImageCheck {
objectId: string;
horizontalPpi: number;
verticalPpi: number;
belowTarget: boolean;
}
const pointsPerInch = 72;
function inspectDensity(image: PlacedImage, targetPpi: number): ImageCheck {
if (image.pixelWidth <= 0 || image.pixelHeight <= 0 ||
image.widthPoints <= 0 || image.heightPoints <= 0 || targetPpi <= 0) {
throw new RangeError("Dimensions and targetPpi must be positive");
}
const horizontalPpi = image.pixelWidth / (image.widthPoints / pointsPerInch);
const verticalPpi = image.pixelHeight / (image.heightPoints / pointsPerInch);
return {
objectId: image.objectId,
horizontalPpi,
verticalPpi,
belowTarget: Math.min(horizontalPpi, verticalPpi) < targetPpi,
};
}
const signature = inspectDensity({
objectId: "signature-7",
pixelWidth: 1200,
pixelHeight: 450,
widthPoints: 288,
heightPoints: 108,
}, 300);
console.log(signature);
The example places an image at 4 by 1.5 inches. Both axes calculate to 300 pixels per inch. Change only widthPoints to 576 and horizontal density falls to 150. No compression flag changed.
The easy mistake is to compare only the input scan with the final PDF and then blame the last visible step. Use one statement page as a trace instead. Record its 2400-by-3000 source image, the bounds reported after placement, and the same values after watermarking. If the pixels are unchanged but the bounds doubled, placement caused the density drop. If the bounds are stable but the pixel dimensions shrink, a resampling stage did it. If both remain stable while the rendered preview looks soft, compare the preview scale and renderer before touching document generation. This sequence is deliberately cheap: metadata checks run before image comparisons, and image comparisons run before anyone adds another quality option to production configuration. It also assigns ownership. The intake path owns source pixels, the template owns placement, the derivative worker owns resampling, and the viewer owns preview rendering.
Run four tests in order. First, record pixel dimensions before generation. Second, calculate effective density from final placement bounds. Third, compare image metadata before and after watermarking to detect resampling. Fourth, render the derivative at a fixed scale and compare it with a known-good render. Stop at the first boundary where evidence changes.
Visual comparison needs care. Anti-aliasing can change pixels without changing legibility, so raw pixel equality is too brittle across renderers. Use deterministic fixtures for geometry, then review representative text, line art, scans, and signatures at intended display size. Keep the original fixture beside its expected derivative.
When the runner-up is the better choice
A processor-owned template is reasonable when the watermark is temporary, documents are low-risk copies, and time-to-first-call matters more than exact transformation evidence. It can fit a prototype whose only question is whether recipients understand the mark. Avoid building a template subsystem before answering that question.
There is a hard boundary. If the processor cannot report placed dimensions, resampling behavior, or full-page rasterization, blur diagnosis becomes output-only. That trade-off may work for disposable previews. Do not make the result an archival master.
The boring deployment pattern wins: immutable input, versioned template, deterministic derivative key, and a failure state that preserves the source. Track page count, render duration, output size, and images below your chosen density threshold. Those signals locate regressions without exposing document contents in logs.
Choose owned templates when auditability and stable page geometry dominate. Choose processor-owned templates when experimentation speed dominates and the derivative can be discarded. In both cases, preserve the source PDF and measure effective image density before changing compression settings.
Pixels divided by placement size first. Codec arguments later.
Further reading
- ISO 32000-2, Portable Document Format: https://www.iso.org/standard/75839.html
Top comments (0)