⚡ RasgaPDF

---

🎯 The Philosophy: Pure Spatial Parsing

Most PDF libraries make fragile guesses: they convert multi-column documents into flat, corrupted text streams, mangle tables, and strip away spatial geometry.

RasgaPDF does one thing with uncompromising precision:
It returns the exact 2D physical spatial geometry of the PDF.

• Bounding Boxes Everywhere: Every character, word span, line, block, and table has exact coordinates [x0, y0, x1, y1].
• Zero Lossy Guesswork: No broken heuristics pretending to be Markdown. Your downstream LLMs, RAG pipelines, or OCR validators receive the true physical layout.
• Microsecond Rayon Parallelism: Multi-threaded page processing in pure Rust utilizing AVX2/AVX-512 SIMD.
• Polyglot First: Native C-ABI FFI bindings for Python, Node.js, Go, and C# (.NET).

---

⚡ Two Parsing Modes

RasgaPDF offers two distinct modes for different engineering needs:

⚡ Modo 1: Coordenadas Brutas (Raw X/Y Puro)

O retorno mais direto, bruto e rápido possível. Retorna exclusivamente a lista plana de coordenadas físicas de cada elemento desenhado na página, sem criar hierarquias de blocos ou overhead de tabelas:

• Latência: ~3 a 8 ms por página
• Saídas suportadas: JSON plano, Text formatado, TSV ou CSV
• Uso ideal: RAG espacial, visualizadores 2D, indexação vetorial, pipelines Unix com awk/grep.

[Pág. 1] (X0:  50.00, Y0:  67.00, X1: 244.00, Y1:  83.00) [12.0pt] A Revolução da Inteligência Artificial
[Pág. 1] (X0:  50.00, Y0: 103.00, X1: 478.00, Y1: 119.00) [12.0pt] A Inteligência Artificial (IA) tem transformado...

🎯 Modo 2: Estruturado Hierárquico

Processa a geometria e agrupa elementos em parágrafos visuais (blocks), linhas (lines), spans de fonte e detecta matrizes de tabelas automaticamente via projeção horizontal de colunas:

• Latência: ~8 a 15 ms por página
• Saída: Árvore hierárquica SpatialDocument -> pages -> text_blocks -> lines -> tables.

---

⚡ Performance Benchmark

Measured on Intel Core i7-1365U (10 Cores / 12 Threads, AVX2):

Library / Tool	Language	Single Page	50 Pages	Memory Footprint	Output Type
⚡ RasgaPDF (Raw X/Y)	Rust (Native)	7.7 ms	95 ms	~14 MB	Flat Raw Coordinates
🚀 RasgaPDF (Structured)	Rust (Native)	8.5 ms	142 ms	~18 MB	Spatial Blocks & Tables
PyMuPDF (fitz)	C / Python	28.0 ms	620 ms	~45 MB	Text / Pixmap
pdfplumber	Python	410.0 ms	9,800 ms	~140 MB	Python dicts
pypdf	Python	95.0 ms	2,100 ms	~85 MB	Flat text string
Apache Tika	Java	650.0 ms	12,400 ms	~320 MB	XHTML

---

💻 Standalone CLI Tool

cargo build --release
./target/release/rasgapdf --help

# ⚡ MODO 1: Coordenadas Brutas (Raw X/Y)
./target/release/rasgapdf sample.pdf --raw
./target/release/rasgapdf sample.pdf --raw --format text
./target/release/rasgapdf sample.pdf --raw --format csv
./target/release/rasgapdf sample.pdf --raw --format tsv

# 🎯 MODO 2: Estruturado (Hierárquico com Blocos e Tabelas)
./target/release/rasgapdf sample.pdf --pretty
./target/release/rasgapdf sample.pdf -o output.json

---

🚀 Polyglot Quickstart

🐍 Python

import rasgapdf

# ⚡ Modo 1: Coordenadas Brutas (Raw X/Y)
raw = rasgapdf.parse_raw("document.pdf")
print(f"Extraídos {raw['total_spans']} spans em {raw['parse_time_ms']:.2f} ms")
for s in raw["spans"]:
    print(f"Pág {s['page']} | ({s['x0']}, {s['y0']}) -> {s['text']}")

# 🎯 Modo 2: Estruturado (Hierárquico)
doc = rasgapdf.parse_pdf("document.pdf", detect_tables=True)
for page in doc["pages"]:
    for table in page["tables"]:
        print("Tabela detectada:", table["rows"])

🟢 Node.js

const rasgapdf = require('rasgapdf');

// ⚡ Modo 1: Coordenadas Brutas
const raw = rasgapdf.parseRaw('document.pdf');
console.log(`Raw: ${raw.total_spans} spans em ${raw.parse_time_ms} ms`);

// 🎯 Modo 2: Estruturado
const doc = rasgapdf.parsePdf('document.pdf');
console.log(`Blocos de texto: ${doc.pages[0].text_blocks.length}`);

🔵 Go

package main

import (
    "fmt"
    "github.com/messiasmartins/rasgapdf/bindings/go"
)

func main() {
    // ⚡ Modo 1: Coordenadas Brutas
    raw, _ := rasgapdf.ParseRaw("document.pdf")
    fmt.Printf("Raw: %d spans em %.2f ms\n", raw.TotalSpans, raw.ParseTimeMs)

    // 🎯 Modo 2: Estruturado
    opts := rasgapdf.DefaultOptions()
    doc, _ := rasgapdf.ParseFile("document.pdf", &opts)
    fmt.Printf("Estruturado: %d páginas\n", doc.TotalPages)
}

🟣 C# / .NET 8

using RasgaPdf;

// ⚡ Modo 1: Coordenadas Brutas
var raw = SpatialPdf.ParseRaw("document.pdf");
Console.WriteLine($"Raw: {raw.TotalSpans} spans em {raw.ParseTimeMs} ms");

// 🎯 Modo 2: Estruturado
var doc = SpatialPdf.Parse("document.pdf");
Console.WriteLine($"Estruturado: {doc.TotalPages} páginas");

---

🎨 Interactive Gradio Demo

We provide an interactive visual spatial explorer built with Gradio:

cd demo_gradio
pip install -r requirements.txt
python app.py

Acesse http://localhost:7860 para:

• Inspecionar a tabela interativa de Coordenadas Físicas (Raw X/Y).
• Visualizar os bounding boxes translúcidos sobrepostos à página do PDF.
• Analisar tabelas detectadas renderizadas em DataFrames.
• Exportar JSONs brutos ou estruturados.

---

🤝 Contributing & Community

Contributions are what make the open-source community thrive!

• Read our Contributing Guide to get started.
• Adhere to our Code of Conduct.

---

📄 License

RasgaPDF is licensed under the MIT License.
Copyright (c) 2026 Messias Martins.