🏷️ QR Code Batch Image Processor

معالج صور دفعي احترافي يضيف QR Code كعلامة مائية على صور المنتجات

الميزات • التثبيت • التشغيل • الثيمات • الإعدادات • المساهمة

---

✨ الميزات

الميزة	الوصف
🎨 7 ثيمات جاهزة	Classic, Luxury, Rose Gold, Midnight — مع أو بدون حاوية
⚡ معالجة متوازية	دعم Multi-processing لمعالجة مئات الصور بسرعة
🔄 EXIF Auto-fix	تصحيح اتجاه الصور تلقائياً
📊 سجل CSV	تتبع كل عملية معالجة بملف سجل مفصل
🛡️ مقاوم للأخطاء	الملفات التالفة تُتخطى دون توقف المعالجة
🏃 وضع المحاكاة	--dry-run لاختبار الإعدادات قبل التنفيذ
📐 حجم ديناميكي	حجم QR يتناسب تلقائياً مع أبعاد الصورة
🎯 SKU تلقائي	استخراج رمز المنتج من اسم الملف

---

🎨 معاينة الثيمات

Classic

Rose Gold Container

7 ثيمات متاحة: classic · luxury · rose-gold · midnight · luxury-container · rose-gold-container · midnight-container

---

📋 المتطلبات

• Python 3.8 أو أحدث
• نظام التشغيل: Linux / macOS / Windows

---

🚀 التثبيت

# 1. استنساخ المشروع
git clone https://github.com/0s-a/QrCode-Batch-Image-Processor.git
cd QrCode-Batch-Image-Processor

# 2. إنشاء بيئة بايثون افتراضية
python3 -m venv venv

# 3. تفعيل البيئة الافتراضية
source venv/bin/activate          # Linux / macOS
# venv\Scripts\activate           # Windows

# 4. تثبيت المكتبات المطلوبة
pip install -r requirements.txt

---

📁 هيكل المشروع

QrCode-Batch-Image-Processor/
├── 📂 input/                  ← ضع صور المنتجات هنا
├── 📂 output/                 ← الصور المعالجة تظهر هنا (تلقائي)
├── 📂 qr_coed_model/          ← أمثلة على أشكال QR المتاحة
├── 📂 assets/                 ← ملفات المشروع (بانر، إلخ)
├── ⚙️ config.json              ← إعدادات قابلة للتعديل
├── 🐍 processor.py             ← السكربت الرئيسي
├── 📦 requirements.txt         ← المكتبات المطلوبة
├── 📄 LICENSE                  ← رخصة MIT
└── 📖 README.md                ← هذا الملف

---

▶️ طريقة التشغيل

الخطوة 1: تفعيل البيئة

source venv/bin/activate

الخطوة 2: ضع صور المنتجات في مجلد input/

