Torch API

Usage

Example usage:

import torchapi

request =
  """
  {
    "request": "banknote",
    "image": "data:image/png;base64,iVBORw0KGg..."
  }
  """
response = torchapi.handle(request)
print(response)

Example output:

{
  "status": "ok",
  "time": "2020-02-25 19:50:53.833346",
  "response": 100,
  "confidence": 0.78
}

Contract

Request

{
  "request": "<REQUEST>",
  "image": "<IMAGE_BASE64>"
}

"<IMAGE_BASE64>" is a base-64 encoding of the image that will be analyzed. The image must be 224px by 224px and contain RGB channels.

The contents of the base-64 string must adhere to the following regex:

^data:image(/(.*))?;base64,(.+)$

Response

{
  "status": "<STATUS>",
  "time": "<SERVER_TIME>",
  "response": "<RESPONSE>",
  "confidence": "<CONFIDENCE>"
}

confidence is a number between 0 and 1 that indicates the level of confidence in the prediction.

Valid values

When the server returns a valid response, the "status" is set to "ok".

Services

Service	Request	Response
Banknote detection	banknote	5 | 10 | 20 | 50 | 100 | 200 | bg
Optical character recognition	ocr	'Lorem ipsum dolor'

Errors

In the case of error, the response is sent as follows:

{
  "status": "error",
  "time": "<SERVER_TIME>",
  "error_origin": "<ERROR_ORIGIN>",
  "error_message": "<ERROR_MESSAGE>"
}

Some of the errors and their meaning:

Error message	Origin	Reason
Unknown service	server	The requested service is not one of those listed above.
No image		A service requires image data but no image was passed in the request.
Invalid image format		The image in the request is not in the proper base-64 format.

Testing

Run

python -m tests all

to run tests on all test modules, or specify the modules to test:

python -m tests modules <module1> <module2> ...

To see which modules are available to test, run

python -m tests list

Development Environment

IDE

We use VS Code as the primary IDE for this project. If you're also using VS Code, it is recommended that you incorporate the settings in settings.json into your project.

Python Virtual Environment

We use Conda environments to manage project packages. The file package-list.txt contains all the packages necessary to run the API. The file also contains instructions on how to create a new Conda environment using it.

If you install a new package to your local environment and want to persist it in the project, run

conda list -e > package-list.txt

and push the file to update the package list for everyone.

Tesseract

The Python wrapper for Tesseract requires the usage of the Tesseract binary. The tesseract command must be invokable as tesseract, which means it should be on the system PATH.

If you're on Windows, the latest working binary can be obtained here. After installation, if the command tesseract is not working from the command prompt, add the installation location (typically C:\Program Files\Tesseract OCR) to the Windows Environment Variables. If it's still not working, uncomment line 60 in ocr.py and put the path to the tesseract EXE.

Datasets

Some datasets are used in this project but not committed to the repository (because of its large size). These datasets can be used locally (must be added to a preferrably local .gitignore). However, their links will always be updated here for reference.

Dataset	Type	Last updated	Link
Turkish banknotes	Test	13.05.2020	https://drive.google.com/open?id=1OQaUwDT8GiROOJehbE0bYXmbcmaxp3_A