rapid-ocr-tool 1.0.0__tar.gz

rapid_ocr_tool-1.0.0/CLAUDE.md

@@ -0,0 +1,145 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a lightweight offline OCR (Optical Character Recognition) tool built with RapidOCR and ONNX Runtime. It achieves 4-5x faster performance than PaddleOCR with 200MB+ lower memory usage while maintaining 99%+ accuracy.
+
+**Core Technology Stack:**
+- OCR Engine: RapidOCR (optimized PaddleOCR)
+- Inference: ONNX Runtime
+- Model: PP-OCRv3 lightweight model (12.3MB)
+- Language: Python 3.8+
+
+## Essential Commands
+
+### Testing
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_ocr_engine.py -v
+
+# Run with coverage report
+pytest tests/ --cov=src --cov-report=html
+
+# Run single test
+pytest tests/test_output_formatter.py::TestOutputFormatter::test_format_text_simple -v
+```
+
+### Running the Tool
+```bash
+# Single image recognition
+python main.py image <image_path>
+
+# Batch processing
+python main.py batch <folder_path>
+
+# With specific output format
+python main.py image <image_path> --format json --coords
+
+# Disable emoji output
+python main.py image <image_path> --no-emoji
+```
+
+### Installation
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run with virtual environment (recommended)
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+venv\Scripts\activate     # Windows
+```
+
+## Architecture
+
+### Module Structure
+
+The codebase follows a modular architecture with clear separation of concerns:
+
+**Core Modules (`src/`)**:
+1. **`ocr_engine.py`** - Wraps RapidOCR, handles single/batch recognition, returns structured results with optional coordinates and confidence scores
+2. **`image_processor.py`** - Preprocessing pipeline: validation, resize (max 2048px), grayscale, contrast enhancement, denoising
+3. **`batch_processor.py`** - Multi-threaded batch processing using ThreadPoolExecutor, handles progress tracking and error recovery
+4. **`output_formatter.py`** - Formats OCR results to multiple output types (TXT, JSON, Markdown, HTML, CSV)
+5. **`constants.py`** - Centralized configuration constants (max file size, supported formats, thresholds)
+
+**Entry Point**:
+- **`main.py`** - Click-based CLI with emoji output control (global `USE_EMOJI` flag)
+
+### Data Flow
+
+```
+Image Input → ImageProcessor (optional preprocessing) → OCREngine → Raw OCR Result → OutputFormatter → File Output
+```
+
+**OCR Result Format**: List of lists where each item is either:
+- `[text]` - Simple text only
+- `[[bbox], text, confidence]` - With bounding box and confidence
+
+Example: `[[[[0,0], [10,0], [10,10], [0,10]], "Hello", 0.99], ["World"]]`
+
+### Configuration System
+
+Two-layer configuration:
+1. **Default config** in `src/__init__.py:get_default_config()`
+2. **YAML override** in `config/config.yaml` (loaded via `load_config()`)
+
+Config merging is recursive - custom values override defaults at any depth.
+
+### Key Design Patterns
+
+**Factory Functions**: Each module exports a `create_*()` function for convenient instantiation:
+- `create_ocr_engine(lang, use_gpu)`
+- `create_image_processor(max_size, auto_rotate)`
+- `create_batch_processor(ocr, threads)`
+- `create_formatter(indent)`
+
+**Text Extraction**: `OutputFormatter` uses helper methods to avoid code duplication:
+- `_extract_text(line)` - Extract text from single OCR result line
+- `_extract_texts(result)` - Extract all text lines using list comprehension with walrus operator
+
+**Batch Processing**: `BatchProcessor.process_single()` was refactored from 88 lines into 6 smaller methods:
+- `_init_result()` - Initialize result dictionary
+- `_should_skip()` - Check if output exists (for skip_exists mode)
+- `_load_and_process()` - Load and OCR image
+- `_save_result()` - Save to file
+- `_process_error()` - Handle errors
+- Main method orchestrates the workflow
+
+## Code Quality Standards
+
+**Testing**: TDD methodology with RED→GREEN→REFACTOR cycle. Current test coverage: 51% (37 tests).
+
+**Refactoring**: Code underwent TDD refactoring to eliminate duplication. Example: `OutputFormatter` reduced from 330 to 280 lines by extracting common text extraction logic.
+
+**Error Handling**: Avoid naked `except:` clauses. Use specific exception types like `(TypeError, ValueError, AttributeError)`.
+
+**Emoji Control**: Global `USE_EMOJI` flag in `main.py` controls emoji output. Use `_emoji()` helper function. Pass `--no-emoji` CLI flag to disable.
+
+**Constants**: All magic numbers centralized in `src/constants.py`:
+- `MAX_FILE_SIZE = 50 * 1024 * 1024` (50MB)
+- `DEFAULT_MAX_IMAGE_SIZE = 2048`
+- `CONFIDENCE_THRESHOLD = 0.8`
+
+## Important Constraints
+
+- **First Run**: Auto-downloads ONNX models (~12MB) to `./models/` directory
+- **Image Size**: Automatically resized to max 2048px on longest side
+- **Supported Formats**: .jpg, .jpeg, .png, .bmp, .tiff, .tif
+- **Thread Safety**: BatchProcessor uses ThreadPoolExecutor with configurable thread count (default: 4)
+- **File Encoding**: All file I/O uses UTF-8 encoding
+
+## Troubleshooting
+
+**Import Errors**: Ensure virtual environment is activated and dependencies installed via `requirements.txt`.
+
+**Model Download Failures**: Check internet connection on first run. Models download from RapidOCR repository.
+
+**Memory Issues**: Reduce `max_size` in config or `ImageProcessor` initialization. Lower thread count in batch processing.
+
+**Low Accuracy**: Enable image preprocessing (contrast enhancement, denoising) or preprocess images externally before OCR.

