### Verify installation Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/installation.md Check the installed version and verify functionality with a test extraction. ```bash pdfvision --version pdfvision --help ``` ```bash pdfvision document.pdf --json ``` -------------------------------- ### Install pdfvision globally Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/installation.md Install the package globally to enable the pdfvision command in any shell. ```bash npm install -g pdfvision pdfvision document.pdf ``` -------------------------------- ### Install without OCR dependencies Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/installation.md Install the package while omitting optional OCR dependencies to reduce footprint. ```bash npm install --omit=optional pdfvision ``` -------------------------------- ### TOON output format example Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/formats.md An example of the TOON format showing YAML-style indentation, tabularized arrays with headers, and nested object folding. ```text file: /path/doc.pdf totalPages: 14 metadata: title: ... overview[2]: - page: 1 charCount: 40 quality: nativeTextStatus: ok width: 612 height: 792 - page: 2 ... pages[2]: - page: 1 text: "line one\nline two" charCount: 40 spans[2]{text,x,y,width,height,fontSize,fontName}: pdfvision headers fixture,50,27.18,108.38,10,10,font1 Body of page 1,50,194.36,134.54,20,20,font1 layout: blocks[2]: - text: ... lines[1]{text,x,y,width,height,fontSize}: ... ``` -------------------------------- ### Install Agent Skills Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/agent-skill.md Add the pdfvision agent skills to your project using npx. ```bash npx skills add yamadashy/pdfvision ``` -------------------------------- ### Install pdfvision as a library Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/installation.md Add pdfvision as a project dependency and import the processDocument API. ```bash npm install pdfvision ``` ```ts import { processDocument } from 'pdfvision'; const result = await processDocument('./document.pdf', { pages: '1-3', render: true }); console.log(result.totalPages); ``` -------------------------------- ### Common starting point commands Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/index.md Practical default commands for various document types including research papers, slide decks, and forms. ```bash npx pdfvision document.pdf --json npx pdfvision paper.pdf --layout --image-boxes --json npx pdfvision deck.pdf --layout --image-boxes --vector-boxes --visual-regions --json npx pdfvision scan.pdf --ocr --ocr-lang eng --json npx pdfvision form.pdf --layout --form-fields --annotations --links --json npx pdfvision report.pdf --search "term" --json npx pdfvision report.pdf --pages 2 --render --render-region 120,180,360,140 --render-output ./crops --json ``` -------------------------------- ### pdfvision docs [topic] Source: https://github.com/yamadashy/pdfvision/blob/main/README.md Displays documentation for the installed version of pdfvision. ```APIDOC ## pdfvision docs [topic] ### Description Provides documentation for the installed version. Running without a topic lists available topics. ``` -------------------------------- ### Install Agent Skills globally Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/agent-skill.md Add the pdfvision agent skills globally using the -g flag. ```bash npx skills add yamadashy/pdfvision -g ``` -------------------------------- ### Conventional Commits Examples Source: https://github.com/yamadashy/pdfvision/blob/main/CLAUDE.md Examples of commit messages following the Conventional Commits specification with module scopes. ```text feat(renderer): add per-page PNG output fix(processor): handle encrypted PDF gracefully refactor(cli): split help text into its own module docs(readme): add multimodal usage section test(pageRange): cover comma + range mix chore(deps): bump pdfjs-dist to v5.6 ``` -------------------------------- ### Install pdfvision agent skill Source: https://github.com/yamadashy/pdfvision/blob/main/README.md Add the pdfvision skill to your project or global environment to enable agentic tool usage. ```bash # Project install (default) — drops the skill into /.claude/skills/pdfvision/ npx skills add yamadashy/pdfvision # Global install — drops it into ~/.claude/skills/pdfvision/ instead npx skills add yamadashy/pdfvision -g ``` -------------------------------- ### Run pdfvision CLI for unknown PDF Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/index.md Use this command as a starting point for processing an unknown PDF document. ```bash npx pdfvision document.pdf --format json ``` -------------------------------- ### pdfvision CLI Usage Examples Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/options.md Common command-line patterns for processing PDF documents, including extraction, rendering, searching, and OCR. ```text pdfvision document.pdf # markdown to stdout pdfvision report.pdf --map # what the document is, no page bodies (first move on a long PDF) pdfvision document.pdf --json # JSON shortcut pdfvision document.pdf -p 1-3 --json # specific pages, JSON pdfvision document.pdf -r --render-output ./images # render PNGs to ./images pdfvision slides.pdf -r --render-scale 1 # 1× raster (smaller PNGs) pdfvision report.pdf -p 3 -r --render-region 100,200,300,150 # zoom into a 300×150 page-view-unit box on page 3 pdfvision report.pdf --search "revenue" --json # find emitted "revenue" matches with bboxes; pipe to --render-region pdfvision paper.pdf --search "GPT" --search "transformer" --json # multi-query (each match keeps its source query) pdfvision paper.pdf --search "BLEU" --matches-only # report metadata + flat match list, without page bodies pdfvision report.pdf -p 3-5 -r --render-output ./images --geometry --json # PNGs + spans for 3-5 pdfvision slides.pdf --xml --geometry # layout / geometry as XML pdfvision report.pdf --toon --geometry # geometry spans in TOON format pdfvision report.pdf --layout --strip-repeated # markdown w/o repeated chrome pdfvision encrypted.pdf --password "secret" --json # encrypted PDF printf "secret\n" | pdfvision encrypted.pdf --password-stdin --json # avoid password in argv pdfvision scan.pdf --ocr --json # OCR a scanned PDF pdfvision scan-ja.pdf --ocr --ocr-lang jpn+eng --json # multi-lang OCR pdfvision --remote https://example.com/paper.pdf --json # fetch + extract JSON pdfvision clear-cache # clear the verified pdfvision cache pdfvision docs # list the built-in documentation topics pdfvision docs warnings # read one topic ``` -------------------------------- ### pdfvision mcp Source: https://github.com/yamadashy/pdfvision/blob/main/README.md Starts the pdfvision server over the Model Context Protocol. ```APIDOC ## pdfvision mcp ### Description Serves pdfvision over the Model Context Protocol on stdio for integration with AI hosts. ``` -------------------------------- ### Check pdfvision version Source: https://github.com/yamadashy/pdfvision/blob/main/skills/pdfvision/SKILL.md Verify the installed version of pdfvision. Requires Node.js >= 22.13. ```bash npx pdfvision --version # Node.js >= 22.13; `npm i -g pdfvision` if used a lot ``` -------------------------------- ### Configure OCR languages with --ocr-lang Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/ocr.md Examples of using the --ocr-lang flag with single or multiple language codes joined by plus signs. Note that the order of languages affects OCR output and runtime. ```bash npx pdfvision doc.pdf --ocr --ocr-lang eng # English only (default) npx pdfvision doc.pdf --ocr --ocr-lang eng+jpn # English + Japanese npx pdfvision doc.pdf --ocr --ocr-lang chi_sim # Simplified Chinese npx pdfvision doc.pdf --ocr --ocr-lang eng+chi_sim+chi_tra ``` -------------------------------- ### Get formatted output with processFile Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/library-api.md Returns formatted text output such as Markdown, XML, or TOON, suitable for feeding directly into an LLM context window. ```ts import { processFile } from 'pdfvision'; const markdown = await processFile('./document.pdf', { format: 'markdown', pages: '1-2', noCache: false, }); ``` -------------------------------- ### XML output structure example Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/formats.md A representative XML document structure showing the hierarchy of metadata, overview, and page-level content including spans, layout blocks, and OCR data. ```xml ... ... ... ... ... ... ... ... ... ...page text body... ...pre-normalization text, when normalization changed it... ...OCR text... ... ... ``` -------------------------------- ### Run project verification commands Source: https://github.com/yamadashy/pdfvision/blob/main/CLAUDE.md Execute the full suite of linting, testing, and build commands to verify the project state before finalizing work. ```bash npm run lint npm run test npm run build ``` -------------------------------- ### Acquire sample PDFs via curl Source: https://github.com/yamadashy/pdfvision/blob/main/tests/agent-regression/README.md Commands to download sample PDF files with stable public URLs for testing purposes. ```bash curl -L https://www.soumu.go.jp/main_content/001019264.pdf -o soumu-r7-summary.pdf curl -L -r 0-131071 https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-63-3.pdf -o truncated.pdf curl -L https://raw.githubusercontent.com/mozilla/pdf.js/master/test/pdfs/xfa_filled_imm1344e.pdf -o xfa-form.pdf ``` -------------------------------- ### pdfvision CLI Help and Usage Source: https://github.com/yamadashy/pdfvision/blob/main/README.md Displays the command-line interface help, including common usage patterns, available options, and subcommands for extracting data from PDF files. ```text pdfvision - Extract text, images, metadata, and layout from PDF files for AI agents Command shape: options are for reading a PDF; anything else is a subcommand. (--help and --version are the usual exceptions, and work anywhere.) Usage: pdfvision [options] pdfvision --remote [options] pdfvision docs [topic] pdfvision clear-cache pdfvision mcp Common flows pdfvision doc.pdf Read it. Per-page quality and warnings name the next flag when the default pass is not enough. pdfvision report.pdf --map What the document is, no page bodies. The first move on a long or unfamiliar PDF. pdfvision doc.pdf --search "term" --matches-only Locate a term without reading the whole body; each match reports its page, bbox, and a crop-ready region. pdfvision doc.pdf -p -r --render-region Crop that region as image evidence (a match's region, or a layout block's bbox when there is no term to search). pdfvision doc.pdf -p --ocr Re-read scanned pages (quality: empty_but_visual_content). Options Every option, with its interactions and caveats: pdfvision docs options -p, --pages Pages to extract: "1", "1-5", "1,3,5", "2-4,7". Default: all pages. -f, --format markdown (default), json, xml, toon. Also --markdown / --json / --xml / --toon. -r, --render Render each selected page to a PNG and report its path. --render-output Where the PNGs land. Requires --render or --render-visual-regions. --render-scale Rasterisation multiplier, default 2 (≈144 DPI); bounds (0, 4]. Requires --render, --render-visual-regions, or --ocr. --render-region Crop one page in raw page-view units. Single-page only. --map A map of the document instead of its contents: pages, metadata, outline, per-page quality and warning codes. Markdown only. --search Find and report each hit's page and bbox. Repeatable. --matches-only Report matches plus compact diagnostics, with crop-ready regions. Needs --search. --search-regex, --search-case-sensitive Regex instead of literal substring; exact case. --ocr OCR the selected pages beside the native text. Slow; opt-in. --ocr-lang Language(s) for --ocr, plus-separated (e.g. `eng+jpn`). Default: eng. --layout Reconstruct lines, blocks, vertical CJK stacks, and table hints. --visual-regions, --render-visual-regions Crop-ready bboxes for figures, charts, tables, forms — and their PNGs. --form-fields, --links, --annotations Interactive widgets; link targets; comments, highlights, stamps, ink. --outline, --page-labels, --attachments, --attachment-output Bookmarks; viewer page labels; embedded files, and where to write them. --geometry, --image-boxes, --vector-boxes Per-text-item, raster, and vector bounding boxes. Structured formats only. --structure, --viewer, --layers Tagged-PDF structure; viewer/JavaScript settings; optional content groups. --strip-repeated Drop running headers / footers from the Markdown body. Requires --layout. --password , --password-stdin Open an encrypted PDF. The password is never emitted in output. --remote Download an http(s) PDF and extract it. --no-cache Re-download and re-extract instead of reusing the cache. --no-normalize Keep the pre-NFKC text as well. --clear-cache Deprecated alias for the clear-cache subcommand; removed in v1.0. -v, --version Show version -h, --help Show this help Subcommands docs [topic] Documentation for the installed version. Bare `docs` lists topics. clear-cache Remove cached extractions, renders, remote PDFs, and OCR data. mcp Serve pdfvision over the Model Context Protocol on stdio, for hosts that cannot run a shell. See "pdfvision mcp --help". A subcommand is recognized only as the first argument, so a file named `docs`, `mcp`, or `clear-cache` must be passed as `./docs` and so on. ``` -------------------------------- ### Render full pages with CLI Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/rendering-and-ocr.md Renders all pages of a PDF to images in the specified output directory. ```bash pdfvision document.pdf --render --render-output ./images --format json ``` -------------------------------- ### Zoom into a specific region Source: https://github.com/yamadashy/pdfvision/blob/main/skills/pdfvision/SKILL.md Re-run the command with specific page and region coordinates to get a cropped PNG of a suspicious or flagged block. ```bash --pages --render --render-region ``` -------------------------------- ### Find-then-zoom Workflow Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/search.md A two-step process using --matches-only to identify a match and then render the specific region. ```bash pdfvision doc.pdf --search "revenue" --matches-only --json # pick a match m from matches[*] pdfvision doc.pdf -p --render --render-region ,,, ``` -------------------------------- ### Missing dependency error message Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/ocr.md The error message displayed when the --ocr flag is used without the required tesseract.js dependency installed. ```text --ocr requires the optional dependency "tesseract.js" (not installed). Install it with: npm install tesseract.js ``` -------------------------------- ### Advanced search with regex and case sensitivity Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/search-and-region-zoom.md Demonstrates using regex for pattern matching and case-sensitive search flags. ```bash pdfvision report.pdf --search "Q[1-4] revenue" --search-regex --json pdfvision report.pdf --search "PDF" --search-case-sensitive --json ``` -------------------------------- ### Render crop from search results Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/use-cases.md Use bounding box information from search results to render a specific region for verification. ```bash pdfvision contract.pdf --pages 9 --render --render-region 96,320,420,96 --render-output ./crops --json ``` -------------------------------- ### Configure MCP server in JSON Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/mcp.md Add this configuration to your MCP host settings to enable the pdfvision server via npx. ```json { "mcpServers": { "pdfvision": { "command": "npx", "args": ["-y", "pdfvision", "mcp"] } } } ``` -------------------------------- ### Enable Navigation and Outline Extraction Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/structured-output.md Use --links and --outline to extract document-level bookmarks and page-level annotations for navigation-heavy documents. ```bash --links --outline ``` -------------------------------- ### Search-Then-Zoom Evidence Check Prompt Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/prompt-examples.md Use this prompt to validate search matches by deciding if visual verification is needed and generating the appropriate crop commands. ```text Use pages[].matches from this pdfvision JSON to choose the best evidence location. For each relevant match: 1. Report the page, query, source, matched text, and bbox. 2. Decide whether the match needs visual verification. 3. If it does, return the exact pdfvision command with --pages, --render, and --render-region. 4. After the crop is rendered, compare the crop against native text, OCR text, and nearby layout blocks. ``` -------------------------------- ### Perform initial structured PDF scan Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/use-cases.md Run a basic JSON scan on an unknown PDF to generate an overview for routing decisions. ```bash pdfvision document.pdf --json ``` -------------------------------- ### Render pages for multimodal models Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/index.md Use the --render flag to generate visual representations of the PDF pages. ```bash npx pdfvision document.pdf --render ``` -------------------------------- ### Run pdfvision with layout reconstruction Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/layout-and-warnings.md Executes pdfvision on a document with the --layout flag to output structured JSON containing geometry, reading-order blocks, and table hints. ```bash pdfvision document.pdf --layout --format json ``` -------------------------------- ### CLI Options and Flags Reference Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/options.md A complete list of available CLI flags for pdfvision, including page ranges, output formats, and rendering configurations. ```text -p, --pages Pages to extract: "1", "1-5", "1,3,5", "2-4,7". Default: all pages. -f, --format Output format: markdown (default), json, xml, toon. --markdown Shortcut for --format markdown. --json Shortcut for --format json. --xml Shortcut for --format xml. --toon Shortcut for --format toon. (Specifying more than one format, or mixing a shortcut with a different --format, is an error — pdfvision does not last-wins-resolve them.) JSON-style field paths below are exact for JSON/TOON and processDocument(); XML maps them to tags/attributes (for example page→no, pageLabel→label). -r, --render Render each selected page to a PNG and include the path on every page result. --render-output Directory to write rendered page PNGs or visual-region PNGs into, created if missing. Requires --render or --render-visual-regions. PNGs land flat as `/page-N.png` (`--render-region` keeps its coordinate-suffixed name); a filename already taken by another PDF in the same dir is written with a `-2` suffix and a note on stderr. Without this, PNGs land under the cache (or OS tmp with --no-cache). --render-scale Rasterisation multiplier for --render / --render-visual-regions / --ocr. Default 2 (≈144 DPI). Smaller values shrink the PNG (and vision-model payload); OCR keeps at least scale 2 for recognition quality; larger values capture more detail. Accepts decimals; bounds (0, 4]. Errors when none of the three flags is present, rather than silently doing nothing — same contract as --render-output. --render-region Render a sub-rectangle in raw unrotated page-view units (top-left origin, y grows downward). Physical points = raw value × pages[].userUnit (or 1 when omitted); pixels = raw region × UserUnit × render scale. Requires --render or --ocr — there is nothing to crop otherwise. Single-page only: --pages must resolve to exactly one page (errors otherwise). Region must fit within the page bounds. Typical use: --search "term" --matches-only reports each match's region; re-run with that region here to zoom in (--layout for a block-level bbox when there is no term to search). --no-normalize Disable Unicode NFKC normalization and C0-control cleanup. Default ON; pre-normalization text is `pages[].rawText` in JSON/TOON and a sibling `` element in XML when normalization changed the string. Markdown output shows only the normalized form — pass --no-normalize if original codepoint fidelity (e.g. fullwidth punctuation `（`, ligatures `fi`, control bytes) matters for downstream diff / forensics. --password Password for encrypted PDFs. The password is used only for pdf.js decryption and is never emitted in output. --password-stdin Read the encrypted PDF password from piped stdin, stripping one trailing newline. If stdin is empty, --password is used as fallback. --geometry Emit per-text-item bbox + font size in `pages[].spans`. Only takes effect with -f json / -f xml / -f toon. --layout Reconstruct `pages[].layout` (lines, blocks, vertical CJK stacks, and numeric-table hints in approximate reading order) from the same span data, and add the structured layout fields to -f json / -f xml / -f toon. In Markdown it also adds the per-page `Layout tables` sections and the Overview `Blocks` / `Tables` columns. Markdown does NOT need this flag for the reading-order body or the ``` -------------------------------- ### Enable Viewer State and Metadata Extraction Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/structured-output.md Use --viewer, --page-labels, and --layers to extract PDF viewer preferences, page labels, and layer visibility settings. ```bash --viewer --page-labels --layers ``` -------------------------------- ### Run PDFVision on a document Source: https://github.com/yamadashy/pdfvision/blob/main/skills/pdfvision/SKILL.md Initial command to process a PDF document, optionally specifying page ranges and output formats. ```bash npx pdfvision doc.pdf ``` -------------------------------- ### Evidence-First Summary Prompt Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/prompt-examples.md Use this prompt to summarize a PDF while prioritizing quality fields and warnings, ensuring claims are backed by specific page and bbox evidence. ```text Summarize this PDF using the pdfvision output as evidence. Rules: 1. Start from overview quality fields and page warnings. 2. Do not summarize pages whose native text is empty, sparse, or glyph-corrupted without saying what evidence is missing. 3. When a conclusion depends on a table, form field, chart, or figure, cite the page and bbox or recommend a crop command. 4. Separate confident text-derived claims from claims that need visual verification. ``` -------------------------------- ### Reconstruct document layout Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/index.md Use --layout, --image-boxes, and --vector-boxes when reading order, columns, tables, forms, or warnings are important. ```bash npx pdfvision document.pdf --layout --image-boxes --vector-boxes --format json ``` -------------------------------- ### Enable Attachment Extraction Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/structured-output.md Use --attachments to extract metadata for embedded files. Use --attachment-output to write the actual file bytes. ```bash --attachments --attachment-output ``` -------------------------------- ### Configure PDFVISION_CACHE_DIR Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/security-and-privacy.md Set the PDFVISION_CACHE_DIR environment variable to a secure, absolute path to define where cache files are stored. ```bash PDFVISION_CACHE_DIR=/secure/cache pdfvision document.pdf --format json ``` -------------------------------- ### Financial Metric Verification Prompt Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/prompt-examples.md Use this prompt to verify financial metrics by checking matches and layout tables, with instructions to request crops for ambiguous or visually encoded values. ```text Use this pdfvision output to verify financial metrics. For each requested metric: 1. Find candidate matches in pages[].matches or layout table labels. 2. Identify the page, row/column context, and bbox evidence. 3. Check warnings for table flattening, reading-order divergence, dense vectors, or raster-only content. 4. If the value is visually encoded or ambiguous, return a pdfvision --render-region command for the smallest useful crop. 5. Do not invent values from nearby text when row or column alignment is unclear. ``` -------------------------------- ### Render Pages to Images Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/usage.md Render PDF pages as PNG images using the --render flag. The --render-output flag specifies the directory, and --render-scale controls image detail. ```bash pdfvision document.pdf --render --render-output ./images --format json ``` ```bash pdfvision document.pdf --render --render-scale 3 ``` -------------------------------- ### Debug blank OCR results with --render Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/ocr.md Use the --render flag to output a page image to a directory for visual inspection when OCR returns empty text and zero confidence. ```bash npx pdfvision doc.pdf -p --render --render-output /tmp/dbg ``` -------------------------------- ### Configure render scale Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/rendering-and-ocr.md Adjusts the detail level of rendered images using the --render-scale flag. ```bash pdfvision document.pdf --render --render-scale 3 ``` -------------------------------- ### Render visual regions automatically Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/rendering-and-ocr.md Automatically detects and renders crop-ready regions like figures, charts, and tables. ```bash pdfvision document.pdf --render-visual-regions --render-output ./regions --format json ``` -------------------------------- ### Search for evidence with pdfvision Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/search-and-region-zoom.md Run this command to locate candidate evidence without page bodies, returning results in JSON format. ```bash pdfvision annual-report.pdf --search "Net sales" --search "Operating income" --matches-only --json ``` -------------------------------- ### Run PDFVision via npx Source: https://github.com/yamadashy/pdfvision/blob/main/docs/comparison.html Execute the PDFVision tool directly using npx to process a PDF file. ```bash npx pdfvision your.pdf ``` -------------------------------- ### Process Local PDF Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/usage.md Basic command to process a local PDF file. ```bash pdfvision document.pdf ``` -------------------------------- ### processFile(filePath, options) Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/library.md Processes a PDF file and returns the output as a formatted string. This is preferred when the integration boundary requires raw text formats like Markdown, JSON, XML, or TOON. ```APIDOC ## processFile(filePath, options) ### Description Processes a PDF file and returns the result as a formatted string, matching the output format of the CLI. ### Parameters - **filePath** (string) - Required - The path to the PDF file. - **options** (ProcessOptions) - Required - Configuration options including format, noCache, matchesOnly, and stripRepeated. ### Returns - **Promise** - A promise that resolves to the formatted string output. ``` -------------------------------- ### Inspect PDF warnings and layout issues Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/index.md Run pdfvision on a specific page to identify reading order divergence and font map decoding issues. ```console $ npx pdfvision tracemonkey.pdf -p 10 _chars: 6944 · images: 0 · coverage: 42% · vectors: 17 · warnings: 1 · size: 612×792pt_ … page body … ### Warnings > **warning** (reading_order_divergence): layout line "?>9@AJ.0A: after "?>9@AJ.D2.@A:0>#3$4,56#" visually but earlier in the native text stream — > native line order diverges from what a human reads; the body above is that reading order, > rebuilt from the layout — render the page when exact sequence is critical ``` -------------------------------- ### Visual Report Review Prompt Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/prompt-examples.md Use this prompt to review visual-heavy reports, focusing on regions and warnings to propose necessary crop commands for verification. ```text Review this visual PDF report using pdfvision output. Focus on: 1. Pages with high imageCount or vectorCount. 2. pages[].visualRegions and their associated text. 3. Warnings that indicate visual-only labels, dense charts, or sparse native text. 4. The smallest set of region crops needed to verify the important charts, diagrams, or screenshots. Return the proposed crop commands before making visual claims. ``` -------------------------------- ### Search for keywords Source: https://github.com/yamadashy/pdfvision/blob/main/skills/pdfvision/SKILL.md Locate keywords within the document and retrieve metadata or bounding box information. ```bash --search "X" --matches-only ``` -------------------------------- ### Detect visual structure and regions Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/use-cases.md Identify layout, image boxes, vector boxes, and visual regions within a document. ```bash pdfvision report.pdf --layout --image-boxes --vector-boxes --visual-regions --format json ``` -------------------------------- ### Search document for specific terms Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/use-cases.md Search for specific clauses or labels to retrieve page numbers, context, and bounding boxes. ```bash pdfvision contract.pdf --search "termination" --search "governing law" --json ``` -------------------------------- ### Search a PDF with matches-only Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/search-and-region-zoom.md Executes a search for 'revenue' in report.pdf and returns compact hits in the matches array without full page bodies. ```bash pdfvision report.pdf --search "revenue" --matches-only --json ``` -------------------------------- ### Enable Annotation Extraction Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/structured-output.md Use --annotations to include comments, highlights, stamps, and FreeText notes that may alter the document's meaning. ```bash --annotations ``` -------------------------------- ### Generate Markdown Output Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/output.md Markdown is the default output format, optimized for conversational AI and human readability. ```bash pdfvision document.pdf pdfvision document.pdf --format markdown ``` -------------------------------- ### Scan multilingual pages with OCR Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/use-cases.md Specify multiple languages for OCR, placing the dominant language first. ```bash pdfvision scan.pdf --ocr --ocr-lang jpn+eng --format json ``` -------------------------------- ### Extract detailed signals for unknown PDFs Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/use-cases.md Add layout, image, vector, and visual region signals to the JSON output for deeper inspection. ```bash pdfvision document.pdf --layout --image-boxes --vector-boxes --visual-regions --json ``` -------------------------------- ### Implement conditional second pass loop Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/library.md Perform an initial cheap pass to identify relevant pages, then selectively process those pages with expensive operations like rendering. ```ts const first = await processDocument('./report.pdf', { search: ['revenue'], layout: true }); for (const page of first.pages) { if (page.quality.nativeTextStatus === 'ok' && !page.warnings && !page.matches?.length) continue; const rendered = await processDocument('./report.pdf', { pages: String(page.page), render: true }); console.log(rendered.pages[0].image); } ``` -------------------------------- ### Render visual PDF pages Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/index.md Use the --render flag for visual, scanned, chart-heavy, or layout-sensitive PDFs. ```bash npx pdfvision document.pdf --render --format json ``` -------------------------------- ### PageLayout Interface Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/layout.md The root structure for layout information, containing blocks in reading order and optional table hints. ```APIDOC ## PageLayout ### Description Represents the layout structure of a page. ### Structure - **blocks** (LayoutBlock[]) - Blocks in approximate reading order (multi-column aware). - **tables** (LayoutTable[], optional) - Row-major hints for aligned numeric tables. ``` -------------------------------- ### Search and crop PDF evidence Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/index.md Search for specific terms and crop the matching area for exact evidence extraction. ```bash npx pdfvision document.pdf --search "revenue" --format json npx pdfvision document.pdf --pages 3 --render --render-region 120,180,360,140 --render-output ./crops --format json ``` -------------------------------- ### Run multiple search queries Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/search-and-region-zoom.md Performs multiple searches for 'transformer' and 'attention' in a single pass. ```bash pdfvision paper.pdf --search "transformer" --search "attention" --json ``` -------------------------------- ### Render PDF page for inspection Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/layout-and-warnings.md Use the render command to visually inspect a specific page of a PDF document to verify if warnings like invisible text or opaque fills are present. ```bash pdfvision document.pdf -p 3 --render --format json ``` -------------------------------- ### Render a search match using a reference Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/mcp-server.md Uses a reference ID from a search result to render the match in place. ```text render_pdf(ref: "p47m1") ``` -------------------------------- ### Specify Page Ranges Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/usage.md Use the --pages flag to select specific pages or ranges. Ranges are one-based and inclusive, and commas can be used to combine multiple selectors. ```bash pdfvision document.pdf --pages 1-3 pdfvision document.pdf --pages 1,3,5 --format json ``` -------------------------------- ### Configure private network access Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/mcp.md Set the PDFVISION_MCP_ALLOW_PRIVATE_NETWORK environment variable to 1 to allow the MCP server to access intranet document stores. ```bash PDFVISION_MCP_ALLOW_PRIVATE_NETWORK=1 ``` -------------------------------- ### Render a specific region using --render-region Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/search-and-region-zoom.md Uses the page number and region coordinates from a compact search hit to render a specific area of the PDF to the output directory. ```bash pdfvision report.pdf --pages 3 --render --render-region 120,180,360,140 --render-output ./crops --json ``` -------------------------------- ### Project Directory Structure Source: https://github.com/yamadashy/pdfvision/blob/main/CLAUDE.md The file system layout of the pdfvision project, highlighting the CLI, MCP, core processing, and output modules. ```text pdfvision/ ├── src/ │ ├── bin/ │ │ └── pdfvision.ts # Thin CLI entry point (delegates to cli/cli.ts) │ ├── cli/ │ │ ├── cli.ts # Argument parsing and dispatch │ │ ├── help.ts # Help text (CLI + `pdfvision mcp`) │ │ ├── mcpCommand.ts # `pdfvision mcp` subcommand dispatch, resolved before parseArgs │ │ ├── clearCacheCommand.ts # `pdfvision clear-cache` dispatch and its ambiguity guard │ │ ├── docsCommand.ts # `pdfvision docs` dispatch and topic index rendering │ │ ├── docs/ # Generated topic index + bodies (see scripts/build-cli-topics.mjs) │ │ ├── optionSpec.ts # The parseArgs option spec, exported so tests can walk it │ │ ├── subcommandFlags.ts # --help / --version handling shared by every subcommand │ │ └── version.ts # Reads version from package.json │ ├── mcp/ │ │ ├── serve.ts # stdio bootstrap behind `pdfvision mcp` │ │ ├── server.ts # MCP tool registration (read_pdf / search_pdf / render_pdf) │ │ ├── tools/ # One module per tool │ │ ├── source.ts # Path-or-URL dispatch and SSRF guard │ │ ├── limits.ts # Response budgets │ │ ├── refs.ts # Short region handles (`p47m1`) for follow-up renders │ │ ├── attachments.ts # Embedded-file classification: inline text, image blocks, refuse the rest │ │ ├── truncate.ts # Page-boundary clipping with recovery guidance │ │ └── result.ts # Content blocks and the untrusted-data banner │ ├── core/ │ │ ├── processor.ts # Document-level processing entry point │ │ ├── annotations/ # PDF annotation normalization and geometry │ │ ├── document/ # Document-level metadata, outline, layers, attachments │ │ ├── formFields/ # Form field extraction, labels, and stacked controls │ │ ├── graphics/ # Image and vector operation analysis │ │ ├── io/ # OS tmpdir cache and remote input helpers │ │ ├── layout/ # Text layout reconstruction and repeated chrome │ │ ├── links/ # Link extraction and visible link text │ │ ├── ocr/ # OCR dispatch, worker, and word geometry │ │ ├── options/ # Option parsers such as page ranges │ │ ├── processor/ # Pipeline helpers used by processor.ts │ │ ├── quality/ # Page quality and extraction confidence signals │ │ ├── renderer/ # Per-page PNG rendering and crop handling │ │ ├── runtime/ # Shared runtime helpers such as bounded parallelism │ │ ├── search/ # Search query compilation and match geometry │ │ ├── text/ # Text joining, geometry, spacing, and direction helpers │ │ ├── visualRegions/ # Figure/table/form visual-region detection │ │ ├── warningTextOverlap/ # Text-overlap warning geometry │ │ ├── warnings/ # User-facing warning detection │ │ └── widgetAppearance/ # Widget appearance stream text extraction │ ├── output/ │ │ ├── documentMap.ts # Aggregated map of a document (no page bodies) │ │ ├── json.ts # Structured JSON formatter │ │ ├── markdown.ts # Agent-readable Markdown formatter │ │ ├── toon.ts # TOON formatter │ │ └── xml.ts # XML formatter │ ├── types/ │ │ └── index.ts # Shared types (DocumentResult, ProcessOptions, ...) │ └── index.ts # Library API entry ├── docs/ │ └── cli-topics/ # Source of `pdfvision docs `; embedded at build time ├── tests/ │ ├── core/ # Unit and integration tests │ └── fixtures/sample.pdf # Hand-crafted minimal PDF ├── .github/workflows/ # ci.yml, npm-publish.yml ├── biome.json ├── tsdown.config.ts ├── vitest.config.ts └── package.json ``` -------------------------------- ### Render diagnostic pages Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/mcp.md The search_pdf tool provides a concrete render_pdf call for pages requiring visual verification. ```text render_pdf(pages: "N") ``` -------------------------------- ### Generate XML Output Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/output.md XML provides a tag-based projection of the document data, useful for prompt workflows requiring explicit boundaries. ```bash pdfvision document.pdf --format xml ``` -------------------------------- ### Extract and render document content Source: https://github.com/yamadashy/pdfvision/blob/main/skills/pdfvision/SKILL.md Flags for extracting text, rendering pages, or analyzing layout structures. ```bash --ocr --render --layout --image-boxes ``` -------------------------------- ### Search and Zoom with pdfvision Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/usage.md Search for text in a PDF and render a specific region for visual verification. This pattern is useful for tying answers to auditable PDF evidence. ```bash pdfvision report.pdf --search "revenue" --format json pdfvision report.pdf --pages 3 --render --render-region 120,180,360,140 --render-output ./crops --format json ``` -------------------------------- ### Render visual regions for slide decks Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/use-cases.md Renders visual regions from a slide deck containing large raster regions into JSON format. ```bash pdfvision deck.pdf --render-visual-regions --format json ``` -------------------------------- ### Extract visual boxes and regions with --layout Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/layout-and-warnings.md Extracts raster image draws, vector drawings, and visual regions for figures, charts, and tables. ```bash pdfvision document.pdf --layout --image-boxes --vector-boxes --visual-regions --format json ``` -------------------------------- ### Table Review Prompt Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/prompt-examples.md Use this prompt to extract tables from pdfvision JSON output while preserving relationships and flagging ambiguous cells for potential crops. ```text Extract the tables from this pdfvision JSON. For each table: 1. Use pages[].layout.tables when available. 2. Preserve row and column relationships. 3. Flag cells that appear ambiguous or may need a rendered crop. 4. Include page number and bounding box evidence for each table. ``` -------------------------------- ### Run JSON extraction shorthand Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/index.md A shorthand command to perform an extraction and output the results in JSON format. ```bash npx pdfvision document.pdf --json ``` -------------------------------- ### Map document structure Source: https://github.com/yamadashy/pdfvision/blob/main/skills/pdfvision/SKILL.md Use the --map flag to retrieve page counts, outlines, and text usability information for long or unfamiliar documents. ```bash --map ``` -------------------------------- ### Crop and render specific regions in reports Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/use-cases.md Renders a specific region of a page in a report to an output directory for verification. ```bash pdfvision report.pdf --pages 12 --render --render-region 72,210,468,240 --render-output ./evidence --json ``` -------------------------------- ### Layout-Sensitive Extraction Prompt Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/prompt-examples.md Use this prompt to reconstruct human reading order by leveraging layout blocks and warnings, especially when native text order differs from visual order. ```text Use the pdfvision layout blocks and warnings to reconstruct the human reading order. Focus on: 1. Headings and section hierarchy. 2. Multi-column reading order. 3. Tables or form labels whose meaning depends on placement. 4. Any warning that suggests native text order differs from visual order. Do not rely only on pages[].text when layout warnings are present. ``` -------------------------------- ### Inspect visual structure and regions Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/index.md Analyze the visual structure of a document, including image and vector boxes, or render specific visual regions. ```bash npx pdfvision slides.pdf --layout --image-boxes --vector-boxes --visual-regions --json npx pdfvision slides.pdf --render-visual-regions --render-output ./regions --json ``` -------------------------------- ### search_pdf Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/zh-cn/guide/mcp-server.md 在 PDF 中搜索关键词或正则表达式，返回命中位置列表及引用标识。 ```APIDOC ## search_pdf ### Description 在 PDF 文档中执行搜索，返回包含 ref 标识的命中结果，便于后续渲染。 ### Parameters - **source** (string) - Required - 本地路径或 http(s) URL - **query** (string) - Required - 搜索关键词 - **pages** (string) - Optional - 搜索的页面范围 - **regex** (boolean) - Optional - 是否使用正则表达式 - **password** (string) - Optional - PDF 密码 ``` -------------------------------- ### Generate JSON Output Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/output.md JSON exposes the full DocumentResult schema and is recommended for tools, agents, and automated workflows. ```bash pdfvision document.pdf --format json ``` -------------------------------- ### Extract slide deck layout and visual regions Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/use-cases.md Extracts layout, image boxes, vector boxes, and visual regions from a slide deck into JSON format. ```bash pdfvision deck.pdf --layout --image-boxes --vector-boxes --visual-regions --format json ``` -------------------------------- ### DocumentViewerState interface Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/document-features.md Defines the structure of the document viewer state returned by the --viewer flag. ```ts interface DocumentViewerState { pageLayout?: string; // initial layout such as TwoColumnLeft pageMode?: string; // initial mode such as UseOutlines or UseThumbs viewerPreferences?: Record; openAction?: { type: 'destination' | 'action'; target?: string; // destination JSON/name when type is destination page?: number; // 1-based, resolved when possible action?: string; // PDF action name for non-destination actions }; jsActions?: Record; // document-level JavaScript action scripts permissions?: { flags: number[]; // raw PDF permission flags allowed: string[]; // decoded names; empty means permissions were present but none matched }; markInfo?: { marked: boolean; // tagged-PDF / structure presence signal userProperties: boolean; suspects: boolean; }; } ``` -------------------------------- ### LayoutBlock Interface Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/layout.md Represents a structural block of text within the page layout. ```APIDOC ## LayoutBlock ### Description Represents a block of text with geometric and role-based metadata. ### Structure - **text** (string) - Line texts joined with \n. - **x, y, width, height** (number) - Geometric coordinates and dimensions. - **lines** (LayoutLine[]) - Array of lines within the block. - **writingMode** ('vertical', optional) - Present for detected CJK top-to-bottom glyph stacks. - **role** ('heading', optional) - Heuristic heading classification. - **level** (1 | 2 | 3, optional) - Heading level (1=title, 2=section, 3=subsection). - **repeated** (boolean, optional) - Indicates if the block is chrome (header/footer/watermark). ```