Classify a handwritten number

This endpoint classifies any image of a handwritten number that conforms to the image format. A neural network trained on the MNIST database of handwritten digits performs the classification.

The first invocation of Classify a handwritten zero or Classify a handwritten number trains the image recognition model, which takes approximately 10 - 20 seconds. The model is then cached for efficient subsequent invocations.

Observe the training delay in the logs:

Training:    100% |████████████████████████████████████████|
Epoch 1 finished.
Training:    100% |████████████████████████████████████████|
Epoch 2 finished.

Table of contents

  1. Handwritten-zero request
  2. Response
  3. Ambiguous request
  4. Response
  5. Custom request
    1. Image format
    2. Request body
  6. Response

Handwritten-zero request

Send the following request to explicitly process the same image processed by the Classify a handwritten zero endpoint 0:

POST /handwriting-recogniser/classify-handwritten-number

{
  "fileName": "0.png"
}

Response

Data is truncated for readability.

Notice that the image is recognised as 0, with a high probability of correctness:

Response

{
  "handwrittenNumber": "0",
  "probabilities": [
    {
      "handwrittenNumber": "0",
      "probability": 0.9999525547
    },
    {
      "handwrittenNumber": "2",
      "probability": 0.0000418071
    },
    {
      "handwrittenNumber": "6",
      "probability": 0.0000029869
    }
  ]
}

Ambiguous request

Send the following request to process an ambiguous image of a three that looks like an eight 3-like-8:

POST /handwriting-recogniser/classify-handwritten-number

{
  "fileName": "3-that-looks-like-8.png"
}

Response

Data is truncated for readability.

Notice that the image is recognised as 3, with a lower probability of correctness than the less ambiguous handwritten zero. Also notice that the second most probable match is 8:

Response

{
  "handwrittenNumber": "3",
  "probabilities": [
    {
      "handwrittenNumber": "3",
      "probability": 0.6336861849
    },
    {
      "handwrittenNumber": "8",
      "probability": 0.2507479191
    },
    {
      "handwrittenNumber": "2",
      "probability": 0.0491732359
    }
  ]
}

Custom request

Create a new image to experiment with the image recognition capabilities.

Image format

The image format is based on the MNIST database format. Images must have the following properties:

  • Resemble a number from zero to nine
  • Written in white with a black background
  • Sized 28x28 pixels
  • PNG format

Place the image in the images source folder: src/main/resources/images.

Stop, recompile and restart the application for the new image to be registered. As per the Install and run quickstart, this involves one of the following:

  • Restart the application in the IDE.
  • Rebuild and rerun the JAR file.

Verify registration via the List example input images endpoint.

Request body

Send a request structured as per the handwritten-zero request, substituting fileName with the name of the created image.

Response

Expect a response structured as per the handwritten-zero response. Notice that the legibility of the handwritten number corresponds to the probability of correctness.