# image-translator

**Repository Path**: wuyuan/image-translator

## Basic Information

- **Project Name**: image-translator
- **Description**: Spring Boot 4 实现的图片翻译流水线：**OCR（PP-OCRv6 / Tesseract）→ DeepSeek（翻译）→ Java2D/OpenCV（抹除原文 + 渲染译文）**。
上传一张含中文文字的图片，返回文字已被替换为英文的图片。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-16
- **Last Updated**: 2026-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Image Translator（图片翻译工具）

Spring Boot 4 实现的图片翻译流水线：**OCR（PP-OCRv6 / Tesseract）→ DeepSeek（翻译）→ Java2D/OpenCV（抹除原文 + 渲染译文）**。
上传一张含中文文字的图片，返回文字已被替换为英文的图片。

## 技术栈

| 组件 | 技术 | 版本 |
|---|---|---|
| Web 框架 | Spring Boot | 4.1.0 |
| OCR（默认） | mica-ppocr-core（PP-OCRv6 纯 ONNX 推理，零 PaddlePaddle 依赖） | 1.1.3 |
| OCR（备选） | Tess4J（Tesseract JNA 封装） | 5.20.0 |
| 翻译 | DeepSeek（OpenAI 兼容 /chat/completions，`deepseek-v4-flash`） | — |
| 文字擦除 | LaMa ONNX（lama-manga-dynamic，ONNX Runtime 推理，全区域方案） | — |
| 渲染/换行 | Java2D | JDK 内置 |(https://huggingface.co/ogkalu/lama-manga-onnx-dynamic/tree/main)

## 环境要求

- JDK 17+（开发环境为 Java 25）
- Maven 3.9+
- 操作系统：Windows 或 Linux（x86_64），macOS 需自行添加对应 OpenCV classifier

## 快速开始

### 1. 下载 OCR 模型

默认 OCR 引擎为 **Paddle（PP-OCRv6）**，先下载模型（默认 medium 档，约 140MB）：

```bash
# Windows（PowerShell），可选 -Tier tiny|small|medium
powershell -ExecutionPolicy Bypass -File scripts/download-ppocr-models.ps1 -Tier medium

# Linux / macOS
bash scripts/download-ppocr-models.sh medium
```

模型会下载并解压到项目根目录 `models/ppocr-v6/medium/`（已加入 .gitignore，不入库）。

### 1.5 下载 LaMa 文字擦除模型（推荐）

复杂背景的文字擦除默认使用 **LaMa ONNX**（约 196MB，从 HuggingFace 国内镜像 hf-mirror.com 下载，含 sha256 校验与断点续传）：

```bash
# Windows（PowerShell）
powershell -ExecutionPolicy Bypass -File scripts/download-lama-model.ps1

# Linux / macOS
bash scripts/download-lama-model.sh
```

模型位于 `models/lama/lama-manga-dynamic.onnx`。**未下载时自动降级为 OpenCV inpaint**，功能不受影响。

> 若改用 **Tesseract** 引擎（`app.ocr.engine=tesseract`），另需下载语言数据：
> `scripts/download-tessdata.ps1` / `scripts/download-tessdata.sh`（下载到 `tessdata/`）。

### 2. 配置 DeepSeek API Key

1. 到 <https://platform.deepseek.com> 注册并创建 API Key。
2. 设置环境变量：

```bash
# Windows
set DEEPSEEK_API_KEY=你的key
# Linux
export DEEPSEEK_API_KEY=你的key
```

> 默认调用 `https://api.deepseek.com` 的 `deepseek-v4-flash` 模型（JSON 批量翻译，条目数不匹配时自动降级逐条）。
> 模型与源/目标语言可在 `application.yml` 的 `app.translation` 中调整。
> 未配置 key 时应用可正常启动，调用翻译接口会返回明确的错误提示。

### 3. 启动

```bash
mvn spring-boot:run
```

## API 使用

### 翻译图片（返回 PNG）

```bash
curl -F "file=@C:\Users\wuyua\Desktop\8.jpg" http://localhost:8080/api/translate/image -o out.png
```

### 识别 + 翻译明细（返回 JSON，便于调试）

```bash
curl -F "file=@cn.png" http://localhost:8080/api/translate/info
```

响应示例：

```json
{
  "width": 800,
  "height": 450,
  "regions": [
    {"x": 40, "y": 30, "width": 300, "height": 60, "text": "你好，世界", "translated": "Hello, world"}
  ]
}
```

## 流水线说明

```
输入图片
  → OcrService（接口，app.ocr.engine 切换）：
      paddle（默认）：PP-OCRv6 检测+识别（mica-ppocr-core），输出文本块外接矩形
      tesseract：Tess4J 词级识别（chi_sim+eng，LSTM 引擎），TextLineMerger 按行聚合
  → TranslationService：DeepSeek 批量翻译（默认 中文 → 英文，JSON 模式一次请求全部区域，异常时降级逐条）
  → ImageEditingService：
      1) 抹除（全区域统一 LaMa ONNX 深度学习修复）：
         - 纯色背景 → 颜色填充
         - 复杂背景 → 双向自适应阈值掩码（暗字+亮字）→ 开运算去噪 → 连通域过滤
           （丢弃小噪点、又大又方的背景块；细长文字笔画保留）→ 字号比例椭圆膨胀
           → LaMa 推理修复（仅在掩码区域替换，保留背景）
      2) 渲染：字号自适应（放不下自动缩小）、英文单词换行（BreakIterator）、
         抗锯齿、按背景亮度选择对比色文字
  → 输出翻译后的图片
```

## 已知限制

- **照片等复杂背景**：译文以半透明底衬形式贴图（保证可读）；底衬会盖住文字区域内的背景/图标，这是图片翻译的通用取舍，截图、文档、简单海报等纯色背景场景效果最佳。
- **竖排/艺术字/手写体**：识别效果有限（PP-OCRv6 优于 Tesseract，仍非全场景覆盖）。
- **图标与文字混排的区域**（营销图/功能截图）：阈值掩码难以区分文字笔画与图标，擦除可能误伤图标——这是图片翻译的通用难点，纯文字截图、文档、海报等场景效果最佳。
- **翻译上下文**：批量翻译时按行独立翻译，长句跨行时上下文可能丢失；模型响应条目数异常时会自动降级逐条翻译，速度较慢。
- PP-OCRv6 / Tesseract 均为纯 CPU 推理，高分辨率大图首次识别较慢（首次加载模型约需数秒）。

## 项目结构

```
src/main/java/com/example/imagetranslator/
├── ImageTranslatorApplication.java   # 入口
├── config/                           # AppProperties / PaddleOcrConfig / RestClientConfig
├── model/                            # TextRegion / OcrWord / TextLineMerger
├── service/                          # OcrService(接口) / TesseractOcrService / PaddleOcrService
│                                     # TranslationService / ImageEditingService / ImageTranslationService
└── web/                              # TranslateController / GlobalExceptionHandler
```