# aidprintPythonScripts

**Repository Path**: aidprint-mysql-handle/aidprint-python-scripts

## Basic Information

- **Project Name**: aidprintPythonScripts
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 身份证裁切与 A4 合并工具

本项目可以将一张或多张身份证照片自动裁切、透视矫正，并排版到一张 A4 白底 PDF 或图片上。

## 脚本说明

| 文件 | 用途 |
| --- | --- |
| `crop_idcard.py` | 单张身份证裁切核心及单图命令行入口 |
| `compose_idcards_a4.py` | 接收多个本地图片路径，裁切并合并到 A4 |
| `compose_idcards_a4_urls.py` | 接收多个 HTTP/HTTPS URL，下载、裁切并合并到 A4 |
| `build_linux.sh` | 在 Linux 上将 URL 版本编译为单文件二进制程序 |
| `requirements.txt` | 跨平台运行依赖，自动选择适合当前系统的 OpenCV |
| `requirements-build.txt` | 运行依赖和 PyInstaller 编译依赖 |

## 环境要求

- Python 3.10 或更高版本，推荐 Python 3.12
- 可用的 `pip` 和 Python 虚拟环境模块
- URL 版本运行时需要访问图片 URL 的网络权限
- URL 版本默认输出 PDF，也支持 JPEG、PNG

已验证的主要依赖版本：

```text
numpy==2.2.6
Pillow==12.3.0
opencv-python==4.12.0.88
opencv-python-headless==4.12.0.88
PyInstaller>=6.14,<7
```

`opencv-python` 和 `opencv-python-headless` 只能选择一个，不要安装在同一个虚拟环境中。

## 一键安装依赖

创建并激活虚拟环境后，运行源码只需执行：

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

需要编译二进制时执行：

```bash
python -m pip install -r requirements-build.txt
```

`requirements.txt` 会根据操作系统自动选择 OpenCV：

- Linux 安装 `opencv-python-headless`，适合无桌面的服务器
- Windows 和 macOS 安装 `opencv-python`，支持图形窗口
- NumPy 和 Pillow 在所有平台安装相同的固定版本

## Linux 安装

### Debian、Ubuntu

安装 Python 和虚拟环境支持：

```bash
sudo apt update
sudo apt install -y python3 python3-venv python3-pip ca-certificates
```

进入项目目录并创建虚拟环境：

```bash
cd /path/to/crop
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
```

服务器或没有桌面的 Linux 推荐安装无界面版 OpenCV：

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

如果需要使用 `--manual-fallback` 打开窗口手动选择角点，请安装桌面版 OpenCV：

```bash
sudo apt install -y libgl1 libglib2.0-0
python -m pip uninstall -y opencv-python-headless
python -m pip install "opencv-python==4.12.0.88"
```

### CentOS Stream 9

先确认系统版本：

```bash
cat /etc/centos-release
uname -m
```

安装 Python 3.11、证书和基础工具：

```bash
sudo dnf install -y \
  python3.11 \
  python3.11-pip \
  python3.11-devel \
  ca-certificates
sudo update-ca-trust
```

进入项目目录，创建并激活虚拟环境：

```bash
cd /path/to/crop
python3.11 -m venv .venv
source .venv/bin/activate
python --version
python -m pip install --upgrade pip setuptools wheel
```

CentOS 服务器通常没有图形桌面，推荐安装无界面版 OpenCV：

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

验证依赖：

```bash
python -c 'import cv2, numpy, PIL; print(cv2.__version__, numpy.__version__, PIL.__version__)'
```

URL 版本默认写入当前工作目录下的 `public/corp`。普通用户在自己拥有的项目目录中运行时，可以直接创建并检查目录：

```bash
mkdir -p public/corp
test -w public/corp && echo "输出目录可写"
```

部署到 `/opt` 并通过服务用户运行时，应由管理员把目录所有权授予实际服务用户。以下示例假设服务用户为 `idcard`：

```bash
sudo install -d -o idcard -g idcard -m 0755 /opt/idcard-crop/public/corp
```

使用源码处理多个 URL：

```bash
cd /path/to/crop
source .venv/bin/activate

python compose_idcards_a4_urls.py \
  "https://example.com/front.jpg" \
  "https://example.com/back.jpg"
```

程序成功后会在标准输出返回绝对路径。Shell 脚本可以直接获取该路径：

```bash
RESULT_PATH=$(python compose_idcards_a4_urls.py \
  "https://example.com/front.jpg" \
  "https://example.com/back.jpg")

echo "${RESULT_PATH}"
```

指定输出路径：

