Metadados e XMP

O PDF Oxide lê metadados em nível de documento a partir de várias fontes: o cabeçalho do PDF (versão), os dicionários do trailer e do catálogo, fluxos de metadados XMP (ISO 16684) e definições de rótulos de página. O XmpExtractor analisa os namespaces Dublin Core, XMP Core, PDF e XMP Rights, além de quaisquer propriedades personalizadas.

Use version() e catalog() para propriedades básicas do documento, XmpExtractor::extract() para metadados detalhados e PageLabelExtractor para esquemas de numeração de páginas.

Exemplo rápido

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("report.pdf")
major, minor = doc.version()
print(f"PDF {major}.{minor}, {doc.page_count()} pages")

Node.js

const { PdfDocument } = require("pdf-oxide");

const doc = new PdfDocument("report.pdf");
const { major, minor } = doc.getVersion();
console.log(`PDF ${major}.${minor}, ${doc.pageCount()} pages`);
doc.close();

Go

import pdfoxide "github.com/yfedoseev/pdf_oxide/go"

doc, _ := pdfoxide.Open("report.pdf")
defer doc.Close()
major, minor, _ := doc.Version()
pages, _ := doc.PageCount()
fmt.Printf("PDF %d.%d, %d pages\n", major, minor, pages)

C#

using PdfOxide.Core;

using var doc = PdfDocument.Open("report.pdf");
var (major, minor) = doc.Version;
Console.WriteLine($"PDF {major}.{minor}, {doc.PageCount} pages");

WASM

const doc = new WasmPdfDocument(bytes);
const version = doc.version();
console.log(`PDF ${version}, ${doc.pageCount()} pages`);

Rust

use pdf_oxide::PdfDocument;

let mut doc = PdfDocument::open("report.pdf")?;
let (major, minor) = doc.version();
println!("PDF {}.{}", major, minor);
println!("Pages: {}", doc.page_count()?);

---

Referência de API

version() -> (u8, u8)

Obtém a versão do PDF a partir do cabeçalho do arquivo.

Retorna: uma tupla (major, minor), por exemplo, (1, 7) para PDF 1.7 ou (2, 0) para PDF 2.0.

---

catalog() -> Result<Object>

Obtém o dicionário do catálogo do documento. O catálogo é a raiz da hierarquia de objetos do PDF e contém referências à árvore de páginas, aos outlines, aos names e a outras estruturas em nível de documento.

Rust

let mut doc = PdfDocument::open("report.pdf")?;
let catalog = doc.catalog()?;
if let Some(dict) = catalog.as_dict() {
    for (key, _) in dict {
        println!("Catalog key: {}", key);
    }
}

---

trailer() -> &Object

Obtém o dicionário do trailer do documento. O trailer contém a localização da tabela de referência cruzada, o ID do documento, a referência ao dicionário de criptografia e a referência ao dicionário Info.

Rust

let doc = PdfDocument::open("report.pdf")?;
let trailer = doc.trailer();
println!("Trailer: {:?}", trailer);

---

XmpExtractor::extract(doc) -> Result<Option<XmpMetadata>>

Extrai metadados XMP (Extensible Metadata Platform) do fluxo de metadados do documento. O XMP fornece metadados mais ricos do que o dicionário Info tradicional, usando namespaces XML padronizados.

Parâmetro	Tipo	Descrição
doc	&mut PdfDocument	O documento PDF

Retorna: Some(XmpMetadata) se houver dados XMP presentes, None caso contrário.

Campos de XmpMetadata

Namespace Dublin Core (dc:)

Campo	Tipo	Descrição
dc_title	Option<String>	Título do documento
dc_creator	Vec<String>	Lista de autores/criadores
dc_description	Option<String>	Descrição do documento
dc_subject	Vec<String>	Palavras-chave do assunto
dc_language	Option<String>	Idioma do documento (ex.: "en-US")
dc_rights	Option<String>	Declaração de direitos autorais
dc_format	Option<String>	Formato MIME (ex.: "application/pdf")

Namespace XMP Core (xmp:)

Campo	Tipo	Descrição
xmp_creator_tool	Option<String>	Ferramenta usada para criar o documento
xmp_create_date	Option<String>	Data de criação (ISO 8601)
xmp_modify_date	Option<String>	Data da última modificação
xmp_metadata_date	Option<String>	Data de modificação dos metadados

Namespace PDF (pdf:)

