| Name | binimage JSON |
| Version |
1.6.0
JSON |
| download |
| home_page | None |
| Summary | Extract binary from images (OCR or grid) and decode to text, saving to results.txt |
| upload_time | 2025-08-14 05:52:33 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
binary
image
ocr
grid
decode
persian
english
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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 ""
```
Raw data
{
"_id": null,
"home_page": null,
"name": "binimage",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "binary, image, OCR, grid, decode, persian, english",
"author": null,
"author_email": "vesper <vesper.oneold@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d1/cb/2cf352fcc26532b428777f725cde84fc37245b32e59e1ce328f4d3debd7f/binimage-1.6.0.tar.gz",
"platform": null,
"description": "# binimage\r\n\r\n\u06a9\u062a\u0627\u0628\u062e\u0627\u0646\u0647\u200c\u0627\u06cc \u0628\u0631\u0627\u06cc \u0627\u0633\u062a\u062e\u0631\u0627\u062c \u0648 \u0631\u0645\u0632\u06af\u0634\u0627\u06cc\u06cc \u06a9\u062f \u0628\u0627\u06cc\u0646\u0631\u06cc \u0627\u0632 \u062a\u0635\u0627\u0648\u06cc\u0631. \r\n\u067e\u0634\u062a\u06cc\u0628\u0627\u0646\u06cc \u0627\u0632 \u0633\u0647 \u062d\u0627\u0644\u062a: **OCR** (\u062e\u0648\u0627\u0646\u062f\u0646 \u0645\u0633\u062a\u0642\u06cc\u0645 `0` \u0648 `1`)\u060c **Grid** (\u062a\u062d\u0644\u06cc\u0644 \u0634\u0628\u06a9\u0647\u200c\u0627\u06cc \u067e\u06cc\u06a9\u0633\u0644\u200c\u0647\u0627) \u0648 **LSB** (\u0627\u0633\u062a\u062e\u0631\u0627\u062c \u0628\u06cc\u062a\u200c\u0647\u0627\u06cc \u06a9\u0645\u200c\u0627\u0647\u0645\u06cc\u062a \u0627\u0632 \u062a\u0635\u0627\u0648\u06cc\u0631 \u0637\u0628\u06cc\u0639\u06cc/\u0627\u0633\u062a\u06af\u0627\u0646\u0648\u06af\u0631\u0627\u0641\u06cc).\r\n### \u062a\u0632\u0631\u06cc\u0642 (LSB Embed)\r\n\u0628\u0631\u0627\u06cc \u0642\u0631\u0627\u0631\u062f\u0627\u062f\u0646 \u0645\u062a\u0646/\u062f\u0627\u062f\u0647 \u062f\u0631 \u062a\u0635\u0648\u06cc\u0631 \u0628\u0627 LSB:\r\n\r\nCLI:\r\n```bash\r\nbinimage in.png --mode lsb --embed --payload \"\u0633\u0644\u0627\u0645 \u062f\u0646\u06cc\u0627\" --embed-out stego.png\r\n# \u0627\u0632 \u0641\u0627\u06cc\u0644:\r\nbinimage in.png --mode lsb --embed --payload @message.txt --embed-out stego.png\r\n```\r\n\r\nAPI:\r\n```python\r\nfrom binimage import lsb_embed\r\n\r\nout_img = lsb_embed(\r\n \"in.png\",\r\n payload=\"\u0633\u0644\u0627\u0645 \u062f\u0646\u06cc\u0627\",\r\n channels=\"RGB\",\r\n bit_index=0,\r\n step=1,\r\n msb_first=True,\r\n bits_per_byte=8,\r\n ensure_utf8_text=True,\r\n)\r\nout_img.save(\"stego.png\")\r\n```\r\n\r\n---\r\n\r\n## \u0646\u0635\u0628\r\n\r\n\u0645\u06cc\u200c\u062a\u0648\u0627\u0646\u06cc\u062f \u06a9\u062a\u0627\u0628\u062e\u0627\u0646\u0647 \u0631\u0627 \u0628\u0627 \u06cc\u06a9\u06cc \u0627\u0632 \u0631\u0648\u0634\u200c\u0647\u0627\u06cc \u0632\u06cc\u0631 \u0646\u0635\u0628 \u06a9\u0646\u06cc\u062f:\r\n\r\n```bash\r\npip install binimage\r\n```\r\n\u06cc\u0627\r\n```bash\r\npython -m pip install binimage\r\n```\r\n\r\n---\r\n\r\n## \u0627\u0633\u062a\u0641\u0627\u062f\u0647\r\n\r\n### \u0627\u0632 \u0637\u0631\u06cc\u0642 \u062e\u0637 \u0641\u0631\u0645\u0627\u0646 (CLI)\r\n\r\n```bash\r\nbinimage path/to/image.png --mode auto --language fa\r\n```\r\n\r\n**\u067e\u0627\u0631\u0627\u0645\u062a\u0631\u0647\u0627\u06cc \u0645\u0647\u0645:**\r\n- `image` (\u0627\u062c\u0628\u0627\u0631\u06cc): \u0645\u0633\u06cc\u0631 \u062a\u0635\u0648\u06cc\u0631 \u0648\u0631\u0648\u062f\u06cc\r\n- `--mode` : \u062d\u0627\u0644\u062a \u0627\u0633\u062a\u062e\u0631\u0627\u062c (`auto`\u060c `ocr`\u060c `grid` \u06cc\u0627 `lsb`)\r\n- `--language` : \u062a\u0631\u062c\u06cc\u062d \u0632\u0628\u0627\u0646 \u0633\u0637\u062d\u200c\u0628\u0627\u0644\u0627 (`fa` \u06cc\u0627 `en`) \u062a\u0627 \u067e\u06cc\u0634\u200c\u0641\u0631\u0636\u200c\u0647\u0627\u06cc \u0645\u0646\u0627\u0633\u0628 OCR/\u062f\u06cc\u06a9\u062f \u062a\u0646\u0638\u06cc\u0645 \u0634\u0648\u062f\r\n- `--ocr-lang` : \u0632\u0628\u0627\u0646 OCR (\u0645\u062b\u0644\u0627\u064b `eng` \u06cc\u0627 `fas`)\u061b \u0627\u06af\u0631 \u062a\u0639\u06cc\u06cc\u0646 \u0634\u0648\u062f \u0628\u0631 `--language` \u063a\u0644\u0628\u0647 \u0645\u06cc\u200c\u06a9\u0646\u062f\r\n- `--rows` \u0648 `--cols` : \u062a\u0639\u062f\u0627\u062f \u0633\u0637\u0631/\u0633\u062a\u0648\u0646 \u0634\u0628\u06a9\u0647 \u062f\u0631 \u062d\u0627\u0644\u062a `grid`\r\n- `--invert` : \u0645\u0639\u06a9\u0648\u0633 \u06a9\u0631\u062f\u0646 \u0646\u06af\u0627\u0634\u062a \u0631\u0646\u06af \u0628\u0647 \u0628\u06cc\u062a\r\n- `--out` : \u0645\u0633\u06cc\u0631 \u0641\u0627\u06cc\u0644 \u062e\u0631\u0648\u062c\u06cc (\u067e\u06cc\u0634\u200c\u0641\u0631\u0636 `results.txt`)\r\n- `--encodings` : \u062a\u0631\u062a\u06cc\u0628 \u062f\u0644\u062e\u0648\u0627\u0647 \u0628\u0631\u0627\u06cc \u062f\u06cc\u06a9\u062f \u0645\u062a\u0646 (\u0645\u062b\u0644\u0627\u064b `utf-8 utf-16le utf-16be latin-1`)\r\n- `--errors` : \u0646\u062d\u0648\u0647\u200c\u06cc \u0628\u0631\u062e\u0648\u0631\u062f \u0628\u0627 \u062e\u0637\u0627\u0647\u0627\u06cc \u062f\u06cc\u06a9\u062f (\u06cc\u06a9\u06cc \u0627\u0632 `strict`\u060c `ignore`\u060c `replace`)\r\n \r\n\u067e\u0627\u0631\u0627\u0645\u062a\u0631\u0647\u0627\u06cc \u062d\u0627\u0644\u062a LSB:\r\n- `--lsb-channels` \u06a9\u0627\u0646\u0627\u0644\u200c\u0647\u0627 \u0628\u0631\u0627\u06cc \u0627\u0633\u062a\u062e\u0631\u0627\u062c (\u0645\u062b\u0644 `RGB` \u06cc\u0627 `R`)\r\n- `--lsb-bit` \u0634\u0645\u0627\u0631\u0647 \u0628\u06cc\u062a \u0627\u0632 \u0647\u0631 \u06a9\u0627\u0646\u0627\u0644 (\u06f0 \u06cc\u0639\u0646\u06cc LSB)\r\n- `--lsb-step` \u0646\u0645\u0648\u0646\u0647\u200c\u0628\u0631\u062f\u0627\u0631\u06cc \u0647\u0631 N \u0645\u0642\u062f\u0627\u0631 \u06cc\u06a9\u200c\u0628\u0627\u0631\r\n- `--lsb-max-bits` \u0633\u0642\u0641 \u062a\u0639\u062f\u0627\u062f \u0628\u06cc\u062a \u0627\u0633\u062a\u062e\u0631\u0627\u062c\u06cc\r\n- `--stop-at-null` \u062a\u0648\u0642\u0641 \u062f\u0631 \u0627\u0648\u0644\u06cc\u0646 \u0628\u0627\u06cc\u062a \u0635\u0641\u0631 \u0642\u0628\u0644 \u0627\u0632 \u062f\u06cc\u06a9\u062f \u0645\u062a\u0646\r\n\r\n\u0645\u062b\u0627\u0644:\r\n```bash\r\n# Grid \u0646\u0645\u0648\u0646\u0647\r\nbinimage ./binary_image.png --mode grid --rows 20 --cols 40 --out output.txt --encodings utf-8 utf-16le utf-16be latin-1 --errors strict\r\n\r\n# LSB \u0646\u0645\u0648\u0646\u0647 \u0628\u0631\u0627\u06cc \u062a\u0635\u0648\u06cc\u0631 \u0637\u0628\u06cc\u0639\u06cc (\u0627\u0633\u062a\u06af\u0627\u0646\u0648)\r\nbinimage ./photo.png --mode lsb --lsb-channels RGB --lsb-bit 0 --lsb-step 1 --stop-at-null --out output.txt\r\n\r\n# \u0646\u0648\u0634\u062a\u0646 \u0628\u06cc\u062a\u200c\u0647\u0627\u06cc \u062e\u0627\u0645 \u062f\u0631 \u0641\u0627\u06cc\u0644 \u062e\u0631\u0648\u062c\u06cc \u0648 \u0633\u067e\u0633 \u0645\u062a\u0646 \u062f\u06cc\u06a9\u062f \u0634\u062f\u0647\r\nbinimage ./photo.png --mode lsb --include-bits --out results.txt\r\n```\r\n\r\n---\r\n\r\n### \u0627\u0633\u062a\u0641\u0627\u062f\u0647 \u062f\u0631 \u067e\u0627\u06cc\u062a\u0648\u0646 (API)\r\n\r\n```python\r\nfrom binimage import decode_image\r\n\r\nresult = decode_image(\r\n image_path=\"image.png\",\r\n mode=\"auto\", # \"auto\" | \"ocr\" | \"grid\" | \"lsb\"\r\n language=\"fa\", # fa | en (\u067e\u06cc\u0634\u200c\u0641\u0631\u0636\u200c\u0647\u0627\u06cc \u0645\u0646\u0627\u0633\u0628 \u0627\u0639\u0645\u0627\u0644 \u0645\u06cc\u200c\u0634\u0648\u062f)\r\n ocr_lang=None, # \u062f\u0631 \u0635\u0648\u0631\u062a \u0646\u06cc\u0627\u0632 override \u06a9\u0646\u06cc\u062f\u060c \u0645\u062b\u0644\u0627\u064b \"fas\" \u06cc\u0627 \"eng\"\r\n rows=None,\r\n cols=None,\r\n invert=False,\r\n bits_per_byte=8,\r\n msb_first=True,\r\n out_file=\"results.txt\", # \u0627\u06af\u0631 \u0646\u062e\u0648\u0627\u0647\u06cc\u062f \u062f\u0631 \u0641\u0627\u06cc\u0644 \u0630\u062e\u06cc\u0631\u0647 \u0634\u0648\u062f: None\r\n encodings=(\"utf-8\", \"utf-16le\", \"utf-16be\", \"latin-1\"),\r\n errors=\"strict\",\r\n)\r\n\r\nprint(\"Encoding:\", result.encoding)\r\nprint(\"Decoded text:\", result.text)\r\n```\r\n\r\n---\r\n\r\n### \u062e\u0631\u0648\u062c\u06cc\r\n\r\n\u067e\u0633 \u0627\u0632 \u0627\u062c\u0631\u0627\u060c \u0645\u062a\u0646 \u0627\u0633\u062a\u062e\u0631\u0627\u062c\u200c\u0634\u062f\u0647 \u062f\u0631 \u0641\u0627\u06cc\u0644 \u0645\u0634\u062e\u0635\u200c\u0634\u062f\u0647 (`results.txt` \u06cc\u0627 \u0647\u0631 \u0645\u0633\u06cc\u0631 \u062f\u0644\u062e\u0648\u0627\u0647) \u0630\u062e\u06cc\u0631\u0647 \u0645\u06cc\u200c\u0634\u0648\u062f. \u0627\u06af\u0631 `out_file=None` \u0628\u062f\u0647\u06cc\u062f\u060c \u0686\u06cc\u0632\u06cc \u062f\u0631 \u062f\u06cc\u0633\u06a9 \u0646\u0648\u0634\u062a\u0647 \u0646\u0645\u06cc\u200c\u0634\u0648\u062f \u0648 \u0645\u06cc\u200c\u062a\u0648\u0627\u0646\u06cc\u062f `result.text` \u0648 `result.bits` \u0631\u0627 \u0645\u0633\u062a\u0642\u06cc\u0645 \u0627\u0633\u062a\u0641\u0627\u062f\u0647 \u06a9\u0646\u06cc\u062f. \u0627\u06af\u0631 \u0645\u062a\u0646 \u0634\u0645\u0627 \u062f\u0627\u0631\u0627\u06cc BOM \u0628\u0627\u0634\u062f (UTF-8 \u06cc\u0627 UTF-16)\u060c \u0628\u0647 \u0635\u0648\u0631\u062a \u062e\u0648\u062f\u06a9\u0627\u0631 \u062a\u0634\u062e\u06cc\u0635 \u0648 \u0628\u0647\u200c\u062f\u0631\u0633\u062a\u06cc \u062f\u06cc\u06a9\u062f \u0645\u06cc\u200c\u0634\u0648\u062f.\r\n\r\n### \u062f\u0631\u06cc\u0627\u0641\u062a \u0628\u06cc\u062a\u200c\u0647\u0627\u06cc \u062e\u0627\u0645 (LSB)\r\n```python\r\nfrom binimage import decode_image\r\n\r\nres = decode_image(\r\n\t\"your_image.png\",\r\n\tmode=\"lsb\",\r\n\tlsb_channels=\"RGB\",\r\n\tlsb_bit=0,\r\n\tlsb_step=1,\r\n\tstop_at_null=True,\r\n\tmsb_first=True,\r\n\tout_file=\"results.txt\",\r\n\tinclude_bits_in_output=False,\r\n)\r\n\r\nprint(res.text) # \u062f\u0631\u06cc\u0627\u0641\u062a \u062e\u0631\u0648\u062c\u06cc \u0628\u0647 \u0635\u0648\u0631\u062a \u0628\u0627\u06cc\u0646\u0631\u06cc\r\n```\r\n\r\n\u062f\u0631 CLI \u0645\u06cc\u200c\u062a\u0648\u0627\u0646\u06cc\u062f \u0628\u06cc\u062a\u200c\u0647\u0627\u06cc \u062e\u0627\u0645 \u0631\u0627 \u0686\u0627\u067e \u06a9\u0646\u06cc\u062f:\r\n```bash\r\nbinimage image.png --mode lsb --print-bits --out \"\"\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Extract binary from images (OCR or grid) and decode to text, saving to results.txt",
"version": "1.6.0",
"project_urls": null,
"split_keywords": [
"binary",
" image",
" ocr",
" grid",
" decode",
" persian",
" english"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eddf0a47ec1bb2057c400a12459bd67bd62c8f7b75e54d0c44a1a6b4d0038e65",
"md5": "c850a570fa1a05d70e4b340a1d84125b",
"sha256": "2e593aefc06dff3b38698f79c30649dca44ffb3bc5887f4d581fbc8c5ffc77fb"
},
"downloads": -1,
"filename": "binimage-1.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c850a570fa1a05d70e4b340a1d84125b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 12562,
"upload_time": "2025-08-14T05:52:32",
"upload_time_iso_8601": "2025-08-14T05:52:32.650277Z",
"url": "https://files.pythonhosted.org/packages/ed/df/0a47ec1bb2057c400a12459bd67bd62c8f7b75e54d0c44a1a6b4d0038e65/binimage-1.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d1cb2cf352fcc26532b428777f725cde84fc37245b32e59e1ce328f4d3debd7f",
"md5": "82a1ce324da95b3879f86790212fbc54",
"sha256": "5a3deccd62abb9da0a759c3616a0c9e5050cb27eed9355b337f1c35318dd4ee8"
},
"downloads": -1,
"filename": "binimage-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "82a1ce324da95b3879f86790212fbc54",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13473,
"upload_time": "2025-08-14T05:52:33",
"upload_time_iso_8601": "2025-08-14T05:52:33.621059Z",
"url": "https://files.pythonhosted.org/packages/d1/cb/2cf352fcc26532b428777f725cde84fc37245b32e59e1ce328f4d3debd7f/binimage-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 05:52:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "binimage"
}