```bash
python compose_idcards_a4_urls.py \
  "https://example.com/front.jpg" \
  "https://example.com/back.jpg" \
  -o /data/idcards/result.pdf
```

处理服务器上的本地图片：

```bash
python compose_idcards_a4.py \
  /data/idcards/front.jpg \
  /data/idcards/back.jpg \
  -o /data/idcards/result-a4.jpg
```

在 CentOS 上编译 URL 版本：

```bash
chmod +x build_linux.sh
PYTHON_BIN=python3.11 ./build_linux.sh
```

生成的文件为 `dist/idcard_a4_url`。运行已编译的二进制不需要再激活 Python 虚拟环境：

```bash
chmod +x dist/idcard_a4_url

./dist/idcard_a4_url \
  "https://example.com/front.jpg" \
  "https://example.com/back.jpg"
```

生产环境必须允许访问图片 URL，并安装 `ca-certificates`，否则 HTTPS 下载会失败。

#### CentOS 7 和 CentOS 8

CentOS Linux 7 和 CentOS Linux 8 已停止维护，其默认 Python 版本低于本项目要求的 Python 3.10。建议升级到 CentOS Stream 9、Rocky Linux 9 或其他仍受支持的发行版。

如果必须使用旧系统，需要单独安装 Python 3.10 或更高版本，并在该系统或兼容的旧版 glibc 构建环境中生成二进制。不要直接把 CentOS Stream 9 上编译的程序复制到 CentOS 7，可能出现 `GLIBC_x.x not found`。

## Windows 安装

