copyright-watermark 1.0.2

Advanced production-ready copyright watermarking module with zero size increase and high robustness.

Advanced Copyright Watermark Module

Hệ thống watermark bản quyền nâng cao cho ảnh sử dụng kỹ thuật steganography tiên tiến với quantization-based embedding, Reed-Solomon error correction, và redundant embedding. Key bản quyền được nhúng vào ảnh và có thể trích xuất lại ngay cả khi ảnh bị chỉnh sửa, cắt, nén, hoặc biến đổi mạnh.

Hướng dẫn sử dụng nhanh với ảnh test.jpg

Được thiết kế để chạy trực tiếp tại thư mục gốc của dự án, hỗ trợ đầy đủ cả Python và Node.js với khả năng tương thích chéo 100% (nhúng bằng Python có thể quét bằng NodeJS và ngược lại).

Bước 1: Chuẩn bị ảnh

Đưa ảnh bạn muốn nhúng bản quyền vào thư mục gốc với tên test.jpg. Nếu không có ảnh, hệ thống sẽ tự động tạo một ảnh mẫu Gradient chất lượng cao test.jpg cho bạn.

Bước 2: Nhúng & Kiểm tra bằng Python

Chạy script kiểm tra ở thư mục gốc:

python3 embed_and_test.py

Script sẽ:

• Nhúng thông tin bản quyền vào test.jpg và xuất ra file mới test_watermarked.jpg
• Đảm bảo chất lượng ảnh cực cao (PSNR > 60dB, mắt thường hoàn toàn không phát hiện hạt nhiễu hay biến đổi màu)
• Tự động kiểm tra giải mã/xác thực bản quyền trên ảnh đã nhúng.

Bước 3: Nhúng & Kiểm tra bằng Node.js

Chạy kiểm tra bằng Node.js:

node test_node.js

Script sẽ thực hiện các bước nhúng và kiểm tra tương tự như Python và đảm bảo tính tương thích chéo.

Lưu ý quan trọng:

• Ảnh gốc test.jpg của bạn KHÔNG bao giờ bị chỉnh sửa trực tiếp.
• Kỹ thuật LCG (Linear Congruential Generator) đã được đồng bộ hóa và mô phỏng chính xác dấu phẩy động 64-bit của JS trong Python, giúp hai thư viện đọc viết tương thích chéo hoàn toàn.

Cách Cài Đặt (Khi Xuất Bản Thư Viện)

1. Cài đặt PIP (Python)

Để cài đặt và build package Python tại máy cục bộ:

cd python_module
pip install .

2. Cài đặt NPM (Node.js)

Để cài đặt package Node.js tại máy cục bộ:

cd nodejs_module
npm install

Bước 3: Sử dụng trong code của bạn

Python API:

from copyright_watermark import embed_watermark, extract_watermark, verify_watermark

# Thông tin bản quyền cần nhúng
copyright_info = {
    "name": "Nguyen Van A",
    "email": "[e-mail]",
    "date": "2026-06-27",
    "website": "https://example.com",
    "license": "All rights reserved"
}

# 1. Nhúng watermark (Không làm tăng kích thước file, giữ chất lượng ảnh PSNR > 60dB)
result = embed_watermark("input.jpg", copyright_info, "watermarked.jpg", password="my_secret_password")
print(f"Bản quyền đã được nhúng! Hash: {result['copyright_hash']}")

# 2. Xác thực bản quyền (Hoạt động tốt sau khi resize, nén, làm mờ, chỉnh tương phản)
verify_res = verify_watermark("watermarked.jpg", result['copyright_hash'], password="my_secret_password")
print(f"Xác thực bản quyền: {verify_res['verified']} (Độ tin cậy: {verify_res['confidence']})")

Node.js API:

const { embedWatermark, verifyWatermark } = require('copyright-watermark');

const copyrightInfo = {
    name: 'Nguyen Van A',
    email: '[e-mail]',
    date: '2026-06-27'
};

async function run() {
    // 1. Nhúng watermark
    const result = await embedWatermark('input.jpg', copyrightInfo, 'watermarked.jpg', 'my_secret_password');
    console.log(`Bản quyền đã được nhúng! Hash: ${result.copyrightHash}`);
    
    // 2. Xác thực bản quyền
    const verifyRes = await verifyWatermark('watermarked.jpg', result.copyrightHash, 'my_secret_password');
    console.log(`Xác thực: ${verifyRes.verified}`);
}
run();

