Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,209 @@
+---
+license: apache-2.0
+language:
+  - en
+tags:
+  - image-quality-assessment
+  - document-quality
+  - mplug-owl2
+  - vision-language
+  - document-analysis
+  - IQA
+pipeline_tag: image-to-text
+library_name: transformers
+---
+
+# DeQA-Doc-Overall: Document Image Quality Assessment
+
+**DeQA-Doc-Overall** is a vision-language model for assessing the **overall quality** of document images. It provides a quality score from 1 (bad) to 5 (excellent) that reflects the general visual quality of scanned or photographed documents.
+
+## Model Family
+
+This model is part of the **DeQA-Doc** family, which includes three specialized models:
+
+| Model | Description | HuggingFace |
+|-------|-------------|-------------|
+| **DeQA-Doc-Overall** | Overall document quality (this model) | [mapo80/DeQA-Doc-Overall](https://huggingface.co/mapo80/DeQA-Doc-Overall) |
+| **DeQA-Doc-Color** | Color quality assessment | [mapo80/DeQA-Doc-Color](https://huggingface.co/mapo80/DeQA-Doc-Color) |
+| **DeQA-Doc-Sharpness** | Sharpness/clarity assessment | [mapo80/DeQA-Doc-Sharpness](https://huggingface.co/mapo80/DeQA-Doc-Sharpness) |
+
+## Quick Start
+
+```python
+import torch
+from transformers import AutoModelForCausalLM
+from PIL import Image
+
+# Load the model
+model = AutoModelForCausalLM.from_pretrained(
+    "mapo80/DeQA-Doc-Overall",
+    trust_remote_code=True,
+    torch_dtype=torch.float16,
+    device_map="auto",
+)
+
+# Score an image
+image = Image.open("document.jpg").convert("RGB")
+score = model.score([image])
+print(f"Overall Quality Score: {score.item():.2f} / 5.0")
+```
+
+## Batch Processing
+
+You can score multiple images at once:
+
+```python
+images = [
+    Image.open("doc1.jpg").convert("RGB"),
+    Image.open("doc2.jpg").convert("RGB"),
+    Image.open("doc3.jpg").convert("RGB"),
+]
+
+scores = model.score(images)
+for i, score in enumerate(scores):
+    print(f"Document {i+1}: {score.item():.2f} / 5.0")
+```
+
+## Score Interpretation
+
+| Score Range | Quality Level | Description |
+|-------------|---------------|-------------|
+| 4.5 - 5.0 | **Excellent** | Perfect quality, no visible defects |
+| 3.5 - 4.5 | **Good** | Minor imperfections, highly readable |
+| 2.5 - 3.5 | **Fair** | Noticeable issues but still usable |
+| 1.5 - 2.5 | **Poor** | Significant quality problems |
+| 1.0 - 1.5 | **Bad** | Severe degradation, hard to read |
+
+## Model Architecture
+
+- **Base Model**: mPLUG-Owl2 (LLaMA2-7B + ViT-L Vision Encoder)
+- **Vision Encoder**: CLIP ViT-L/14 (1024 visual tokens via Visual Abstractor)
+- **Language Model**: LLaMA2-7B
+- **Training**: Full fine-tuning on document quality datasets
+- **Input Resolution**: Images are resized to 448x448 (with aspect ratio preservation)
+
+## Technical Details
+
+| Property | Value |
+|----------|-------|
+| Model Size | ~16 GB (float16) |
+| Parameters | ~7.2B |
+| Input | RGB images (any resolution) |
+| Output | Quality score (1.0 - 5.0) |
+| Inference | ~2-3 seconds per image on A100 |
+
+## Hardware Requirements
+
+| Setup | VRAM Required | Recommended |
+|-------|---------------|-------------|
+| Full precision (fp32) | ~32 GB | A100, H100 |
+| Half precision (fp16) | ~16 GB | A100, A40, RTX 4090 |
+| With CPU offload | ~8 GB GPU + RAM | RTX 3090, RTX 4080 |
+
+### GPU Inference (Recommended)
+
+```python
+model = AutoModelForCausalLM.from_pretrained(
+    "mapo80/DeQA-Doc-Overall",
+    trust_remote_code=True,
+    torch_dtype=torch.float16,
+    device_map="auto",
+)
+```
+
+### CPU Offload (Lower VRAM)
+
+```python
+model = AutoModelForCausalLM.from_pretrained(
+    "mapo80/DeQA-Doc-Overall",
+    trust_remote_code=True,
+    torch_dtype=torch.float16,
+    device_map="auto",
+    offload_folder="/tmp/offload",
+)
+```
+
+## Installation
+
+```bash
+pip install torch transformers accelerate pillow sentencepiece protobuf
+```
+
+**Note**: Use `transformers>=4.36.0` for best compatibility.
+
+## Use Cases
+
+- **Document Scanning QA**: Automatically flag low-quality scans for re-scanning
+- **Archive Digitization**: Prioritize documents needing restoration
+- **OCR Preprocessing**: Filter images likely to produce poor OCR results
+- **Document Management**: Sort and categorize documents by quality
+- **Quality Control**: Automated quality checks in document processing pipelines
+
+## Example: Quality-Based Filtering
+
+```python
+import torch
+from transformers import AutoModelForCausalLM
+from PIL import Image
+from pathlib import Path
+
+model = AutoModelForCausalLM.from_pretrained(
+    "mapo80/DeQA-Doc-Overall",
+    trust_remote_code=True,
+    torch_dtype=torch.float16,
+    device_map="auto",
+)
+
+# Filter documents by quality
+def filter_by_quality(image_paths, min_score=3.0):
+    good_docs = []
+    bad_docs = []
+
+    for path in image_paths:
+        img = Image.open(path).convert("RGB")
+        score = model.score([img]).item()
+
+        if score >= min_score:
+            good_docs.append((path, score))
+        else:
+            bad_docs.append((path, score))
+
+    return good_docs, bad_docs
+
+# Usage
+docs = list(Path("documents/").glob("*.jpg"))
+good, bad = filter_by_quality(docs, min_score=3.5)
+
+print(f"Good quality: {len(good)} documents")
+print(f"Need review: {len(bad)} documents")
+```
+
+## Limitations
+
+- Optimized for document images (forms, letters, reports, etc.)
+- May not perform well on natural photos or artistic images
+- Requires GPU with sufficient VRAM for efficient inference
+- Score is subjective and based on training data distribution
+
+## Citation
+
+If you use this model in your research, please cite:
+
+```bibtex
+@misc{deqa-doc-2024,
+  title={DeQA-Doc: Document Image Quality Assessment},
+  author={mapo80},
+  year={2024},
+  publisher={HuggingFace},
+  url={https://huggingface.co/mapo80/DeQA-Doc-Overall}
+}
+```
+
+## License
+
+Apache 2.0
+
+## Related Models
+
+- [DeQA-Doc-Color](https://huggingface.co/mapo80/DeQA-Doc-Color) - Color quality assessment
+- [DeQA-Doc-Sharpness](https://huggingface.co/mapo80/DeQA-Doc-Sharpness) - Sharpness assessment