تحويل (Tahweel)

تحويل ملفات PDF والصور إلى نصوص باستخدام التعرف الضوئي من Google Drive

المميزات • التثبيت • المتطلبات • المصادقة • الاستخدام • واجهة البرمجة • المساهمة

🌐 English

---

تحويل (بالإنجليزية: Tahweel، وتعني "التحويل") هي أداة Ruby قوية لتحويل ملفات PDF والصور إلى نصوص قابلة للتحرير باستخدام تقنية التعرف الضوئي من Google Drive. تم تحسينها بشكل خاص للنصوص العربية، لكنها تعمل بامتياز مع جميع اللغات التي يدعمها محرك Google.

المميزات

• 🔤 تعرف ضوئي عالي الجودة — يستخدم محرك Google Drive القوي لاستخراج النصوص بدقة
• 📄 صيغ إدخال متعددة — يدعم ملفات PDF و JPG و JPEG و PNG
• 📝 صيغ إخراج متعددة — تصدير إلى TXT أو DOCX أو JSON
• 🌐 دعم النصوص العربية — اكتشاف تلقائي لاتجاه النص من اليمين لليسار
• ⚡ معالجة متزامنة — معالجة متعددة الخيوط على مستوى الملفات والصفحات
• 📊 تتبع التقدم اللحظي — واجهة طرفية جميلة مع تتبع التقدم لكل خيط
• 🖥️ واجهة رسومية — واجهة سطح مكتب عبر المنصات بالعربية والإنجليزية
• 🔄 تخطي ذكي — يتخطى الملفات تلقائياً عندما يكون الإخراج موجوداً
• 📁 الحفاظ على هيكل المجلدات — يحافظ على التسلسل الهرمي للمجلدات في الإخراج
• 🛡️ معالجة أخطاء قوية — إعادة المحاولة بتأخير تصاعدي لحدود واجهة البرمجة

التثبيت

من RubyGems

gem install tahweel

باستخدام Bundler

أضف هذا السطر إلى ملف Gemfile الخاص بتطبيقك:

gem 'tahweel'

ثم نفّذ:

bundle install

من المصدر

git clone https://github.com/ieasybooks/tahweel.rb.git
cd tahweel.rb
bundle install

المتطلبات

إصدار Ruby

يتطلب تحويل Ruby 3.2.0 أو أحدث.

أدوات Poppler

يستخدم تحويل أدوات Poppler (pdftoppm و pdfinfo) لتقسيم ملفات PDF إلى صور.

macOS:

brew install poppler

Ubuntu/Debian:

sudo apt install poppler-utils

Windows:

يقوم تحويل بتنزيل وتثبيت Poppler تلقائياً على Windows عند التشغيل لأول مرة.

حساب Google

ستحتاج إلى حساب Google للمصادقة مع خدمة التعرف الضوئي في Google Drive. في أول تشغيل لتحويل، سيفتح نافذة متصفح للمصادقة عبر OAuth.

المصادقة

يستخدم تحويل OAuth 2.0 للمصادقة مع Google Drive. عند التشغيل لأول مرة:

1. ستفتح نافذة متصفح تلقائياً
2. سجّل الدخول بحسابك في Google
3. امنح تحويل صلاحية إنشاء وإدارة الملفات في Google Drive الخاص بك
4. بعد المصادقة، سترى صفحة نجاح ويمكنك إغلاق المتصفح

ملاحظة: يقوم تحويل فقط بإنشاء ملفات مؤقتة لمعالجة التعرف الضوئي ويحذفها فوراً بعد الاستخراج. يستخدم نطاق drive.file الذي يسمح فقط بالوصول إلى الملفات التي أنشأها التطبيق.

يتم تخزين بيانات الاعتماد بشكل آمن في:

• Linux/macOS: ~/.cache/tahweel/token.yaml
• Windows: %LOCALAPPDATA%\tahweel\token.yaml

مسح بيانات الاعتماد

