Metadata-Version: 2.4
Name: pdf-hidden-text-inspector
Version: 0.2.0
Summary: Local PDF hidden-text inspection with visual evidence
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pypdfium2>=4.30
Requires-Dist: pypdf>=5
Requires-Dist: Pillow>=10
Dynamic: license-file

# PDF Hidden Text Inspector

Inspect PDFs for text that extraction can read but a person may not see or easily notice on the page. The tool compares native PDF text with rendered pixels and local OCR, then writes an HTML evidence report and machine-readable JSON. It runs locally and does not send PDFs to a model or cloud service.

This is an early inspection tool. Findings need human review; a completed scan is not a claim that a PDF is safe.

## Install

Requires Python 3.10 or newer.

```powershell
py -m pip install pdf-hidden-text-inspector
```

Until the first PyPI release, install from a local copy of this project:

```powershell
py -m pip install .
```

Windows uses built-in Windows OCR by default. On other systems, install Tesseract separately and make sure its executable is on `PATH`. OCR can be disabled with `--ocr none`, but the resulting scan will be marked partial.

## Use

```powershell
inspect-pdf-hidden-text "C:\path\document.pdf" --out report
```

Open `report/report.html` to review highlighted page images and findings. Use `report/report.json` for structured results. Options include `--ocr auto|windows|tesseract|none`, `--lang eng`, and `--max-pages N`. For example:

```powershell
inspect-pdf-hidden-text "C:\path\document.pdf" --out report --ocr tesseract --lang eng+chi_tra
```

Exit code `0` means all implemented checks completed. Exit code `2` means coverage is partial, such as when OCR is unavailable, pages were skipped, or a page failed. The report records the specific coverage and errors. Neither exit code is a security verdict.

Reports contain extracted document text and rendered pages. Handle them like the source PDF.

## What it checks

The inspector highlights very small or invisible PDF text, near-transparent text, text outside the visible page, regions with little rendered variation, and differences between native text and OCR in the same region. It also checks selected metadata and annotation fields for instruction-like wording. It distinguishes a possible legitimate OCR text layer when invisible text agrees with visible OCR.

The heuristic checks can produce false positives, especially for formulas, unusual fonts, and languages that OCR handles poorly. Some PDF channels are not covered, including disabled optional-content layers, arbitrary clipping, attachment contents, and historical revisions. The project source includes further coverage notes.

## Develop and test

```powershell
py -m pip install -r inspect-pdf-hidden-text/requirements.txt
py -m pip install reportlab
py inspect-pdf-hidden-text/tests/test_inspector.py --out outputs/tests
```

The controlled fixtures exercise concealment methods, normal text, white text on a dark panel, OCR overlays, annotation text, and partial coverage. The packaged command and the underlying script share the same scanner.

## 中文簡介

這個工具在本機檢查 PDF 中「文字擷取讀得到，但頁面畫面看不到或難以閱讀」的內容，輸出 HTML 與 JSON 證據報告。候選項目需要人工確認；完成掃描不代表檔案安全。Windows 預設使用本機 Windows OCR，其他系統需要安裝 Tesseract。
