# OCR Servlet Setup

1. Download the latest Tesseract data models for English, Maori and OSD and place them into a directory of your choosing.

    - [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
    > sudo /etc/init.d/apache2 reload
    
    // ADD THE FOLLOWING
    ProxyPass /gs3-atea-ocr http://localhost:8383/gs3-atea-ocr
    ProxyPassReverse /gs3-atea-ocr http://localhost:8383/gs3-atea-ocr
    ```

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
    },
    ...
}
```

### Response Fields

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.

#### Example Response

```json
[
    {
       "key": "0test.png",
       "fileName": "test.png",
       "text": "Te Kāwanatanga o Aotearoa\n",
       "thresholdedImageKey": "7e383d85-4a4c-481d-83bf-c5e384512399.webp"
    },
    ...
]
```

## Image Retrieval

- 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.

### Expected Request Parameters

Name | Type | Optional | Description
--|--|--|--
`key` | `string` | No | The key of the image to retrieve.