tahweel 0.1.1 → 0.1.3

data/bin/tahweel-ui

@@ -0,0 +1,300 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Add the ../lib directory to the load path so we can require 'tahweel'
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "matrix"
+require "glimmer-dsl-libui"
+require "launchy"
+require "tahweel"
+
+Tahweel::Authorizer.authorize unless defined?(Ocran)
+
+class TahweelApp # rubocop:disable Metrics/ClassLength,Style/Documentation
+  include Glimmer::LibUI::Application
+
+  TRANSLATIONS = {
+    # https://www.perplexity.ai/search/add-direction-unicode-controls-Z5haIOFEQZeCbG5B8Wt2dg#3
+    ar: {
+      window_title: "تحويل",
+      title_label: "‫تحويل: حوّل الملفات من صيغة ‪PDF‬ إلى ‪TXT‬ و ‪DOCX‬ ↓‬",
+      note_label: "‫ملاحظة: يدعم تحويل الملفات بصيغة ‪PDF‬ أو صورة (‪JPG‬ و ‪JPEG‬ و ‪PNG‬) فقط.‬",
+      file_btn: "تحويل ملف واحد",
+      folder_btn: "تحويل مجلد كامل",
+      language_btn: "English",
+      global_progress: "التقدم العام:",
+      file_progress: "تقدم الملف الحالي:",
+      status_done: "انتهى التحويل.",
+      msg_success_title: "اكتمل التحويل",
+      msg_error_title: "خطأ",
+      msg_no_files: "لم نعثر على ملفات لتحويلها.",
+      msg_bad_extension: "صيغة الملف غير مدعومة.",
+      stage_preparing: "جارٍ التحضير...",
+      stage_splitting: "جارٍ تقسيم الملف...",
+      stage_ocr: "جارٍ استخراج النصوص...",
+      stage_done: "انتهى"
+    },
+    en: {
+      window_title: "Tahweel",
+      title_label: "Tahweel: Convert PDF files to TXT and DOCX ↓",
+      note_label: "Note: Tahweel supports PDF or image files (JPG, JPEG, and PNG) only.",
+      file_btn: "Convert a Single File",
+      folder_btn: "Convert a Folder",
+      language_btn: "العربية",
+      global_progress: "Progress:",
+      file_progress: "Current File:",
+      status_done: "Conversion complete.",
+      msg_success_title: "Conversion Complete",
+      msg_error_title: "Error",
+      msg_no_files: "No files found to convert.",
+      msg_bad_extension: "Unsupported file format.",
+      stage_preparing: "Preparing...",
+      stage_splitting: "Splitting file...",
+      stage_ocr: "Extracting text...",
+      stage_done: "Done"
+    }
+  }.freeze
+
+  def initialize(*args)
+    @lang = :ar
+    @rtl_components = []
+    @ltr_components = []
+
+    super
+  end
+
+  body do
+    @main_window = window(t(:window_title)) do
+      margined true
+
+      vertical_box do
+        @header_label = right_aligned_label(t(:title_label))
+        convert_buttons
+        @note_label = right_aligned_label(t(:note_label))
+
+        @progress_section = progress_section
+        @progress_section.visible = false
+
+        horizontal_separator { stretchy false }
+
+        @language_btn = language_button
+      end
+    end
+  end
+
+  private
+
+  def language_button # rubocop:disable Metrics/MethodLength
+    ref = nil
+
+    horizontal_box do
+      stretchy false
+
+      right_alignment_label = label("") { stretchy true }
+      right_alignment_label.visible = false
+      @rtl_components << right_alignment_label
+
+      ref = button(t(:language_btn)) do
+        stretchy false
+        on_clicked { toggle_language }
+      end
+
+      left_alignment_label = label("") { stretchy true }
+      @ltr_components << left_alignment_label
+    end
+
+    ref
+  end
+
+  def convert_buttons
+    horizontal_box do
+      @ar_convert_folder_btn = button(t(:folder_btn, lang: :ar)) { on_clicked { on_folder_click } }
+      @rtl_components << @ar_convert_folder_btn
+
+      @convert_file_btn = button(t(:file_btn)) { on_clicked { on_file_click } }
+
+      @en_convert_folder_btn = button(t(:folder_btn, lang: :en)) { on_clicked { on_folder_click } }
+      @en_convert_folder_btn.visible = false
+      @rtl_components << @en_convert_folder_btn
+    end
+  end
+
+  def progress_section
+    group do
+      stretchy false
+
+      vertical_box do
+        @global_progress_label = right_aligned_label(t(:global_progress))
+        @global_progress = progress_bar { stretchy true }
+
+        @file_progress_label = right_aligned_label(t(:file_progress))
+        @file_progress = progress_bar { stretchy true }
+      end
+    end
+  end
+
+  def on_file_click
+    file = open_file
+    convert(File.dirname(file), [file]) if file && valid_file?(file)
+  end
+
+  def valid_file?(file)
+    return true if %w[.pdf .jpg .jpeg .png].include? File.extname(file).downcase
+
+    msg_box_error(t(:msg_error_title), t(:msg_bad_extension))
+    false
+  end
+
+  def on_folder_click
+    folder = open_folder
+    paths = collect_files(folder)
+    convert(folder, paths) if paths.any?
+  end
+
+  def collect_files(folder)
+    paths = folder ? Tahweel::CLI::FileCollector.collect(folder) : []
+    return paths if folder && paths.any?
+
+    msg_box_error(t(:msg_error_title), t(:msg_no_files))
+    []
+  end
+
+  def convert(folder, paths)
+    disable_window
+    @progress_section.visible = true
+
+    Thread.new do
+      paths.each_with_index { |path, index| process_path(path, index, paths.size) }
+      finish_conversion(folder, paths.size)
+    end
+  end
+
+  def disable_window
+    @convert_file_btn.enabled = false
+    @ar_convert_folder_btn.enabled = false
+    @en_convert_folder_btn.enabled = false
+    @language_btn.enabled = false
+  end
+
+  def process_path(path, index, total_files)
+    reset_file_progress(index, total_files)
+
+    Tahweel::CLI::FileProcessor.process(path, options(path)) { update_file_progress(_1) }
+  end
+
+  def reset_file_progress(index, total_files)
+    Glimmer::LibUI.queue_main do
+      @global_progress.value = ((index.to_f / total_files) * 100).to_i
+      @global_progress_label.text = "\u202B#{t(:global_progress)} (\u202A#{index}/#{total_files}\u202C)\u202C"
+      @file_progress.value = 0
+      @file_progress_label.text = "#{t(:file_progress)} #{t(:stage_preparing)}"
+    end
+  end
+
+  def options(path)
+    {
+      dpi: 150,
+      processor: :google_drive,
+      ocr_concurrency: Tahweel::Converter::DEFAULT_CONCURRENCY,
+      file_concurrency: 1,
+      formats: %i[txt docx],
+      base_input_path: File.directory?(path) ? path : File.dirname(path)
+    }
+  end
+
+  def update_file_progress(progress)
+    Glimmer::LibUI.queue_main do
+      @file_progress.value = progress[:percentage].to_i
+      @file_progress_label.text = "#{t(:file_progress)} (#{stage_text(progress[:stage])})"
+    end
+  end
+
+  def stage_text(stage)
+    case stage
+    when :splitting then t(:stage_splitting)
+    when :ocr       then t(:stage_ocr)
+    end
+  end
+
+  def finish_conversion(folder, total_files)
+    Glimmer::LibUI.queue_main do
+      @global_progress.value = 100
+      @file_progress.value = 100
+      @global_progress_label.text = "#{t(:global_progress)} (#{total_files}/#{total_files})"
+      @file_progress_label.text = "#{t(:file_progress)} (#{t(:stage_done)})"
+
+      enable_window
+      msg_box(t(:msg_success_title), convert_finished_message(total_files))
+    end
+
+    Launchy.open(folder)
+  end
+
+  def enable_window
+    @convert_file_btn.enabled = true
+    @ar_convert_folder_btn.enabled = true
+    @en_convert_folder_btn.enabled = true
+    @language_btn.enabled = true
+  end
+
+  def convert_finished_message(files_count)
+    if @lang == :en
+      "Finished converting #{files_count} file(s) successfully."
+    else
+      arabic_convert_finished_message(files_count)
+    end
+  end
+
+  def arabic_convert_finished_message(files_count)
+    return "انتهى تحويل ملف واحد بنجاح." if files_count == 1
+    return "انتهى تحويل ملفين بنجاح." if files_count == 2
+
+    last_two_digits = files_count % 100
+
+    suffix = case last_two_digits
+             when 0..2 then "ملف"
+             when 3..10 then "ملفات"
+             else "ملفًا"
+             end
+
+    "انتهى تحويل #{files_count} #{suffix} بنجاح."
+  end
+
+  def toggle_language # rubocop:disable Metrics/AbcSize
+    @lang = @lang == :ar ? :en : :ar
+
+    @main_window.title = t(:window_title)
+    @header_label.text = t(:title_label)
+    @note_label.text = t(:note_label)
+    @convert_file_btn.text = t(:file_btn)
+    @language_btn.text = t(:language_btn)
+
+    @global_progress_label.text = t(:global_progress)
+    @file_progress_label.text = t(:file_progress)
+
+    @rtl_components.each { _1.visible = !_1.visible }
+    @ltr_components.each { _1.visible = !_1.visible }
+  end
+
+  def t(key, lang: nil) = TRANSLATIONS[lang || @lang][key]
+
+  def right_aligned_label(text)
+    ref = nil
+
+    horizontal_box do
+      right_alignment_label = label("") { stretchy true }
+      @rtl_components << right_alignment_label
+
+      ref = label(text) { stretchy false }
+
+      left_alignment_label = label("") { stretchy true }
+      left_alignment_label.visible = false
+      @ltr_components << left_alignment_label
+    end
+
+    ref
+  end
+end
+
+TahweelApp.launch unless defined?(Ocran)

