README.md

---
title: MolScribe OCR (Docker)
emoji: 🧬
colorFrom: green
colorTo: blue
sdk: docker
pinned: false
---

# MolScribe OCR

MolScribe OCR / OCSR service for Hugging Face Spaces (Docker SDK). The service accepts chemical structure images as `base64` payloads, runs MolScribe inference, and returns the predicted structure data.

## References

* MolScribe repository: <https://github.com/thomas0809/MolScribe>
* Model repository: `yujieq/MolScribe`

## Default Model

* `repo`: `yujieq/MolScribe`
* `file`: `swin_base_char_aux_1m.pth`

Alternative checkpoints can be selected through the Hugging Face Space variables `MODEL_REPO` and `MODEL_FILE`.

## Features

* Docker-ready Hugging Face Space packaging.
* Direct `base64` image input.
* Automatic white-border trimming before inference.
* Automatic image downscaling for oversized screenshots.
* Optional soft request timeout protection for long-running CPU inference.
* Structured JSON output with `smiles`, `molfile`, and optional `confidence`, `atoms`, `bonds`.
* Built-in Gradio web UI for interactive testing.

## Environment Variables

* `MODEL_REPO`: default `yujieq/MolScribe`
* `MODEL_FILE`: default `swin_base_char_aux_1m.pth`
* `DEVICE`: default `cpu`
* `AUTO_TRIM_WHITE`: default `1`
* `WHITE_THRESHOLD`: default `245`
* `WHITE_PADDING`: default `16`
* `MAX_IMAGE_EDGE`: default `1280`
* `MIN_IMAGE_EDGE`: default `0`
* `REQUEST_TIMEOUT_SECONDS`: default `180`

## REST API

### 1. Health Check

**GET** `/healthz`

Response example:

```json
{
  "ok": true,
  "model": {
    "repo": "yujieq/MolScribe",
    "file": "swin_base_char_aux_1m.pth",
    "device": "cpu"
  }
}
```

### 2. Single Image Recognition

**POST** `/api/molscribe`

Request body:

```json
{
  "image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "return_atoms_bonds": true,
  "return_confidence": true,
  "timeout_seconds": 180
}
```

Response example:

```json
{
  "success": true,
  "smiles": "CCO",
  "prediction": {
    "smiles": "CCO",
    "molfile": "...",
    "confidence": 0.98,
    "atoms": [],
    "bonds": []
  },
  "image": {
    "mode": "RGB",
    "original_width": 2200,
    "original_height": 1400,
    "width": 1280,
    "height": 814,
    "trimmed": true,
    "trim_bbox": [182, 211, 2018, 1312],
    "scaled": true,
    "scale_factor": 0.5818
  },
  "model": {
    "repo": "yujieq/MolScribe",
    "file": "swin_base_char_aux_1m.pth",
    "device": "cpu"
  },
  "elapsed_ms": 1234.56
}
```

### 3. Batch Image Recognition

**POST** `/api/molscribe/batch`

Request body:

```json
{
  "inputs": [
    {
      "image_base64": "data:image/png;base64,...",
      "return_atoms_bonds": true,
      "return_confidence": true,
      "timeout_seconds": 180
    },
    {
      "image_base64": "data:image/png;base64,...",
      "return_atoms_bonds": false,
      "return_confidence": true
    }
  ]
}
```

## Deployment

1. Create a new **Docker Space** on Hugging Face.
2. Upload the contents of this directory to the Space repository root.
3. Wait for the image build to complete.
4. Access the Gradio UI from the Space root path.
5. Access the inference API through `/api/molscribe` and `/api/molscribe/batch`.

## Notes

* The default configuration uses CPU inference. Runtime depends on the selected Hugging Face Space resources.
* White-border trimming and `MAX_IMAGE_EDGE` downscaling are enabled by default to reduce wasted CPU time on large screenshots with empty margins.
* The timeout protection is a soft timeout. It prevents the client from waiting indefinitely, but an already running CPU inference may still continue briefly in the background.
* Predictions are returned directly from MolScribe output without extra SMILES canonicalization or post-correction.