ancient-ocr-viewer/README.md

# 古籍OCR对照查看器

基于Canvas的古籍OCR识别结果可视化工具，支持图片与文字的像素级精确对照。

## 功能特性

### 双Canvas渲染
- **左侧画布**：显示原始古籍图片（JPG/JP2转换）
- **右侧画布**：根据OCR JSON数据，在相同坐标位置渲染识别的文字
- 两个画布完全同步，尺寸一致，字符位置精确对应

### 交互功能
- **缩放控制**：10%-200%自由缩放，支持鼠标滚轮
- **拖拽平移**：鼠标拖动查看大图的不同区域
- **同步滚动**：左右画布自动同步滚动位置
- **适应窗口**：一键调整画布大小适应窗口

### 文字渲染选项
- **文字大小调整**：50%-150%独立调整文字显示大小
- **边框显示**：可选显示/隐藏字符边界框
- **网格显示**：辅助对齐的参考网格
- **颜色自定义**：自定义文字颜色和背景颜色
- **透明背景**：文字渲染支持透明背景

### 质量控制
- **置信度过滤**：根据OCR置信度过滤显示字符
- **低置信度标记**：自动标记识别不确定的字符
- **悬停提示**：鼠标悬停显示字符详细信息（置信度、坐标、行号等）

### 统计与导出
- **实时统计**：显示总字符数、可见字符、平均置信度
- **导出对比图**：一键导出左右对照的PNG图片
- **原始数据保留**：完整保留OCR元数据

## 项目结构

```
ancient-ocr-viewer/
├── index.html              # 主页面
├── src/
│   ├── js/
│   │   ├── main.js         # 主入口，应用初始化
│   │   ├── canvasRenderer.js   # Canvas渲染器基类
│   │   ├── imageCanvas.js      # 图片Canvas渲染器
│   │   ├── textCanvas.js       # 文字Canvas渲染器
│   │   ├── controls.js         # 控制面板管理器
│   │   └── utils.js            # 工具函数集合
│   └── css/
│       └── style.css       # 全局样式
├── data/
│   ├── 0003A.jpg           # 古籍图片
│   └── 0003A.json          # OCR识别数据
├── package.json            # 项目配置
└── README.md               # 项目说明
```

## 技术栈

- 纯原生JavaScript（ES6 Modules）
- HTML5 Canvas API
- CSS3（Grid/Flex布局）
- 无第三方依赖

## 使用方法

### 1. 启动本地服务器

由于使用了ES6 Modules，需要通过HTTP服务器访问：

```bash
# 方法1: Python简单服务器
python3 -m http.server 8801

# 方法2: Node.js http-server
npx http-server -p 8801

# 方法3: PHP内置服务器
php -S localhost:8801
```

### 2. 访问应用

在浏览器打开：
```
http://localhost:8801/index.html
```

### 3. 操作说明

- **缩放**：拖动缩放滑块或使用鼠标滚轮
- **平移**：鼠标拖拽画布
- **查看字符详情**：鼠标悬停在右侧文字上
- **调整文字**：使用控制面板调整大小、颜色等
- **导出**：点击"导出对比图"按钮保存PNG

## 数据格式

### JSON数据结构
```json
{
  "FileName": "0003A",
  "Width": 4921,
  "Height": 8286,
  "CharNumber": 143,
  "LineNumber": 10,
  "chars": ["字", "符", "数", "组"],
  "coors": [[x1, y1, x2, y2], ...],
  "char_probs": [0.998, 0.995, ...],
  "line_ids": [0, 0, 1, 1, ...],
  "text": "完整文本..."
}
```

### 添加新数据

1. 将图片文件放入 `data/` 目录
2. 将对应的JSON文件放入 `data/` 目录
3. 修改 `src/js/main.js` 中的文件路径：
```javascript
this.ocrData = await loadJSON('data/your-file.json');
await this.imageCanvas.loadImage('data/your-file.jpg');
```

## 集成到其他项目

本项目设计为独立模块，可以轻松集成：

### 作为独立页面
直接复制整个目录到目标项目即可。

### 作为组件集成
```javascript
import { ImageCanvas } from './src/js/imageCanvas.js';
import { TextCanvas } from './src/js/textCanvas.js';

// 创建实例
const imageCanvas = new ImageCanvas('canvasId', 'wrapperId');
const textCanvas = new TextCanvas('canvasId', 'wrapperId');

// 加载数据
await imageCanvas.loadImage('path/to/image.jpg');
textCanvas.loadOCRData(ocrJsonData);
```

## 浏览器兼容性

- Chrome/Edge 90+
- Firefox 88+
- Safari 14+

需要支持：
- ES6 Modules
- Canvas API
- Custom Events
- Async/Await

## 开发计划

- [ ] 支持多页面浏览（上一页/下一页）
- [ ] 支持键盘快捷键
- [ ] 添加文字选择和复制功能
- [ ] 支持OCR数据编辑
- [ ] 添加图片预处理选项（亮度、对比度）
- [ ] 支持更多图片格式（TIFF、WebP等）

## 许可证

MIT License

## 作者

古籍OCR项目组