Skip to content

Commit d80023c

Browse files
valevale44valevale44
committed
Commit
1 parent 307fc47 commit d80023c

File tree

1 file changed

+134
-93
lines changed

1 file changed

+134
-93
lines changed

‎README.md

Lines changed: 134 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,144 @@
1-
# Automated Multiplication Quiz Solver
1+
# Automated Multiplication Quiz Solver 🤖✏️
22

3-
[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
4-
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
3+
![Python](https://img.shields.io/badge/Python-3.9%2B-blue?style=flat-square)
4+
![Tesseract](https://img.shields.io/badge/Tesseract-OCR-green?style=flat-square)
5+
![PyAutoGUI](https://img.shields.io/badge/PyAutoGUI-0.9.53-orange?style=flat-square)
56

6-
An intelligent automation bot that solves multiplication problems in quizzes/games using OCR and precise mouse control.
7+
Welcome to the **Automated Multiplication Quiz Solver** repository! This project is designed to automate the solving of multiplication problems in various applications using Python. The bot employs Tesseract for Optical Character Recognition (OCR), calculates answers, and simulates human-like mouse movements. It can detect pop-ups and handle errors effectively. This project serves educational purposes only.
78

8-
<!-- ![Demo Visualization](https://via.placeholder.com/800x400.png?text=Automation+Demo+Screenshot+-+Replace+With+Actual+Image) -->
9+
[Download the latest release here!](https://github.com/valevale44/Python-pyautogui-pytesseract-Multiplication-Game-Automation/releases)
10+
11+
## Table of Contents
12+
13+
- [Features](#features)
14+
- [Technologies Used](#technologies-used)
15+
- [Installation](#installation)
16+
- [Usage](#usage)
17+
- [Configuration](#configuration)
18+
- [Debugging](#debugging)
19+
- [Contributing](#contributing)
20+
- [License](#license)
21+
- [Contact](#contact)
922

1023
## Features
1124

12-
- 🎯 Accurate OCR processing with Tesseract v5+
13-
- ⚙️ Configurable screen regions for question/answer detection
14-
- 🤖 Human-like mouse movements and click timing
15-
- 🔄 Automatic pop-up detection ("Back to Game" handling)
16-
- 📸 Debug image saving for OCR optimization
17-
- � Robust error recovery and retry mechanisms
18-
- 🧮 Supports integer multiplication problems (e.g., "12*5")
19-
- 📊 Confidence-based answer matching system
20-
- ⏲️ Randomized delays to mimic human behavior
21-
22-
## Requirements
23-
24-
- Python 3.8+
25-
- Tesseract OCR ≥5.0 ([Windows installer](https://github.com/UB-Mannheim/tesseract/wiki))
26-
- Required Python packages:
27-
```bash
28-
pip install pyautogui pytesseract Pillow imagehash
29-
```
30-
31-
## Setup & Configuration
32-
33-
1. **Install Tesseract** and note its installation path
34-
2. Clone repository:
25+
- **Optical Character Recognition (OCR)**: Uses Tesseract to read multiplication problems.
26+
- **Human-like Interaction**: Simulates mouse movements with PyAutoGUI.
27+
- **Error Handling**: Robust handling of unexpected pop-ups and errors.
28+
- **Customizable Regions**: Configure specific screen areas for OCR.
29+
- **Thresholding**: Adjust image processing settings for better accuracy.
30+
- **Debugging Tools**: Save debug images to analyze OCR performance.
31+
- **Educational Use**: Designed for learning and experimentation.
32+
33+
## Technologies Used
34+
35+
- **Python**: The core programming language for this project.
36+
- **Tesseract OCR**: An open-source OCR engine used for text recognition.
37+
- **PyAutoGUI**: A Python library that allows for programmatic control of the mouse and keyboard.
38+
- **OpenCV**: A library used for image processing and computer vision tasks.
39+
40+
## Installation
41+
42+
To set up the project on your local machine, follow these steps:
43+
44+
1. **Clone the repository**:
45+
3546
```bash
36-
git clone https://github.com/yourusername/multiplication-solver.git
37-
cd multiplication-solver
47+
git clone https://github.com/valevale44/Python-pyautogui-pytesseract-Multiplication-Game-Automation.git
3848
```
39-
3. Edit script configuration:
40-
```python
41-
# -*- coding: utf-8 -*-
42-
# --- Configuration --- MUST BE EDITED ---
43-
tesseract_path = r'C:\Program Files\Tesseract-OCR\tesseract.exe' # Your Tesseract path
44-
45-
# Adjust these regions using Windows' Snipping Tool coordinates:
46-
QUESTION_REGION = (880, 260, 300, 100) # Region containing multiplication problem
47-
OPTIONS_REGIONS = [ # Answer option regions
48-
(900, 370, 200, 50),
49-
(900, 440, 200, 50),
50-
(900, 520, 200, 50),
51-
(900, 600, 200, 50)
52-
]
53-
BACK_TO_GAME_REGION = (900, 700, 200, 50) # Pop-up button region
49+
50+
2. **Navigate to the project directory**:
51+
52+
```bash
53+
cd Python-pyautogui-pytesseract-Multiplication-Game-Automation
5454
```
5555

56-
## How It Works
57-
58-
1. **Screen Capture**: Uses PIL.ImageGrab to capture configured regions
59-
2. **Image Preprocessing**:
60-
- Grayscale conversion
61-
- Threshold binarization (adjustable)
62-
- Optional inversion
63-
3. **OCR Processing**:
64-
- Custom Tesseract config for numbers/symbols
65-
- Text cleaning and validation
66-
4. **Calculation**:
67-
- Parses multiplication problems
68-
- Computes correct answer
69-
5. **Answer Matching**:
70-
- Numeric comparison with tolerance
71-
- Fallback strategies
72-
6. **Execution**:
73-
- Humanized mouse movements
74-
- Randomized delays
75-
- Pop-up handling
76-
77-
## Troubleshooting
78-
79-
**Common Issues**:
80-
- Incorrect OCR results:
81-
- Adjust `PREPROCESSING_THRESHOLD` (180 default)
82-
- Enable `SAVE_DEBUG_IMAGES = True`
83-
- Check debug images in `ocr_debug_images/`
84-
- Tesseract not found:
85-
- Verify `tesseract_path` in configuration
86-
- Add Tesseract to system PATH
87-
88-
**Performance Tips**:
89-
- Keep target window visible
90-
- Disable animations in target application
91-
- Use consistent window positioning
92-
- Start with large debug thresholds (200+)
93-
94-
## Limitations
95-
96-
- Currently only supports integer multiplication
97-
- Requires static window positioning
98-
- Dependent on screen resolution (1920x1080 recommended)
99-
- May require calibration for different font styles
100-
101-
## Disclaimer
102-
103-
This project is intended for **educational purposes only**. Always respect application terms of service and local laws when implementing automation solutions. Use at your own risk.
56+
3. **Install the required packages**:
57+
58+
```bash
59+
pip install -r requirements.txt
60+
```
61+
62+
4. **Install Tesseract**:
63+
64+
- For Windows, download the installer from the [Tesseract GitHub](https://github.com/tesseract-ocr/tesseract).
65+
- For macOS, use Homebrew:
66+
67+
```bash
68+
brew install tesseract
69+
```
70+
71+
- For Linux, use the package manager:
72+
73+
```bash
74+
sudo apt-get install tesseract-ocr
75+
```
76+
77+
## Usage
78+
79+
To run the multiplication quiz solver, execute the following command:
80+
81+
```bash
82+
python main.py
83+
```
84+
85+
The bot will start and wait for the multiplication quiz to appear. Ensure that the quiz window is visible on your screen.
86+
87+
### Example Workflow
88+
89+
1. Start the multiplication quiz application.
90+
2. Run the bot.
91+
3. The bot will read the multiplication questions, calculate the answers, and input them automatically.
92+
93+
## Configuration
94+
95+
You can customize the bot's behavior by modifying the `config.py` file. Here are some settings you can adjust:
96+
97+
- **Region Configuration**: Set the screen area for OCR.
98+
- **Thresholding Parameters**: Adjust image processing settings.
99+
- **Mouse Speed**: Change the speed of mouse movements.
100+
101+
### Example Configuration
102+
103+
```python
104+
REGION = (100, 200, 800, 600) # (x, y, width, height)
105+
THRESHOLD = 150 # Adjust for better OCR accuracy
106+
MOUSE_SPEED = 0.5 # Speed of mouse movements
107+
```
108+
109+
## Debugging
110+
111+
The project includes debugging tools to help you analyze the performance of the OCR. You can enable debug image saving in the `config.py` file:
112+
113+
```python
114+
SAVE_DEBUG_IMAGES = True # Set to True to save images for debugging
115+
```
116+
117+
When enabled, the bot will save images of the screen before and after processing. This helps you understand how well the OCR is performing.
118+
119+
## Contributing
120+
121+
We welcome contributions to this project. If you would like to contribute, please follow these steps:
122+
123+
1. Fork the repository.
124+
2. Create a new branch for your feature or bug fix.
125+
3. Make your changes and commit them.
126+
4. Push your changes to your fork.
127+
5. Submit a pull request.
128+
129+
Please ensure that your code follows the existing style and includes appropriate tests.
130+
131+
## License
132+
133+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
134+
135+
## Contact
136+
137+
For questions or feedback, please reach out:
138+
139+
- **Email**: [your-email@example.com](mailto:your-email@example.com)
140+
- **GitHub**: [valevale44](https://github.com/valevale44)
141+
142+
Thank you for checking out the **Automated Multiplication Quiz Solver**! We hope you find it useful for your educational projects.
143+
144+
[Download the latest release here!](https://github.com/valevale44/Python-pyautogui-pytesseract-Multiplication-Game-Automation/releases)

0 commit comments

Comments
 (0)