ocr 0.1.0

A minimalist OCR library for Rust — from scratch, no external engine
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
127
128
129
130
131
132

# SPEC

## Library API (crate `ocr`)

### `OcrEngine`

Builder-style configuration and OCR entry points.

| Method           | Signature | Description |
|------------------|-----------|-------------|
| `new`            | `() -> Self` | Default engine (`language`: `"eng"`, preprocessing off) |
| `language`       | `(impl Into<String>) -> Self` | Sets `language` field (reserved / future use) |
| `preprocessing`  | `(bool) -> Self` | Enable grayscale + threshold preprocessing before binarize |
| `recognize_file` | `(&Path) -> Result<OcrResult>` | Load image from path and run OCR |
| `recognize_bytes`| `(&[u8]) -> Result<OcrResult>` | Decode image from memory and run OCR |
| `recognize_image`| `(&DynamicImage) -> Result<OcrResult>` | Run OCR on an already-loaded image |

### `OcrResult`

| Field         | Type | Description |
|---------------|------|-------------|
| `text`        | `String` | Full text; lines joined with `\n` |
| `words`       | `Vec<OcrWord>` | Word-level segments (space-split within a line) |
| `confidence`  | `f32` | Average character confidence (0–100) |

### `OcrWord`

| Field            | Type | Description |
|------------------|------|-------------|
| `text`           | `String` | Recognized word |
| `confidence`     | `f32`  | Average confidence for characters in the word |
| `bounding_box`   | `BoundingBox` | Union bbox of character boxes in the word |

### `BoundingBox`

| Field    | Type | Description |
|----------|------|-------------|
| `x`      | `u32` | Left edge (pixels) |
| `y`      | `u32` | Top edge (pixels) |
| `width`  | `u32` | Width (pixels) |
| `height` | `u32` | Height (pixels) |

### `Error`

| Variant   | Description |
|-----------|-------------|
| `Io`      | I/O errors (including filesystem) |
| `Image`   | Image decode errors (`image` crate) |
| `NoText`  | No text detected (reserved / optional use) |

### Preprocessing (`preprocess` module)

| Item / fn     | Description |
|---------------|-------------|
| `grayscale`   | Luminance from dynamic image |
| `threshold`   | Binary image at fixed level |
| `binarize`    | Otsu threshold → `Vec<Vec<bool>>` grid (used by engine) |
| `preprocess`  | Grayscale then threshold at 128 (optional path) |
| `clean_noise` | Remove small foreground components |

---

## CLI (binary `ocr`)

```
ocr [OPTIONS] <IMAGE_PATH>

Arguments:
  <IMAGE_PATH>     Path to the image file

Options:
  -f, --format <FORMAT>   Output format: text, json [default: text]
      --preprocess       Enable preprocessing before OCR
  -h, --help             Print help
  -V, --version          Print version
```

**Output**

- `text` — plain text to stdout  
- `json` — pretty-printed `OcrResult`

**Note:** There is **no** `--tesseract` (or any external OCR) option; recognition is entirely in-process.

---

## MCP server (binary `ocr-mcp`)

Transport: stdio (MCP JSON-RPC on stdin/stdout).

### Tools

#### `ocr_image`

OCR on an image file (absolute path recommended for tools).

| Parameter     | Type   | Description |
|---------------|--------|-------------|
| `image_path`  | string | Path to the image file |

**Returns:** Extracted text; may append a short confidence / word-count footer.

#### `ocr_base64`

OCR on base64-encoded image bytes (raw base64 or data URI).

| Parameter       | Type   | Description |
|-----------------|--------|-------------|
| `image_base64`  | string | Encoded image |

**Returns:** Same shape as `ocr_image`. Errors are returned as plain-text lines starting with `Error:`.

---

## System dependencies

**None** for OCR. Only a normal Rust toolchain is required to build. Runtime does not invoke Tesseract or other OCR installations.

## Rust dependencies (see `Cargo.toml`)

| Crate              | Purpose |
|--------------------|---------|
| `image`            | Load/decode images, export formats |
| `thiserror`        | Error enum |
| `serde` / `serde_json` | JSON serialization (CLI / MCP) |
| `clap`             | CLI parsing |
| `anyhow`           | CLI error convenience |
| `tokio`            | Async runtime (MCP server) |
| `rmcp`             | MCP server implementation |
| `schemars`         | JSON Schema for MCP tool params |
| `base64`           | MCP base64 decoding |
| `tracing` / `tracing-subscriber` | Logging (MCP) |