Initial commit of img2cbz script and documentation

README.md

@@ -0,0 +1,74 @@
+# img2cbz: Folder to CBZ Archive Converter
+
+`img2cbz` is a powerful, user-friendly Python command-line utility to convert folders of images (including WebP, JPEG, PNG, GIF, BMP, and TIFF) into CBZ (Comic Book Zip) archives. It is located at [img2cbz](file:///var/home/david/.local/bin/img2cbz) and is globally runnable from the terminal.
+
+## Key Features
+
+- **Multi-Format Support**: Processes `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.bmp`, and `.tiff`.
+- **Natural Sorting (Alphanumeric)**: Sorts filenames naturally (e.g., `page_2.png` comes before `page_10.png` rather than alphabetical order).
+- **Parallel Image Conversion**: Convert images to `webp`, `jpg`, or `png` in parallel using multithreading.
+  - **Space Saving**: Converting images to WebP can compress the CBZ size by 30-70% with virtually no loss in quality.
+  - **Maximum Compatibility**: Convert WebP/PNG to JPEG with automatic transparency flattening (pasting transparent images over a solid white background to avoid black-background issues).
+- **Recursive Mode (`-r`)**: Scan a parent directory recursively to locate all directories that contain image files, converting each folder into its own CBZ archive.
+- **Dry-Run Mode (`-d`)**: Safely test commands and see what files would be processed and where archives would be saved without making modifications.
+- **Interactive Mode**: If run without arguments, it launches a step-by-step interactive setup wizard guiding you through configuration.
+- **Verify & Clean (`--clean`)**: Safely deletes source folders only after verifying the created CBZ archive is complete, uncorrupted, and has a matching file count.
+
+---
+
+## Command-Line Arguments Reference
+
+| Option | Long Option | Description |
+| :--- | :--- | :--- |
+| `DIR` | | One or more folders containing images to convert. |
+| `-r` | `--recursive` | Find subdirectories containing images and convert each to a CBZ. |
+| `-o` | `--output-dir` | Path to save CBZ files (defaults to next to each source folder). |
+| `-e` | `--extensions` | Comma-separated list of image extensions to scan (default: all). |
+| `-c` | `--convert` | Convert images to `webp`, `jpg`, or `png` before archiving. |
+| `-q` | `--quality` | Compression quality (`1`-`100`) for WebP/JPEG conversions (default: `85`). |
+| `-j` | `--jobs` | Number of parallel threads to use for conversion (default: CPU core count). |
+| `--overwrite` | | Replace existing `.cbz` files if they exist. |
+| `--clean` | | Delete source folders after successful CBZ creation & integrity checks. |
+| `-d` | `--dry-run` | Show planned archive creations and image conversions without executing them. |
+| `--verbose` | | Print debug information. |
+| `--quiet` | | Suppress standard log output (only outputs errors). |
+
+---
+
+## Common Usage Examples
+
+### 1. Simple Single-Folder Conversion
+Create `Chapter_01.cbz` in the same directory as `Chapter_01/`:
+```bash
+img2cbz Chapter_01/
+```
+
+### 2. Recursive Multi-Folder Conversion
+Convert all subdirectories containing images in a series folder (e.g., `Manga_Series/Volume_1/Chapter_1/`, `Manga_Series/Volume_1/Chapter_2/`) into separate CBZ archives (`Chapter_1.cbz`, `Chapter_2.cbz`):
+```bash
+img2cbz -r Manga_Series/
+```
+
+### 3. Compress Archives to WebP
+Convert all images to space-saving WebP format with `80%` quality during archiving:
+```bash
+img2cbz -c webp -q 80 Chapter_01/
+```
+
+### 4. Output to a Specific Directory
+Save all created CBZ archives in a separate `Comics/` folder instead of next to the source directories:
+```bash
+img2cbz -r -o ~/Comics/ Manga_Series/
+```
+
+### 5. Safe Conversion & Cleanup
+Convert to WebP, save to a separate directory, verify archives, and then delete the original uncompressed source folders:
+```bash
+img2cbz -r -c webp -o ~/Comics/ --clean Manga_Series/
+```
+
+### 6. Dry Run (Test First)
+Preview which folders and images would be processed by a command:
+```bash
+img2cbz -r -c webp -o ~/Comics/ --clean -d Manga_Series/
+```