لإزالة بيانات الاعتماد المخزنة وإعادة المصادقة:

tahweel-clear

الاستخدام

واجهة سطر الأوامر

الاستخدام الأساسي

تحويل ملف PDF واحد:

tahweel document.pdf

تحويل جميع ملفات PDF في مجلد:

tahweel /path/to/documents/

صيغ الإخراج

تحديد صيغ الإخراج (الافتراضي: txt,docx):

# Text only
tahweel document.pdf -f txt

# DOCX only
tahweel document.pdf -f docx

# JSON only
tahweel document.pdf -f json

# Multiple formats
tahweel document.pdf -f txt,docx,json

مجلد إخراج مخصص

tahweel document.pdf -o /path/to/output/

التصفية حسب امتدادات الملفات

# Process only PDF files
tahweel /path/to/documents/ -e pdf

# Process only images
tahweel /path/to/documents/ -e jpg,jpeg,png

إعدادات التزامن

# Process 4 files concurrently
tahweel /path/to/documents/ -F 4

# Use 8 concurrent OCR operations per file
tahweel /path/to/documents/ -O 8

إعدادات DPI

DPI أعلى ينتج جودة أفضل لكن معالجة أبطأ:

tahweel document.pdf --dpi 300

فاصل صفحات مخصص (إخراج TXT)

tahweel document.pdf --page-separator "\\n---PAGE BREAK---\\n"

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

الخيار	المختصر	الوصف	الافتراضي
--extensions	-e	امتدادات الملفات للمعالجة	pdf,jpg,jpeg,png
--dpi		DPI لتحويل PDF إلى صورة	150
--processor	-p	معالج OCR المستخدم	google_drive
--file-concurrency	-F	أقصى عدد ملفات للمعالجة المتزامنة	المعالجات - 2
--ocr-concurrency	-O	أقصى عمليات OCR متزامنة	12
--formats	-f	صيغ الإخراج (مفصولة بفواصل)	txt,docx
--page-separator		فاصل الصفحات لإخراج TXT	\n\nPAGE_SEPARATOR\n\n
--output	-o	مجلد الإخراج	مجلد ملف الإدخال
--version	-v	عرض الإصدار

الواجهة الرسومية

لتشغيل واجهة سطح المكتب:

tahweel-ui

توفر الواجهة الرسومية:

• تحويل ملف واحد أو مجلد كامل
• واجهة بالعربية والإنجليزية
• تتبع التقدم للمستوى العام ولكل ملف
• فتح مجلد الإخراج تلقائياً عند الانتهاء

عرض التقدم

تعرض واجهة سطر الأوامر لوحة تقدم لحظية:

Total Progress: [3/10] 30.0% | Time: 45s
 [Worker 1] document1.pdf | Ocr        | 75.0% (6/8)
 [Worker 2] document2.pdf | Splitting  | 50.0% (5/10)
 [Worker 3] Idle
 [Worker 4] document4.pdf | Ocr        | 25.0% (2/8)

صيغ الإخراج

TXT (نص عادي)

إخراج نصي بسيط مع فواصل صفحات قابلة للتخصيص:

محتوى الصفحة 1 هنا...

PAGE_SEPARATOR

محتوى الصفحة 2 هنا...

DOCX (Microsoft Word)

مستندات Word منسقة مع:

• صفحة محتوى واحدة لكل صفحة مستند
• اتجاه نص تلقائي (RTL للعربية، LTR لغيرها)
• فواصل أسطر متوافقة مع جميع المنصات
• دمج ذكي للأسطر لقراءة أفضل

JSON (بيانات منظمة)

إخراج منظم صفحة بصفحة:

[
  {
    "page": 1,
    "content": "محتوى الصفحة 1 هنا..."
  },
  {
    "page": 2,
    "content": "محتوى الصفحة 2 هنا..."
  }
]

واجهة البرمجة

تحويل ملفات PDF

require 'tahweel'

# Convert a PDF to text (returns array of page texts)
pages = Tahweel.convert('document.pdf')

