# document-scanner

**Repository Path**: YH699/document-scanner

## Basic Information

- **Project Name**: document-scanner
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-02
- **Last Updated**: 2026-08-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📄 Document Scanner

> 基于 OpenCV 的文档扫描仪 | Tkinter GUI Document Scanner with Perspective Correction

[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
[![OpenCV](https://img.shields.io/badge/OpenCV-4.8+-green.svg)](https://opencv.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## 📖 项目简介 | Overview

一个使用 Python + OpenCV 实现的**文档扫描仪桌面应用**。通过 Tkinter 构建简洁的 GUI 界面，可以自动检测文档的四个角点，并使用**透视变换（Perspective Transform）**将拍摄的文档图片「展平」为正面视角，效果类似手机扫描 App。

---

## 🎯 功能特性 | Features

- ✅ **自动角点检测**：基于轮廓检测自动定位文档四个角
- ✅ **手动微调角点**：支持鼠标拖拽角点进行精细调整
- ✅ **透视变换校正**：将倾斜拍摄的文档展平为正面视图
- ✅ **简洁 GUI 界面**：Tkinter 构建，轻量无额外依赖
- ✅ **模块化设计**：核心扫描逻辑独立封装，便于复用

---

## 📁 项目结构

`
document-scanner/
├── app.py            # 🖥️ Tkinter GUI 主程序
├── doc_scanner.py    # 🔧 文档扫描核心逻辑（DocScanner 类）
├── doc.jpg           # 🖼️ 测试图片
├── image.png         # 🖼️ 运行截图
├── image-1.png       # 🖼️ 运行截图
├── requirements.txt  # 📦 Python 依赖
└── README.md         # 📖 本文件
`

---

## 🚀 快速开始

### 安装

`ash
git clone https://github.com/YOUR_USERNAME/document-scanner.git
cd document-scanner
pip install -r requirements.txt
`

### 运行

`ash
python app.py
`

---

## 🕹️ 使用说明

1. 点击 **"Select Image"** 选择要扫描的文档照片
2. 系统自动检测文档四个角点（显示为可拖拽的角标）
3. 如需调整，**拖拽角点**到正确位置
4. 点击 **"Crop"** 执行透视变换，展平文档
5. 勾选 **"Show Mouse Move"** 查看鼠标坐标信息

---

## 🔬 技术原理

`
输入图片 → 灰度化 → 二值化 → 轮廓检测 → 四边形拟合
                                            ↓
                                order_points() 角点排序
                                            ↓
                    getPerspectiveTransform() 计算变换矩阵
                                            ↓
                    warpPerspective() 透视变换 → 展平文档
`

### DocScanner 类设计

`python
class DocScanner:
    def load_image(file_path)     # 加载图片 + 自动检测角点
    def order_points(pts)          # 四点排序（左上→右上→右下→左下）
    def crop_image(img, corners)   # 透视变换裁剪
    def get_image_dimensions(...)  # 计算目标尺寸
`

---

## 📝 License

MIT License © 2024