How udayraj123/omrchecker works
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.