README.md

Optical Mark Recognition with PHP

This is an open source library written in PHP for recognition markings on questionnaires scans

See: https://en.wikipedia.org/wiki/Optical_mark_recognition

How to use

Add library:

$ composer require jansenfelipe/omr

Instantiate the Scanner class responsible for reading the image and enter its path

/*
 * Setup scanner
 */
$scanner = new ImagickScanner();
$scanner->setImagePath($imagePath);

You will need to scan a blank form and create the Target Mapping File to be able to use the library.

After creating the map.json file, enter its path:

/*
 * Setup map
 */
$map = MapJson::create($mapJsonPath);

Now you can scan and get the result

$result = $scanner->scan($map);

Scanners

This library currently has only one scanner class using Imagemagick 6. It has been tested using the following configurations:

• PHP 7.3
• imagemagick6
• Extension imagick-3.4.4

See https://github.com/jansenfelipe/omr/blob/master/src/Scanners/ImagickScanner.php

Target Mapping File

It is a .json file that describes, in addition to the image information, the coordinates of the places (targets) that the script must do the pixel analysis. This file follows the following pattern:

{
    "width": 600,
    "height": 800,
    "targets": [
      {
        "x1": 50,
        "y1": 43,
        "x2": 65,
        "y2": 57,
        "id": "Foo",
        "type": "rectangle",
        "tolerance": 60
      }
    ] 
}

Example

In the example directory there is an image of a completed questionnaire response.png. There is also a map.json file that gives the coordinates of the image areas that will be analyzed the pixels.

To help with setting up the environment, there is a Dockerfile in the project based on the official PHP 7.3 image that adds composer, imagemagick and the imagick extension to PHP.

That way you can install the dependencies and run the command to process the image without headaches :)

1. Clone this repo:

$ git clone https://github.com/jansenfelipe/omr.git
$ cd omr/

2. Install dependencies:

$ docker-compose run php composer install

2. Process example image:

$ docker-compose run php bin/omr scan example/response.png example/map.json

License

The MIT License (MIT)