palimpsest-qr 0.1.3
A hyper-realistic QR code replacer with perspective transform, tone matching, and noise simulation.
Requires Python: >=3.8

# Palimpsest (Hyper-QR)

<p align="center">
  <b>Hyper-Realistic QR Code Replacement Tool</b><br>
  <b>超写实二维码替换工具</b>
</p>

<p align="center">
  <a href="#english">English</a> | <a href="#chinese">中文指南</a>
</p>

---

<br>

<div id="english"></div>

# 🇬🇧 English Guide

## Introduction

**Palimpsest** (published on PyPI as `palimpsest-qr`) is a professional computer vision utility designed to seamlessly replace QR codes in images while maintaining photorealistic consistency. 

Unlike simple overlay tools, Palimpsest employs advanced techniques to ensure the new QR code matches the **perspective**, **lighting**, **tone**, and **noise profile** of the original image, making the replacement virtually undetectable.

### Key Features

*   **PERSPECTIVE WARP**: Automatically detects the 4 corners of the original QR code and warps the new QR code to match the exact perspective.
*   **INTELLIGENT INPAINTING**: Uses Telea algorithm to erase the original QR code first, preventing "ghosting" artifacts.
*   **TONE MATCHING**: Analyzes the black/white points of the target area and adjusts the new QR's histogram to match exposure and contrast.
*   **NOISE SIMULATION**: Adds monochromatic Gaussian noise to match the camera sensor's ISO grain.
*   **SOFT BLENDING**: Supports Alpha Blending with edge feathering for perfect integration.
*   **INTERACTIVE MODE**: A "Click-to-Run" GUI for easy operation without command line.

## Installation

### From PyPI (Recommended)

```bash
pip install palimpsest-qr
```

### From Source (Development)

```bash
git clone https://github.com/YourUsername/Palimpsest.git
cd Palimpsest
pip install . -r requirements.txt
```

## Usage

### 1. Interactive GUI Mode (Easiest)

Simply run the command without any arguments. A file picker will appear.

```bash
palimpsest
```

1.  Select **Target Image** (Background).
2.  Select **Source Image** (New QR Code).
3.  Done! The result is saved as `*_replaced.jpg`.

### 2. Command Line Interface (CLI)

For batch processing or precise control:

```bash
palimpsest -t target.jpg -s new_qr.png
```

#### Arguments

| Argument | Description | Default |
| :--- | :--- | :--- |
| `-t`, `--target` | Path to background image containing old QR | Required (or GUI) |
| `-s`, `--source` | Path to new QR code image | Required (or GUI) |
| `-o`, `--output` | Path to save result | `*_replaced.jpg` |
| `--noise` | ISO Noise strength (float, e.g. `10.0`) | `0.0` |
| `--content-blur` | Blur radius to match soft focus (float) | `0.0` |
| `--no-tone` | Disable tone matching | `False` |
| `--no-inpaint` | Disable background erasure | `False` |

**Example:**
```bash
palimpsest -t poster.jpg -s code.png --noise 15.0 --content-blur 0.5
```

## Python API

```python
from palimpsest.core import process_image
import cv2

# Process and get numpy array
result = process_image(
    target_path="target.jpg",
    source_path="source.png",
    match_tone=True,
    noise=10.0
)

cv2.imwrite("output.jpg", result)
```

## License

This project is licensed under the [GPL-3.0 License](LICENSE).

---

<br>
<br>

<div id="chinese"></div>

# 🇨🇳 中文指南

## 简介

**Palimpsest** (PyPI 包名: `palimpsest-qr`) 是一个专业的计算机视觉工具，用于在保持照片级真实感的前提下替换图片中的二维码。

与简单的“贴图”不同，本工具使用先进的图像处理技术，确保新的二维码在**透视角度**、**光照色调**、**噪点颗粒**等方面与原图完美融合，肉眼几乎无法辨别。

### 核心功能

*   **自动透视变换**: 自动识别原图二维码的四个角点，将新二维码进行精确的透视扭曲以贴合原图角度。
*   **智能去重 (Inpainting)**: 在贴图前使用 Telea 算法智能擦除原二维码，防止边缘出现重影或黑边。
*   **色调映射 (Tone Matching)**: 分析目标区域的黑白电平，自动调整新二维码的直方图，使其亮度和对比度与环境光一致（避免在暗光照片中二维码“死黑”或“死白”）。
*   **噪点模拟**: 添加单色高斯噪点以模拟相机传感器的 ISO 颗粒感，消除“数码贴纸”感。
*   **柔和融合**: 边缘羽化处理，使结合处过渡自然。
*   **所见即所得交互**: 支持无参数启动，直接弹出文件选择窗口，操作零门槛。

## 安装指南

### 方法一：通过 PyPI 安装（推荐）

直接在终端运行：
```bash
pip install palimpsest-qr
```

### 方法二：源码安装

如果您需要参与开发或自行修改代码：
```bash
git clone https://github.com/YourUsername/Palimpsest.git
cd Palimpsest
pip install . -r requirements.txt
```

##以此工具的使用

### 1. 交互模式（最简单）

无需输入任何命令参数，直接运行：

```bash
palimpsest
```

1.  程序会弹出窗口，请选择**背景图片**（含有旧二维码的图）。
2.  程序再次弹出窗口，请选择**新二维码图片**。
3.  自动处理完成！结果会保存在原图同目录下，文件名后缀为 `_replaced.jpg`。

### 2. 命令行模式 (CLI)

适合批量处理或需要精细调整参数的高级用户。

```bash
palimpsest -t target.jpg -s new_qr.png
```

#### 参数说明

| 参数 | 说明 | 默认值 |
| :--- | :--- | :--- |
| `-t`, `--target` | 目标图片路径（背景） | 必填 (或使用 GUI) |
| `-s`, `--source` | 源图片路径（新二维码） | 必填 (或使用 GUI) |
| `-o`, `--output` | 输出路径 | 自动生成 |
| `--noise` | 模拟噪点强度 (浮点数, 推荐 `5.0`-`20.0`) | `0.0` |
| `--content-blur` | 内容模糊 (模拟失焦/低分辨率), 推荐 `0.5` | `0.0` |
| `--no-tone` | 禁用色调匹配 | `False` |
| `--no-inpaint` | 禁用智能擦除 | `False` |

**高拟真示例:**
```bash
palimpsest -t photo.jpg -s code.png --noise 12.0 --content-blur 0.8
```

## Python 开发调用

您也可以在自己的 Python 代码中调用核心逻辑：

```python
from palimpsest.core import process_image
import cv2

# 执行处理，返回 numpy 数组
result = process_image(
    target_path="poster.jpg",
    source_path="my_code.png",
    match_tone=True,       # 开启色调匹配
    noise=10.0,            # 添加噪点
    inpaint=True           # 开启去重
)

if result is not None:
    cv2.imwrite("final_result.jpg", result)
```

## 许可证

本项目采用 [GPL-3.0 License](LICENSE) 授权。