Add OCR processing integration and module scanner routes

- Implemented `get_ocr_result` method in the `ocr_space` class to interact with the OCR Space API.
- Added `process_ocr` method to `image_processor_t` for handling OCR logic.
- Updated interfaces (`ocr_space_i` and `image_processor_i`) to support OCR functionality.
- Introduced `moduleScannerRoute` with endpoints for testing and license plate recognition workflows.
- Included data validation and exception handling for OCR processing.

services/nginx/app/classes/ocr_space.php

@@ -14,6 +14,11 @@ class ocr_space implements ocr_space_i
      * @var ocrSpace_c
      */
     public ocrSpace_c $config;
+    /**
+     * API URL
+     * @var string
+     */
+    private string $api_url = 'https://api.ocr.space/parse/image';
 
 
     public function __construct()
@@ -31,4 +36,53 @@ class ocr_space implements ocr_space_i
             throw new Exception('OCR Space module is not enabled.');
         }
     }
+
+
+    /**
+     * @inheritDoc
+     * @throws Exception If the module is not enabled or if there is an error in the API request
+     * @throws Exception If the API response cannot be parsed
+     */
+    public function get_ocr_result(string $base64_image): array
+    {
+        $this->requireModuleEnabled();
+        if (empty($base64_image)) {
+            throw new Exception('Base64 image string cannot be empty.');
+        }
+
+        $formData = [
+            'base64Image' => $base64_image,
+            'isOverlayRequired' => 'true',
+            'scale' => 'true',
+            'detectOrientation' => 'true',
+            'language' => 'eng',
+            'OCREngine' => '2'
+        ];
+
+        $options = [
+            'http' => [
+                'method' => 'POST',
+                'header' => [
+                    'apikey: ' . $this->config->api_key->getVariableValue(),
+                    'Content-Type: application/x-www-form-urlencoded'
+                ],
+                'content' => http_build_query($formData)
+            ]
+        ];
+
+        $context = stream_context_create($options);
+        $result = file_get_contents($this->api_url, false, $context);
+
+        if ($result === false) {
+            throw new Exception('Failed to get OCR result from API.');
+        }
+
+        $response = json_decode($result, true);
+
+        if (json_last_error() !== JSON_ERROR_NONE) {
+            throw new Exception('Failed to parse OCR API response.');
+        }
+
+        return $response;
+    }
 }

services/nginx/app/interfaces/image_processor_i.php

@@ -35,4 +35,14 @@ interface image_processor_i
      * @throws RuntimeException If the image format cannot be determined.
      */
     public function get_image_format(): string;
+    /**
+     * Process the image with ocrSpace.
+     * @return array An associative array containing the OCR results.
+     * @throws RuntimeException If the OCR processing fails.
+     * @throws InvalidArgumentException If the image is not set or is invalid.
+     * @throws Exception If there is a general error during OCR processing.
+     * @note This method is abstract and must be implemented by the class that implements this interface.
+     */
+    public function process_ocr(): array;
+
 }

services/nginx/app/interfaces/ocr_space_i.php

@@ -4,5 +4,16 @@ namespace interfaces;
 
 interface ocr_space_i extends universal_module_i
 {
-
+    /**
+     * Get the OCR result from the OCR Space API.
+     * @param string $base64_image The base64 encoded image to be processed.
+     */
+    public function get_ocr_result(string $base64_image): array;
+    /**
+     * Cache the OCR result. (for 24 hours)
+     * @param string $base64_image The base64 encoded image to be cached.
+     * @param array $result The OCR result to be cached.
+     * @return bool True if caching was successful, false otherwise.
+     * @throws \Exception If there is an error during caching.
+     */
 }

services/nginx/app/routes/moduleScannerRoute.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace routes;
+
+use classes\authentication;
+use classes\image_processor;
+use classes\response;
+use classes\router;
+use objects\logs_o;
+use traits\route_t;
+
+class moduleScannerRoute
+{
+    use route_t;
+
+    public function run(): void
+    {
+        global /** @var response $response */
+        $router, $response;
+        /** Modules > Scanner > test > GET */
+        $this->get('/modules/scanner/test', function () {
+            global $response;
+            $base64_image = '';
+            //self::requirePermission('modules_scanner_test');
+            $image_processor = new image_processor();
+            $response->success('Scanner module test executed successfully.');
+        },
+            [
+                'modules_scanner_test' => 'Test the scanner module',
+            ]
+        );
+        /** Modules > Scanner > License Plate Recognition > POST */
+        $this->post('/modules/scanner/lpr', function () {
+            global $response;
+            self::requireParameters(['base64_image']);
+            $base64_image = self::getParameter('base64_image');
+            //self::requirePermission('modules_scanner_lpr');
+            if (empty($base64_image)) {
+                $response->error('Base64 image is required.');}
+            $image_processor = new image_processor();
+            $image_processor->set_image_base64($base64_image);
+            $response->success([
+                //'ocr' => $image_processor->process_ocr(),
+                'base64_image' => $base64_image
+            ]);
+        },
+            [
+                'modules_scanner_lpr' => 'License Plate Recognition',
+            ]
+        );
+    }
+}

services/nginx/app/traits/image_processor_t.php

@@ -3,6 +3,7 @@
 namespace traits;
 
 use classes\image_processor;
+use classes\ocr_space;
 
 trait image_processor_t
 {
@@ -85,5 +86,17 @@ trait image_processor_t
             throw new \RuntimeException("Invalid base64 image format.");
         }
     }
+    /**
+     * @inheritDoc
+     */
+    public function process_ocr(): array
+    {
+        if ($this->base64_image === null) {
+            throw new \RuntimeException("No base64 image string set for OCR processing.");
+        }
+        // Check if this exact image has already been processed
+        // Return the OCR result using the ocr_space class
+        return (new ocr_space())->get_ocr_result($this->base64_image);
+    }
 
 }