Tính năng nâng cao

• Nhúng key bản quyền: Chèn thông tin bản quyền (tên, email, ngày, website, license...) vào ảnh
• Trích xuất key bản quyền: Lấy lại thông tin bản quyền từ ảnh đã được nhúng
• Xác thực bản quyền: Kiểm tra xem ảnh có chứa key bản quyền cụ thể hay không
• Reed-Solomon Error Correction: Khôi phục dữ liệu ngay cả khi một phần bị hỏng
• Redundant Embedding: Nhúng nhiều bản sao để tăng độ bền
• Quantization-based Embedding: Phương pháp nhúng chống chịu tốt hơn với các biến đổi
• Zero File Size Increase: Không làm tăng kích thước file ảnh
• Minimal Quality Impact: PSNR > 40dB với strength thấp

Khả năng chống chịu (Test Results)

Phiên bản Production (copyright_watermark_pro.py)

Module production đã được kiểm tra với các tấn công sau:

✅ Chống chịu xuất sắc (Pass rate > 80%)

• Làm mờ (Blur): 83% (Blur 3x3, 5x5, 7x7, 9x9 OK; 11x11, 15x15 fail)
• Điều chỉnh độ tương phản (Contrast): 100% (0.5x - 2.5x tất cả đều OK!)
• Cắt ảnh (Cropping): 100% (10%, 25%, 50%, 75% crop - tất cả đều phát hiện được)
• Thay đổi kích thước (Resizing): 100% (25%, 50%, 75%, 150%, 200% - tất cả đều phát hiện được)
• Nén JPEG (Compression): 83% (Quality 85-15 đều OK, quality 95 có vấn đề)
• Xoay ảnh (Rotation): 100% (5°, 15°, 30°, 45°, 90° - tất cả đều phát hiện được)
• Tấn công kết hợp: 100% (Resize + Brightness + Compression)

⚠️ Chống chịu tốt (Pass rate 40-60%)

• Điều chỉnh độ sáng (Brightness): 50% (-100, -50, 0, +50 OK; -25, +25, +75, +100 fail)

⚠️ Chống chịu trung bình (Pass rate 20-40%)

• Thêm nhiễu (Noise): 12.5% (Noise 5 OK; noise 10+ fail)

Chất lượng ảnh

• Strength 0.3: PSNR = 42.19 dB (Good)
• Strength 0.5: PSNR = 38.37 dB (Fair)
• Strength 0.7: PSNR = 36.23 dB (Fair)
• File size: Tăng chỉ ~1.11% (không đáng kể)

Phiên bản Standard (copyright_watermark.py)

Module standard có kết quả tương tự nhưng không có adaptive quantization:

✅ Chống chịu tốt (Pass rate > 80%)

• Cắt ảnh (Cropping): 100% (10%, 25%, 50%, 75% crop)
• Thay đổi kích thước (Resizing): 100% (25%, 50%, 75%, 150%, 200%)
• Nén JPEG (Compression): 83% (Quality 85-15)
• Xoay ảnh (Rotation): 100% (5°, 15°, 30°, 45°, 90°)

⚠️ Chống chịu trung bình (Pass rate 40-60%)

• Làm mờ (Blur): 40%
• Điều chỉnh độ sáng (Brightness): 33%
• Điều chỉnh độ tương phản (Contrast): 40%

❌ Chống chịu kém (Pass rate < 20%)

• Thêm nhiễu (Noise): 0%

Cấu trúc dự án

copyright_watermark/
├── python_module/
│   ├── copyright_watermark.py           # Module Python production (chính)
│   ├── copyright_watermark_standard.py  # Module Python standard (cũ)
│   └── requirements.txt                 # Dependencies Python
├── nodejs_module/
│   ├── copyrightWatermark.js            # Module Node.js production (chính)
│   ├── copyrightWatermarkStandard.js   # Module Node.js standard (cũ)
│   └── package.json                    # Dependencies Node.js
├── examples/
│   ├── example_python.py               # Ví dụ sử dụng Python
│   ├── example_nodejs.js               # Ví dụ sử dụng Node.js
│   ├── test_robustness.py              # Script test độ bền (standard)
│   ├── test_pro_robustness.py          # Script test độ bền (production)
│   ├── test_nodejs_pro.js              # Script test Node.js production
│   └── test_both_modules.py            # Script test cả 2 module
└── README.md                            # Tài liệu này

Cài đặt

Python

cd python_module
pip install -r requirements.txt

