README.md

metadata

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:

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

2. Single Image Recognition

POST /api/molscribe

Request body:

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

Response example:

{
  "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:

{
  "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.