# HiOCR

**Repository Path**: ylxdxx/hiocr

## Basic Information

- **Project Name**: HiOCR
- **Description**: 针对 Linux 桌面 Wayland 环境写的一款文字、公式、表格识别工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-29
- **Last Updated**: 2026-05-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HiOCR

一款 Linux 桌面智能截图识别工具，将屏幕上的**文字、数学公式、表格**一键转为可编辑文本。

![Screenshot](Screenshot.png)

---

## 特性

- **截图识别** — 框选屏幕任意区域，自动识别内容，支持 Wayland / X11
- **三种模式** — 文字、公式、表格，各有独立可配置的提示词
- **流式输出** — 识别结果边出边看，无需等待完整响应
- **公式渲染** — Temml 引擎 + 六种数学字体，渲染效果接近 LaTeX 排版
- **多服务管理** — 同时配置本地模型和远程 API，一键切换，自动故障转移
- **LaTeX 格式化** — 复制前可调用外部工具（如 `latexindent`）美化代码，可设执行顺序
- **外部脚本处理** — 对复制内容二次加工（去换行、格式转换等），支持分类型配置
- **静默模式** — 窗口不弹出，悬浮球动画通知识别状态，右键查看结果
- **历史记录** — SQLite 持久化，分页浏览，支持加载回溯
- **源码行号** — 编辑器行号显示，可开关

---

## 快速开始

### 依赖

- CMake ≥ 3.20
- C++17 编译器
- Qt6：Core、Gui、Widgets、Network、WebEngineWidgets、WebChannel、DBus、Sql
- 可选：KF6GlobalAccel（KDE 全局快捷键）、KF6WindowSystem（Wayland 悬浮球置顶）

### 编译

```bash
git clone https://gitee.com/ylxdxx/hiocr.git
cd hiocr && mkdir build && cd build
cmake ..
make
sudo make install
```

### 首次使用

1. 设置中填写识别服务地址（兼容 OpenAI Vision API 格式）
2. 按下截图快捷键（默认 `Ctrl+Alt+M`）
3. 框选屏幕区域，等待识别结果
4. 点击「内容」「行内」「行间」按钮复制

---

## 界面布局

```
┌──────────────────────────────────────────────────────┐
│  文件  工具  识别服务  设置   脚本|文字 公式 表格 纯公式|格式化  │
├────────────────────┬─────────────────────────────────┤
│                    │  提示词: [______________]        │
│   图片查看器       │  [文字] [公式] [表格] [识别]     │
│   (支持缩放/拖拽)  ├─────────────────────────────────┤
│                    │  Markdown 源码编辑区             │
│                    │  (支持行号显示)                   │
├────────────────────┼─────────────────────────────────┤
│  Markdown 渲染区    │  [内容] [行内] [行间]            │
└────────────────────┴─────────────────────────────────┘
```

---

## 功能详解

### 截图与输入

| 方式 | 操作 |
|------|------|
| 快捷键截图 | 按下全局快捷键后框选区域 |
| 粘贴图片 | 图片区 `Ctrl+V` 粘贴剪贴板图片 |
| 打开文件 | 菜单 → 文件 → 打开图片 |
| 命令行 | `hiocr -i /path/to/image.png` |

高 DPI 屏幕自动适配，区域选择器带红色十字光标。

### 识别服务管理

HiOCR 是客户端，需连接兼容 OpenAI Vision API 的服务。

**服务类型：**

| 类型 | 示例 |
|------|------|
| 远程 API | 通义千问、DeepSeek、Gemini 等 |
| 本地模型 | llama-server、Ollama、vLLM 等 |

**功能亮点：**

- 每个服务独立配置地址、API Key、模型名称和提示词
- 两种运行策略：「仅保留一个」（省内存）或「并行运行」（零延迟切换）
- 设置默认本地服务后，远程失败时自动切换并启动
- 工具栏下拉框 + 启动/停止按钮，运行状态一目了然

### 复制选项

识别结果下方三个按钮：

| 按钮 | 行为 |
|------|------|
| **内容** | 复制原始文本，纯公式自动去 `$` 包裹 |
| **行内** | 复制为 `$...$` 格式 |
| **行间** | 复制为 `$$...$$` / `\begin{equation}` / `\begin{align}` |

混合内容（文字+公式）的行间复制会自动将 `$$...$$` 统一转换为所选环境。

### LaTeX 代码格式化

在复制前自动调用格式化工具美化 LaTeX 代码。

- **设置**：行为设置 → 填入格式化命令（如 `latexindent -`）
- **执行顺序**：可设"先格式化再外部处理"或"先外部处理再格式化"
- **快速开关**：工具栏「格式化」复选框一键启停
- **错误处理**：格式化失败时弹出错误提示并取消复制

### 外部脚本处理

对不同类型内容配置独立的处理脚本，通过 stdin → stdout 管道执行。

