# PDF Extract > Extrakce ručních poznámek, zvýraznění, podtržení a označených obrázků z PDF knih. Detekuje barevné anotace (zelené, žluté, červené, modré, černé) a vytvoří strukturovaný .md soubor s přepisem. - Skill: `jmech-pepa/pdf-extract` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add jmech-pepa/pdf-extract` - Raw SKILL.md: https://api.skillmd.com/api/skills/jmech-pepa/pdf-extract/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: jmech-pepa (https://skillmd.com/u/jmech-pepa) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jmech-pepa/pdf-extract --- # PDF Extract – extrakce poznámek z knih v5.0 (script-backed) ## Kdy použít - Uživatel chce vytáhnout své ruční poznámky a zvýraznění z PDF knihy - Trigger fráze: "extrahuj poznámky", "poznámky z PDF", "/pdf-extract", "vytáhni z knihy" ## Vstup - Cesta k PDF souboru (povinné) - Volitelně: výstupní cesta, konkrétní rozsah stran ## Kontext uživatele - Uživatel anotuje **digitálním perem na tabletu** - Typické anotace: čárky u textu, ohraničení pasáží, podtržení, sem tam ruční poznámka - Tahy jsou **vždy nepravidelné** (nikdy dokonale rovné) – to je klíčový rozlišovací znak od tištěného obsahu - Schémata a diagramy v knize mají být **zachovány jako obrázky**, NE převáděny na text ## Architektura — AI dělá úsudek, skript mechaniku **Veškerá deterministická logika žije v `~/.claude/skills/pdf-extract/scripts/detect.py`** (JSON na stdout, progress na stderr). Detekční pravidla, prahy a draze zaplacené poučky z verzí v3–v4.1 (fill-only paths neviditelné v PNG, řazení merge_ranges dle y_min, margin=15, rozlišení ručního tahu od layoutu) jsou zapsané ve skriptu jako kód + komentáře — **při úpravách logiky edituj skript, nepiš ad-hoc Python do session**. AI (tato session + subagenti) dělá jen to, co skript neumí: vizuální čtení ručního textu, interpretaci složitých stran, sestavení výstupu. ``` scan → kategorizace stran: simple / marginal / complex extract-simple → strany s vestavěnými PDF anotacemi (highlight/underline/strikeout) → hotový markdown extract-margins → zatržení na okrajích → hotový markdown (vektorová data, SPOLEHLIVĚJŠÍ než vizuální analýza) render → PNG + txt + hints pro složité strany (jediné, co jde na subagenty) clip → výřez schématu/obrázku do PNG (pro subagenty) ``` ## Dávkový režim (výchozí chování) **KRITICKÉ – MUSÍŠ DODRŽET:** - **Výchozí:** zpracuj prvních 50 stran, vytvoř výstupní `.md` soubor a **ZASTAV SE** - Vypiš uživateli výsledky a ČEKEJ na jeho odpověď — **NEPOKRAČUJ automaticky** na strany 51+ - Pokud uživatel řekne "zpracuj celou knihu" / "pokračuj", pokračuj dalšími dávkami - Při pokračování **přidávej** do existujícího `.md`, nemazej předchozí výsledky ## Workflow ### 1. Závislosti ```bash python3 ~/.claude/skills/pdf-extract/scripts/detect.py deps-check ``` Pokud `"ok": false` → `python3 -m pip install --user --break-system-packages PyMuPDF Pillow numpy` a znovu. ### 2. Scan (detekce + kategorizace) ```bash python3 ~/.claude/skills/pdf-extract/scripts/detect.py scan "" --start 1 --end 50 ``` JSON vrátí metadata knihy a `summary` se stranami ve třech kategoriích: - **simple** — pouze vestavěné PDF anotace (highlight/underline/strikeout) → krok 3a - **marginal** — ruční kresby POUZE na okrajích → krok 3b (programaticky! fill-only tahy jsou v PNG neviditelné) - **complex** — kresby v těle, ink anotace, barevné pixely, ruční text → krok 4 (subagenti) Vypiš uživateli přehled: název/autor, kolik stran nalezeno, rozklad simple/marginal/complex. Skript sám filtruje layout vzory opakující se na >30 % stran (dekorace, rámečky). ### 3. Programatická extrakce (bez subagentů, extrémně levná) ```bash # 3a — simple strany python3 ~/.claude/skills/pdf-extract/scripts/detect.py extract-simple "" --pages 12,15,23 # 3b — marginal strany python3 ~/.claude/skills/pdf-extract/scripts/detect.py extract-margins "" --pages 8,31 ``` Oba vrací hotový markdown v JSON poli `markdown` — jde přímo do výstupního souboru. ### 4. Vizuální analýza složitých stran (subagenti) **NIKDY nečti PNG stran v hlavním kontextu — vždy deleguj.** ```bash python3 ~/.claude/skills/pdf-extract/scripts/detect.py render "" --pages 5,9,14 --outdir temp_pages ``` Vytvoří `page_NNNN.png` (250 DPI), `page_NNNN.txt` (tištěný text) a `page_NNNN_hints.txt` (pozice detekovaných kreseb vč. `hand_drawn` příznaku — říká subagentovi KAM se dívat). Rozděl složité strany do dávek po **max 10–15 stranách**, dávky spusť paralelně (2–3 subagenty). Model: `sonnet` default; `opus` pokud jde o hustý/špatně čitelný rukopis. Prompt pro každého subagenta: ``` Jsi expert na extrakci ručních poznámek z PDF knih. Zpracuj strany: [seznam] | PNG+txt+hints: temp_pages/page_NNNN.* Pro každou stranu: (1) přečti _hints.txt — pozice detekovaných kreseb, (2) přečti PNG (Read tool), (3) přečti .txt pro kontext tištěného textu, (4) identifikuj anotace dle tabulky, ZAMĚŘ SE na pozice z hints. Typy: [RUKOU PSÁNO] ruční text · [ZATRŽENO] svislá čára na okraji · [ZVÝRAZNĚNO] highlight/rámeček · [PODTRŽENO] · [OBRÁZEK] označený obrázek · [SCHÉMA] diagram — VŽDY jako obrázek, NIKDY nepřevádět na text · [ŠIPKA] · [SYMBOL] hvězdička/vykřičník/otazník · [ZÁLOŽKA] celá strana Rozlišení ruční vs. tištěné: uživatel píše digitálním perem na tabletu — tahy jsou VŽDY nepravidelné. Dokonalá geometrie (tabulky, rámečky, dekorace) = tištěný prvek, NEoznačuj jako anotaci. Při nejistotě zahrň s poznámkou [nejisté]. Schéma/obrázek extrahuj výřezem (souřadnice odhadni z PNG + hints): python3 ~/.claude/skills/pdf-extract/scripts/detect.py clip "" --page N \ --rect x0,y0,x1,y1 --out "_images/img_pageN_1.png" V markdownu pak: ![popis](_images/img_pageN_1.png) VÝSTUP: pouze strukturovaný markdown per strana: ## Strana XX ### [TYP] emoji_barvy(jen u barevných: 🟢🟡🔴🔵🟠) > text (zatržené pasáže = citace tištěného textu; ruční poznámky kurzívou) --- Nečitelný text = [nečitelné]. NIKDY text nevymýšlej. ``` ### 5. Programatická verifikace po subagentech **KRITICKÉ:** Pro každou stranu, kde subagent nenašel nic (nebo hlásil „false positive"), zkontroluj scan JSON — pokud měla `margin_drawings > 0`, subagent se mýlil (fill-only tahy v PNG nevidí). Spusť na tyto strany: ```bash python3 ~/.claude/skills/pdf-extract/scripts/detect.py extract-margins "" --pages X,Y --min-items 10 ``` a doplň výsledky do výstupu. Vektorová data z PDF jsou pro okrajová zatržení autoritativní. ### 6. Sestavení výstupního souboru Sluč markdown z kroků 3a + 3b + 4 + 5, **řazeno podle čísla strany**. - Název: `Nazev_knihy (Autor).md` (mezery v názvu knihy → podtržítka), do složky zdrojového PDF - Hlavička: název, autor, datum extrakce, zdrojový soubor, počet anotovaných stran z celku - **NEMAZAT existující obsah** — uživatel může mít vlastní poznámky nad extrakcí; doplňuj jen sekce za oddělovačem `---` - Černé anotace bez emoji (default), barevné s emoji ### 7. Úklid a shrnutí ```bash rm -rf temp_pages/ ``` Ponech `{nazev_knihy}_images/`. Vypiš: cestu k .md, cestu k obrázkům, počet stran/anotací, rozložení typů, nejčastěji anotovaná témata. ## Pravidla kvality **Vždy:** dávky (nedrž celé PDF v paměti) · přesný přepis ručních poznámek · `[nečitelné]` když nejde přečíst · dostatečně velký citovaný blok u zatržení · průběžně informuj o postupu · schémata vždy jako PNG. **Nikdy:** nevynechávej nalezené anotace · nevymýšlej text · nemaž existující obsah · nečti PNG stran v hlavním kontextu · neoznačuj tištěné prvky jako anotace · nepřeváděj schémata na text. ## Changelog - **2026-07-02 (v5.0)** — Konverze na script-backed: veškerá detekce a programatická extrakce přesunuta do `scripts/detect.py` (otestováno na syntetickém PDF: simple/marginal/complex kategorizace, layout filtr, párování textu, clip). SKILL.md už neobsahuje inline Python — konec re-implementace při každém běhu. Nový `clip` subcommand pro subagenty. Model subagentů: sonnet default (odstraněno mylné „opus má 1M kontext"). - **v4.1** — Programatická extrakce marginálních stran (fill-only paths jsou v PNG neviditelné → vektorová data autoritativní), verifikace po subagentech, merge_ranges řazení dle y_min, margin=15. - **v3–v4** — is_hand_drawn heuristika (bezier/krátké segmenty/odchylka od osy), klasifikace pozice kreseb, dávkový režim 50 stran.