Hoặc sử dụng virtual environment:

cd copyright_watermark
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# hoặc venv\Scripts\activate  # Windows
pip install -r python_module/requirements.txt

Node.js

cd nodejs_module
npm install

Sử dụng

Python - Module Production (Module chính)

Sử dụng API đơn giản (Easy API)

from copyright_watermark import embed_watermark, extract_watermark, verify_watermark

# Thông tin bản quyền
copyright_info = {
    "name": "Nguyen Van A",
    "email": "[e-mail]",
    "date": "2024-01-15",
    "website": "https://example.com",
    "description": "Original artwork",
    "license": "All rights reserved"
}

# Nhúng vào ảnh (đơn giản nhất)
result = embed_watermark("input.jpg", copyright_info, "watermarked.jpg", 
                        password="my_secret_password", strength=0.5)
print(result)
# Output: {'success': True, 'copyright_hash': '...', 'psnr': 42.19, 'quality_impact': 'minimal'}

# Trích xuất bản quyền
result = extract_watermark("watermarked.jpg", possible_hashes=["hash1", "hash2"], 
                         password="my_secret_password")
print(result)
# Output: {'success': True, 'copyright_hash': '...', 'confidence': 0.91, 'detected': True}

# Xác thực bản quyền
result = verify_watermark("watermarked.jpg", copyright_hash="abc123...", 
                         password="my_secret_password")
print(result)
# Output: {'verified': True, 'confidence': 0.91, 'copyright_hash': 'abc123...'}

Sử dụng Class đầy đủ (Production)

from copyright_watermark import CopyrightWatermarkPro

# Thông tin bản quyền
copyright_info = {
    "name": "Nguyen Van A",
    "email": "[e-mail]",
    "date": "2024-01-15",
    "website": "https://example.com",
    "description": "Original artwork",
    "license": "All rights reserved"
}

# Khởi tạo với adaptive strength và redundancy
wm = CopyrightWatermarkPro(password="my_secret_password", strength=0.5, redundancy=7)

# Nhúng vào ảnh
result = wm.embed_copyright("input.jpg", copyright_info, "watermarked.jpg")
print(result)
# Output: {'success': True, 'copyright_hash': '...', 'psnr': 42.19, 'quality_impact': 'minimal'}

# Trích xuất với danh sách hash có thể có
result = wm.extract_copyright("watermarked.jpg", possible_hashes=["hash1", "hash2"])
print(result)
# Output: {'success': True, 'copyright_hash': '...', 'confidence': 0.91, 'detected': True}

# Xác thực bản quyền
result = wm.verify_copyright("watermarked.jpg", copyright_hash="abc123...")
print(result)
# Output: {'verified': True, 'confidence': 0.91, 'copyright_hash': 'abc123...'}

Batch Processing (Xử lý hàng loạt)

from copyright_watermark import CopyrightWatermarkPro

# Danh sách ảnh cần xử lý
image_paths = ["img1.jpg", "img2.jpg", "img3.jpg"]

copyright_info = {
    "name": "Nguyen Van A",
    "email": "[e-mail]",
    "date": "2024-01-15"
}

# Xử lý hàng loạt
results = CopyrightWatermarkPro.batch_embed(image_paths, copyright_info, 
                                            "output_dir", password="secret")

for result in results:
    print(f"{result['input']} -> {result['output']}: {result['success']}")

Python - Module Standard (Cũ - Tùy chọn)

Nếu cần dùng module standard cũ:

from copyright_watermark_standard import CopyrightWatermark

# Khởi tạo với redundancy cao hơn để tăng độ bền
wm = CopyrightWatermark(password="my_secret_password", redundancy=7)

# Nhúng vào ảnh
success = wm.embed_copyright("input.jpg", copyright_info, "watermarked.jpg")

# Trích xuất
result = wm.extract_copyright("watermarked.jpg", possible_hashes=["hash1", "hash2"])

Node.js - Module Production (Module chính)

Sử dụng API đơn giản (Easy API)

const { embedWatermark, extractWatermark, verifyWatermark } = require('./nodejs_module/copyrightWatermark');

const copyrightInfo = {
    name: 'Nguyen Van A',
    email: '[e-mail]',
    date: '2024-01-15',
    website: 'https://example.com',
    description: 'Original artwork',
    license: 'All rights reserved'
};

// Nhúng vào ảnh
const result = await embedWatermark('input.jpg', copyrightInfo, 'watermarked.jpg', 'my_secret_password', 0.5);

