# udayraj123/omrchecker architecture

> Architecture diagram of the GitHub repository udayraj123/omrchecker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/udayraj123/omrchecker
- Repository: https://github.com/udayraj123/omrchecker

## Overview

##### Project Type and Purpose
- This is a specialized full-stack (processing pipeline) application focused on computer vision and image processing. Its primary purpose is to read and evaluate OMR sheets uploaded as images. It supports custom templates and is designed for both high-quality scans (from scanners) and lower quality images (from mobile phones).

##### Analyzing the File Structure
- Top-level files and directories:
- Files like main.py, pyproject.toml, and requirements.txt indicate a Python command-line application.
- The samples/ folder contains multiple examples with configurations (template.json, evaluation.json) and answer keys, which emphasize extensibility for various OMR layouts.
- The src/ directory holds the core application code structured into modules: core logic (core.py, entry.py), processors (with specific image processing tasks like CropOnMarkers, CropPage, FeatureBasedAlignment), schema/ configuration & validation (templates and evaluation schemas), logging, and utility functions.

- Under src/processors:
- There are plugins/modules for different pre-processing steps, such as cropping and alignment. This suggests a pipeline/middleware design where different image-preprocessing steps are chained.

- The existence of tests, docs, and GitHub-specific directories (like .github) indicates support for quality assurance, community contributions, and developer best practices.

##### Insights from the README
- The README emphasizes step-by-step processing of OMR sheets with visual depictions, output (a CSV file with evaluated responses), and customizability through JSON templates.
- The README guides on configuring the system (using template.json) and describes the processing steps (e.g., rotation, cropping, feature-based alignment). This confirms a modular pipeline architecture.

a. Main Components:
- Entry Point: main.py / src/entry.py that starts the process.
- Configuration Loader/Template Manager: Modules within src/defaults, src/template.py, and src/schemas handle loading and validating the OMR layouts and configurations.
- Processing Pipeline / Core Engine: Core logic in src/core.py orchestrates the overall workflow.
- Image Processors: Located under src/processors (e.g., CropOnMarkers, CropPage, FeatureBasedAlignment, and the builtins module). These are plugged into the pipeline to preprocess images.
- Evaluation Module: src/evaluation.py for reading the processed images, applying answer keys, and computing the final scores.
- Utilities & Logging: src/utils and src/logger.py support file interactions, image parsing, validations, and logging of processing steps.
- Tests & Validation: The src/tests segment ensures that each module and overall workflow is robust.

b. Relationships and Data Flow:
- Start from the “Entry Point” which reads input images from configured directories (or samples/).
- The “Configuration Manager” loads the template and evaluation parameters.
- The “Image Processing Pipeline” sequentially calls various pre-processors (cropping, alignment, etc.) that work on the input image.
- Post preprocessing, the “Evaluation Module” interprets the marks, compares them with the answer key, and generates an output (e.g., CSV file).
- Throughout, the “Utility & Logging” modules record the process and assist in error checking.
- Optionally, tests validate each stage of the data flow.

c. Architectural Patterns:
- Pipeline Pattern: The chain of image processors provides a clear pipeline for input processing.
- Modular Design: Each processing component has a defined role (e.g., cropping, feature alignment) and communicates via interfaces (see src/processors/interfaces).
- Configuration-Driven Behavior: Template and configuration JSON control processing parameters, making the tool easily adaptable to different OMR layouts.
- Separation of Concerns: Clear division between image processing, configuration management, evaluation, logging, and tests.

