Document Detection

Detecting documents in the images and preprocessing them.

Overview

Document Detection is one of the intelligence services of Filestack platform. You can detect your document in the image, transform it to fully fit the image, and preprocess it such as de-noising and distortion reduction in order to increase the accuracy of OCR engine in text extraction. Please see following resources to learn more:

Resources

Document Detection API can only accept images with the resolution no more than 2000x2000 pixels. You can use Resize task in chain to configure your image size and make it compatible with Document Detection.

Processing API

In order to use this task in Processing API, the following signature needs to be provided alongside with your image handle:

doc_detection=coords:<coords>,preprocess:<preprocess>

Providing coords and preprocess in the above signature is not mandatory. If you do not configure these parameters in your URL and just use the signature /doc_detection/, default values of coords:false and preprocess:true would be set.
To use this task in Processing API, you should use security policy and signature. For more information you can follow this Link.

Parameters

coords boolean false Indicates whether this task to return coordinates of detected document in the image.
preprocess boolean true Indicates whether this task to return preprocessed image or the warped one.

Response

  • Original image:

  • /doc_detection=coords:true/
{
    "coords": [
        [421, 1633], "coordinates of bottom right edge (x, y)"
        [415, 727], "coordinates of bottom left edge (x, y)"
        [1065, 719], "coordinates of upper left edge (x, y)"
        [1072, 1624] "coordinates of upper right edge (x, y)"
    ]
}

Response Parameters

coords array Includes the coordinates of four edges belonging to the detected document inside of your image.

  • /doc_detection=coords:false,preprocess:true/

  • /doc_detection=coords:false,preprocess:false/

Examples

  • Get the coordinates of the detected document in the image (the same result with both values of preprocess):
https://cdn.filestackcontent.com/security=p:<POLICY>,s:<SIGNATURE>/doc_detection=coords:true,preprocess:true/<HANDLE>
  • Get the preprocessed warped document from your original image:
https://cdn.filestackcontent.com/security=p:<POLICY>,s:<SIGNATURE>/doc_detection=coords:false,preprocess:true/<HANDLE>
  • Get the warped document from your original image:
https://cdn.filestackcontent.com/security=p:<POLICY>,s:<SIGNATURE>/doc_detection=coords:false,preprocess:false/<HANDLE>
  • Use doc_detection in a chain with other tasks such as resize:
https://cdn.filestackcontent.com/security=p:<POLICY>,s:<SIGNATURE>/resize=h:<HEIGHT>/doc_detection=coords:false,preprocess:true/<HANDLE>

Workflows Task Configuration

Visit Creating Workflows Tutorial to learn how you can use Workflows UI to configure your tasks and logic between them.

Document Detection task is available under Intelligence tasks category.

Parameters

Task Name string Unique name of the task. It will be included in the webhook response and can be used to build logic below.

Logic

Document Detection task returns following response to the workflow:

{
    "url": "the URL where the image is stored",
    "mimetype": "image/<image_format>",
    "size": "image size"
}

Parameters

url string Indicates the result file URL.
mimetype string Indictaes the result file type and its format.
size integer Indictaes result file size in bytes.

Considering the response from the task, you can build logic that tells the workflow how dependent tasks should be executed. For example, if you would like to implement another task if the image size is greater than or equal to a specific value, you can use the following rule:

size gte 300000

In Workflows UI this command looks like the following exaple:

You can visit Creating Workflows Tutorial to learn how to use Workflows UI to configure your tasks and logic between them.

Webhook

Below you can find an example webhook payload for a Document Detection task on a sample image:

{
    "id": 67015448,
    "action": "fs.workflow",
    "timestamp": 1551981663,
    "text": {
        "workflow": "0a3c0172-e7d5-4994-a6e0-b02hs7hv3p0q",
        "createdAt": "2019-03-07T16:28:13.520745456Z",
        "updatedAt": "2019-03-07T16:28:15.452548223Z",
        "sources": [
            "jTHlNSQRQgj5gsg5p0y3"
        ],
        "results": {
            "doc_detection_1551973696993": {
                "url": "http://cdn.filestackcontent.com/A3d9FYlESAMd92hc3G60W/wf://0a3c0172-e7d5-4994-a6e0-b02hs7hv3p0q/jTHlNSQRQgj5gsg5p0y3/3c17c5dc-dd93-4cf1-abac-0whs7b5v2p/7e900f75d25d12a93305171ts5b8ps3v",
                "mimetype": "image/jpeg",
                "size": 351697
            }
        },
    "status": "Finished"
    }
}

Please visit the webhooks documentation page to learn more.