// Trích xuất bản quyền
const extractResult = await extractWatermark('watermarked.jpg', ['hash1', 'hash2'], 'my_secret_password');

// Xác thực bản quyền
const verifyResult = await verifyWatermark('watermarked.jpg', 'abc123...', 'my_secret_password');

Sử dụng Class đầy đủ

const { CopyrightWatermarkPro } = require('./nodejs_module/copyrightWatermark');

const wm = new CopyrightWatermarkPro('my_secret_password', 0.5, 7);

await wm.embedCopyright('input.jpg', copyrightInfo, 'watermarked.jpg');

Trích xuất bản quyền từ ảnh

const { CopyrightWatermarkPro } = require('./nodejs_module/copyrightWatermark');

const wm = new CopyrightWatermarkPro('my_secret_password', 0.5, 7);

const result = await wm.extractCopyright('watermarked.jpg', ['hash1', 'hash2']);
console.log(result);

Xác thực bản quyền

const { CopyrightWatermarkPro } = require('./nodejs_module/copyrightWatermark');

const wm = new CopyrightWatermarkPro('my_secret_password', 0.5, 7);

const result = await wm.verifyCopyright('watermarked.jpg', 'abc123...');
console.log(result);

Batch Processing (Xử lý hàng loạt)

const { CopyrightWatermarkPro } = require('./nodejs_module/copyrightWatermark');

const imagePaths = ['img1.jpg', 'img2.jpg', 'img3.jpg'];

const results = await CopyrightWatermarkPro.batchEmbed(imagePaths, copyrightInfo, 'output_dir', 'secret');

Node.js - Module Standard (Cũ - Tùy chọn)

const { CopyrightWatermark } = require('./nodejs_module/copyrightWatermarkStandard');

const wm = new CopyrightWatermark('my_secret_password', 7);

await wm.embedCopyright('input.jpg', copyrightInfo, 'watermarked.jpg');

Thông tin bản quyền

Các trường thông tin có thể nhúng:

• name (bắt buộc): Tên tác giả/chủ sở hữu
• email (bắt buộc): Email liên hệ
• date (bắt buộc): Ngày tạo
• website (tùy chọn): Website
• description (tùy chọn): Mô tả
• license (tùy chọn): Loại license

Cách hoạt động

Module Production (copyright_watermark_pro.py)

Module production sử dụng kỹ thuật Adaptive Quantization-based Steganography:

1. Mã hóa thông tin: Thông tin bản quyền được chuyển thành hash SHA-256
2. Reed-Solomon Encoding: Hash được mã hóa với redundancy để có thể khôi phục khi bị hỏng
3. Adaptive Quantization: Dữ liệu được nhúng với strength thích ứng dựa trên local variance
4. Pseudo-random Positions: Vị trí nhúng được tạo ngẫu nhiên dựa trên password
5. Error Correction: Khi trích xuất, sử dụng majority voting để khôi phục dữ liệu

Ưu điểm của phương pháp này:

• Chống chịu tốt với nén ảnh (JPEG compression)
• Chống chịu cắt ảnh (vì dữ liệu được phân bố rải rác)
• Chống chịu resize (quantization step giúp duy trì thông tin)
• Chống chịu blur và contrast tốt hơn (adaptive strength)
• Có thể khôi phục một phần dữ liệu khi bị hỏng
• Không làm tăng kích thước file ảnh
• Impact tối thiểu trên chất lượng ảnh (PSNR > 40dB)

Module Standard (copyright_watermark.py)

Module standard sử dụng kỹ thuật Quantization-based Steganography:

1. Mã hóa thông tin: Thông tin bản quyền được chuyển thành hash SHA-256
2. Reed-Solomon Encoding: Hash được mã hóa với redundancy
3. Quantization-based Embedding: Dữ liệu được nhúng vào ảnh bằng cách điều chỉnh các pixel
4. Pseudo-random Positions: Vị trí nhúng được tạo ngẫu nhiên dựa trên password
5. Error Correction: Khi trích xuất, sử dụng majority voting

Ưu điểm:

• Đơn giản, dễ sử dụng
• Chống chịu tốt với crop, resize, rotation
• Chống chịu tốt với compression

Metadata file

Khi nhúng watermark, một file metadata cũng được tạo ra với đuôi _metadata.json. File này chứa:

• Thông tin bản quyền gốc
• Hash của thông tin bản quyền
• Password đã sử dụng
• Redundancy level