data/lib/tahweel/authorizer.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-require "google/apis/drive_v3"
-require "googleauth"
-require "googleauth/stores/file_token_store"
+require "fileutils"
 require "socket"
 require "uri"
+
+require "googleauth"
+require "googleauth/stores/file_token_store"
+require "google/apis/drive_v3"
 require "launchy"
-require "fileutils"
 require "xdg"
 
 module Tahweel
@@ -18,8 +19,8 @@ module Tahweel
   # 3. Initiating the OAuth 2.0 flow via a local web server if needed.
   # 4. Exchanging the authorization code for credentials and persisting them.
   class Authorizer
-    CLIENT_ID = "512416833080-hptj9s5r92pjmdgigrcugbp40ng9isvj.apps.googleusercontent.com"
-    CLIENT_SECRET = "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"
+    CLIENT_ID = "512416833080-808aqp20iith31t9rgtdmsgc53jp0sc2.apps.googleusercontent.com"
+    CLIENT_SECRET = "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"
 
     PORT = 3027
     REDIRECT_URI = "http://localhost:#{PORT}/".freeze
@@ -104,7 +105,16 @@ module Tahweel
     end
 
     # Opens the system default browser to the Google Authorization URL.
-    def open_browser_for_auth = Launchy.open(@authorizer.get_authorization_url(base_url: REDIRECT_URI))
+    def open_browser_for_auth
+      url = @authorizer.get_authorization_url(base_url: REDIRECT_URI)
+
+      if Gem.win_platform?
+        # https://github.com/copiousfreetime/launchy/issues/167
+        system("start \"\" \"#{url}\"")
+      else
+        Launchy.open(url)
+      end
+    end
 
     # Listens on the local server for the OAuth callback request.
     # Handles multiple incoming requests to filter out noise (like favicon.ico).

