From 5d4965f014e38184acdaf954cd2aab901b25cf5c Mon Sep 17 00:00:00 2001
From: wangjue <wangjue@maxieyetech.com>
Date: Fri, 29 May 2026 16:25:34 +0800
Subject: [PATCH] Add README

---
 README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..014f352
--- /dev/null
+++ b/README.md
@@ -0,0 +1,80 @@
+# OCR
+
+Offline OCR tool based on [llama.cpp](https://github.com/ggml-org/llama.cpp) and its multimodal extension (mmproj). Supports GLM-OCR and other vision‑language models.
+
+## Requirements
+
+- **C++17** compiler
+- CMake ≥ 3.15
+- llama.cpp libraries: `libllama.so`, `libmtmd.so`, `libggml*.so`
+- llama.cpp headers: `llama.h`, `mtmd.h`, `mtmd-helper.h`, `ggml.h`
+- (Optional) CUDA 12.2 runtime for GPU acceleration
+
+### Runtime Dependencies
+
+| Feature       | Tool                          |
+| ------------- | ----------------------------- |
+| File input    | —                             |
+| Clipboard     | `wl-paste` (Wayland) / `xclip` (X11) |
+| Screenshot    | `gnome-screenshot`, `flameshot`, `spectacle`, `maim`, or `slurp+grim` |
+
+## Build
+
+```bash
+cmake -S . -B build
+cmake --build build
+```
+
+### Custom dependency paths
+
+The build expects the llama.cpp libraries and headers under `deps/llama.cpp/`. To use a different location, edit `DEPS_DIR` in `CMakeLists.txt`.
+
+## Usage
+
+```bash
+ocr -m <model.gguf> --mmproj <mmproj.gguf> [options] [<image_path>]
+```
+
+### Options
+
+| Flag                   | Description                                  |
+| ---------------------- | -------------------------------------------- |
+| `-m`, `--model`        | Model file path (GGUF)                       |
+| `--mmproj`             | Multimodal projection file path (GGUF)       |
+| `-p`                   | OCR prompt (default: `OCR`)                  |
+| `-t`                   | Thread count (default: CPU cores)            |
+| `--ngl`                | GPU layers (`-1` = all, default: `-1`)       |
+| `-c`                   | Context size (default: `8192`)               |
+| `--temp`               | Sampling temperature (`0` = greedy, default: `0`) |
+| `-s`                   | Random seed                                  |
+| `--json`               | Output in JSON format                        |
+| `--chat-template`      | Chat template name (default: auto from model) |
+| `--screenshot`         | Interactively select screen region to OCR    |
+| `-q`, `--quiet`        | Suppress info logs, show only OCR result     |
+| `-h`                   | Show help                                    |
+
+### Examples
+
+```bash
+# OCR an image file
+ocr -m GLM-OCR-Q8_0.gguf --mmproj mmproj-GLM-OCR-Q8_0.gguf -p "OCR" screenshot.png
+
+# Read image from clipboard
+ocr -m GLM-OCR-Q8_0.gguf --mmproj mmproj-GLM-OCR-Q8_0.gguf
+
+# Interactive screen region selection
+ocr -m GLM-OCR-Q8_0.gguf --mmproj mmproj-GLM-OCR-Q8_0.gguf --screenshot
+
+# Quiet mode (suppress loading logs)
+ocr -m model.gguf --mmproj mmproj.gguf -q image.png
+
+# JSON output
+ocr -m model.gguf --mmproj mmproj.gguf --json image.png
+```
+
+## Notes
+
+- The `--mmproj` flag is **required** (no short form).
+- The chat template is auto-detected from the model's GGUF metadata. Use `--chat-template` to override.
+- When `add_special=false`, BOS is not added because the chat template output already contains the necessary prefix tokens (e.g. `[gMASK]<sop>` for GLM-OCR models).
+- The screenshot temp file is automatically cleaned up after processing.