# With options
pages = Tahweel.convert(
  'document.pdf',
  dpi: 300,              # Higher quality
  processor: :google_drive,
  concurrency: 8
)

# With progress tracking
pages = Tahweel.convert('document.pdf') do |progress|
  puts "Stage: #{progress[:stage]}"
  puts "Progress: #{progress[:percentage]}%"
  puts "Current page: #{progress[:current_page]}"
end

استخراج النص من الصور

require 'tahweel'

# Extract text from a single image
text = Tahweel.extract('image.png')
text = Tahweel.extract('photo.jpg', processor: :google_drive)

كتابة ملفات الإخراج

require 'tahweel'

pages = Tahweel.convert('document.pdf')

# Write to multiple formats
Tahweel::Writer.write(pages, 'output', formats: [:txt, :docx, :json])

# Write to a single format with options
Tahweel::Writer.write(
  pages,
  'output',
  formats: [:txt],
  page_separator: "\n---\n"
)

خط معالجة كامل

require 'tahweel'

# Using the CLI FileProcessor for complete workflow
Tahweel::CLI::FileProcessor.process('document.pdf', {
  dpi: 150,
  processor: :google_drive,
  ocr_concurrency: 12,
  formats: [:txt, :docx],
  output: '/path/to/output'
}) do |progress|
  puts "#{progress[:stage]}: #{progress[:percentage]}%"
end

جمع الملفات من مجلد

require 'tahweel'

# Get all supported files in a directory
files = Tahweel::CLI::FileCollector.collect('/path/to/documents/')

# Filter by specific extensions
files = Tahweel::CLI::FileCollector.collect(
  '/path/to/documents/',
  extensions: ['pdf']
)

أمثلة

تحويل دفعي للكتب العربية

# Convert all PDFs in an Arabic books directory with high quality
tahweel ~/arabic-books/ -f txt,docx --dpi 200 -o ~/converted-books/

معالجة المستندات الممسوحة ضوئياً

# Convert scanned images to searchable text
tahweel ~/scanned-docs/ -e jpg,png -f txt -o ~/ocr-output/

التكامل مع المكتبة

require 'tahweel'

# Convert and process in your application
def process_document(pdf_path)
  pages = Tahweel.convert(pdf_path) do |progress|
    update_progress_bar(progress[:percentage])
  end

  # Process the extracted text
  full_text = pages.join("\n\n")
  word_count = full_text.split.size

  {
    pages: pages.size,
    words: word_count,
    text: full_text
  }
end

استكشاف الأخطاء وإصلاحها

حدود واصفات الملفات

إذا واجهت أخطاء اتصال أو تجمد مع دفعات كبيرة:

ulimit -n 4096

تحديد المعدل

يتعامل تحويل تلقائياً مع حدود معدل Google API بتأخير تصاعدي. إذا استمرت المشاكل، جرّب تقليل التزامن:

tahweel documents/ -F 2 -O 6

Poppler غير موجود

تأكد من تثبيت Poppler وأنه في مسار PATH:

which pdftoppm  # Should return a path

المساهمة

تقارير الأخطاء وطلبات السحب مرحب بها على GitHub في https://github.com/ieasybooks/tahweel.rb.

1. انسخ المستودع (Fork)
2. أنشئ فرع الميزة (git checkout -b feature/amazing-feature)
3. ثبّت تغييراتك (git commit -am 'Add amazing feature')
4. ادفع إلى الفرع (git push origin feature/amazing-feature)
5. افتح طلب سحب (Pull Request)

التطوير

بعد استنساخ المستودع:

bin/setup          # Install dependencies
rake spec          # Run tests
bin/console        # Interactive prompt

الرخصة

هذه الأداة متاحة كمصدر مفتوح بموجب شروط رخصة MIT.

قواعد السلوك

يُتوقع من جميع المتفاعلين في مشروع تحويل اتباع قواعد السلوك.

---

صُنع بـ ❤️ بواسطة iEasyBooks