d. Relevant Technologies and Libraries:
- Python 3.5+ as the runtime environment.
- OpenCV (opencv-python, opencv-contrib-python) for image processing.
- Pylint, Black for code formatting and quality.
- Standard Python libraries for file I/O and logging.
- JSON schema validation libraries likely used in src/schemas for configuration verification.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Configuration Layer
    subgraph "Input & Configuration Layer"
        EP1["Entry Point: main.py"]:::entry
        EP2["Entry Point: src/entry.py"]:::entry
        CL["Configuration Loader/Template Manager"]:::config
        subgraph "Configuration Components"
            Conf1["Default Template (src/defaults/template.py)"]:::config
            Conf2["Template Loader (src/template.py)"]:::config
            Conf3["Template Schema (src/schemas/template_schema.py)"]:::config
            Conf4["Config Schema (src/schemas/config_schema.py)"]:::config
        end
    end

    %% Processing Pipeline Layer
    subgraph "Processing Pipeline Layer"
        PE["Core Processing Engine (src/core.py)"]:::engine
        subgraph "Image Processors"
            IP1["CropOnMarkers (src/processors/CropOnMarkers.py)"]:::processor
            IP2["CropPage (src/processors/CropPage.py)"]:::processor
            IP3["FeatureBasedAlignment (src/processors/FeatureBasedAlignment.py)"]:::processor
            IP4["Builtins (src/processors/builtins.py)"]:::processor
            IP5["ImagePreprocessor Interface (src/processors/interfaces/ImagePreprocessor.py)"]:::processor
        end
    end

    %% Evaluation and Output Layer
    subgraph "Evaluation and Output Layer"
        Eval["Evaluation Module (src/evaluation.py)"]:::evaluation
    end

    %% Utilities & Logging Layer
    subgraph "Utilities & Logging Layer"
        Util1["Logger (src/logger.py)"]:::utility
        Util2["Utilities (src/utils)"]:::utility
    end

    %% Tests & Validation Layer
    subgraph "Tests & Validation Layer"
        Test1["Tests (src/tests)"]:::test
    end

    %% Data Flow Connections
    EP1 -->|"start"| CL
    EP2 -->|"start"| CL
    CL -->|"loads config"| PE
    PE -->|"invokes"| IP1
    PE -->|"invokes"| IP2
    PE -->|"invokes"| IP3
    PE -->|"invokes"| IP4
    PE -->|"invokes"| IP5
    PE -->|"processes data"| Eval
    Eval -->|"logs output"| Util1
    EP1 -->|"logging"| Util1
    EP2 -->|"logging"| Util1
    CL -->|"logs config"| Util1
    PE -->|"logs process"| Util1
    Eval -->|"logs evaluation"| Util1
    Util2 ---|"provides utilities"| PE
    Util2 ---|"supports"| Eval
    Test1 ---|"validates"| PE
    Test1 ---|"validates"| Eval

    %% Click Events
    click EP1 "https://github.com/udayraj123/omrchecker/blob/master/main.py"
    click EP2 "https://github.com/udayraj123/omrchecker/blob/master/src/entry.py"
    click Conf1 "https://github.com/udayraj123/omrchecker/blob/master/src/defaults/template.py"
    click Conf2 "https://github.com/udayraj123/omrchecker/blob/master/src/template.py"
    click Conf3 "https://github.com/udayraj123/omrchecker/blob/master/src/schemas/template_schema.py"
    click Conf4 "https://github.com/udayraj123/omrchecker/blob/master/src/schemas/config_schema.py"
    click PE "https://github.com/udayraj123/omrchecker/blob/master/src/core.py"
    click IP1 "https://github.com/udayraj123/omrchecker/blob/master/src/processors/CropOnMarkers.py"
    click IP2 "https://github.com/udayraj123/omrchecker/blob/master/src/processors/CropPage.py"
    click IP3 "https://github.com/udayraj123/omrchecker/blob/master/src/processors/FeatureBasedAlignment.py"
    click IP4 "https://github.com/udayraj123/omrchecker/blob/master/src/processors/builtins.py"
    click IP5 "https://github.com/udayraj123/omrchecker/blob/master/src/processors/interfaces/ImagePreprocessor.py"
    click Eval "https://github.com/udayraj123/omrchecker/blob/master/src/evaluation.py"
    click Util1 "https://github.com/udayraj123/omrchecker/blob/master/src/logger.py"
    click Util2 "https://github.com/udayraj123/omrchecker/tree/master/src/utils"
    click Test1 "https://github.com/udayraj123/omrchecker/tree/master/src/tests"

    %% Styles
    classDef entry fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef config fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef engine fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef processor fill:#FAD7A0,stroke:#B9770E,stroke-width:2px;
    classDef evaluation fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef utility fill:#D5DBDB,stroke:#566573,stroke-width:2px;
    classDef test fill:#F5B7B1,stroke:#943126,stroke-width:2px;
```