data/lib/tahweel/cli/file_processor.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "pathname"
 
 module Tahweel
@@ -17,7 +18,7 @@ module Tahweel
       # @option options [String] :output The directory to save output files (defaults to current directory).
       # @option options [Integer] :dpi DPI for PDF conversion (defaults to 150).
       # @option options [Symbol] :processor The OCR processor to use (e.g., :google_drive).
-      # @option options [Integer] :page_concurrency Max concurrent operations.
+      # @option options [Integer] :ocr_concurrency Max concurrent operations.
       # @option options [Array<Symbol>] :formats Output formats (e.g., [:txt, :docx]).
       # @option options [String] :page_separator Separator string for TXT output.
       # @option options [String] :base_input_path The base path used to determine relative output structure.
@@ -66,8 +67,11 @@ module Tahweel
 
       private
 
+      # Creates the output directory if it doesn't exist.
       def ensure_output_directory_exists = FileUtils.mkdir_p(output_directory)
 
+      # Checks if all requested output formats already exist.
+      # @return [Boolean] True if all output files exist.
       def all_outputs_exist?
         @options[:formats].all? do |format|
           extension = Tahweel::Writer.new(format: format).extension
@@ -75,22 +79,29 @@ module Tahweel
         end
       end
 
+      # Checks if the input file is a PDF.
+      # @return [Boolean]
       def pdf? = File.extname(@file_path).downcase == ".pdf"
 
