# CameraFileScan

**Repository Path**: alder2019/CameraFileScan

## Basic Information

- **Project Name**: CameraFileScan
- **Description**: CameraFileScan
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-08
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CameraFileScan

通过 USB 摄像头扫描 A4 文档：实时预览、自动检测边框、透视矫正裁边，保存为 JPG；支持扫描后批量图像增强。

## 功能

### 扫描（scan.py）

- USB 摄像头实时取景，绿色四边形标注检测到的 A4 文档边框
- 按空格拍摄，自动透视矫正并裁边为 A4 比例
- 预览画面顺时针旋转（默认 90°）
- 保存 JPG 并写入 DPI 元数据
- 自动压缩到指定体积（默认 500KB 以下）
- 文档增强：对比度（CLAHE）+ 锐化
- 支持 macOS / Windows / Linux

### 后处理（img.py）

- 单张 JPG 锐化/清晰度、亮度、对比度调整，并排预览前后效果
- 批处理目录下所有子文件夹中的 JPG
- 处理后文件统一保存在指定目录根目录（如 `D4/`）

## 项目结构

```
CameraFileScan/
├── scan.py              # 扫描主入口
├── img.py               # JPG 后处理（单张预览 / 批处理）
├── requirements.txt
├── scanner/
│   ├── camera.py        # 摄像头采集与旋转
│   ├── detector.py      # A4 边框检测
│   ├── transform.py     # 透视矫正与图像增强
│   └── storage.py       # JPG 保存与压缩
└── output/              # 扫描结果（运行时自动创建）
```

## 环境要求

- Python 3.10+
- USB 摄像头（或内置摄像头）
- macOS 用户需在 **系统设置 → 隐私与安全性 → 摄像头** 中授权终端

## 安装

```bash
pip install -r requirements.txt
```

依赖：`opencv-python`、`numpy`、`Pillow`

## 摄像头扫描 A4：怎么调用

正式入口是 `scan.py`（日常扫描请用它；`myscan.py` 为本地草稿，不是正式入口）。

### 1. 安装依赖（只需一次）

```bash
cd /Users/alder/workspace/26Alder/CameraFileScan
pip install -r requirements.txt
```

macOS：到 **系统设置 → 隐私与安全性 → 摄像头**，给 Terminal（或你用的终端）开权限。

### 2. 启动扫描

```bash
python scan.py
```

等价于：摄像头 `0`，输出目录 `output/`，约 `1920x1080` 采集，预览默认旋转 `90°`，约 `300 DPI`，JPG 默认压到 `500KB` 以下。

常用参数：

```bash
python scan.py --camera 0              # 指定摄像头
python scan.py --output output         # 指定保存目录
python scan.py --cam-width 1280 --cam-height 960   # 4:3 采集，纸张占画面更大
python scan.py --rotate 0              # 不旋转预览
python scan.py --probe                 # 查看摄像头能力后退出
```

### 3. 窗口操作

| 按键 | 作用 |
|------|------|
| `空格` | 拍摄当前检测到的 A4，矫正裁边后保存 JPG |
| `Q` / `Esc` | 退出 |
| `+/-` | 手动对焦（支持硬件对焦时） |
| `F` | 切换自动对焦 |

流程：打开窗口 → 放好 A4 → 出现**绿色四边形** → 按**空格**保存。未检测到绿框时按空格无效。

建议：纸张占画面约 **40% 以上**，光线充足，距离约 25–40 cm。

### 4. 扫描结果在哪

默认保存在：

```
CameraFileScan/output/scan_YYYYMMDD_HHMMSS.jpg
```

### 5. （可选）扫描后再增强

```bash
python img.py output/某张扫描.jpg    # 单张前后对比
python img.py --batch output         # 批处理该目录下 JPG
```

---

## 快速开始

### 扫描

```bash
python scan.py
```

默认配置：摄像头 0、1920×1080 采集、顺时针旋转 90°、300 DPI 输出、JPG 压缩至 500KB 以下。

### 后处理

```bash
# 单张预览（前后对比）
python img.py D1/scan_20260608_094615.jpg

# 批处理 D4 下所有子文件夹中的 JPG，结果存到 D4 根目录
python img.py --batch D4
```

默认参数：锐化 81%、亮度 70%、对比度 80%。

## 操作说明（scan.py）

| 按键 | 功能 |
|------|------|
| `空格` | 拍摄并保存当前预览帧 |
| `+/-` | 手动对焦（支持硬件对焦时） |
| `F` | 切换自动对焦 |
| `Q` / `Esc` | 退出 |

预览窗口底部显示：

