NAV Navbar
shell python php
  • Verifai Serverside Classifier
  • Verifai Serverside Classifier

    Serverside version of the classifier component of Verifai.

    index-page

    Introduction

    Because a picture is worth a thousand words, lets start with the high level overview of the serverside solution we offer.

    index-page

    At the top-right you see the Verifai Serverside Classifier. This document describes how you can get it up and running, and send data to the classifier.

    As you can see in the image we do not send the document to our servers. After classification we only get the metadata on the document to help you process it.

    Prerequisites

    Setting up the service

    Get credentials via the "Verifai Dashboard" > "Downloads" > "Docker Registry"

    $ docker login docker-registry.verifai.com -u \<username> -p \<password>
    $ docker pull docker-registry.verifai.com/serverside-classifier:latest
    

    Example docker-compose.yml

    version: "3"
    
    services:
      verifai-classifier:
        # login to our registry first
        image: docker-registry.verifai.com/serverside-classifier:latest
        container_name: verifai-classifier
        volumes:
          - './:/data'
        hostname: "<application identifier from the dashboard>"
        ports:
          - "5000:80"
    

    The service will extract the required credentials from a license file, this license file can be obtained through the Verifai Dashboard.

    In the data folder there needs to be a licence.txt file. That should contain the licence that can be found on the Verifai Dashboard. With the example docker-compose (on the right) it mounts the current directory into the container.

    The most convenient way of running the service on your development environment is by using Docker Compose. You can use the example on the right, to quickly get the service up and running.

    Starting the service

    $ docker-compose up
    

    Console output should be something like this:

    Starting verifai-serverside-classifier_verifai-classifier_1 ... done
    Attaching to verifai-serverside-classifier_verifai-classifier_1
    verifai-classifier_1  | [2018-05-01 16:22:50 +0000] [1] [INFO] Starting gunicorn 19.7.1
    verifai-classifier_1  | [2018-05-01 16:22:50 +0000] [1] [INFO] Listening at: http://0.0.0.0:80 (1)
    verifai-classifier_1  | [2018-05-01 16:22:50 +0000] [1] [INFO] Using worker: threads
    verifai-classifier_1  | [2018-05-01 16:22:50 +0000] [8] [INFO] Booting worker with pid: 8
    verifai-classifier_1  | 2018-05-01 16:22:52,224 - VERIFAI - INFO - Starting appliction
    verifai-classifier_1  | 2018-05-01 16:22:52,224 - VERIFAI - INFO - Initializing Licence
    verifai-classifier_1  | 2018-05-01 16:22:52,235 - VERIFAI - INFO - Licenced to: Belsimpel
    verifai-classifier_1  | 2018-05-01 16:22:52,235 - VERIFAI - INFO - Licence valid until: 2018-12-31 23:59:59, thats in 244 days.
    verifai-classifier_1  | 2018-05-01 16:22:52,236 - VERIFAI - INFO - No Neural Network package found. Getting options...
    verifai-classifier_1  | 2018-05-01 16:22:54,333 - VERIFAI - INFO - Found "Set 9 (All Dutch documents)" 01002/02003, size 23994 KB
    verifai-classifier_1  | 2018-05-01 16:22:54,479 - VERIFAI - INFO - Starting Download
    verifai-classifier_1  | 2018-05-01 16:22:54,700 - VERIFAI - INFO - Download progress:  10%:   2280 KB
    verifai-classifier_1  | 2018-05-01 16:22:54,942 - VERIFAI - INFO - Download progress:  20%:   4679 KB
    verifai-classifier_1  | 2018-05-01 16:22:55,160 - VERIFAI - INFO - Download progress:  30%:   7079 KB
    verifai-classifier_1  | 2018-05-01 16:22:55,396 - VERIFAI - INFO - Download progress:  40%:   9478 KB
    verifai-classifier_1  | 2018-05-01 16:22:55,595 - VERIFAI - INFO - Download progress:  50%:  11877 KB
    verifai-classifier_1  | 2018-05-01 16:22:55,811 - VERIFAI - INFO - Download progress:  60%:  14277 KB
    verifai-classifier_1  | 2018-05-01 16:22:56,092 - VERIFAI - INFO - Download progress:  70%:  16676 KB
    verifai-classifier_1  | 2018-05-01 16:22:56,245 - VERIFAI - INFO - Download progress:  80%:  19075 KB
    verifai-classifier_1  | 2018-05-01 16:22:56,516 - VERIFAI - INFO - Download progress:  90%:  21475 KB
    verifai-classifier_1  | 2018-05-01 16:22:56,722 - VERIFAI - INFO - Download progress: 100%:  23874 KB
    verifai-classifier_1  | 2018-05-01 16:22:56,765 - VERIFAI - INFO - Download complete
    verifai-classifier_1  | 2018-05-01 16:22:56,766 - VERIFAI - INFO - Extracting Neural Network
    verifai-classifier_1  | 2018-05-01 16:22:57,188 - VERIFAI - INFO - Loading Neural Network for inference
    verifai-classifier_1  | 2018-05-01 16:22:58,679 - VERIFAI - INFO - ---------------------------------------------
    verifai-classifier_1  | 2018-05-01 16:22:58,680 - VERIFAI - INFO - Startup sequence has been completed. Now ready to classify.
    

    Running docker-compose up should do the trick. At the end of the log it should expose a webservice on http://localhost:5000/.

    As you can see in the log there are serval steps it takes:

    Sending an image to the classifier

    $ curl -F "file=@dutch-id-front-sample.jpg" http://localhost:5000/api/classify/
    
    import requests
    
    image = 'dutch-id-front-sample.jpg'
    
    r = requests.post(
        'http://localhost:5000/api/classify/',
        files={'file': image}
    )
    # Print the raw JSON response
    print(r.text)
    
    <?php
    $image = 'dutch-id-front-sample.jpg';
    
    $ch = curl_init('http://localhost:5000/api/classify/');
    $data = array(
        'file' => '@'.$image,
    );
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $output = curl_exec($ch);
    curl_close($ch);
    
    # Print the raw JSON response
    print($output);
    ?>
    

    It will return the following:

       {
          "confidence": 0.8347759246826172,
          "coords": {
            "xmax": 0.6118464469909668,
            "xmin": 0.21217313408851624,
            "ymax": 0.8527788519859314,
            "ymin": 0.45336633920669556
          },
          "message": "",
          "side": "F",
          "status": "SUCCESS",
          "uuid": "c6beadb8-ef56-43d4-b69f-e0df8163279f"
        }
    

    dutch-sample-document You can send files to the API endpoint (/api/classify/) using for example curl. If you've done that you will get a response. The faster your computer, the quicker the response. As you can see in the response the document is classified successfuly.

    You will receive a response with the following data:

    Field Description
    confidence The float between 0 and 1 defining how sure the classifier is. 0.99 being very certain, 0.61 less certain. For example: 0.8347759246826172
    coords The bounding box coordinates. Next topic is how to interpert these values. This is a map of coordinates (see response example).
    status Technical status you can use to process programmatically. Possible values are: "SUCCESS", "NOT_FOUND" or "ERROR"
    message Friendly message which can be shown to the user. Empty when successful. Example messages: "No document found.", "Image can not be decoded.", ""
    side The side of the document, F for Front and B for Back.
    uuid Internal Verifai uuid of the docment. Can be used for further processing, for example with the SDKs. For example: "c6beadb8-ef56-43d4-b69f-e0df8163279f"

    Interpreting the coordinates

    The response contains a map of coordinates in coords. You can use these coordinates to crop or isolate the document from the image.

    The way it works is that you can figure out the left-top and right-bottom of the image. That is enough information to isolate the rectangle from the image. The values like the xmax value 0.6118464469909668 is a float that represents its relative postion on the image.

    For example: lets assume that the image is 1024 x 768 pixels. The left-top position of the document can be calculated like this: 1024.0 x 0.21217313408851624 (xmin value) = 217 by 768.0 x 0,45336633920669556 (ymin value) = 348 pixels (rounded because you don't have parial pixels)

    The following image is a mockup of the test image with an overlay so you can see how to interpert the data. The percentages in the image reffer to the float values of the coordinates. 0.21217313408851624 is displayed as "21%"

    dutch-sample-processed

    Issues

    Service starting errors

    Check the logs before you do anything

    $ docker-compose logs
    

    If the licence is not valid, the service will exit while starting. You should check the logs first for abnormalities.

    Performance issues

    Check for GPU support in your running container

    $ docker exec -ti verifai-classifier nvidia-smi
    

    It should output something like this (in idle state):

    Wed May  9 12:14:21 2018
    +-----------------------------------------------------------------------------+
    | NVIDIA-SMI 390.48                 Driver Version: 390.48                    |
    |-------------------------------+----------------------+----------------------+
    | GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
    | Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
    |===============================+======================+======================|
    |   0  GeForce GTX 108...  On   | 00000000:02:00.0 Off |                  N/A |
    | 23%   31C    P8    15W / 250W |      1MiB / 11178MiB |      0%      Default |
    +-------------------------------+----------------------+----------------------+
    |   1  GeForce GTX 108...  On   | 00000000:03:00.0 Off |                  N/A |
    | 23%   32C    P8    16W / 250W |      1MiB / 11178MiB |      0%      Default |
    +-------------------------------+----------------------+----------------------+
    
    +-----------------------------------------------------------------------------+
    | Processes:                                                       GPU Memory |
    |  GPU       PID   Type   Process name                             Usage      |
    |=============================================================================|
    |  No running processes found                                                 |
    +-----------------------------------------------------------------------------+
    

    If the performance is not optimal you should check if the GPU is detected inside the container. If that's not the case, contact support or your sysadmin to help you setup Docker to work with CUDA.

    More information about how to configure Docker in combination with CUDA can be found on NVIDIAs Github wiki: Github nvidia-docker Wiki

    The second thing that you can check is the input size of your images. If they are large then it can cause a delay because the classifier has to scale them back to fit the images in memory. Images larger than 1024x768 will be scaled back by the server, causing overhead.

    Errors and status during classification

    This list contains all the errors the webservice can throw.

    Status Message Description
    ERROR No 'file' field in request. There should be a field in the POST data called file.
    ERROR Image can not be decoded. Not able to read the image, can be wrong format.
    NOT_FOUND No document found. Unable to find an ID document in the image.
    SUCCESS - Found an ID document.