Class: ActiveStorage::Ocr::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/activestorage/ocr/client.rb

Overview

HTTP client for communicating with the OCR server.

The Client handles all communication with the Rust OCR server, including file uploads and response parsing.

Basic Usage

client = ActiveStorage::Ocr::Client.new

# Extract text from an Active Storage blob
result = client.extract_text(document.file)

# Extract text from a file path
result = client.extract_text_from_path("/path/to/image.png")

# Use a specific OCR engine
result = client.extract_text(document.file, engine: :leptess)

# Compare results from both engines
comparison = client.compare(document.file)

# Check server health
client.healthy?  # => true

Instance Method Summary collapse

Constructor Details

#initialize(config: ActiveStorage::Ocr.configuration) ⇒ Client

Creates a new Client.

Parameters

  • config - Configuration object (defaults to global configuration)


35
36
37
 
# File 'lib/activestorage/ocr/client.rb', line 35

def initialize(config: ActiveStorage::Ocr.configuration)
  @config = config
end

Instance Method Details

#compare(blob) ⇒ Object

Compares OCR results from both engines.

Runs OCR on the same file using both ocrs and leptess engines, allowing you to compare accuracy and performance.

Parameters

  • blob - An ActiveStorage::Blob instance

Returns

A Hash with :ocrs and :leptess keys, each containing a Result object.

Raises

  • ConnectionError - if the server is unreachable
  • ServerError - if the server returns an error


150
151
152
153
154
155
156
157
158
 
# File 'lib/activestorage/ocr/client.rb', line 150

def compare(blob)
  ocrs_result = extract_text(blob, engine: :ocrs)
  leptess_result = extract_text(blob, engine: :leptess)

  {
    ocrs: ocrs_result,
    leptess: leptess_result
  }
end

#compare_from_path(path, content_type: nil, filename: nil) ⇒ Object

Compares OCR results from both engines using a file path.

Parameters

  • path - Path to the file
  • content_type - MIME type (auto-detected if not provided)
  • filename - Filename to send (defaults to basename of path)

Returns

A Hash with :ocrs and :leptess keys, each containing a Result object.



171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/activestorage/ocr/client.rb', line 171

def compare_from_path(path, content_type: nil, filename: nil)
  content_type ||= Marcel::MimeType.for(Pathname.new(path))
  filename ||= File.basename(path)

  ocrs_result = extract_text_from_path(path, content_type: content_type, filename: filename, engine: :ocrs)
  leptess_result = extract_text_from_path(path, content_type: content_type, filename: filename, engine: :leptess)

  {
    ocrs: ocrs_result,
    leptess: leptess_result
  }
end

#extract_text(blob, engine: nil, preprocess: nil) ⇒ Object

Extracts text from an Active Storage blob.

Opens the blob temporarily and sends it to the OCR server.

Parameters

  • blob - An ActiveStorage::Blob instance
  • engine - OCR engine to use (:ocrs or :leptess). Defaults to configured engine.
  • preprocess - Preprocessing preset (:none, :minimal, :default, :aggressive). Defaults to configured preset.

Returns

A Result object with extracted text and metadata.

Raises

  • ConnectionError - if the server is unreachable
  • ServerError - if the server returns an error


58
59
60
61
62
 
# File 'lib/activestorage/ocr/client.rb', line 58

def extract_text(blob, engine: nil, preprocess: nil)
  blob.open do |file|
    extract_text_from_file(file, blob.content_type, blob.filename.to_s, engine: engine, preprocess: preprocess)
  end
end

#extract_text_from_file(file, content_type, filename, engine: nil, preprocess: nil) ⇒ Object

Extracts text from an IO object.

This is the low-level method that performs the actual HTTP request.

Parameters

  • file - An IO object (File, StringIO, etc.)
  • content_type - MIME type of the file
  • filename - Filename to send to the server
  • engine - OCR engine to use (:ocrs or :leptess). Defaults to configured engine.
  • preprocess - Preprocessing preset (:none, :minimal, :default, :aggressive). Defaults to configured preset.

Returns

A Result object with extracted text and metadata.

Raises

  • ConnectionError - if the server is unreachable
  • ServerError - if the server returns an error


113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/activestorage/ocr/client.rb', line 113

def extract_text_from_file(file, content_type, filename, engine: nil, preprocess: nil)
  target_engine = engine || @config.engine
  target_preprocess = preprocess || @config.preprocess
  endpoint = ocr_endpoint_for(target_engine, target_preprocess)

  response = connection.post(endpoint) do |req|
    req.body = {
      file: Faraday::Multipart::FilePart.new(
        file,
        content_type,
        filename
      )
    }
  end

  handle_response(response)
rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
  raise ConnectionError, "Failed to connect to OCR server: #{e.message}"
end

#extract_text_from_path(path, content_type: nil, filename: nil, engine: nil, preprocess: nil) ⇒ Object

Extracts text from a file path.

Parameters

  • path - Path to the file
  • content_type - MIME type (auto-detected if not provided)
  • filename - Filename to send (defaults to basename of path)
  • engine - OCR engine to use (:ocrs or :leptess). Defaults to configured engine.
  • preprocess - Preprocessing preset (:none, :minimal, :default, :aggressive). Defaults to configured preset.

Returns

A Result object with extracted text and metadata.

Raises

  • ConnectionError - if the server is unreachable
  • ServerError - if the server returns an error


83
84
85
86
87
88
89
90
 
# File 'lib/activestorage/ocr/client.rb', line 83

def extract_text_from_path(path, content_type: nil, filename: nil, engine: nil, preprocess: nil)
  content_type ||= Marcel::MimeType.for(Pathname.new(path))
  filename ||= File.basename(path)

  File.open(path, "rb") do |file|
    extract_text_from_file(file, content_type, filename, engine: engine, preprocess: preprocess)
  end
end

#healthy? ⇒ Boolean

Checks if the OCR server is healthy.

Returns

true if the server responds with status "ok", false otherwise.

Returns:

  • (Boolean) 


189
190
191
192
193
194
 
# File 'lib/activestorage/ocr/client.rb', line 189

def healthy?
  response = connection.get("/health")
  response.success? && JSON.parse(response.body)["status"] == "ok"
rescue StandardError
  false
end

#server_info ⇒ Object

Gets information about the OCR server.

Returns

A Hash with server information including:

  • :version - Server version
  • :supported_formats - Array of supported MIME types

Raises

  • ConnectionError - if the server is unreachable


207
208
209
210
211
212
 
# File 'lib/activestorage/ocr/client.rb', line 207

def server_info
  response = connection.get("/info")
  JSON.parse(response.body, symbolize_names: true)
rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
  raise ConnectionError, "Failed to connect to OCR server: #{e.message}"
end