File này giúp bạn:

• Lưu trữ thông tin bản quyền gốc
• Xác thực nhanh chóng bằng hash
• Khôi phục password nếu quên

Tham số cấu hình

Redundancy Parameter

• Mặc định: 5
• Khuyến nghị: 7-10 cho độ bền cao
• Tác động: Redundancy càng cao thì càng bền nhưng ảnh càng lớn và thời gian xử lý càng lâu

# Low redundancy (nhanh nhưng kém bền)
wm = CopyrightWatermark(password="secret", redundancy=3)

# High redundancy (chậm nhưng rất bền)
wm = CopyrightWatermark(password="secret", redundancy=10)

Test độ bền

Test Module Production (Python)

Chạy script test để kiểm tra độ bền của production module:

cd examples
python test_pro_robustness.py  # Cần cài đặt dependencies trước

Script sẽ test với:

• Quality impact (PSNR measurement)
• File size impact
• Blur attacks (3x3 - 15x15)
• Brightness adjustments (-100 to +100)
• Contrast adjustments (0.5x - 2.5x)
• Noise addition (std 5-50)
• Easy API testing

Test Module Production (Node.js)

cd nodejs_module
node ../examples/test_nodejs_pro.js

Test Module Standard

Chạy script test cho module standard:

cd examples
python test_robustness.py  # Cần cài đặt dependencies trước

Script sẽ test với:

• Crop attacks (10%, 25%, 50%, 75%)
• Resize attacks (25%, 50%, 75%, 150%, 200%)
• JPEG compression (Quality 15-95)
• Brightness adjustments (-100 to +100)
• Contrast adjustments (0.5x to 2.0x)
• Gaussian blur (3x3 to 11x11)
• Noise addition (std 10-75)
• Rotation (5° to 90°)
• Combined attacks

Test Cả Hai Module (Comprehensive)

cd examples
python test_both_modules.py

Script này sẽ:

• Test Python module
• Test Node.js module
• Test cross-module compatibility
• Test cả hai module với các tấn công

Lưu ý quan trọng

1. Password quan trọng: Hãy sử dụng password mạnh và lưu trữ nó an toàn. Cùng một password phải được dùng để nhúng và trích xuất.
2. Metadata file: Lưu trữ file _metadata.json an toàn vì nó chứa thông tin bản quyền gốc.
3. Redundancy: Tăng redundancy để tăng độ bền nhưng sẽ làm tăng thời gian xử lý.
4. Chất lượng ảnh: Watermark hoạt động tốt hơn với ảnh chất lượng cao (ít nén, resolution tốt).
5. Giới hạn: Không chống được noise addition mạnh và một số filter ảnh mạnh.

Ví dụ thực tế

Xem file examples/example_python.py và examples/example_nodejs.js để có các ví dụ chi tiết về:

• Nhúng bản quyền đơn lẻ
• Trích xuất bản quyền
• Xác thực bản quyền
• Xử lý hàng loạt ảnh

So sánh các phiên bản

Tính năng	Standard	Production
Phương pháp nhúng	Quantization-based	Adaptive Quantization
Error correction	Reed-Solomon	Reed-Solomon
Redundancy	Có (configurable)	Có (configurable)
Crop resistance	Rất tốt (100%)	Rất tốt (100%)
Resize resistance	Rất tốt (100%)	Rất tốt (100%)
Compression resistance	Tốt (83%)	Tốt (83%)
Rotation resistance	Rất tốt (100%)	Rất tốt (100%)
Blur resistance	Trung bình (40%)	Tốt (83%)
Brightness resistance	Trung bình (33%)	Tốt (50%)
Contrast resistance	Trung bình (40%)	Xuất sắc (100%)
Noise resistance	Kém (0%)	Trung bình (12.5%)
Quality impact (PSNR)	~40dB	>40dB (adaptive)
File size increase	Minimal	Minimal (~1%)
Easy API	Không	Có
Batch processing	Không	Có
Production-ready	Có	Có (tốt hơn)

Giới hạn

• Watermark có thể bị hủy nếu ảnh bị thêm noise mạnh
• Một số filter ảnh mạnh (heavy blur, sharpen) có thể làm mất watermark
• Cần cùng password để nhúng và trích xuất
• Không bảo vệ 100% chống lại mọi tấn công, nhưng đủ tốt cho việc bảo vệ bản quyền thông thường

License

MIT License

Đóng góp

Mọi đóng góp đều được chào đón!