تحويل (Tahweel)

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

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

🌐 English

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

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

gem install tahweel

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

gem 'tahweel'

ثم نفّذ:

bundle install

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

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

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

macOS:

brew install poppler

Ubuntu/Debian:

sudo apt install poppler-utils

Windows:

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

ستحتاج إلى حساب 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 أعلى ينتج جودة أفضل لكن معالجة أبطأ:

tahweel document.pdf --dpi 300

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

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

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)

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

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

PAGE_SEPARATOR

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

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

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

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

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

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 وأنه في مسار 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