palimpsest-qr 0.1.3

A hyper-realistic QR code replacer with perspective transform, tone matching, and noise simulation.

Palimpsest (Hyper-QR)

Hyper-Realistic QR Code Replacement Tool
超写实二维码替换工具

English | 中文指南

---

🇬🇧 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)

pip install palimpsest-qr

From Source (Development)

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.

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:

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:

palimpsest -t poster.jpg -s code.png --noise 15.0 --content-blur 0.5

Python API

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.

---

🇨🇳 中文指南

简介

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

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

核心功能

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

安装指南

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

直接在终端运行：

pip install palimpsest-qr

方法二：源码安装

如果您需要参与开发或自行修改代码：

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

##以此工具的使用

1. 交互模式（最简单）

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

palimpsest

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

2. 命令行模式 (CLI)

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

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

高拟真示例:

palimpsest -t photo.jpg -s code.png --noise 12.0 --content-blur 0.8

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 授权。