cp /path/to/your/images/*.jpg input/

الخطوة 3: تشغيل المعالجة

python processor.py

الخطوة 4: النتائج في مجلد output/ ✅

---

🎨 الثيمات المتاحة

بدون حاوية

python processor.py --theme classic       # الشكل التقليدي
python processor.py --theme luxury        # زوايا مستديرة، رمادي أنيق
python processor.py --theme rose-gold     # وردي ذهبي (مثالي للتجميل) ⭐
python processor.py --theme midnight      # كحلي عصري

مع حاوية (بطاقة بيضاء + ظل)

python processor.py --theme luxury-container
python processor.py --theme rose-gold-container    # الأفخم ⭐
python processor.py --theme midnight-container

إضافة حاوية لأي ثيم

python processor.py --theme luxury --container

---

🛠️ جميع خيارات سطر الأوامر

الخيار	الوصف	مثال
--theme THEME	اختيار شكل QR Code	--theme rose-gold
--container	إضافة حاوية بظل حول QR	--container
--input PATH	تغيير مجلد الإدخال	--input ./my_images
--output PATH	تغيير مجلد الإخراج	--output ./processed
--quality N	جودة JPEG من 1 إلى 100	--quality 90
--qr-size N	نسبة حجم QR (0.01 - 0.50)	--qr-size 0.20
--workers N	عدد العمليات المتوازية	--workers 4
--dry-run	محاكاة بدون كتابة ملفات	--dry-run
--skip-existing	تخطي الملفات الموجودة مسبقاً	--skip-existing

---

📝 أمثلة عملية

# معالجة بسيطة (الوضع الافتراضي)
python processor.py

# معالجة بثيم Rose Gold مع حاوية
python processor.py --theme rose-gold-container

# معالجة سريعة بـ 4 عمليات متوازية
python processor.py --theme rose-gold-container --workers 4

# تغيير حجم QR إلى 20% مع جودة 90
python processor.py --qr-size 0.20 --quality 90

# محاكاة أولاً ثم تنفيذ
python processor.py --dry-run
python processor.py --theme rose-gold-container

# معالجة صور من مجلد مختلف
python processor.py --input /path/to/images --output /path/to/results

# دمج عدة خيارات
python processor.py \
  --theme rose-gold-container \
  --workers 4 \
  --quality 90 \
  --qr-size 0.18 \
  --skip-existing

---

⚙️ الإعدادات

يمكنك تعديل ملف config.json بدلاً من كتابة الخيارات في كل مرة:

📄 عرض config.json الافتراضي

{
  "input_dir": "./input",
  "output_dir": "./output",
  "supported_extensions": [".jpg", ".jpeg", ".png", ".webp"],
  "qr_size_ratio": 0.15,
  "padding_ratio": 0.02,
  "min_padding_px": 10,
  "jpeg_quality": 95,
  "qr_position": "bottom-right",
  "qr_border_modules": 4,
  "overwrite_existing": true,
  "log_file": "processing_log.csv",
  "workers": 1,

  "qr_style": {
    "theme": "classic",
    "rounded_modules": false,
    "container": false,
    "container_padding_ratio": 0.15,
    "container_radius": 16,
    "shadow": true,
    "shadow_blur": 10,
    "shadow_opacity": 50,
    "fg_color": "#000000",
    "bg_color": "#FFFFFF"
  }
}

الإعدادات الأساسية

الإعداد	الوصف	القيمة الافتراضية
input_dir	مسار مجلد الصور الأصلية	./input
output_dir	مسار مجلد الصور المعالجة	./output
qr_size_ratio	نسبة حجم QR من عرض الصورة	0.15 (15%)
jpeg_quality	جودة حفظ JPEG	95
workers	عدد العمليات المتوازية	1

إعدادات شكل QR (qr_style)

الإعداد	الوصف	القيمة الافتراضية
theme	اسم الثيم	classic
rounded_modules	زوايا مستديرة للمربعات	false
container	إضافة حاوية بيضاء حول QR	false
shadow	إضافة ظل خلف الحاوية	true
fg_color	لون QR	#000000
bg_color	لون خلفية QR	#FFFFFF

ملاحظة: خيارات سطر الأوامر لها الأولوية الأعلى وتتجاوز إعدادات config.json.

---

📊 ملف السجل

بعد كل تشغيل يُنشأ ملف processing_log.csv في مجلد output/ يحتوي:

العمود	الوصف
timestamp	وقت المعالجة
filename	اسم الملف
sku	رمز المنتج المستخرج
status	success / failed / skipped / dry-run
original_size	أبعاد الصورة الأصلية
qr_size_px	حجم QR بالبكسل
error	رسالة الخطأ (إن وجد)

---

📝 استخراج SKU

يتم استخراج رمز المنتج تلقائياً من اسم الملف:

اسم الملف	SKU المستخرج
BF-1012-1.jpg	BF-1012-1
BF-891-8.png	BF-891-8
PROD-ABC.v2.jpeg	PROD-ABC.v2

---

⚠️ ملاحظات مهمة

• الملفات التالفة يتم تخطيها تلقائياً مع تسجيل الخطأ
• يتم تصحيح اتجاه الصور (EXIF orientation) تلقائياً
• صور PNG الشفافة تُعالج بشكل صحيح
• حجم QR الأدنى هو 50px لضمان إمكانية المسح
• الامتدادات المدعومة: .jpg, .jpeg, .png, .webp

---

🔧 حل المشاكل الشائعة

المشكلة	الحل
No images found	تأكد من وضع الصور في مجلد input/
command not found: python	فعّل البيئة: source venv/bin/activate
الصور بطيئة	استخدم: --workers 4
QR لا يُقرأ بالكاميرا	كبّر الحجم: --qr-size 0.20

---

🤝 المساهمة

المساهمات مرحب بها! يمكنك:

1. عمل Fork للمشروع
2. إنشاء Branch جديد (git checkout -b feature/amazing-feature)
3. Commit التغييرات (git commit -m 'Add amazing feature')
4. Push إلى Branch (git push origin feature/amazing-feature)
5. فتح Pull Request

---

📄 الرخصة

هذا المشروع مرخص تحت MIT License.

---

صُنع بـ ❤️ بواسطة 0s-a