Skip to content

About

Rust OFD/PDF/DOCX engine: format conversion, layout/pagination, PNG rasterization, text search and font subsetting on write. Rust 多格式文档引擎:OFD/PDF/DOCX 互转与排版,页面光栅化为 PNG,支持文本搜索与 OFD/PDF 写出(含字体子集化)。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

English | 简体中文

ofdbox-folio

OFDBox Folio is a page-centric multi-format document engine: it reads OFD, PDF and DOCX, unifies them into Flow IR / Fixed IR, and handles layout, rendering and writing.

Features

  • Open OFD, PDF and DOCX through one reader: OFD/PDF load pages on demand, DOCX is read into Flow IR and laid out eagerly.
  • Import Markdown into Flow IR (headings, emphasis, links, lists, code blocks, tables and images) and export it through the same layout and OFD/PDF writers.
  • Build Flow IR with one creation API: write DOCX directly, or write OFD/PDF/bitmaps after layout.
  • Fixed IR as the unified read model: lazy pages, text selection/search, page cache, incremental rendering.
  • Wrap any laid-out FixedDocument back into the reader (FixedDocumentSource) to reuse caching, selection and search.
  • Deterministic output for the same input, font bytes and engine version.
  • CPU renderer plus optional GPU (wgpu 27/30) and tiny-skia backends; the GPU backend is selected at build time with gpu27 / gpu30.
  • OFD/PDF writers with font subsetting.

The engine is organized around a single flow:

Creation API ───┐
                ├──► Flow IR ──────► DOCX write
DOCX read ──────┘       │
                        │ layout (one-way)
                        ▼
                    Fixed IR ─────┬──► bitmap rendering
                        ▲         ├──► OFD write
                        │         └──► PDF write
                        │
OFD / PDF read ─────────┘

Flow IR is the semantic, editable model (twips, no absolute coordinates); Fixed IR is the immutable, cacheable page model (millimetres, origin top-left, y down). Layout is the only downward path; OFD/PDF reading bypasses it, and DOCX writing consumes Flow IR directly.

Architecture

ofdbox-folio                façade: format probing, Reader, creation API, convenience conversion
├─ ofdbox-folio-ofd        OFD read/write        → ofdbox-core
├─ ofdbox-folio-pdf        PDF read/write        → lopdf
├─ ofdbox-folio-docx       DOCX read/write       → zip + quick-xml
├─ ofdbox-folio-markdown   Markdown → Flow IR
├─ ofdbox-folio-layout     Flow → Fixed, one-way layout
├─ ofdbox-folio-render     Fixed → bitmap, CPU/GPU rendering and caching
└─ ofdbox-folio-ir         Flow IR, Fixed IR, geometry, resources, text layer, Reader contracts

Format adapters, layout and rendering depend on ofdbox-folio-ir; ofdbox-folio-ir depends on no format library or rendering backend.

Details: architecture · facade & reader · IR · layout · OFD · PDF · DOCX · render.

Quick Start

cargo test --workspace

Read a page (OFD, PDF and DOCX use the same API):

use ofdbox_folio::{Document, OpenOptions};

let mut document = Document::open_path("input.ofd", OpenOptions::default())?;
let page = document.page(0)?;

// DOCX is read into Flow IR and laid out on open.
let mut document = Document::open_path("input.docx", OpenOptions::default())?;

Build Flow IR and write DOCX, or lay it out and write OFD:

use ofdbox_folio::{
    docx::{DocxWriteOptions, write_flow},
    ir::{Block, FlowDocument, Inline, ParaStyle, Paragraph, TextRun, TextStyle},
    layout::layout,
    ofd::{OfdWriteOptions, write_fixed},
};

let mut flow = FlowDocument::new(Default::default());
let mut paragraph = Paragraph::new(ParaStyle::default());
paragraph.runs.push(Inline::Text(TextRun::new("Hello, world", TextStyle::default())));
flow.push(Block::Paragraph(paragraph));

let docx = write_flow(&flow, &DocxWriteOptions::default())?;

let mut fonts = MyFontProvider::new();
let fixed = layout(&flow, &mut fonts)?;
let ofd = write_fixed(&fixed, &OfdWriteOptions::default())?;

Render or convert from the command line:

cargo run -p ofdbox-folio --example ofd_to_png -- input.ofd output.png 0 96
cargo run -p ofdbox-folio --example docx_to_ofd -- input.docx output.ofd

Guarantees & Limits

  • One-way: only Flow → Fixed; Fixed IR keeps no back-references to Flow.
  • Format-neutral: OFD/PDF/DOCX types never appear in IR, layout or rendering interfaces.
  • Immutable pages: a Page is cacheable and shareable; OFD/PDF documents are not fully built on open (DOCX is laid out eagerly).
  • Units: Flow uses twips, Fixed uses millimetres, origin top-left, y down.
  • Determinism: no clock, randomness or environment reads; same input + fonts + options + version → identical output.
  • Failures are returned as errors or recorded as diagnostics; parsers do not panic on untrusted input.

Known limits:

  • OFD without embedded fonts needs a caller-provided FontProvider; otherwise text is kept in the text layer but not drawn.
  • OFD template pages are flattened into page content.
  • The page cache accounts for page structure only; fonts and images are shared document resources.
  • The GPU backend covers solid fills, strokes, linear gradients, clipping, atlas-backed text and RGBA images; path radial gradients and blend modes are CPU-only, while text radial gradients are supported.
  • OFD pattern/mesh fills are not written yet; PDF tiling patterns and JPEG2000 are not read yet.
  • DOCX is laid out eagerly when opened, so its page count and layout cost are paid up front; the page cache then caches laid-out pages instead of deferring parsing.
  • DOCX layout approximates Word (no line-by-line fidelity); table and header/footer fidelity is still being hardened.

Status & Roadmap

Phase Content State
R1 Reader kernel IR, OFD reading, CPU rendering, text layer, page cache done
R2 Flow documents Flow IR, layout (columns/tables/headers/footers/TOC), DOCX read/write, creation API in progress
R3 PDF hardening fonts/CMaps, patterns, transparency, encryption, malformed files in progress
R4 Document capabilities annotations/forms, attachments, outline editing, GPU planned

Verification

cargo test --workspace

Acceptance highlights: generated OFD is strictly readable and byte-identical after a strict rewrite; layout digests are stable across platforms; reader memory stays bounded as page count grows; selection/search never re-parse pages; a damaged page does not affect others.

Docs & License

Dual-licensed under MIT or Apache-2.0, at your option: LICENSE-MIT · LICENSE-APACHE.

About

Rust OFD/PDF/DOCX engine: format conversion, layout/pagination, PNG rasterization, text search and font subsetting on write. Rust 多格式文档引擎:OFD/PDF/DOCX 互转与排版,页面光栅化为 PNG,支持文本搜索与 OFD/PDF 写出(含字体子集化)。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages