Changeset 35783

Timestamp:

2021-12-09T15:05:51+13:00 (2 years ago)

Author:

cstephen

Message:

Update README

Location:

gs3-extensions/atea-nlp-tools/trunk/src/ocr

Files:

• README.md (modified) (1 diff)
• src/main/java/org/atea/nlptools/ocr/services/TesseractOcrService.java (modified) (1 diff)

gs3-extensions/atea-nlp-tools/trunk/src/ocr/README.md

@@ -1 @@
-# Installation
+# OCR Servlet Setup
 
-Find the path to your tesseract binaries directory, then run
+1. Download the latest Tesseract data models for English, Maori and OSD and place them into a directory of your choosing.
 
-```
-./setup.sh
+    - [English](https://github.com/tesseract-ocr/tessdata_fast/raw/main/eng.traineddata)
+    - [Maori](https://github.com/tesseract-ocr/tessdata_fast/raw/main/mri.traineddata)
+    - [OSD](https://github.com/tesseract-ocr/tessdata_fast/raw/main/osd.traineddata)
+
+    Then, run the setup script, providing the path to this directory. You MUST NOT move or delete this directory without re-running the setup script and re-compiling the project.
+
+    ```sh
+    > ./setup.sh
+    ```
+
+2. Edit the HTML content of the `unauthorised` page so that the button redirects to your preferred location.
+
+    ```sh
+    nano src/main/webapp/webContent/unauthorised.html
+    ```
+
+3. Compile and install the WAR file.
+
+    ```sh
+    > ant install
+    ```
+
+4. Update the apache2 config with the relevant `ProxyPass` rules
+
+    ```sh
+    > sudo nano /etc/apache2/sites-enabled/000-default-le-ssl.conf
+    > sudo nano /etc/apache2/sites-enabled/000-default.conf
+    
+    ProxyPass /gs3-koreromaori http://localhost:8383/gs3-macroniser
+    ProxyPassReverse /gs3-koreromaori http://localhost:8383/gs3-macroniser
+    ```
+
+5. If `403 Forbidden` errors are observed when consuming the API, update the CORS filter in `web.xml` to include your root domains, and re-install.
+
+    ```sh
+    > nano src/main/webapp/WEB-INF/web.xml
+
+    <filter>
+        <filter-name>CorsFilter</filter-name>
+        <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
+        <init-param>
+            <param-name>cors.allowed.origins</param-name>
+            -- <param-value>http://localhost:8080</param-value> <!-- Separate values by a comma -->
+            ++ <param-value>http://localhost:8080,http://atea.space,https://atea.space</param-value>
+        </init-param>
+    </filter>
+    ```
+
+# Consuming the API
+
+## OCR Endpoint
+
+- Endpoint: `/tesseract`
+- Method: `POST`
+- Request Content Type: `multipart/form-data`
+- Response Content Type: `application/json`
+
+The `tesseract` endpoint runs the Tesseract OCR engine on the provided images, and returns the results.
+
+### Expected Form Parts
+
+Name | Type | Optional | Description
+--|--|--|--
+`options` | `OptionMap` | Yes | The options to use when macronising each file.
+Image file parts | `blob` | At least one. | The images to perform OCR on.
+
+#### `OptionMap` Object
+
+A map of options for each submitted file. The option key should match the name of the corresponding file part in the request.
+
+- `layoutDetection`: A value indicating whether or not Tesseract should attempt to automatically detect the layout of the image. 
+
+```json
+{
+    "key1": {
+        "layoutDetection": true
+    },
+    ...
+}
 ```
 
-# Now edit:
+### Response Fields
 
-  src/main/webapp/webContent/unauthorizsed.html
+Name | Type | Optional | Description
+--|--|--|--
+`key` | `string` | No | The unique key of the image that this result was produced from. Matches the name of the file part in the request.
+`fileName` | `string` | No | The name of the file that this result was produced from.
+`text` | `string` | No | The extracted text.
+`thresholdedImageKey` | `string` | No | A key that can be used with the `image` endpoint to retrieve the 'thresholded image', which is the final stage of Tesseract's internal image processing before it runs the OCR algorithm.
 
-so the button displays the name Atea, and points to the https://atea.space website
+#### Example Response
 
+```json
+[
+    {
+       "key": "0test.png",
+       "fileName": "test.png",
+       "text": "Te Kāwanatanga o Aotearoa\n",
+       "thresholdedImageKey": "7e383d85-4a4c-481d-83bf-c5e384512399.webp"
+    },
+    ...
+]
+```
 
-# Compile up and install the war file
+## Image Retrieval
 
-  ant install
+- Endpoint: `/image`
+- Method: `GET`
+- Response Content Type: `image/webp`
 
+The `image` endpoint can be used to retrieve images associated with the OCR process that occurs when calling other endpoints. It returns images in the `webp` format.
 
-# Now update apache2 config with ProxyPass rules
+### Expected Request Parameters
 
- sudo emacs /etc/apache2/sites-enabled/000-default-le-ssl.conf
-
-   ProxyPass /gs3-atea-ocr http://localhost:8383/gs3-atea-ocr
-   ProxyPassReverse /gs3-atea-ocr http://localhost:8383/gs3-atea-ocr
-
-#Same for the http version:
-
- sudo emacs /etc/apache2/sites-enabled/000-default.conf
+Name | Type | Optional | Description
+--|--|--|--
+`key` | `string` | No | The key of the image to retrieve.

gs3-extensions/atea-nlp-tools/trunk/src/ocr/src/main/java/org/atea/nlptools/ocr/services/TesseractOcrService.java

@@ -71 +71 @@
             File thresholdOutput = new File(this.thresholdOutputPath, fileName);
             thresholdedImage = api.GetThresholdedImage();
-            // lept.pixWriteWebP("temp", thresholdedImage, 75, 100);
             lept.pixWrite(thresholdOutput.getAbsolutePath(), thresholdedImage, lept.IFF_WEBP);