Campo	Tipo	Descrição
pdf_producer	Option<String>	Aplicativo produtor do PDF
pdf_keywords	Option<String>	String de palavras-chave
pdf_version	Option<String>	Versão do PDF a partir do XMP (pode diferir do cabeçalho)
pdf_trapped	Option<String>	Status de trapping

Namespace XMP Rights (xmpRights:)

Campo	Tipo	Descrição
xmp_rights_usage_terms	Option<String>	Termos de uso
xmp_rights_marked	Option<bool>	Se está marcado com direitos
xmp_rights_web_statement	Option<String>	URL da declaração na web

Outros

Campo	Tipo	Descrição
custom	HashMap<String, String>	Propriedades personalizadas (namespace:propriedade para valor)
raw_xml	Option<String>	O pacote XML XMP original

Rust

use pdf_oxide::extractors::xmp::XmpExtractor;

let mut doc = PdfDocument::open("report.pdf")?;
if let Some(xmp) = XmpExtractor::extract(&mut doc)? {
    if let Some(title) = &xmp.dc_title {
        println!("Title: {}", title);
    }
    for creator in &xmp.dc_creator {
        println!("Author: {}", creator);
    }
    if let Some(tool) = &xmp.xmp_creator_tool {
        println!("Created with: {}", tool);
    }
    if let Some(date) = &xmp.xmp_create_date {
        println!("Created: {}", date);
    }
    if let Some(producer) = &xmp.pdf_producer {
        println!("Producer: {}", producer);
    }
}

WASM

const doc = new WasmPdfDocument(bytes);
const xmp = doc.xmpMetadata();

if (xmp) {
  console.log(`Title: ${xmp.dc_title}`);
  console.log(`Authors: ${xmp.dc_creator}`);
  console.log(`Created with: ${xmp.xmp_creator_tool}`);
  console.log(`Created: ${xmp.xmp_create_date}`);
  console.log(`Producer: ${xmp.pdf_producer}`);
}
doc.free();

Python

doc = PdfDocument("report.pdf")
xmp = doc.xmp_metadata()

if xmp:
    print(f"Title: {xmp.get('dc_title')}")
    print(f"Authors: {xmp.get('dc_creator')}")
    print(f"Created with: {xmp.get('xmp_creator_tool')}")
    print(f"Created: {xmp.get('xmp_create_date')}")
    print(f"Producer: {xmp.get('pdf_producer')}")

<!-- Node.js: no equivalent on PdfDocumentImpl — xmp metadata not exposed in js/src/index.ts -->

Go

doc, _ := pdfoxide.Open("report.pdf")
defer doc.Close()
xmp, _ := doc.XmpMetadata() // returns JSON string
fmt.Println(xmp)

C#

using var doc = PdfDocument.Open("report.pdf");
var xmp = doc.GetXmpMetadata(); // returns JSON string
Console.WriteLine(xmp);

---

Métodos de conveniência de Pdf

A API de alto nível Pdf fornece métodos de atalho para consultas comuns de metadados.

xmp_metadata() -> Result<Option<XmpMetadata>>

Obtém o objeto completo de metadados XMP.

xmp_title() -> Result<Option<String>>

Obtém apenas o título do documento a partir do XMP.

xmp_creators() -> Result<Vec<String>>

Obtém a lista de criadores/autores a partir do XMP.

Rust

use pdf_oxide::api::Pdf;

let mut pdf = Pdf::open("report.pdf")?;

if let Some(title) = pdf.xmp_title()? {
    println!("Title: {}", title);
}

let creators = pdf.xmp_creators()?;
for creator in &creators {
    println!("Author: {}", creator);
}

---

PageLabelExtractor::extract(doc) -> Result<Vec<PageLabelRange>>

Extrai as definições de rótulos de página do documento. Os rótulos de página definem como os números de página são exibidos (por exemplo, numerais romanos para as páginas iniciais, numerais arábicos para o corpo).

Parâmetro	Tipo	Descrição
doc	&mut PdfDocument	O documento PDF

Retorna: um vetor de definições PageLabelRange.

Campos de PageLabelRange

Campo	Tipo	Descrição
start_page	usize	Índice da primeira página à qual este intervalo se aplica
style	PageLabelStyle	Estilo de numeração
prefix	Option<String>	String de prefixo do rótulo
start_number	u32	Número inicial deste intervalo

Variantes de PageLabelStyle

