README.md

---
language:
  - en
license: agpl-3.0
library_name: onnxruntime
tags:
  - captcha
  - ocr
  - cnn
  - onnx
  - phpwind
pipeline_tag: image-to-text
model_type: phpwind-captcha-ocr
metrics:
  - name: validation accuracy
    type: accuracy
    value: 0.8861
---

# PHPWind Captcha OCR

[![Hugging Face Model](https://img.shields.io/badge/Hugging%20Face-Model-FFD21E?logo=huggingface&logoColor=000)](https://huggingface.co/FlanChanXwO/phpwind-captcha-ocr)
[![ONNX](https://img.shields.io/badge/Runtime-ONNX-005CED?logo=onnx&logoColor=fff)](https://onnx.ai/)
[![PHPWind](https://img.shields.io/badge/Target-PHPWind-3776AB)](https://github.com/alibaba/phpwind)
[![License: AGPL--3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)

An ONNX OCR model trained on four-digit numeric captcha images from one legacy
PHPWind deployment. It runs entirely on the local machine: no external API or
GPU is required.

**PHPWind reference implementation**: [alibaba/phpwind](https://github.com/alibaba/phpwind)
contains the `PwVerifyCode` and `PwGDCode` classes targeted by this model.

**中文文档**: [README_zh.md](README_zh.md)

![Example PHPWind captcha](assets/example_captcha.png)

> **Answer for the captcha shown above:** `9125`

## Scope and responsible use

This model is intended for PHPWind site operators, developers, and researchers
working with PHPWind deployments they own or are explicitly authorized to test.
Use it for local integration tests, accessibility research, or evaluation of
your own captcha implementation. Do not use it to automate account logins or
bypass access controls.

Different PHPWind versions and custom themes can generate visually different
captchas. Validate on representative, authorized samples before deployment.

## Version support

This checkpoint was trained only on four-digit captcha images from a target
deployment whose footer displayed `v0.7β`. This is an observed deployment
label, **not** a claim about an official PHPWind release version.

| Deployment or version label | Status | Evidence | Notes |
|---|---|---|---|
| Target deployment — footer label `v0.7β` | Training scope | 997 manually labelled images; 88.61% held-out validation accuracy | The only visual configuration represented in the training and reference evaluation data. |
| Other PHPWind releases, forks, themes, or captcha generators | Unverified | No version-specific evaluation | Validate with authorized representative samples; fine-tune if the visual distribution differs. |

## Quick start

Install the runtime:

```bash
pip install onnxruntime pillow numpy
```

Run local inference on a captcha image you are authorized to process:

```python
import numpy as np
import onnxruntime as ort
from PIL import Image

session = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])

def predict_captcha(path: str) -> str:
    image = Image.open(path).convert("RGB").resize((160, 64), Image.BILINEAR)
    inputs = np.asarray(image, dtype=np.float32).transpose(2, 0, 1)[None] / 255.0
    logits = session.run(None, {"input": inputs})[0]
    return "".join(str(int(logits[0, position].argmax())) for position in range(4))

print(predict_captcha("captcha.png"))
```

## Model interface

| Item | Value |
|---|---|
| Input | `input`: `[batch, 3, 64, 160]`, `float32`, RGB values in `[0, 1]` |
| Output | `logits`: `[batch, 4, 10]`; argmax per position gives one digit |
| Preprocessing | RGB → resize to `160 × 64` (bilinear) → divide by `255` |
| Format | ONNX, opset 18 |
| Runtime | CPU supported; no GPU requirement |

## Evaluation

The published checkpoint reached **88.61% validation accuracy** on a held-out
split of 997 manually labelled images from the target `v0.7β` footer-label
deployment. This is a model-card reference metric, not a guarantee for another
PHPWind version, theme, or deployment. See [the evaluation
protocol](docs/en/EVALUATION.md) for the scope and reproducibility requirements.

## Documentation

- [Inference guide](docs/en/INFERENCE.md) — Python and Go integration details
- [Training and fine-tuning](docs/en/TRAINING.md) — data preparation and model training
- [Evaluation](docs/en/EVALUATION.md) — offline validation protocol
- [Documentation index](docs/en/README.md)

## Training data and license

The checkpoint was trained from scratch with a position-preserving CNN on 997
manually labelled images. For adaptation, use only captcha images from PHPWind
deployments you operate or are authorized to evaluate.

This project is licensed under [GNU AGPL-3.0](LICENSE). Modified or networked
derivative works must meet the license's corresponding-source requirements.