Fix: Replace deprecated getsize() with getbbox() for Pillow 10+ compatibility (Added requirements.txt file; updated README.md and .gitignore)

.gitignore

@@ -0,0 +1,2 @@
+venv/
+__pycache__/

README.md

@@ -117,7 +117,110 @@ By running the sript **img2img_color.py** or **img2img.py** with different value
 
 ## Requirements
 
-* **python 3.6**
-* **cv2**
-* **PIL** 
+* **Python 3.6+**
+* **opencv-python**
+* **Pillow** 
 * **numpy**
+
+## Installation
+
+### 1. Clone the repository
+```bash
+git clone https://github.com/uvipen/ASCII-generator.git
+cd ASCII-generator
+```
+
+### 2. Create a virtual environment (recommended)
+```bash
+python -m venv venv
+
+# Windows
+venv\Scripts\activate
+
+# macOS/Linux
+source venv/bin/activate
+```
+
+### 3. Install dependencies
+```bash
+pip install -r requirements.txt
+```
+
+## Usage
+
+### Image to Text (ASCII .txt output)
+```bash
+python img2txt.py --input data/input.jpg --output output/result.txt --mode complex --num_cols 150
+```
+
+**Arguments:**
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `--input` | `data/input.jpg` | Path to input image |
+| `--output` | `data/output.txt` | Path to output text file |
+| `--mode` | `complex` | `simple` (10 chars) or `complex` (70 chars) |
+| `--num_cols` | `150` | Number of characters for output width |
+
+---
+
+### Image to Image (ASCII .jpg/.png output)
+
+**Grayscale:**
+```bash
+python img2img.py --input data/input.jpg --output output/result.jpg --background black --num_cols 300
+```
+
+**Color:**
+```bash
+python img2img_color.py --input data/input.jpg --output output/result.jpg --background black --num_cols 300 --language english
+```
+
+**Arguments:**
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `--input` | `data/input.jpg` | Path to input image |
+| `--output` | `data/output.jpg` | Path to output image |
+| `--language` | `english` | Language alphabet (english, german, french, korean, chinese, japanese, russian, spanish, etc.) |
+| `--mode` | `standard` | Character mode |
+| `--background` | `black` | `black` or `white` background |
+| `--num_cols` | `300` | Number of characters for output width |
+| `--scale` | `2` | Upscale output (only in color version) |
+
+---
+
+### Video to Video (ASCII .mp4/.avi output)
+
+**Grayscale:**
+```bash
+python video2video.py --input data/input.mp4 --output output/result.mp4 --mode simple --background white --num_cols 100
+```
+
+**Color:**
+```bash
+python video2video_color.py --input data/input.mp4 --output output/result.mp4 --mode complex --background black --num_cols 100
+```
+
+**Arguments:**
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `--input` | `data/input.mp4` | Path to input video |
+| `--output` | `data/output.mp4` | Path to output video |
+| `--mode` | `simple`/`complex` | `simple` (10 chars) or `complex` (70 chars) |
+| `--background` | `white`/`black` | `black` or `white` background |
+| `--num_cols` | `100` | Number of characters for output width |
+| `--scale` | `1` | Upscale output |
+| `--fps` | `0` | Frame rate (0 = use original) |
+| `--overlay_ratio` | `0.2` | Size of original video overlay (0 to disable) |
+
+## Examples
+
+```bash
+# Simple black & white ASCII from image
+python img2img.py --input my_photo.jpg --output ascii_photo.png --background white --num_cols 200
+
+# Colorful Japanese ASCII art
+python img2img_color.py --input anime.jpg --output anime_ascii.jpg --language japanese --num_cols 400
+
+# Convert a video with color ASCII
+python video2video_color.py --input video.mp4 --output ascii_video.avi --num_cols 150 --overlay_ratio 0.15
+```

img2img.py

@@ -41,7 +41,8 @@ def main(opt):
         cell_height = 12
         num_cols = int(width / cell_width)
         num_rows = int(height / cell_height)
-    char_width, char_height = font.getsize(sample_character)
+    bbox = font.getbbox(sample_character)
+    char_width, char_height = bbox[2] - bbox[0], bbox[3] - bbox[1]
     out_width = char_width * num_cols
     out_height = scale * char_height * num_rows
     out_image = Image.new("L", (out_width, out_height), bg_code)

img2img_color.py

@@ -43,7 +43,8 @@ def main(opt):
         cell_height = 12
         num_cols = int(width / cell_width)
         num_rows = int(height / cell_height)
-    char_width, char_height = font.getsize(sample_character)
+    bbox = font.getbbox(sample_character)
+    char_width, char_height = bbox[2] - bbox[0], bbox[3] - bbox[1]
     out_width = char_width * num_cols
     out_height = scale * char_height * num_rows
     out_image = Image.new("RGB", (out_width, out_height), bg_code)

requirements.txt

@@ -0,0 +1,5 @@
+# ASCII Generator Dependencies
+opencv-python>=4.5.0
+numpy>=1.19.0
+Pillow>=8.0.0
+

utils.py

@@ -4,15 +4,16 @@
 
 def sort_chars(char_list, font, language):
     if language == "chinese":
-        char_width, char_height = font.getsize("制")
+        bbox = font.getbbox("制")
     elif language == "korean":
-        char_width, char_height = font.getsize("ㅊ")
+        bbox = font.getbbox("ㅊ")
     elif language == "japanese":
-        char_width, char_height = font.getsize("あ")
+        bbox = font.getbbox("あ")
     elif language in ["english", "german", "french", "spanish", "italian", "portuguese", "polish"]:
-        char_width, char_height = font.getsize("A")
+        bbox = font.getbbox("A")
     elif language == "russian":
-        char_width, char_height = font.getsize("A")
+        bbox = font.getbbox("A")
+    char_width, char_height = bbox[2] - bbox[0], bbox[3] - bbox[1]
     num_chars = min(len(char_list), 100)
     out_width = char_width * len(char_list)
     out_height = char_height

video2video.py

@@ -57,7 +57,8 @@ def main(opt):
             cell_height = 12
             num_cols = int(width / cell_width)
             num_rows = int(height / cell_height)
-        char_width, char_height = font.getsize("A")
+        bbox = font.getbbox("A")
+        char_width, char_height = bbox[2] - bbox[0], bbox[3] - bbox[1]
         out_width = char_width * num_cols
         out_height = 2 * char_height * num_rows
         out_image = Image.new("L", (out_width, out_height), bg_code)

video2video_color.py

@@ -57,7 +57,8 @@ def main(opt):
             cell_height = 12
             num_cols = int(width / cell_width)
             num_rows = int(height / cell_height)
-        char_width, char_height = font.getsize("A")
+        bbox = font.getbbox("A")
+        char_width, char_height = bbox[2] - bbox[0], bbox[3] - bbox[1]
         out_width = char_width * num_cols
         out_height = 2 * char_height * num_rows
         out_image = Image.new("RGB", (out_width, out_height), bg_code)