rapid_ocr_tool-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OCR Tool Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rapid_ocr_tool-1.0.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include requirements.txt
+include config/*.yaml
+recursive-include docs *.md
+recursive-include src *.py
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude .git*

rapid_ocr_tool-1.0.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: rapid-ocr-tool
+Version: 1.0.0
+Summary: 本地轻量级OCR识别工具
+Home-page: https://github.com/yourusername/ocr-tool
+Author: OCR Tool Team
+Author-email: your-email@example.com
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# 本地轻量级OCR识别工具
+
+<div align="center">
+
+**基于 RapidOCR + ONNX Runtime**
+
+🚀 极速识别 (~1秒/张) | 💻 低资源占用 (<300MB) | 🔒 完全离线
+
+[Python](https://www.python.org/) >= 3.8 | [Windows/Linux/Mac](https://github.com/RapidAI/RapidOCR)
+
+</div>
+
+---
+
+## 项目简介
+
+这是一个轻量级的本地OCR文字识别工具,基于[RapidOCR](https://github.com/RapidAI/RapidOCR)实现,采用[ONNX Runtime](https://onnxruntime.ai/)推理框架。相比PaddleOCR,速度提升4-5倍,内存占用降低200MB+,同时保持99%+的识别准确率。
+
+- ✅ 完全离线运行,保护隐私
+- ✅ 低资源占用(内存<300MB)
+- ✅ 识别速度快(~1秒/张)
+- ✅ 高准确率(99.5%中文,99%+英文)
+- ✅ 支持批量处理
+- ✅ 多种输出格式
+- ✅ 跨平台支持(Windows/Linux/Mac)
+
+## 安装
+
+### 1. 创建虚拟环境(推荐)
+
+```bash
+# Windows
+python -m venv venv
+venv\Scripts\activate
+
+# Linux/Mac
+python3 -m venv venv
+source venv/bin/activate
+```
+
+### 2. 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+## 使用方法
+
+### 单张图片识别
+
+```bash
+python main.py image 图片路径.jpg
+```
+
+### 批量处理文件夹
+
+```bash
+python main.py batch 文件夹路径
+```
+
+### 指定输出格式
+
+```bash
+# 输出为文本
+python main.py image 图片.jpg --format txt
+
+# 输出为JSON(包含坐标信息)
+python main.py image 图片.jpg --format json
+
+# 输出为Markdown
+python main.py image 图片.jpg --format md
+```
+
+### 高级选项
+
+```bash
+# 保存到文件
+python main.py image 图片.jpg --output result.txt
+
+# 指定识别语言(ch/en)
+python main.py image 图片.jpg --lang ch
+
+# 显示详细信息
+python main.py image 图片.jpg --verbose
+```
+
+## 支持的图片格式
+
+- PNG
+- JPG/JPEG
+- BMP
+- TIFF
+
+## 性能指标
+
+| 指标 | 数值 |
+|------|------|
+| 单张识别速度 | ~1秒(CPU) |
+| 内存占用 | <300MB |
+| 中文准确率 | 99.5% |
+| 英文准确率 | 99%+ |
+| 支持分辨率 | 最高4096px |
+
+## 项目结构
+
+```
+ocr/
+├── src/
+│   ├── ocr_engine.py       # OCR引擎核心
+│   ├── image_processor.py  # 图像预处理
+│   ├── batch_processor.py  # 批量处理
+│   └── output_formatter.py # 输出格式化
+├── models/                  # 模型文件(自动下载)
+├── output/                  # 默认输出目录
+├── config/
+│   └── config.yaml         # 配置文件
+├── main.py                 # 主入口
+├── requirements.txt        # 依赖列表
+└── README.md              # 使用文档
+```
+
+## 📚 文档
+
+- **[命令参考](docs/命令参考.md)** - 完整的CLI命令文档及示例
+- **[贡献指南](docs/贡献指南.md)** - 开发环境设置、编码规范、工作流程
+- **[运维手册](docs/运维手册.md)** - 部署、监控、故障排除指南
+- **[文档索引](docs/文档索引.md)** - 所有文档的导航索引
+
+## 常见问题
+
+### 1. 首次运行慢?
+首次运行会自动下载模型文件(约12MB),请耐心等待。
+
+### 2. 识别结果不准确?
+- 确保图片清晰,分辨率足够
+- 尝试调整图片对比度
+- 对于复杂背景,先进行图像预处理
+
+### 3. 批量处理中断?
+已处理的结果会自动保存,可以重新运行继续处理。
+
+## 技术栈
+
+- **OCR引擎**: [RapidOCR](https://github.com/RapidAI/RapidOCR) (基于PaddleOCR优化)
+- **推理框架**: [ONNX Runtime](https://onnxruntime.ai/)
+- **模型**: PP-OCRv3 轻量级模型 (12.3MB)
+- **图像处理**: OpenCV + Pillow
+- **CLI框架**: Click + Rich
+
+## 项目结构
+
+```
+ocr/
+├── src/
+│   ├── __init__.py           # 模块初始化
+│   ├── ocr_engine.py         # OCR引擎核心
+│   ├── image_processor.py    # 图像预处理
+│   ├── batch_processor.py    # 批量处理
+│   └── output_formatter.py   # 输出格式化
+├── config/
+│   └── config.yaml           # 配置文件
+├── models/                    # 模型文件(自动下载)
+├── output/                    # 默认输出目录
+├── main.py                   # CLI入口
+├── examples.py               # 使用示例
+├── test_install.py           # 安装测试
+├── requirements.txt          # 依赖列表
+├── QUICKSTART.md            # 快速开始指南
+└── README.md                # 项目文档
+```
+
+## 开源协议
+
+MIT License
+
+---
+
+## 致谢
+
+- [RapidOCR](https://github.com/RapidAI/RapidOCR) - 高性能OCR引擎
+- [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) - 飞桨OCR工具
+- [ONNX Runtime](https://onnxruntime.ai/) - 跨平台推理框架

rapid_ocr_tool-1.0.0/README.md

@@ -0,0 +1,182 @@
+# 本地轻量级OCR识别工具
+
+<div align="center">
+
+**基于 RapidOCR + ONNX Runtime**
+
+🚀 极速识别 (~1秒/张) | 💻 低资源占用 (<300MB) | 🔒 完全离线
+
+[Python](https://www.python.org/) >= 3.8 | [Windows/Linux/Mac](https://github.com/RapidAI/RapidOCR)
+
+</div>
+
+---
+
+## 项目简介
+
+这是一个轻量级的本地OCR文字识别工具,基于[RapidOCR](https://github.com/RapidAI/RapidOCR)实现,采用[ONNX Runtime](https://onnxruntime.ai/)推理框架。相比PaddleOCR,速度提升4-5倍,内存占用降低200MB+,同时保持99%+的识别准确率。
+
+- ✅ 完全离线运行,保护隐私
+- ✅ 低资源占用(内存<300MB)
+- ✅ 识别速度快(~1秒/张)
+- ✅ 高准确率(99.5%中文,99%+英文)
+- ✅ 支持批量处理
+- ✅ 多种输出格式
+- ✅ 跨平台支持(Windows/Linux/Mac)
+
+## 安装
+
+### 1. 创建虚拟环境(推荐)
+
+```bash
+# Windows
+python -m venv venv
+venv\Scripts\activate
+
+# Linux/Mac
+python3 -m venv venv
+source venv/bin/activate
+```
+
+### 2. 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+## 使用方法
+
+### 单张图片识别
+
+```bash
+python main.py image 图片路径.jpg
+```
+
+### 批量处理文件夹
+
+```bash
+python main.py batch 文件夹路径
+```
+
+### 指定输出格式
+
+```bash
+# 输出为文本
+python main.py image 图片.jpg --format txt
+
+# 输出为JSON(包含坐标信息)
+python main.py image 图片.jpg --format json
+
+# 输出为Markdown
+python main.py image 图片.jpg --format md
+```
+
+### 高级选项
+
+```bash
+# 保存到文件
+python main.py image 图片.jpg --output result.txt
+
+# 指定识别语言(ch/en)
+python main.py image 图片.jpg --lang ch
+
+# 显示详细信息
+python main.py image 图片.jpg --verbose
+```
+
+## 支持的图片格式
+
+- PNG
+- JPG/JPEG
+- BMP
+- TIFF
+
+## 性能指标
+
+| 指标 | 数值 |
+|------|------|
+| 单张识别速度 | ~1秒(CPU) |
+| 内存占用 | <300MB |
+| 中文准确率 | 99.5% |
+| 英文准确率 | 99%+ |
+| 支持分辨率 | 最高4096px |
+
+## 项目结构
+
+```
+ocr/
+├── src/
+│   ├── ocr_engine.py       # OCR引擎核心
+│   ├── image_processor.py  # 图像预处理
+│   ├── batch_processor.py  # 批量处理
+│   └── output_formatter.py # 输出格式化
+├── models/                  # 模型文件(自动下载)
+├── output/                  # 默认输出目录
+├── config/
+│   └── config.yaml         # 配置文件
+├── main.py                 # 主入口
+├── requirements.txt        # 依赖列表
+└── README.md              # 使用文档
+```
+
+## 📚 文档
+
+- **[命令参考](docs/命令参考.md)** - 完整的CLI命令文档及示例
+- **[贡献指南](docs/贡献指南.md)** - 开发环境设置、编码规范、工作流程
+- **[运维手册](docs/运维手册.md)** - 部署、监控、故障排除指南
+- **[文档索引](docs/文档索引.md)** - 所有文档的导航索引
+
+## 常见问题
+
+### 1. 首次运行慢?
+首次运行会自动下载模型文件(约12MB),请耐心等待。
+
+### 2. 识别结果不准确?
+- 确保图片清晰,分辨率足够
+- 尝试调整图片对比度
+- 对于复杂背景,先进行图像预处理
+
+### 3. 批量处理中断?
+已处理的结果会自动保存,可以重新运行继续处理。
+
+## 技术栈
+
+- **OCR引擎**: [RapidOCR](https://github.com/RapidAI/RapidOCR) (基于PaddleOCR优化)
+- **推理框架**: [ONNX Runtime](https://onnxruntime.ai/)
+- **模型**: PP-OCRv3 轻量级模型 (12.3MB)
+- **图像处理**: OpenCV + Pillow
+- **CLI框架**: Click + Rich
+
+## 项目结构
+
+```
+ocr/
+├── src/
+│   ├── __init__.py           # 模块初始化
+│   ├── ocr_engine.py         # OCR引擎核心
+│   ├── image_processor.py    # 图像预处理
+│   ├── batch_processor.py    # 批量处理
+│   └── output_formatter.py   # 输出格式化
+├── config/
+│   └── config.yaml           # 配置文件
+├── models/                    # 模型文件(自动下载)
+├── output/                    # 默认输出目录
+├── main.py                   # CLI入口
+├── examples.py               # 使用示例
+├── test_install.py           # 安装测试
+├── requirements.txt          # 依赖列表
+├── QUICKSTART.md            # 快速开始指南
+└── README.md                # 项目文档
+```
+
+## 开源协议
+
+MIT License
+
+---
+
+## 致谢
+
+- [RapidOCR](https://github.com/RapidAI/RapidOCR) - 高性能OCR引擎
+- [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) - 飞桨OCR工具
+- [ONNX Runtime](https://onnxruntime.ai/) - 跨平台推理框架

rapid_ocr_tool-1.0.0/config/config.yaml

@@ -0,0 +1,48 @@
+# OCR配置文件
+
+# 模型设置
+model:
+  # 模型类型: ch(中文), en(英文)
+  lang: ch
+  # 是否使用GPU(需要CUDA)
+  use_gpu: false
+  # 模型下载路径
+  download_path: ./models
+
+# 图像处理设置
+image:
+  # 最大图片尺寸(长边)
+  max_size: 2048
+  # 是否自动旋转
+  auto_rotate: true
+  # 是否增强对比度
+  enhance_contrast: false
+
+# 输出设置
+output:
+  # 默认输出目录
+  default_dir: ./output
+  # 默认输出格式: txt/json/md
+  default_format: txt
+  # 是否包含坐标信息
+  include_coords: false
+  # JSON缩进
+  json_indent: 2
+
+# 批量处理设置
+batch:
+  # 并发线程数
+  threads: 4
+  # 失败重试次数
+  retry: 2
+  # 是否跳过已存在
+  skip_exists: false
+
+# 日志设置
+logging:
+  # 日志级别: DEBUG/INFO/WARNING/ERROR
+  level: INFO
+  # 是否输出到文件
+  to_file: true
+  # 日志文件路径
+  file_path: ./logs/ocr.log