# PDF Image Quality – Help

This tool analyzes images embedded in PDF documents and reports basic print-readiness / visual quality heuristics.
It extracts images, computes metrics, and generates per-PDF outputs.

> Tips:
> - Hover over table cells / tags to see tooltips.
> - If a value is missing, the metric could not be computed for that image.

---

## Quick workflow

1. **Select input** → choose one or more PDF files.
2. **File** dropdown → pick which PDF you want to inspect.
3. **Analyze** → analyze all loaded PDFs.
4. **Results table** → click a row to see the image preview, image details and recommendations.

### Duplicate filenames are not allowed
When you select multiple PDFs, their **filenames (without extension)** must be unique.
Outputs are based on the filename, so duplicates would overwrite each other. Rename the files and select again.

---

## Outputs

For each input PDF named `MyThesis.pdf`, the tool writes:

- `OUTPUT_DIR/MyThesis.csv` – one row per image draw call (occurrence)
- `OUTPUT_DIR/MyThesis/` – extracted images saved to disk

---

## Table columns (what each column means)

### Page
PDF page number (starts at 1).

### Image ID
A stable ID combining page and the order of the image on that page (e.g., `p1_Im2` = 2nd image on page 1).

### DPI
The image’s effective resolution on the page (based on pixel size and displayed size in the PDF).
Higher DPI generally means sharper print; **≥ 300 DPI** is commonly recommended for print.

Tag thresholds used:
- **Low DPI**: min(X/Y) < **200**
- **Borderline DPI**: **200–299**
- **Not flagged**: ≥ **300**

> Note: DPI may be shown as one number (X≈Y) or `X×Y` if the two directions differ.

### Shadow clip [%]
Percentage of pixels at exact value `0` (pure black). Higher values can mean lost shadow detail.

Typical interpretation:
- ~0–0.5%: usually very good
- >0.5%: check if important shadow details are lost

Tag thresholds used:
- **Moderate Shadow Clip**: **0.5–5%**
- **High Shadow Clip**: **> 5%**

### Highlight clip [%]
Percentage of pixels at exact value `255` (pure white). Higher values can mean lost highlight detail.

Typical interpretation:
- ~0–0.5%: usually very good
- >0.5%: check if important highlight details are lost

Tag thresholds used:
- **Moderate Highlight Clip**: **0.5–5%**
- **High Highlight Clip**: **> 5%**

### Contrast (P1–P99) [%]
A simple contrast indicator based on the difference between the 1st and 99th percentile of brightness,
normalized to **0–100%**. Higher values usually mean a punchier image; very low values can look flat.

Tag thresholds used:
- **Low Contrast**: < **5%**
- **Borderline Contrast**: **5–10%**
- **Not flagged**: ≥ **10%**

### Colorfulness (HS)
An estimate of perceived colorfulness using the Hasler–Süsstrunk opponent-channel measure (unitless).
Higher values indicate more vibrant, saturated color; grayscale images are near zero.

Reference points (approx., from the original scale):
- ≈ 0 – not colourful (grayscale)
- ≈ 15 – slightly colourful
- ≈ 33 – moderately colourful
- ≈ 45 – averagely colourful
- ≈ 59 – quite colourful
- ≈ 82 – highly colourful
- ≈ 109 – extremely colourful

Tag thresholds used:
- **Low Colorfulness**: < **15**
- **Limited Colorfulness**: **15–33**
- **Not flagged**: ≥ **33**

### Color richness [%]
An estimate of overall color diversity (0–100%), computed as normalized Shannon entropy of a quantized RGB histogram.
Lower values suggest fewer effectively used colors (e.g., grayscale or limited palette).

Tag thresholds used:
- **Low Color Richness**: < **20%** (very limited palette)
- **Limited Color Richness**: **20–33.3%** (limited palette)
- **Not flagged**: ≥ **33.3%**

> Note: Monochrome or intentionally minimalistic images can naturally score low here.

### Recommendations
A comma-separated list of non-blocking suggestions (tags) derived from the metrics.
If set to **All Good**, nothing notable was detected.

### BBox [cm]
The image’s bounding box on the page, in centimeters (page coordinate space).
Useful for locating the image and understanding its printed size.

### Page dimensions [cm]
The page size in centimeters (width × height).

---

## Recommendations (tag meanings)

These tags are **friendly suggestions**, not errors. Always consider the actual content and purpose of the image.

- **Low DPI** – min(X/Y) DPI is **below 200**. Often too soft for quality print.
- **Borderline DPI** – min(X/Y) DPI is **200–299**. Usually OK on-screen; print may benefit from ≥300.

- **Moderate Shadow Clip** – **0.5–5%** of pixels are exactly pure black (`0`), so some shadow detail may be lost.
- **High Shadow Clip** – **>5%** of pixels are exactly pure black (`0`), so shadow detail loss is more likely.

- **Moderate Highlight Clip** – **0.5–5%** of pixels are exactly pure white (`255`), so some highlight detail may be lost.
- **High Highlight Clip** – **>5%** of pixels are exactly pure white (`255`), so highlight detail loss is more likely.

- **Low Contrast** – Contrast (P1–P99 spread) is **<5%**; image likely looks flat/low-contrast.
- **Borderline Contrast** – Contrast (P1–P99 spread) is **5–10%**; close to low-contrast threshold.

- **Low Colorfulness** – **<15** (HS units); image looks nearly grayscale.
- **Limited Colorfulness** – **15–33** (HS units); modest color intensity.

- **Low Color Richness** – **<20%**; extremely limited palette.
- **Limited Color Richness** – **20–33.3%**; limited palette.

If no tag applies, the **Recommendations** cell is set to **All Good**.

---

## Notes & limitations

- PDF pages may draw the *same embedded image* multiple times (different positions/scales). The report is occurrence-based.
- Some PDFs flatten a single figure into many small tiles. The tool may warn about suspected tiling (heuristic).
- Values are heuristics: they help you quickly spot potential problems, but they are not absolute “pass/fail”.

