ofd-rs 0.2.0

OFD (Open Fixed-layout Document, GB/T 33190-2016) library for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

# ofd-rs

Rust library for creating OFD (Open Fixed-layout Document) files, based on the Chinese national standard **GB/T 33190-2016**.

[![Crates.io](https://img.shields.io/crates/v/ofd-rs.svg)](https://crates.io/crates/ofd-rs)
[![Documentation](https://docs.rs/ofd-rs/badge.svg)](https://docs.rs/ofd-rs)
[![License](https://img.shields.io/crates/l/ofd-rs.svg)](https://github.com/yealou/ofd-rs/blob/main/LICENSE)

## What is OFD?

OFD (Open Fixed-layout Document) is a fixed-layout document format standardized by the Chinese national standard GB/T 33190-2016. It serves a similar role to PDF and is widely used in Chinese government and enterprise document workflows, especially for electronic invoices, official documents, and archival purposes.

An OFD file is a ZIP archive containing XML descriptors and embedded resources (images, fonts, etc.).

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
ofd-rs = "0.1"
```

## Quick Start

```rust
use ofd_rs::{OfdWriter, ImageSource};

// Convert a JPEG image to a single-page OFD document
let jpeg_bytes = std::fs::read("photo.jpg").unwrap();
let ofd = OfdWriter::from_images(vec![
    ImageSource::jpeg(jpeg_bytes, 2480, 3508, 300.0), // width_px, height_px, DPI
]).build().unwrap();
std::fs::write("output.ofd", ofd).unwrap();
```

## Features

### Current (v0.1)

- **Image to OFD** - Convert images (JPEG, PNG, BMP, TIFF) to OFD documents
- **Multi-page support** - Combine multiple images into a single OFD file
- **Mixed page sizes** - Each page can have different dimensions
- **Custom metadata** - Set document title, author, creator, creation date
- **Builder pattern** - Flexible API for constructing OFD documents
- **Spec compliant** - Follows GB/T 33190-2016 namespace and structure conventions
- **Minimal dependencies** - Only `zip` and `uuid`, no heavy XML frameworks

### API Overview

**Quick API** - One image per page:

```rust
use ofd_rs::{OfdWriter, ImageSource};

let ofd = OfdWriter::from_images(vec![
    ImageSource::jpeg(page1_bytes, 2480, 3508, 300.0),
    ImageSource::jpeg(page2_bytes, 2480, 3508, 300.0),
]).build()?;
```

**Builder API** - More control:

```rust
use ofd_rs::{OfdWriter, ImageSource, DocInfo};

let mut writer = OfdWriter::new();
writer.set_doc_info(DocInfo {
    doc_id: "my-doc-id".into(),
    title: Some("Invoice".into()),
    author: Some("Company".into()),
    creator: Some("MyApp".into()),
    creator_version: Some("1.0".into()),
    creation_date: Some("2026-03-06".into()),
});
writer.add_image_page(ImageSource::jpeg_mm(jpeg_bytes, 210.0, 297.0)); // A4 size in mm
let ofd = writer.build()?;
```

**Page size options**:

```rust
// From pixel dimensions + DPI (auto-calculates mm)
ImageSource::jpeg(bytes, width_px, height_px, dpi);

// From explicit mm dimensions
ImageSource::jpeg_mm(bytes, width_mm, height_mm);

// Any format with explicit mm dimensions
ImageSource::new(bytes, ImageFormat::Png, width_mm, height_mm);
```

## OFD File Structure

The generated OFD follows this structure:

```
output.ofd (ZIP)
├── OFD.xml                         # Entry point
└── Doc_0/
    ├── Document.xml                # Document root (pages, resources)
    ├── DocumentRes.xml             # Image resource declarations
    ├── PublicRes.xml               # Fonts, color spaces
    ├── Pages/
    │   ├── Page_0/Content.xml      # Page 0 content
    │   ├── Page_1/Content.xml      # Page 1 content
    │   └── ...
    └── Res/
        ├── Image_0.jpg             # Embedded image files
        ├── Image_1.jpg
        └── ...
```

## Roadmap

- [ ] **OFD Reader** - Parse and extract content from existing OFD files
- [ ] **Text rendering** - TextObject support with font embedding
- [ ] **Vector graphics** - PathObject for lines, curves, shapes
- [ ] **Digital signatures** - Electronic seal and signature support (GB/T 38540)
- [ ] **Template rendering** - Generate OFD from templates with dynamic data
- [ ] **PDF to OFD** - Convert PDF documents to OFD format
- [ ] **OFD to PDF** - Convert OFD documents to PDF format

## License

Licensed under Apache License 2.0. See [LICENSE](LICENSE) for details.