Offline Math CAPTCHA Solver API

A high-performance, concurrent, and 100% offline Math CAPTCHA Solver API written in Python. It parses and solves mathematical captcha equations (e.g., A op B = ? like 8 - 4 = ? or 3 x 5 = ?) directly from base64 encoded images, and supports synthetic generation, automatic template learning, and local benchmarking.

---

Features

• 100% Offline: Runs entirely locally without network requests, API keys, or external model downloads.
• State-of-the-Art Speed: Captcha solving completes in ~140ms, optimized using HOG descriptor caching and fast Mean Absolute Error (MAE) pre-filtering.
• High Concurrency Support: Built on FastAPI and Uvicorn with a threading Semaphore to bypass Python GIL contention.
• Local Dataset-Driven: Generate synthetic captchas locally, label unlabeled data, and extract templates automatically to learn new fonts or captcha shapes.

---

Installation & Setup

1. Install the required dependencies:

   pip install -r requirements.txt

   (Dependencies: pillow, opencv-python, numpy, scikit-image, scikit-learn, fastapi, uvicorn, pydantic, requests)

---

Usage Guide

1. Generating CAPTCHAs Locally (generate.py)

Generate a custom dataset of math captchas locally using 10 different styles (Clean Minimal, Multi-color, Hollow Outline, Shadow, Grid Noise, Dot Noise, Tilted, Gradient Background, Blurred, Mixed Noise).

• Generate 50 captchas of Style 3 (Hollow Outline):

  python generate.py --count 50 --clear --style 3

• Generate a blend of all styles (default):

  python generate.py --count 100 --style mixed

Generated images are automatically labeled with the ground-truth equation: <equation>_<id>.png.

2. Labeling Unlabeled Captchas (rename_dataset.py)

If you have numeric or unlabeled captchas in images/ (e.g., 1.png, 2.png), automatically rename them to their solved equations using the solver's predictions:

python rename_dataset.py

3. Automatic Template Learning (captcha_solver.py)

To teach the solver a new font or style, you can extract character templates automatically from any folder of labeled images:

python captcha_solver.py --learn-dataset

This segments the images, correlates regions to expected equation characters, and updates the templates in templates_v2.pkl uniquely.

4. Running the Local Benchmark (benchmark_offline.py)

Verify the solver's accuracy and speed entirely offline against your local labeled dataset in images/:

python benchmark_offline.py

---

Running the API Server

Start the API server locally:

python api_server.py

This runs the Uvicorn server on port 8000 (i.e. http://localhost:8000).

POST /solve

Solves a base64 encoded captcha image.

Request Body (JSON):

{
  "image_base64": "data:image/png;base64,iVBORw0KGgoAAA..."
}

Response (JSON - 200 OK):

{
  "success": true,
  "answer": 15.0,
  "equation": "3 x 5",
  "raw_text": "3×5=?",
  "method": "offline_template",
  "elapsed_sec": 0.145,
  "error": null
}

---

Technical Details

1. Color Segmentation: K-Means clustering splits characters of different colors.
2. Multi-Component Merging: Overlapping/adjacent segments of the same color (like ÷ dots or = lines) are merged vertically.
3. Template Extraction: Character components are normalized to (40, 32) and matched using HOG descriptors and Structural Similarity (SSIM) against candidates pre-filtered by MAE.

---

Dataset Styles Gallery

Below is a gallery showcasing the 10 distinct styles of CAPTCHAs that can be generated locally. Each style has been customized with random fonts, colors, and noise characteristics.

Style Index	Style Name	Example Image 1	Example Image 2
Style 01	Clean Minimal
Style 02	Multi-color
Style 03	Hollow Outline
Style 04	Text Shadow
Style 05	Grid Noise
Style 06	Dot Noise
Style 07	Tilted Characters
Style 08	Gradient Background
Style 09	Gaussian Blur
Style 10	Mixed Noise