Variante	Descrição	Exemplo
DecimalArabic	Numerais arábicos	1, 2, 3
UppercaseRoman	Romanos maiúsculos	I, II, III
LowercaseRoman	Romanos minúsculos	i, ii, iii
UppercaseLetters	Letras maiúsculas	A, B, C
LowercaseLetters	Letras minúsculas	a, b, c
None	Sem numeração (apenas prefixo)	–

---

Métodos de conveniência de rótulos de página de Pdf

page_labels() -> Result<Vec<PageLabelRange>>

Obtém todas as definições de intervalos de rótulos de página.

page_label(page) -> Result<String>

Obtém o rótulo de exibição para um índice de página específico.

Rust

use pdf_oxide::api::Pdf;

let mut pdf = Pdf::open("book.pdf")?;

// Get all label ranges
let ranges = pdf.page_labels()?;
for range in &ranges {
    println!(
        "Pages from {}: {:?} style, prefix={:?}, start={}",
        range.start_page, range.style, range.prefix, range.start_number
    );
}

// Get label for a specific page
let label = pdf.page_label(0)?;
println!("Page 0 label: {}", label); // e.g., "i" or "Cover"

WASM

const doc = new WasmPdfDocument(bytes);
const labels = doc.pageLabels();

for (const range of labels) {
  console.log(`Pages from ${range.start_page}: style=${range.style}, prefix=${range.prefix}`);
}
doc.free();

Python

doc = PdfDocument("book.pdf")
labels = doc.page_labels()

for range in labels:
    print(f"Pages from {range['start_page']}: style={range['style']}, prefix={range['prefix']}")

<!-- Node.js: no equivalent on PdfDocumentImpl — pageLabels not exposed on class, only via properties mixin -->

Go

doc, _ := pdfoxide.Open("book.pdf")
defer doc.Close()
labels, _ := doc.PageLabels() // returns JSON string
fmt.Println(labels)

C#

using var doc = PdfDocument.Open("book.pdf");
var labels = doc.GetPageLabels(); // returns JSON string
Console.WriteLine(labels);

---

Exemplos avançados

Exibir os metadados completos do documento

use pdf_oxide::PdfDocument;
use pdf_oxide::extractors::xmp::XmpExtractor;

let mut doc = PdfDocument::open("report.pdf")?;

// Basic info
let (major, minor) = doc.version();
println!("PDF Version: {}.{}", major, minor);
println!("Pages: {}", doc.page_count()?);

// XMP metadata
if let Some(xmp) = XmpExtractor::extract(&mut doc)? {
    println!("\nXMP Metadata:");
    println!("  Title:       {:?}", xmp.dc_title);
    println!("  Authors:     {:?}", xmp.dc_creator);
    println!("  Description: {:?}", xmp.dc_description);
    println!("  Keywords:    {:?}", xmp.pdf_keywords);
    println!("  Creator:     {:?}", xmp.xmp_creator_tool);
    println!("  Producer:    {:?}", xmp.pdf_producer);
    println!("  Created:     {:?}", xmp.xmp_create_date);
    println!("  Modified:    {:?}", xmp.xmp_modify_date);
    println!("  Language:    {:?}", xmp.dc_language);
    println!("  Rights:      {:?}", xmp.dc_rights);

    if !xmp.custom.is_empty() {
        println!("\n  Custom properties:");
        for (key, value) in &xmp.custom {
            println!("    {}: {}", key, value);
        }
    }
}

Acessar o XML XMP bruto

use pdf_oxide::extractors::xmp::XmpExtractor;

let mut doc = PdfDocument::open("report.pdf")?;
if let Some(xmp) = XmpExtractor::extract(&mut doc)? {
    if let Some(xml) = &xmp.raw_xml {
        std::fs::write("metadata.xml", xml)?;
        println!("Raw XMP saved ({} bytes)", xml.len());
    }
}

Gerar strings de exibição dos números de página

use pdf_oxide::api::Pdf;

let mut pdf = Pdf::open("thesis.pdf")?;
let page_count = pdf.page_count()?;

for i in 0..page_count {
    let label = pdf.page_label(i)?;
    println!("Physical page {} -> display label '{}'", i + 1, label);
}
// Example output:
//   Physical page 1 -> display label 'i'
//   Physical page 2 -> display label 'ii'
//   Physical page 3 -> display label 'iii'
//   Physical page 4 -> display label '1'
//   Physical page 5 -> display label '2'

---

Páginas relacionadas

• Extração de texto – Extraia o conteúdo de texto das páginas
• Extração de anotações – Acesse marcadores e anotações
• Extração de dados de formulário – Extraia os dados dos campos de formulário