USAGE_GUIDE.md

# راهنمای استفاده از dots.ocr Space

## نصب و راه‌اندازی

### 1. آپلود به Hugging Face Space

1. فایل‌های پروژه را به یک Hugging Face Space جدید آپلود کنید
2. مطمئن شوید که Space از نوع Gradio است
3. GPU را در تنظیمات Space فعال کنید (توصیه می‌شود: T4 یا بالاتر)

### 2. استفاده از رابط کاربری

بعد از راه‌اندازی Space:

1. تصویر سند خود را آپلود کنید
2. نوع پرامپت را انتخاب کنید:
   - **Full Layout + OCR**: تحلیل کامل با bounding box، دسته‌بندی و متن
   - **OCR Only**: استخراج ساده متن
   - **Layout Detection Only**: فقط تشخیص چیدمان
   - **Custom**: پرامپت سفارشی
3. دکمه "Process Document" را بزنید
4. نتیجه را در قالب JSON دریافت کنید

### 3. استفاده از API

#### روش Python:

```python
from gradio_client import Client

# آدرس Space خود را وارد کنید
client = Client("YOUR_USERNAME/YOUR_SPACE_NAME")

# پردازش تصویر
result = client.predict(
    image="path/to/your/image.jpg",
    prompt_type="Full Layout + OCR (English)",
    custom_prompt="",
    api_name="/predict"
)

print(result)
```

#### استفاده از اسکریپت آماده:

```bash
# نصب کتابخانه
pip install gradio_client

# اجرای اسکریپت
python api_example.py \
    --image your_document.jpg \
    --space-url YOUR_SPACE_URL \
    --prompt-type "Full Layout + OCR (English)"
```

### 4. استفاده از cURL:

```bash
curl -X POST "YOUR_SPACE_URL/api/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"path": "base64_encoded_image_or_url"},
      "Full Layout + OCR (English)",
      ""
    ]
  }'
```

## فرمت خروجی

### Full Layout + OCR:

```json
[
  {
    "bbox": [x1, y1, x2, y2],
    "category": "Text",
    "text": "محتوای متن..."
  },
  {
    "bbox": [x1, y1, x2, y2],
    "category": "Table",
    "text": "<table>...</table>"
  },
  {
    "bbox": [x1, y1, x2, y2],
    "category": "Formula",
    "text": "\\LaTeX{formula}"
  }
]
```

## نکات مهم

1. **کیفیت تصویر**: برای نتایج بهتر از تصاویر با کیفیت بالا استفاده کنید
2. **رزولوشن**: حداکثر 11,289,600 پیکسل توصیه می‌شود
3. **زبان**: مدل از زبان‌های متعدد پشتیبانی می‌کند
4. **PDF**: فایل‌های PDF با DPI=200 بهترین نتیجه را می‌دهند

## عیب‌یابی

### خطای Out of Memory:
- سایز تصویر را کاهش دهید
- از GPU بزرگتری استفاده کنید

### خروجی نادرست:
- پرامپت دیگری امتحان کنید
- کیفیت تصویر را بهبود دهید

### مدل لود نمی‌شود:
- مطمئن شوید GPU فعال است
- صبر کنید تا مدل دانلود شود (اولین بار کمی طول می‌کشد)

## پشتیبانی

- GitHub: https://github.com/rednote-hilab/dots.ocr
- Hugging Face Model: https://huggingface.co/rednote-hilab/DotsOCR

## مثال‌های کاربردی

### 1. استخراج متن از فاکتور:
```python
result = client.predict(
    image="invoice.jpg",
    prompt_type="Full Layout + OCR (English)",
    custom_prompt=""
)
```

### 2. تشخیص فرمول‌های ریاضی:
```python
result = client.predict(
    image="math_document.png",
    prompt_type="Full Layout + OCR (English)",
    custom_prompt=""
)
# فرمول‌ها به فرمت LaTeX استخراج می‌شوند
```

### 3. استخراج جداول:
```python
result = client.predict(
    image="table_document.jpg",
    prompt_type="Full Layout + OCR (English)",
    custom_prompt=""
)
# جداول به فرمت HTML استخراج می‌شوند
```