omrchecker

The sample5 directory serves as a demonstration for several advanced OMRChecker workflows:

• Document Scanning App Compatibility: Demonstrates how to run OMRChecker on images captured using popular mobile document scanning applications.
• Shared Template Configuration: Shows how to use a single template.json file across multiple sub-folders (useful for processing multiple scan batches with the same layout).
• Custom Marking Evaluation: Demonstrates how to use an evaluation.json file to implement custom marking logic that does not rely on streak-based marking.

Feature-based alignment is used to correct rotation and translation errors in scanned OMR scripts. When document scanners produce imperfect alignments, you can use a reference image to align the scans correctly.

To implement this, use a reference image that contains distinct features. Avoid using images with many repeated patterns (like OMR bubbles), as these cause ambiguity during feature extraction. Instead, use forms with significant text or unique markings. For best results, generate the reference image from a vector PDF rather than a scanned blank to ensure a perfectly aligned baseline.

If you need a different number of choices or a specific sequence for RTL bubbles, you can define a custom field inline in your template.json. To do this, specify the bubbleValues array and set the direction to "horizontal" within the field block. This overrides the default left-to-right behavior.

"MCQBlock_CUSTOM_RTL": {
    "bubbleValues": ["G", "F", "E", "D", "C", "B", "A"],
    "direction": "horizontal",
    "fieldLabels": ["q1..7"],
    "bubblesGap": 40,
    "labelsGap": 50,
    "origin": [100, 100]
}

For OMR sheets used in Right-To-Left (RTL) languages where answer bubbles are reversed (e.g., D, C, B, A), OMRChecker provides two built-in field types. You can use these in your template.json by setting the fieldType key.

Available built-in RTL types:

• QTYPE_MCQ4_RTL: 4-choice questions with reversed values ["D", "C", "B", "A"].
• QTYPE_MCQ5_RTL: 5-choice questions with reversed values ["E", "D", "C", "B", "A"].

"MCQBlock_RTL": {
    "fieldType": "QTYPE_MCQ4_RTL",
    "fieldLabels": ["q1..10"],
    "bubblesGap": 40,
    "labelsGap": 50,
    "origin": [100, 100]
}

If OMR bubbles are not shaded dark enough for accurate detection, perform a level adjustment to enhance contrast.

In the provided sample, the following adjustments were used to darken light shading and clean the background:

• Set the black point to 70% to darken light shading.
• Set the white point to 80% to remove light-grey backgrounds in columns.

A FieldBlock represents a structured area on the OMR sheet containing bubbles. It is automatically instantiated by the Template class when parsing fieldBlocks from the JSON.

Key properties of a FieldBlock include:

• name: The identifier for the block.
• origin: The [x, y] starting coordinates.
• direction: Either "vertical" or "horizontal".
• fieldType: The type of field (e.g., integer, custom, etc.).
• bubbleValues: The set of values the bubbles represent.
• parsed_field_labels: The labels associated with the fields in this block.

A Template object is initialized by reading a JSON file. The following keys are expected in the JSON object:

• customLabels: Mapping of custom label names to their associated label strings.
• fieldBlocks: Definitions of specific areas on the sheet (e.g., roll number, question answers).
• outputColumns: An array defining the expected output columns.
• preProcessors: Configuration for image pre-processing steps.
• bubbleDimensions: Dimensions for the bubbles.
• emptyValue: The value to represent an empty/unmarked field.
• options: General template options.
• pageDimensions: The width and height of the OMR sheet page.

The framework uses a plugin-style architecture based on Python's pkgutil and inspect modules.

1. Discovery: ProcessorManager walks the directory tree of a specified package.
2. Filtering: For every module found, the manager uses get_name_filter to find class definitions within that module.
3. Validation: It checks if a class is a subclass of Processor but ensures it is not the Processor base class itself.
4. Registration: Valid subclasses are added to the self.processors dictionary, making them available for instantiation by the application.

When the setLayout flag is set to True in your args dictionary, OMRChecker enters a visualization mode instead of full processing. This mode is useful for debugging and verifying that your template correctly aligns with the physical OMR sheets.

It will load each image, apply the template's pre-processors, and use InteractionUtils.show to display the template layout overlaid on the image.

args = {
    "output_dir": "./output",
    "setLayout": True  # Enables layout visualization mode
}
entry_point("./input_dir", args)