binimage 1.6.0
Extract binary from images (OCR or grid) and decode to text, saving to results.txt
License: MIT
Requires Python: >=3.9
Keywords: binary, image, OCR, grid, decode, persian, english

# binimage

کتابخانه‌ای برای استخراج و رمزگشایی کد باینری از تصاویر.  
پشتیبانی از سه حالت: **OCR** (خواندن مستقیم `0` و `1`)، **Grid** (تحلیل شبکه‌ای پیکسل‌ها) و **LSB** (استخراج بیت‌های کم‌اهمیت از تصاویر طبیعی/استگانوگرافی).
### تزریق (LSB Embed)
برای قراردادن متن/داده در تصویر با LSB:

CLI:
```bash
binimage in.png --mode lsb --embed --payload "سلام دنیا" --embed-out stego.png
# از فایل:
binimage in.png --mode lsb --embed --payload @message.txt --embed-out stego.png
```

API:
```python
from binimage import lsb_embed

out_img = lsb_embed(
    "in.png",
    payload="سلام دنیا",
    channels="RGB",
    bit_index=0,
    step=1,
    msb_first=True,
    bits_per_byte=8,
    ensure_utf8_text=True,
)
out_img.save("stego.png")
```

---

## نصب

می‌توانید کتابخانه را با یکی از روش‌های زیر نصب کنید:

```bash
pip install binimage
```
یا
```bash
python -m pip install binimage
```

---

## استفاده

### از طریق خط فرمان (CLI)

```bash
binimage path/to/image.png --mode auto --language fa
```

**پارامترهای مهم:**
- `image` (اجباری): مسیر تصویر ورودی
- `--mode` : حالت استخراج (`auto`، `ocr`، `grid` یا `lsb`)
- `--language` : ترجیح زبان سطح‌بالا (`fa` یا `en`) تا پیش‌فرض‌های مناسب OCR/دیکد تنظیم شود
- `--ocr-lang` : زبان OCR (مثلاً `eng` یا `fas`)؛ اگر تعیین شود بر `--language` غلبه می‌کند
- `--rows` و `--cols` : تعداد سطر/ستون شبکه در حالت `grid`
- `--invert` : معکوس کردن نگاشت رنگ به بیت
- `--out` : مسیر فایل خروجی (پیش‌فرض `results.txt`)
- `--encodings` : ترتیب دلخواه برای دیکد متن (مثلاً `utf-8 utf-16le utf-16be latin-1`)
- `--errors` : نحوه‌ی برخورد با خطاهای دیکد (یکی از `strict`، `ignore`، `replace`)
  
پارامترهای حالت LSB:
- `--lsb-channels` کانال‌ها برای استخراج (مثل `RGB` یا `R`)
- `--lsb-bit` شماره بیت از هر کانال (۰ یعنی LSB)
- `--lsb-step` نمونه‌برداری هر N مقدار یک‌بار
- `--lsb-max-bits` سقف تعداد بیت استخراجی
- `--stop-at-null` توقف در اولین بایت صفر قبل از دیکد متن

مثال:
```bash
# Grid نمونه
binimage ./binary_image.png --mode grid --rows 20 --cols 40 --out output.txt --encodings utf-8 utf-16le utf-16be latin-1 --errors strict

# LSB نمونه برای تصویر طبیعی (استگانو)
binimage ./photo.png --mode lsb --lsb-channels RGB --lsb-bit 0 --lsb-step 1 --stop-at-null --out output.txt

# نوشتن بیت‌های خام در فایل خروجی و سپس متن دیکد شده
binimage ./photo.png --mode lsb --include-bits --out results.txt
```

---

### استفاده در پایتون (API)

```python
from binimage import decode_image

result = decode_image(
    image_path="image.png",
    mode="auto",        # "auto" | "ocr" | "grid" | "lsb"
    language="fa",       # fa | en (پیش‌فرض‌های مناسب اعمال می‌شود)
    ocr_lang=None,        # در صورت نیاز override کنید، مثلاً "fas" یا "eng"
    rows=None,
    cols=None,
    invert=False,
    bits_per_byte=8,
    msb_first=True,
    out_file="results.txt",  # اگر نخواهید در فایل ذخیره شود: None
    encodings=("utf-8", "utf-16le", "utf-16be", "latin-1"),
    errors="strict",
)

print("Encoding:", result.encoding)
print("Decoded text:", result.text)
```

---

### خروجی

پس از اجرا، متن استخراج‌شده در فایل مشخص‌شده (`results.txt` یا هر مسیر دلخواه) ذخیره می‌شود. اگر `out_file=None` بدهید، چیزی در دیسک نوشته نمی‌شود و می‌توانید `result.text` و `result.bits` را مستقیم استفاده کنید. اگر متن شما دارای BOM باشد (UTF-8 یا UTF-16)، به صورت خودکار تشخیص و به‌درستی دیکد می‌شود.

### دریافت بیت‌های خام (LSB)
```python
from binimage import decode_image

res = decode_image(
	"your_image.png",
	mode="lsb",
	lsb_channels="RGB",
	lsb_bit=0,
	lsb_step=1,
	stop_at_null=True,
	msb_first=True,
	out_file="results.txt",
	include_bits_in_output=False,
)

print(res.text) # دریافت خروجی به صورت باینری
```

در CLI می‌توانید بیت‌های خام را چاپ کنید:
```bash
binimage image.png --mode lsb --print-bits --out ""
```