Upload model card

README.md

@@ -0,0 +1,90 @@
+---
+license: mit
+tags:
+  - image-to-text
+  - ocr
+  - cipher
+  - moon-cipher
+  - pytorch
+  - crnn
+  - cnn
+---
+
+# Moon Cipher Detector
+
+Deep learning models for detecting and decoding **moon cipher** glyphs from images (A–Z plus `~`).
+
+## Model variants
+
+| File | Description |
+|------|-------------|
+| `best_end_to_end.pth` | End-to-end CRNN: full image → decoded text (recommended for full-page decoding). |
+| `best_classifier.pth` | CNN classifier for single glyphs (used with a separate detector in two-stage decoding). |
+
+Use **end-to-end** for full image decoding; use **classifier** if you already have cropped glyphs or use the two-stage pipeline (detect then classify).
+
+## Model metadata
+
+| Model | Format | Size | Params | Tensor type |
+|-------|--------|------|--------|--------------|
+| End-to-end (`best_end_to_end.pth`) | PyTorch .pth (state_dict) | 30.0 MB | 7,856,348 params | F32 |
+| Classifier (`best_classifier.pth`) | PyTorch .pth (state_dict) | 51.98 MB | 13,616,347 params | F32 |
+
+Weights are saved as **PyTorch state dict** (`.pth`), not Safetensors. Load with `torch.load(..., weights_only=True)`.
+
+## Usage
+
+### 1. Install
+
+```bash
+pip install torch torchvision huggingface_hub
+```
+
+### 2. Download from Hugging Face
+
+```python
+from huggingface_hub import hf_hub_download
+
+# End-to-end model (full image → text)
+model_path = hf_hub_download(
+    repo_id="nhellyercreek/moon-cipher-detector",
+    filename="best_end_to_end.pth"
+)
+mappings_path = hf_hub_download(
+    repo_id="nhellyercreek/moon-cipher-detector",
+    filename="mappings.json"
+)
+```
+
+### 3. Load and decode (end-to-end)
+
+Use the same architecture as in this repo’s `models/end_to_end_decoder.py`:
+
+```python
+import torch
+import json
+from pathlib import Path
+
+# Add the Moon-Cipher-Detector repo to path, then:
+# from models.end_to_end_decoder import EndToEndMoonCipherDecoder
+
+# decoder = EndToEndMoonCipherDecoder(
+#     model_path=model_path,
+#     model_type="crnn",
+#     mappings_path=mappings_path,
+#     device="cuda" if torch.cuda.is_available() else "cpu"
+# )
+# result = decoder.decode_with_confidence(your_grayscale_image)
+# print(result["text"])
+```
+
+For the **classifier**, use `models/moon_classifier.MoonClassifier` and load `best_classifier.pth`; see the project’s `models/sequence_decoder.py` and `backend/main.py` for the full pipeline.
+
+## Config
+
+- **Classes**: 27 (A–Z + `~`)
+- **End-to-end**: Deep CRNN (CNN + bidirectional LSTM, CTC).
+- **Classifier**: Custom CNN, 128×128 input, 27 classes.
+- **Weight format**: PyTorch `.pth` (state_dict), **tensor type**: F32.
+
+See `config.json` in this repo for machine-readable settings (params, size, format).