+      # Handles PDF processing: splitting, OCR, and saving.
+      # @param &block [Proc] Progress callback.
       def process_pdf(&)
         texts = Tahweel.convert(
           @file_path,
           dpi: @options[:dpi],
           processor: @options[:processor],
-          concurrency: @options.fetch(:page_concurrency, Tahweel::Converter::DEFAULT_CONCURRENCY),
+          concurrency: @options.fetch(:ocr_concurrency, Tahweel::Converter::DEFAULT_CONCURRENCY),
           &
         )
 
         write_output(texts)
       end
 
+      # Handles single image processing.
       def process_image = write_output([Tahweel.extract(@file_path, processor: @options[:processor])])
 
+      # Writes the extracted text to all configured formats.
+      # @param texts [Array<String>] The list of extracted texts (per page).
       def write_output(texts)
         Tahweel::Writer.write(
           texts,
@@ -100,6 +111,7 @@ module Tahweel
         )
       end
 
+      # @return [String] The full path for output files without extension.
       def base_output_path = File.join(output_directory, File.basename(@file_path, ".*"))
 
       # Determines the output directory.

data/lib/tahweel/cli/options.rb

@@ -3,6 +3,13 @@
 require "etc"
 require "optparse"
 
+require_relative "../version"
+require_relative "../converter"
+require_relative "../ocr"
+require_relative "../writer"
+require_relative "../writers/txt"
+require_relative "file_collector"
+
 module Tahweel
   module CLI
     # Parses command-line arguments for the Tahweel CLI.
@@ -26,11 +33,13 @@ module Tahweel
         options
       end
 
+      # Returns the default configuration options.
+      # @return [Hash] Default options.
       def self.default_options
         {
           dpi: 150,
           processor: :google_drive,
-          page_concurrency: Tahweel::Converter::DEFAULT_CONCURRENCY,
+          ocr_concurrency: Tahweel::Converter::DEFAULT_CONCURRENCY,
           file_concurrency: (Etc.nprocessors - 2).clamp(2..),
           output: nil,
           formats: %i[txt docx],
@@ -38,6 +47,10 @@ module Tahweel
         }
       end
 
+      # Configures the OptionParser instance.
+      #
+      # @param opts [OptionParser] The parser instance.
+      # @param options [Hash] The options hash to populate.
       def self.configure_parser(opts, options) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
         opts.program_name = "tahweel"
         opts.version = Tahweel::VERSION
@@ -69,17 +82,17 @@ module Tahweel
         end
 
         opts.on(
-          "-P", "--page-concurrency PAGE_CONCURRENCY", POSITIVE_INTEGER,
-          "Max concurrent OCR operations (default: #{options[:page_concurrency]})"
+          "-F", "--file-concurrency FILE_CONCURRENCY", POSITIVE_INTEGER,
+          "Max concurrent files to process (default: CPUs - 2 = #{options[:file_concurrency]})"
         ) do |value|
-          options[:page_concurrency] = value
+          options[:file_concurrency] = value
         end
 
         opts.on(
-          "-F", "--file-concurrency FILE_CONCURRENCY", POSITIVE_INTEGER,
-          "Max concurrent files to process (default: CPUs - 2 = #{options[:file_concurrency]})"
+          "-O", "--ocr-concurrency OCR_CONCURRENCY", POSITIVE_INTEGER,
+          "Max concurrent OCR operations (default: #{options[:ocr_concurrency]})"
         ) do |value|
