Skip to content
PDF Oxide

Primeros pasos con PDF Oxide (Ruby)

PDF Oxide es la librería PDF más rápida para Ruby: 0,8 ms de media en extracción de texto y 100 % de aciertos sobre 3830 PDF. Una sola gem para extraer, buscar, convertir, crear y redactar PDF, construida sobre el mismo núcleo en Rust que impulsa los bindings de Python, Java, Node, Go, C# y PHP.

Instalación

gem install pdf_oxide

O añádela a tu Gemfile:

gem 'pdf_oxide', '~> 0.3'

La librería nativa precompilada libpdf_oxide viene incluida dentro de la gem etiquetada por plataforma: no necesitas compilador ni instalar nada a nivel de sistema. Las gems precompiladas cubren Ruby 3.1–3.4 en x86_64-linux, aarch64-linux, macOS con Intel y Apple Silicon, y Windows (x64-mingw-ucrt).

Abrir un PDF

Usa PdfDocument.open para cargar un archivo. La forma con bloque cierra el documento automáticamente cuando el bloque termina; también tienes #close, que es idempotente.

require 'pdf_oxide'

PdfOxide::PdfDocument.open('research-paper.pdf') do |doc|
  puts "Pages: #{doc.page_count}"
  puts "PDF version: #{doc.pdf_version}"
  puts "Encrypted: #{doc.encrypted?}"
end

Para documentos cifrados, pasa password::

PdfOxide::PdfDocument.open('confidential.pdf', password: 'secret') do |doc|
  puts doc.extract_text(0)
end

También puedes abrir desde bytes en memoria, algo muy práctico al recibir datos de S3, HTTP o una base de datos. PdfDocument.open detecta automáticamente los bytes de un PDF mediante la cabecera mágica %PDF-:

bytes = File.binread('report.pdf')
PdfOxide::PdfDocument.open(bytes) do |doc|
  puts doc.extract_text(0)
end

Extracción de texto

Una sola página

Extrae texto plano de cualquier página por su índice, que empieza en cero.

PdfOxide::PdfDocument.open('report.pdf') do |doc|
  text = doc.extract_text(0)
  puts text
end

Todas las páginas

PdfOxide::PdfDocument.open('book.pdf') do |doc|
  doc.page_count.times do |i|
    puts "--- Page #{i + 1} ---"
    puts doc.extract_text(i)
  end
end

Atajo en una sola llamada

Cuando solo necesitas el texto de una página, PdfDocument.extract_text abre, extrae y cierra en una única llamada:

text = PdfOxide::PdfDocument.extract_text('report.pdf', page: 0)
puts text

Extracción con enrutado automático

extract_text_auto usa el enrutador automático de la v0.3.51 para elegir entre texto nativo u OCR en cada página. En una build sin la característica ocr, recurre con elegancia a la capa de texto nativa: nunca lanza un error de “OCR no disponible”.

PdfOxide::PdfDocument.open('scan.pdf') do |doc|
  puts doc.extract_text_auto(0)
end

Para obtener un motivo tipado que describa la calidad de la extracción, usa el AutoExtractor:

PdfOxide::PdfDocument.open('scan.pdf') do |doc|
  ax     = doc.auto_extractor
  result = ax.extract_page(0)
  puts result[:text]
  warn "degraded: #{result[:reason]}" unless ax.ok?(result[:reason])
end

Trabajar con páginas

PdfDocument#page devuelve una vista ligera PdfPage que toma prestados los datos del documento. #pages devuelve una por cada página.

PdfOxide::PdfDocument.open('paper.pdf') do |doc|
  page = doc.page(0)
  puts "Index: #{page.index}"
  puts page.text   # same as doc.extract_text(0)

  doc.pages.each do |p|
    puts "Page #{p.index}: #{p.text.length} chars"
  end
end

Conversión a Markdown y HTML

Convierte una sola página (pasa su índice) o el documento completo (omite el índice) a Markdown o HTML.

PdfOxide::PdfDocument.open('paper.pdf') do |doc|
  puts doc.to_markdown(0)   # first page to Markdown
  puts doc.to_html(0)       # first page to HTML
  puts doc.to_markdown      # entire document to Markdown
end

Extracción estructurada

extract_structured devuelve la maquetación analizada de la página como un Hash: las dimensiones de la página más regiones tipadas con su texto, sus cajas delimitadoras (bounding boxes) y los índices de columna.

PdfOxide::PdfDocument.open('paper.pdf') do |doc|
  page = doc.extract_structured(0)
  puts "Size: #{page['page_width']} x #{page['page_height']}"
  page['regions'].each do |region|
    puts "#{region['kind']}: #{region['text']}"
  end
end

Búsqueda

search recorre todo el documento y devuelve un array de hashes de coincidencias, cada uno con :page, :text y un hash :bbox con :x, :y, :width y :height.

PdfOxide::PdfDocument.open('manual.pdf') do |doc|
  matches = doc.search('configuration', case_sensitive: false)
  matches.each do |m|
    bbox = m[:bbox]
    puts "Page #{m[:page]}: '#{m[:text]}' at (#{bbox[:x].round}, #{bbox[:y].round})"
  end
end

Renderizado

Renderiza una página a bytes PNG con un DPI dado:

PdfOxide::PdfDocument.open('poster.pdf') do |doc|
  png = doc.render(0, dpi: 150)
  File.binwrite('page-0.png', png)
end

Creación de PDF

La clase Pdf crea PDF a partir de Markdown, HTML o texto plano. Las instancias son dueñas de un handle nativo; usa la forma con bloque (que cierra automáticamente) o llama tú mismo a #close.

PdfOxide::Pdf.from_markdown("# Hello World\n\nThis is a PDF.") do |pdf|
  pdf.save('output.pdf')
end

PdfOxide::Pdf.from_html('<h1>Invoice</h1><p>Amount due: $42.00</p>') do |pdf|
  pdf.save('invoice.pdf')
end

PdfOxide::Pdf.from_text("Plain text document.\n\nSecond paragraph.") do |pdf|
  pdf.save('notes.pdf')
end

Obtén los bytes en lugar de guardarlos en disco con #to_bytes:

pdf_bytes = PdfOxide::Pdf.from_markdown('# Report').to_bytes
# upload pdf_bytes, attach to an email, etc.

Redacción

DocumentEditor abre un PDF existente para una redacción destructiva. apply_redactions! elimina de forma permanente el contenido cubierto y, en la misma pasada, puede limpiar los metadatos del documento.

PdfOxide::DocumentEditor.open('source.pdf') do |ed|
  ed.add_redaction(page: 0, rect: [100, 200, 300, 250])
  ed.apply_redactions!(scrub_metadata: true)
  ed.save_to('redacted.pdf')
end

Manejo de errores

PDF Oxide lanza subclases tipadas de PdfOxide::Error para los fallos específicos de PDF.

begin
  PdfOxide::PdfDocument.open('document.pdf') do |doc|
    puts doc.extract_text(0)
  end
rescue PdfOxide::FileNotFoundError
  warn 'File not found'
rescue PdfOxide::EncryptedError
  warn 'Wrong or missing password'
rescue PdfOxide::ParseError => e
  warn "Malformed PDF: #{e.message}"
rescue PdfOxide::Error => e
  warn "PDF error: #{e.message}"
end

Próximos pasos