- **Fill** — 纸张占画面比例（建议 >40%）
- **EstDPI** — 估算有效 DPI（越高越清晰）
- **Rotate** — 当前旋转角度

未检测到 A4 边框时按空格无效。

## 操作说明（img.py）

### 单张预览模式

| 按键 | 功能 |
|------|------|
| `S` | 保存处理结果（`原文件名_enhanced.jpg`） |
| `Q` / `Esc` | 退出 |

### 批处理模式

```bash
python img.py --batch D4
```

- 扫描 `D4/output1/`、`D4/output2/` 等子文件夹中所有 `.jpg`
- 跳过已增强文件（`*_enhanced.jpg`）
- 输出统一保存在 `D4/` 根目录，命名格式：`{子文件夹}_{原文件名}_enhanced.jpg`

示例：

```
D4/output1/scan_20260608_142338.jpg
  → D4/output1_scan_20260608_142338_enhanced.jpg
```

## 命令行参数

### scan.py — 摄像头

| 参数 | 默认 | 说明 |
|------|------|------|
| `--camera` | 0 | 摄像头索引 |
| `--cam-width` | 1920 | 采集宽度 |
| `--cam-height` | 1080 | 采集高度 |
| `--rotate` | 90 | 顺时针旋转（0/90/180/270） |
| `--warmup` | 15 | 启动预热帧数 |
| `--probe` | — | 探测摄像头分辨率与属性后退出 |

### scan.py — 输出

| 参数 | 默认 | 说明 |
|------|------|------|
| `--output` | output | JPG 输出目录 |
| `--dpi` | 300 | 目标 DPI（约 2480px 短边） |
| `--width` | — | 输出短边像素上限（覆盖 --dpi） |
| `--auto-width` | 关闭 | 按源图像素输出，不放大 |
| `--quality` | 85 | JPG 质量上限（1-100） |
| `--max-kb` | 500 | 文件体积上限（KB），0=不限制 |
| `--sharpen` | 1.5 | 锐化强度（0=关闭） |
| `--enhance` / `--no-enhance` | 开启 | 对比度增强 |

### img.py — 后处理

| 参数 | 默认 | 说明 |
|------|------|------|
| `--batch` | — | 批处理目录下所有子文件夹 JPG |
| `--sharpness` | 81 | 锐化/清晰度 |
| `--brightness` | 70 | 亮度（0=不变） |
| `--contrast` | 80 | 对比度（0=不变） |
| `--quality` | 95 | JPG 保存质量 |
| `--output` | — | 单张模式指定输出路径 |

## 使用示例

```bash
# 默认扫描
python scan.py

# 4:3 采集（纸张占画面更大）
python scan.py --cam-width 1280 --cam-height 960

# 400 DPI 高清输出，不限制体积
python scan.py --dpi 400 --max-kb 0 --quality 95

# 压缩到 300KB 以下
python scan.py --max-kb 300

# 不旋转
python scan.py --rotate 0

# 探测摄像头能力
python scan.py --probe

# 单张后处理预览
python img.py D1/scan_20260608_094615.jpg

# 批处理 D4，结果存 D4 根目录
python img.py --batch D4

# 自定义后处理参数
python img.py --batch D4 --sharpness 81 --brightness 70 --contrast 80
```

## DPI 与清晰度

| DPI | 输出尺寸（约） | 用途 |
|-----|----------------|------|
| 150 | 1240 × 1753 | 屏幕阅读 |
| 200 | 1654 × 2338 | 一般打印 |
| 300 | 2480 × 3508 | 默认，清晰打印 |
| 400 | 3307 × 4676 | 高精度 |

**提高清晰度的关键**：让纸张占画面 40% 以上（看预览中的 Fill 数值），摄像头靠近文档、光线充足。EstDPI 是实际上限，设置高于它的 DPI 只会放大变糊。

## JPG 压缩

默认自动将文件压缩到 **500KB 以下**：

1. 二分查找最高质量使体积达标
2. 仍超限则逐步缩小尺寸再压缩

保存时终端显示实际大小与质量，例如：

```
[已保存] output/scan_20260608_120000.jpg  输出=2108x2981  大小=475KB  质量=72  目标DPI=300  估算源DPI=180
```

需要高清大图时：

```bash
python scan.py --max-kb 0 --quality 98
```

## macOS 说明

macOS 使用 AVFoundation 后端，OpenCV 无法调节硬件对焦/曝光/锐度，属正常现象。改善清晰度请：

- 调整摄像头与纸张距离（约 25–40 cm）
- 保证充足光线
- 使用 `--sharpen` 软件锐化
- 让 Fill > 40%

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request