-          options[:file_concurrency] = value
+          options[:ocr_concurrency] = value
         end
 
         opts.on(
@@ -104,6 +117,10 @@ module Tahweel
         end
       end
 
+      # Validates that arguments were provided.
+      #
+      # @param args [Array<String>] The remaining arguments after parsing.
+      # @param parser [OptionParser] The parser instance for printing help.
       def self.validate_args!(args, parser)
         return unless args.empty?
 

data/lib/tahweel/cli/progress_renderer.rb

@@ -102,6 +102,7 @@ module Tahweel
 
       private
 
+      # Starts a background thread to refresh the display periodically.
       def start_ticker
         @ticker_thread = Thread.new do
           while @running
@@ -111,6 +112,7 @@ module Tahweel
         end
       end
 
+      # Renders the progress dashboard to stdout.
       def render # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         # Move cursor up to the start of our block
         $stdout.print "\e[#{@concurrency + 1}A"
@@ -138,6 +140,11 @@ module Tahweel
         $stdout.flush
       end
 
+      # Truncates a file path to fit within the display.
+      #
+      # @param path [String] The file path.
+      # @param max_length [Integer] Maximum allowed length.
+      # @return [String] The truncated path.
       def truncate_path(path, max_length)
         return path.ljust(max_length) if path.length <= max_length
 

data/lib/tahweel/converter.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
+require "fileutils"
+
 require_relative "pdf_splitter"
 require_relative "ocr"
-require "fileutils"
 
 module Tahweel
   # Orchestrates the full conversion process:
@@ -60,10 +61,10 @@ module Tahweel
     # }
     # @return [Array<String>] An array containing the text of each page.
     def convert(&)
-      image_paths, temp_dir = PdfSplitter.split(@pdf_path, dpi: @dpi, &).values_at(:image_paths, :folder_path)
+      images_paths, temp_dir = PdfSplitter.split(@pdf_path, dpi: @dpi, &).values_at(:images_paths, :folder_path)
 
       begin
-        process_images(image_paths, Ocr.new(processor: @processor_type), &)
+        process_images(images_paths, Ocr.new(processor: @processor_type), &)
       ensure
         FileUtils.rm_rf(temp_dir)
       end
@@ -71,31 +72,55 @@ module Tahweel
 
     private
 
-    def process_images(image_paths, ocr_engine, &)
-      texts = Array.new(image_paths.size)
+    # Processes the list of images concurrently using the specified OCR engine.
+    #
+    # @param images_paths [Array<String>] List of paths to the image files.
+    # @param ocr_engine [Tahweel::Ocr] The initialized OCR engine instance.
+    # @param &block [Proc] Block to yield progress updates.
+    # @return [Array<String>] The text extracted from the images.
+    def process_images(images_paths, ocr_engine, &)
+      texts = Array.new(images_paths.size)
       mutex = Mutex.new
       processed_count = 0
 
-      run_workers(build_queue(image_paths), ocr_engine, texts, mutex) do
+      run_workers(build_queue(images_paths), ocr_engine, texts, mutex) do
         processed_count += 1
-        report_progress(processed_count, image_paths.size, &)
+        report_progress(processed_count, images_paths.size, &)
       end
 
       texts
     end
 
-    def build_queue(image_paths)
+    # Builds a queue of images paths and their indices.
+    #
+    # @param images_paths [Array<String>] List of image paths.
+    # @return [Queue] A queue containing [path, index] tuples.
+    def build_queue(images_paths)
       queue = Queue.new
-      image_paths.each_with_index { |path, index| queue << [path, index] }
+      images_paths.each_with_index { |path, index| queue << [path, index] }
       queue
     end
 
+    # Spawns worker threads to process items from the queue.
+    #
+    # @param queue [Queue] The queue of images to process.
+    # @param ocr_engine [Tahweel::Ocr] The OCR engine.
+    # @param texts [Array<String>] Shared array to store results.
+    # @param mutex [Mutex] Mutex for thread-safe updates.
+    # @param &block [Proc] Block to yield progress updates.
     def run_workers(queue, ocr_engine, texts, mutex, &)
       Array.new(@concurrency) do
         Thread.new { process_queue_items(queue, ocr_engine, texts, mutex, &) }
       end.each(&:join)
     end
 
+    # Processing loop for a single worker thread.
+    #
+    # @param queue [Queue] The shared queue.
+    # @param ocr_engine [Tahweel::Ocr] The OCR engine.
+    # @param texts [Array<String>] Shared result array.
+    # @param mutex [Mutex] Synchronization primitive.
+    # @param &block [Proc] Block to yield progress updates.
     def process_queue_items(queue, ocr_engine, texts, mutex, &)
       loop do
         begin
@@ -109,6 +134,13 @@ module Tahweel
       end
     end
 
+    # Thread-safe saving of OCR results.
+    #
+    # @param texts [Array<String>] The results array.
+    # @param index [Integer] Index of the current page.
+    # @param text [String] Extracted text.
+    # @param mutex [Mutex] Synchronization primitive.
+    # @yield Executes the progress reporting block within the lock.
     def save_result(texts, index, text, mutex)
       mutex.synchronize do
         texts[index] = text
@@ -116,6 +148,11 @@ module Tahweel
       end
     end
 
+    # Reports progress to the optional block.
+    #
+    # @param processed [Integer] Number of pages processed.
+    # @param total [Integer] Total number of pages.
+    # @yield [Hash] Progress information.
     def report_progress(processed, total)
       return unless block_given?