| 类型 | 用途 |
|------|------|
| 文字处理 | 处理普通文本结果 |
| 公式处理 | 处理公式结果 |
| 表格处理 | 处理表格结果 |
| 纯公式处理 | 优先级最高，仅含单个公式时使用 |

脚本示例（去除换行）：

```python
#!/usr/bin/env python3
import sys
text = sys.stdin.read()
print(text.replace('\n', ' '))
```

设置中填入 `python3 /path/to/script.py`，工具栏勾选对应类型。脚本会收到 `--mode-name` 参数传入当前服务名称。

### 图片查看器

- 四种模式：**整页** / **同宽** / **同高** / **原大**
- `Ctrl+滚轮` 自由缩放
- 右键菜单复制图片

### 源码编辑器与行号

- Markdown 源码实时编辑，修改后渲染区同步更新
- 设置 → 显示 → "显示行号"，开启后编辑器左侧显示行号
- 渲染区和编辑器字体大小可独立调整

### 公式渲染

六种数学字体可选，通过 Temml 引擎渲染：

Latin Modern（默认） · Asana · STIX Two · Libertinus · Noto Sans · Local

支持 `\begin{aligned}`、`\begin{cases}`、矩阵、物理单位等复杂结构。

### 快捷键

所有快捷键可在设置中自定义。

| 功能 | 默认快捷键 |
|------|-----------|
| 文字识别截图 | `Ctrl+Alt+M` |
| 强制中断识别 | `Ctrl+.` |
| 查看历史 | `Ctrl+H` |
| 普通截图 / 公式识别 / 表格识别 | 自定义 |
| 各类型脚本触发 | 自定义 |

KDE 桌面使用 KGlobalAccel，Wayland 使用 XDG GlobalShortcuts Portal，X11 使用 Qt 本地快捷键。

### 静默模式与悬浮球

开启静默模式后截图不弹窗，通过通知反馈状态：

- **系统通知**：托盘消息
- **悬浮球**：屏幕右下角彩色小球
  - 🔵 蓝色旋转 — 识别中
  - 🟢 绿色 ✓ — 完成
  - 🔴 红色 ✗ — 失败
  - **左键** — 截图 / **右键** — 打开窗口 / **右键拖动** — 移动

悬浮球大小、自动隐藏时间、始终显示均可设置。

### 历史记录

- 自动保存截图 + 识别文本到 SQLite
- `Ctrl+H` 或菜单 → 查看历史，分页浏览
- 双击加载到编辑器，可删除单条或清空
- 条数上限可设（默认 100）

---

## 设置一览

配置文件 `~/.config/hiocr/hiocr.conf`，所有选项可在 GUI 中修改。

| 分类 | 设置项 |
|------|--------|
| 识别服务 | 服务列表、切换策略、空闲超时、默认本地服务 |
| 全局默认 | 服务器地址、API Key、模型名称、三种提示词 |
| 快捷键 | 截图、文字/公式/表格识别、中断、各类型脚本触发 |
| 显示 | 行间公式环境、数学字体、渲染/编辑字体大小、行号 |
| 行为 | 自动识别、自动复制、自动脚本、自动启动本地服务、LaTeX 格式化 |
| 静默模式 | 开关、通知方式 |
| 悬浮球 | 大小、自动隐藏时间、始终显示 |
| 历史记录 | 开关、条数上限 |
| 脚本处理 | 文字/公式/表格/纯公式 命令与快捷键 |
| 高级 | 请求超时、自定义 JSON 参数 |

---

## 使用场景

**远程 API**
1. 设置 → 识别服务管理 → 添加
2. 填名称、API 地址、Key、模型名
3. 保存，工具栏选择即可

**本地模型自动启动**
1. 添加服务，填启动命令
2. 设为默认启动
3. 勾选「远程失败自动启动本地服务」

**截图后自动格式化**
1. 设置 → 行为 → 填入 LaTeX 格式化命令
2. 工具栏勾选「格式化」
3. 识别完成点复制，自动美化后入剪贴板

**静默使用**
1. 勾选静默模式 → 通知方式选「悬浮球」
2. 截图看球颜色判断状态
3. 右键球查看结果

---

## 命令行

```bash
hiocr                          # 启动（单实例，已有实例则激活窗口）
hiocr -i image.png             # 加载图片
hiocr -i image.png -r "文本"   # 加载图片并显示结果（跳过识别）
hiocr --verbose                # 调试输出
```

---

## 技术栈

- **Qt6 + C++17** · header-only 架构
- **QWebEngineView + Temml** · Markdown + LaTeX 渲染
- **SQLite** · 历史记录持久化
- **XDG Desktop Portal** · Wayland 截图与全局快捷键
- **KF6GlobalAccel**（可选）· KDE 原生快捷键
- **KF6WindowSystem**（可选）· Wayland 悬浮球置顶
- 兼容所有 **OpenAI Vision API** 格式的服务

---

## 许可证

「随君所想，成君所愿」