# adigashivani/omr-evaluation architecture

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

- Interactive diagram: https://gitdiagram.com/adigashivani/omr-evaluation
- Repository: https://github.com/adigashivani/omr-evaluation

## Overview

OMR-Evaluation reads a multiple-choice answer sheet image, identifies the paper and bubbles, compares selected bubbles with a CSV answer key, calculates a score, and presents marked results. It offers two entry points: a command-line script and a Streamlit upload interface. The processing stages are embedded in those scripts rather than separated into modules; the graph reflects their documented flow without assuming shared runtime code.

Main entry points: [`answer.csv`](https://github.com/adigashivani/omr-evaluation/blob/main/answer.csv) (Answer key), [`app.py`](https://github.com/adigashivani/omr-evaluation/blob/main/app.py) (CLI workflow), [`streamitapp.py`](https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py) (Streamlit workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI workflow<br/>[app.py]"]
  node_web["Streamlit workflow<br/>[streamitapp.py]"]
  node_cli_result["Score display<br/>[app.py]"]
  node_web_result["Result display<br/>[streamitapp.py]"]
end

subgraph group_processing["OMR processing"]
  node_cli_image["Image input<br/>[app.py]"]
  node_cli_sheet["Sheet detection<br/>[app.py]"]
  node_cli_bubbles["Bubble detection<br/>[app.py]"]
  node_cli_grade["Answer grading<br/>[app.py]"]
  node_web_image["Image upload<br/>[streamitapp.py]"]
  node_web_sheet["Sheet detection<br/>[streamitapp.py]"]
  node_web_bubbles["Bubble detection<br/>[streamitapp.py]"]
  node_web_grade["Answer grading<br/>[streamitapp.py]"]
end

subgraph group_answers["Answer data"]
  node_answer_key["Answer key<br/>[answer.csv]"]
end

node_cli_user(("CLI user"))
node_web_user(("Web user"))

node_cli_user -->|"runs"| node_cli
node_cli -->|"reads"| node_answer_key
node_cli -->|"loads"| node_cli_image
node_cli_image -->|"prepares image"| node_cli_sheet
node_cli_sheet -->|"warps sheet"| node_cli_bubbles
node_cli_bubbles -->|"selects bubbles"| node_cli_grade
node_answer_key -->|"provides key"| node_cli_grade
node_cli_grade -->|"scores and marks"| node_cli_result
node_web_user -->|"uploads image"| node_web
node_web -->|"reads"| node_answer_key
node_web -->|"decodes upload"| node_web_image
node_web_image -->|"prepares image"| node_web_sheet
node_web_sheet -->|"warps sheet"| node_web_bubbles
node_web_bubbles -->|"selects bubbles"| node_web_grade
node_answer_key -->|"provides key"| node_web_grade
node_web_grade -->|"scores and marks"| node_web_result

click node_cli "https://github.com/adigashivani/omr-evaluation/blob/main/app.py"
click node_web "https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py"
click node_cli_image "https://github.com/adigashivani/omr-evaluation/blob/main/app.py"
click node_cli_sheet "https://github.com/adigashivani/omr-evaluation/blob/main/app.py"
click node_cli_bubbles "https://github.com/adigashivani/omr-evaluation/blob/main/app.py"
click node_cli_grade "https://github.com/adigashivani/omr-evaluation/blob/main/app.py"
click node_cli_result "https://github.com/adigashivani/omr-evaluation/blob/main/app.py"
click node_web_image "https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py"
click node_web_sheet "https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py"
click node_web_bubbles "https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py"
click node_web_grade "https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py"
click node_web_result "https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py"
click node_answer_key "https://github.com/adigashivani/omr-evaluation/blob/main/answer.csv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_web,node_cli_result,node_web_result,node_cli_user,node_web_user toneBlue
class node_cli_image,node_cli_sheet,node_cli_bubbles,node_cli_grade,node_web_image,node_web_sheet,node_web_bubbles,node_web_grade toneAmber
class node_answer_key toneMint
```

## Components

### User interfaces

- [CLI workflow](https://github.com/adigashivani/omr-evaluation/blob/main/app.py): `app.py`
- [Streamlit workflow](https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py): `streamitapp.py`
- [Score display](https://github.com/adigashivani/omr-evaluation/blob/main/app.py): `app.py`
- [Result display](https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py): `streamitapp.py`

### OMR processing

- [Image input](https://github.com/adigashivani/omr-evaluation/blob/main/app.py): `app.py`
- [Sheet detection](https://github.com/adigashivani/omr-evaluation/blob/main/app.py): `app.py`
- [Bubble detection](https://github.com/adigashivani/omr-evaluation/blob/main/app.py): `app.py`
- [Answer grading](https://github.com/adigashivani/omr-evaluation/blob/main/app.py): `app.py`
- [Image upload](https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py): `streamitapp.py`
- [Sheet detection](https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py): `streamitapp.py`
- [Bubble detection](https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py): `streamitapp.py`
- [Answer grading](https://github.com/adigashivani/omr-evaluation/blob/main/streamitapp.py): `streamitapp.py`

### Answer data

- [Answer key](https://github.com/adigashivani/omr-evaluation/blob/main/answer.csv): `answer.csv`

### Other components

- **CLI user**
- **Web user**

## Connections

- CLI user → CLI workflow: runs
- CLI workflow → Answer key: reads
- CLI workflow → Image input: loads
- Image input → Sheet detection: prepares image
- Sheet detection → Bubble detection: warps sheet
- Bubble detection → Answer grading: selects bubbles
- Answer key → Answer grading: provides key
- Answer grading → Score display: scores and marks
- Web user → Streamlit workflow: uploads image
- Streamlit workflow → Answer key: reads
- Streamlit workflow → Image upload: decodes upload
- Image upload → Sheet detection: prepares image
- Sheet detection → Bubble detection: warps sheet
- Bubble detection → Answer grading: selects bubbles
- Answer key → Answer grading: provides key
- Answer grading → Result display: scores and marks