先从 [Python 官网](https://www.python.org/downloads/windows/) 安装 64 位 Python 3.12。安装时勾选 `Add Python to PATH`。

在 PowerShell 中进入项目目录：

```powershell
cd C:\path\to\crop
py -3.12 -m venv .venv
Set-ExecutionPolicy -Scope Process Bypass
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

使用传统命令提示符时，激活命令为：

```bat
.venv\Scripts\activate.bat
```

## macOS 安装

可以使用 [Homebrew](https://brew.sh/) 安装 Python 3.12：

```bash
brew install python@3.12
```

进入项目目录并安装依赖：

```bash
cd /path/to/crop
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

Apple Silicon 和 Intel Mac 必须使用与机器架构一致的 Python，不要混用 x86_64 与 arm64 环境。

## 运行脚本

以下命令均假设虚拟环境已经激活。如果没有激活，也可以直接使用 Linux/macOS 的 `.venv/bin/python` 或 Windows 的 `.venv\Scripts\python.exe`。

### 处理多个本地图片

Linux 和 macOS：

```bash
python compose_idcards_a4.py \
  "/path/to/front.jpg" \
  "/path/to/back.jpg" \
  -o "output/idcards-a4.jpg"
```

Windows PowerShell：

```powershell
python compose_idcards_a4.py `
  "C:\images\front.jpg" `
  "C:\images\back.jpg" `
  -o "output\idcards-a4.jpg"
```

保存每张独立裁切结果：

```bash
python compose_idcards_a4.py \
  front.jpg back.jpg \
  -o output/idcards-a4.jpg \
  --save-crops output/crops
```

### 处理多个图片 URL

Linux 和 macOS：

```bash
python compose_idcards_a4_urls.py \
  "https://example.com/front.jpg" \
  "https://example.com/back.jpg"
```

Windows PowerShell：

```powershell
python compose_idcards_a4_urls.py `
  "https://example.com/front.jpg" `
  "https://example.com/back.jpg"
```

URL 版本成功后只在标准输出打印最终文件的绝对路径。下载和裁切进度写入标准错误，方便其他程序获取返回值。

未指定 `-o` 时，默认输出到执行命令时所在目录的：

```text
public/corp/idcards-a4-时间戳-随机值.pdf
```

指定输出路径：

```bash
python compose_idcards_a4_urls.py \
  "https://example.com/front.jpg" \
  "https://example.com/back.jpg" \
  -o output/result.pdf
```

### 常用参数

| 参数 | 说明 |
| --- | --- |
| `-o`, `--output` | 指定最终 PDF、JPG 或 PNG 输出路径 |
| `--dpi 300` | 设置 A4 输出 DPI，默认 300 |
| `--margin-mm 15` | 设置页边距，单位毫米 |
| `--gap-mm 8` | 设置图片间距，单位毫米 |
| `--landscape` | 使用横向 A4 画布 |
| `--corner-radius 25` | 设置裁切图片圆角半径 |
| `--manual-fallback` | 自动检测失败时手动选择四个角点，需要桌面环境 |
| `--debug` | 输出裁切调试信息 |
| `--timeout 30` | URL 版本单个请求的超时时间 |
| `--max-download-mb 25` | URL 版本单张图片的最大下载体积 |

查看全部参数：

```bash
python compose_idcards_a4.py --help
python compose_idcards_a4_urls.py --help
```

## 编译说明

PyInstaller 不是跨平台编译器：

- Linux 二进制必须在 Linux 上构建
- Windows `.exe` 必须在 Windows 上构建
- macOS 可执行程序必须在 macOS 上构建
- x86_64 和 arm64 通常也需要分别构建

为了获得更好的兼容性，建议在与部署环境相同或更旧的系统版本上构建。

## Linux 编译

项目提供了自动构建脚本，目标为 URL 版本：

```bash
chmod +x build_linux.sh
./build_linux.sh
```

脚本会自动创建 `.venv-build-linux`、安装构建依赖、生成单文件程序并执行启动检查。

生成文件：

```text
dist/idcard_a4_url
```

运行二进制：

```bash
./dist/idcard_a4_url \
  "https://example.com/front.jpg" \
  "https://example.com/back.jpg"
```

指定 Python 解释器：

```bash
PYTHON_BIN=python3.12 ./build_linux.sh
```

手动编译本地图片版本：

```bash
source .venv/bin/activate
python -m pip install -r requirements-build.txt
python -m PyInstaller \
  --noconfirm \
  --clean \
  --onefile \
  --console \
  --name idcard_a4_local \
  compose_idcards_a4.py
```

生成文件为 `dist/idcard_a4_local`。

## Windows 编译

激活虚拟环境并安装 PyInstaller：

```powershell
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-build.txt
```

编译 URL 版本：

```powershell
python -m PyInstaller `
  --noconfirm `
  --clean `
  --onefile `
  --console `
  --name idcard_a4_url `
  compose_idcards_a4_urls.py
```

生成文件：

```text
dist\idcard_a4_url.exe
```

运行：

```powershell
.\dist\idcard_a4_url.exe `
  "https://example.com/front.jpg" `
  "https://example.com/back.jpg"
```

编译本地图片版本时，将名称和入口替换为：

```powershell
python -m PyInstaller `
  --noconfirm `
  --clean `
  --onefile `
  --console `
  --name idcard_a4_local `
  compose_idcards_a4.py
```

## macOS 编译

激活虚拟环境并安装 PyInstaller：

```bash
source .venv/bin/activate
python -m pip install -r requirements-build.txt
```

编译 URL 版本：

```bash
python -m PyInstaller \
  --noconfirm \
  --clean \
  --onefile \
  --console \
  --name idcard_a4_url \
  compose_idcards_a4_urls.py
```

生成文件：

```text
dist/idcard_a4_url
```

运行：

```bash
./dist/idcard_a4_url \
  "https://example.com/front.jpg" \
  "https://example.com/back.jpg"
```

编译本地图片版本：

```bash
python -m PyInstaller \
  --noconfirm \
  --clean \
  --onefile \
  --console \
  --name idcard_a4_local \
  compose_idcards_a4.py
```

macOS 构建的程序首次在其他机器运行时，可能受到 Gatekeeper 限制。正式分发需要使用 Apple Developer ID 进行代码签名和公证。

## 常见问题

### Linux 提示缺少 `libGL.so.1`

服务器部署优先使用 `opencv-python-headless`。如果必须使用桌面版 OpenCV，可安装：

```bash
sudo apt install -y libgl1 libglib2.0-0
```

### 同时安装了两个 OpenCV 包

先卸载，再根据运行环境选择其中一个：

```bash
python -m pip uninstall -y opencv-python opencv-python-headless
python -m pip install "opencv-python-headless==4.12.0.88"
```

### Linux 无法创建虚拟环境

Debian 或 Ubuntu 通常需要安装：

```bash
sudo apt install -y python3-venv
```

### URL 下载失败或超时

确认服务器可以访问对应 URL，并适当增加超时时间：

```bash
python compose_idcards_a4_urls.py \
  "https://example.com/front.jpg" \
  --timeout 60 \
  --max-download-mb 50
```

### 单文件程序较大或启动较慢

OpenCV、NumPy 和 Pillow 会被打包进程序，单文件体积达到 100 MB 以上属于正常情况。PyInstaller 的 `--onefile` 模式启动时还需要先解压运行文件。

如需更快启动，可以将 `--onefile` 改为 `--onedir`，并分发整个 `dist` 子目录。

### Linux 二进制在另一台机器不能运行

检查 CPU 架构和 glibc 版本。Linux 二进制通常应在与目标机器相同架构、相同或更旧的发行版上构建，不能直接将在 macOS 或 Windows 构建的文件复制到 Linux 使用。