imagex 0.1.0__tar.gz

imagex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kushal Baral
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

imagex-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: imagex
+Version: 0.1.0
+Summary: Image processing CLI tool - right in your terminal
+Author: kushal1o1
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0
+Requires-Dist: questionary>=2.0
+Requires-Dist: Pillow>=10.0
+Provides-Extra: heif
+Requires-Dist: pillow-heif>=0.16; extra == "heif"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: pillow-heif>=0.16; extra == "dev"
+Dynamic: license-file
+
+```
+██╗███╗   ███╗ █████╗  ██████╗ ███████╗██╗  ██╗
+██║████╗ ████║██╔══██╗██╔════╝ ██╔════╝╚██╗██╔╝
+██║██╔████╔██║███████║██║  ███╗█████╗   ╚███╔╝
+██║██║╚██╔╝██║██╔══██║██║   ██║██╔══╝   ██╔██╗
+██║██║ ╚═╝ ██║██║  ██║╚██████╔╝███████╗██╔╝ ██╗
+╚═╝╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝
+```
+
+Image processing CLI tool — right in your terminal.
+
+```bash
+pip install .
+imagex
+```
+
+Navigate to any folder with images and run `imagex`.
+
+## Features
+
+| Feature | Description |
+|---|---|
+| Remove Metadata | Strip EXIF/XMP/IPTC (incl. AI generation markers) |
+| Convert Format | JPG ↔ PNG ↔ WEBP ↔ TIFF ↔ BMP ↔ GIF ↔ HEIC |
+| Compress / Optimize | Reduce file size with quality slider |
+| Resize | Percentage, exact dimensions, fit within bounds |
+| Rename Batch | Pattern-based renaming (%n, %o) |
+| Add Noise | Gaussian or salt & pepper (bypass AI detection) |
+| Watermark | Add text/image or remove existing |
+
+Full details in [OPERATIONS.md](OPERATIONS.md).
+
+## Install
+
+```bash
+# From the repo directory
+pip install .
+
+# Dev mode (changes take effect immediately)
+pip install -e .
+```
+
+Then run `imagex` from any folder.
+
+## Adding Features
+
+See [CONTRIBUTION.md](CONTRIBUTION.md) for the contribution guide.
+
+## License
+
+MIT

imagex-0.1.0/README.md

@@ -0,0 +1,51 @@
+```
+██╗███╗   ███╗ █████╗  ██████╗ ███████╗██╗  ██╗
+██║████╗ ████║██╔══██╗██╔════╝ ██╔════╝╚██╗██╔╝
+██║██╔████╔██║███████║██║  ███╗█████╗   ╚███╔╝
+██║██║╚██╔╝██║██╔══██║██║   ██║██╔══╝   ██╔██╗
+██║██║ ╚═╝ ██║██║  ██║╚██████╔╝███████╗██╔╝ ██╗
+╚═╝╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝
+```
+
+Image processing CLI tool — right in your terminal.
+
+```bash
+pip install .
+imagex
+```
+
+Navigate to any folder with images and run `imagex`.
+
+## Features
+
+| Feature | Description |
+|---|---|
+| Remove Metadata | Strip EXIF/XMP/IPTC (incl. AI generation markers) |
+| Convert Format | JPG ↔ PNG ↔ WEBP ↔ TIFF ↔ BMP ↔ GIF ↔ HEIC |
+| Compress / Optimize | Reduce file size with quality slider |
+| Resize | Percentage, exact dimensions, fit within bounds |
+| Rename Batch | Pattern-based renaming (%n, %o) |
+| Add Noise | Gaussian or salt & pepper (bypass AI detection) |
+| Watermark | Add text/image or remove existing |
+
+Full details in [OPERATIONS.md](OPERATIONS.md).
+
+## Install
+
+```bash
+# From the repo directory
+pip install .
+
+# Dev mode (changes take effect immediately)
+pip install -e .
+```
+
+Then run `imagex` from any folder.
+
+## Adding Features
+
+See [CONTRIBUTION.md](CONTRIBUTION.md) for the contribution guide.
+
+## License
+
+MIT

imagex-0.1.0/imagex/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

imagex-0.1.0/imagex/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

imagex-0.1.0/imagex/cli.py

@@ -0,0 +1,223 @@
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+import questionary
+from rich.console import Console
+from rich.panel import Panel
+
+from imagex import __version__
+from imagex.features import get_features
+from imagex.utils.file_ops import find_images
+from imagex.utils.progress import process_files
+
+console = Console()
+
+USAGE = """
+Image processing CLI tool — right in your terminal.
+
+Run without arguments to launch the interactive menu:
+
+    imagex
+
+Features:
+  • Remove Metadata    Strip EXIF/XMP/IPTC (incl. AI generation markers)
+  • Convert Format     JPG ↔ PNG ↔ WEBP ↔ TIFF ↔ BMP ↔ GIF ↔ HEIC
+  • Compress/Optimize  Reduce file size with quality slider
+  • Resize             Percentage, exact dimensions, fit within bounds
+  • Rename Batch       Pattern-based renaming (%%n, %%o)
+  • Add Noise          Gaussian or salt & pepper (bypass AI detection)
+  • Watermark          Add text/image or remove existing
+"""
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="imagex",
+        description="Image processing CLI tool — right in your terminal",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="Run without arguments to launch the interactive menu.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"imagex v{__version__}",
+    )
+    return parser.parse_args(argv)
+
+
+def fmt_size(size: int) -> str:
+    for unit in ("B", "KB", "MB"):
+        if size < 1024:
+            return f"{size:.0f} {unit}"
+        size /= 1024
+    return f"{size:.1f} GB"
+
+
+def show_banner():
+    art = """[bold cyan]
+██╗███╗   ███╗ █████╗  ██████╗ ███████╗██╗  ██╗
+██║████╗ ████║██╔══██╗██╔════╝ ██╔════╝╚██╗██╔╝
+██║██╔████╔██║███████║██║  ███╗█████╗   ╚███╔╝
+██║██║╚██╔╝██║██╔══██║██║   ██║██╔══╝   ██╔██╗
+██║██║ ╚═╝ ██║██║  ██║╚██████╔╝███████╗██╔╝ ██╗
+╚═╝╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝
+[/bold cyan]"""
+
+    text = (
+        f"{art}"
+        f"[white]v{__version__}[/white]\n"
+        "[dim]Image processing, right in ur CLI[/dim]"
+    )
+    console.print(Panel(text, width=60))
+
+
+def select_features() -> Optional[list[str]]:
+    features = get_features()
+
+    if not features:
+        console.print("[red]No features found! Add a .py file to imagex/features/.[/red]")
+        return None
+
+    choices = []
+    for name, info in features.items():
+        label = f"{info['name']:<30} {info['description']}"
+        choices.append(questionary.Choice(title=label, value=name))
+
+    choices.append(questionary.Choice(title="[Done] Quit", value="__quit__"))
+
+    selected = questionary.checkbox(
+        "What do you want to do? (↑↓ to move, Space to toggle, Enter to confirm)",
+        choices=choices,
+    ).ask()
+
+    if not selected:
+        return None
+
+    if "__quit__" in selected:
+        return None
+
+    return selected
+
+
+def ask_output_mode() -> tuple[str, Optional[Path]]:
+    mode = questionary.select(
+        "Where should the processed images go?",
+        choices=[
+            questionary.Choice(
+                title="Overwrite originals (backup created in .imagex_backup/)",
+                value="overwrite",
+            ),
+            questionary.Choice(
+                title="Save to ./output/ folder",
+                value="output",
+            ),
+            questionary.Choice(
+                title="Save to custom folder",
+                value="custom",
+            ),
+        ],
+    ).ask()
+
+    output_dir = None
+    if mode == "custom":
+        custom = questionary.text(
+            "Enter output folder path:",
+            validate=lambda p: len(p.strip()) > 0 or "Path cannot be empty",
+        ).ask()
+        output_dir = Path(custom.strip())
+
+    return mode, output_dir
+
+
+def select_files(all_files: list[Path]) -> Optional[list[Path]]:
+    if not all_files:
+        return None
+
+    if len(all_files) == 1:
+        return all_files
+
+    all_choice = questionary.Choice(
+        title=f"All images ({len(all_files)} files)",
+        value="__all__",
+    )
+
+    file_choices = []
+    for f in all_files:
+        size_str = fmt_size(f.stat().st_size)
+        label = f"{f.name:<50} {size_str:>8}"
+        file_choices.append(questionary.Choice(title=label, value=str(f)))
+
+    selected = questionary.checkbox(
+        "Which images to process? (Space to toggle, Enter to confirm)",
+        choices=[all_choice] + file_choices,
+    ).ask()
+
+    if not selected:
+        return None
+
+    if "__all__" in selected:
+        return all_files
+
+    return [Path(f) for f in selected]
+
+
+def main():
+    _parse_args()
+
+    try:
+        show_banner()
+
+        selected = select_features()
+        if selected is None:
+            console.print("[yellow]No feature selected. Exiting.[/yellow]")
+            return
+
+        all_files = find_images(Path.cwd())
+        if not all_files:
+            console.print("[red]No image files found in current directory.[/red]")
+            console.print("[dim]Supported: .jpg .jpeg .png .webp .tiff .tif .bmp .gif .ico[/dim]")
+            return
+
+        files = select_files(all_files)
+        if not files:
+            console.print("[yellow]No files selected. Exiting.[/yellow]")
+            return
+
+        console.print(f"[green]Selected {len(files)} image(s)[/green]")
+
+        features = get_features()
+        any_needs_output = any(
+            info.get("needs_output", True)
+            for name, info in features.items()
+            if name in selected
+        )
+
+        if any_needs_output:
+            mode, output_dir = ask_output_mode()
+        else:
+            mode, output_dir = "overwrite", None
+
+        for feature_name in selected:
+            info = features[feature_name]
+            ask_args = info.get("ask_args")
+            feature_args = ask_args(files) if ask_args else {}
+            console.print(f"\n[bold]→ {info['name']}[/bold]")
+            process_files(
+                files=files,
+                process_func=info["run"],
+                feature_name=info["name"],
+                output_mode=mode,
+                output_dir=output_dir,
+                args=feature_args,
+            )
+
+        console.print("\n[bold green]✓ All done![/bold green]")
+
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted. Exiting.[/yellow]")
+        sys.exit(0)
+    except Exception as e:
+        console.print(f"\n[red]Error: {e}[/red]")
+        sys.exit(1)

imagex-0.1.0/imagex/config.py

@@ -0,0 +1,13 @@
+from pathlib import Path
+
+IMAGE_EXTENSIONS = {
+    ".jpg", ".jpeg", ".png", ".webp",
+    ".tiff", ".tif", ".bmp", ".gif", ".ico",
+}
+
+BACKUP_DIR_NAME = ".imagex_backup"
+DEFAULT_OUTPUT_DIR_NAME = "output"
+
+
+def is_image(file: Path) -> bool:
+    return file.suffix.lower() in IMAGE_EXTENSIONS

imagex-0.1.0/imagex/features/__init__.py

@@ -0,0 +1,34 @@
+import importlib
+import pkgutil
+from pathlib import Path
+
+REGISTRY: dict[str, dict] = {}
+
+
+def _register(module):
+    name = getattr(module, "NAME", None)
+    description = getattr(module, "DESCRIPTION", "")
+    run_func = getattr(module, "run", None)
+    ask_args_func = getattr(module, "ask_args", None)
+    needs_output = getattr(module, "NEEDS_OUTPUT_MODE", True)
+
+    if name and run_func:
+        REGISTRY[name] = {
+            "name": name,
+            "description": description,
+            "run": run_func,
+            "ask_args": ask_args_func,
+            "needs_output": needs_output,
+            "module": module.__name__,
+        }
+
+
+_features_dir = Path(__file__).parent
+for _finder, _name, _ispkg in pkgutil.iter_modules([str(_features_dir)]):
+    if _name != "__init__":
+        _module = importlib.import_module(f".{_name}", __package__)
+        _register(_module)
+
+
+def get_features() -> dict[str, dict]:
+    return dict(REGISTRY)

imagex-0.1.0/imagex/features/add_noise.py

@@ -0,0 +1,80 @@
+import random
+from pathlib import Path
+from typing import Any, Optional
+
+import questionary
+from PIL import Image
+
+NAME = "Add Noise"
+DESCRIPTION = "Add subtle pixel noise (helps bypass AI detection)"
+
+
+def ask_args(files: list[Path]) -> dict[str, Any]:
+    intensity_val = questionary.text(
+        "Noise intensity (1-100, higher = more visible):",
+        default="5",
+        validate=lambda v: v.isdigit() and 1 <= int(v) <= 100 or "Enter 1-100",
+    ).ask()
+
+    noise_type = questionary.select(
+        "Noise type:",
+        choices=[
+            "Gaussian (subtle, uniform)",
+            "Salt & Pepper (random pixels)",
+        ],
+    ).ask()
+
+    return {
+        "intensity": int(intensity_val),
+        "noise_type": "gaussian" if "Gaussian" in noise_type else "salt_pepper",
+    }
+
+
+def run(file: Path, output_path: Path, args: Optional[dict[str, Any]] = None) -> bool:
+    if args is None:
+        msg = "args required for add_noise"
+        raise ValueError(msg)
+
+    intensity = args["intensity"]
+    noise_type = args.get("noise_type", "gaussian")
+    img = Image.open(file)
+
+    if noise_type == "gaussian":
+        _add_gaussian_noise(img, intensity)
+    else:
+        _add_salt_pepper(img, intensity)
+
+    img.save(str(output_path), format=img.format or "JPEG")
+    return True
+
+
+def _add_gaussian_noise(img: Image.Image, intensity: int):
+    pixels = img.load()
+    w, h = img.size
+    scale = intensity / 100
+    noise_range = int(scale * 60)
+    num_pixels = int(w * h * scale * 0.8)
+
+    for _ in range(num_pixels):
+        x = random.randint(0, w - 1)
+        y = random.randint(0, h - 1)
+        px = list(pixels[x, y])
+        for c in range(min(len(px), 3)):
+            px[c] = max(0, min(255, px[c] + random.randint(-noise_range, noise_range)))
+        pixels[x, y] = tuple(px)
+
+
+def _add_salt_pepper(img: Image.Image, intensity: int):
+    pixels = img.load()
+    w, h = img.size
+    scale = intensity / 100
+    num_pixels = int(w * h * scale * 0.3)
+
+    for _ in range(num_pixels):
+        x = random.randint(0, w - 1)
+        y = random.randint(0, h - 1)
+        px = list(pixels[x, y])
+        val = 255 if random.random() < 0.5 else 0
+        for c in range(min(len(px), 3)):
+            px[c] = val
+        pixels[x, y] = tuple(px)

imagex-0.1.0/imagex/features/compress.py

@@ -0,0 +1,95 @@
+from pathlib import Path
+from typing import Any, Optional
+
+import questionary
+from PIL import Image
+from rich.console import Console
+
+NAME = "Compress / Optimize"
+DESCRIPTION = "Reduce file size (quality slider, optimization)"
+
+console = Console()
+
+
+def ask_args(files: list[Path]) -> dict[str, Any]:
+    quality = questionary.text(
+        "Quality (1-100):",
+        default="80",
+        validate=lambda v: v.isdigit() and 1 <= int(v) <= 100 or "Enter a number 1-100",
+    ).ask()
+
+    return {"quality": max(1, min(100, int(quality)))}
+
+
+def run(file: Path, output_path: Path, args: Optional[dict[str, Any]] = None) -> bool:
+    if args is None:
+        msg = "args required for compress (quality)"
+        raise ValueError(msg)
+
+    quality = args.get("quality", 80)
+    img = Image.open(file)
+    fmt = img.format
+    original_size = file.stat().st_size
+
+    if fmt == "JPEG":
+        _compress_jpeg(img, output_path, quality)
+    elif fmt == "PNG":
+        _compress_png(img, output_path, quality)
+    elif fmt == "WEBP":
+        _compress_webp(img, output_path, quality)
+    else:
+        _compress_other(img, output_path, fmt, quality)
+
+    new_size = output_path.stat().st_size
+    saved = original_size - new_size
+    pct = (1 - new_size / original_size) * 100 if original_size else 0
+    console.print(
+        f"  [dim]{file.name}: {_fmt_size(original_size)} → {_fmt_size(new_size)} "
+        f"({'−' if saved >= 0 else '+'}{abs(pct):.0f}%)[/dim]"
+    )
+
+    return True
+
+
+def _compress_jpeg(img: Image.Image, output_path: Path, quality: int):
+    if img.mode == "RGBA":
+        bg = Image.new("RGB", img.size, (255, 255, 255))
+        bg.paste(img, mask=img.split()[3])
+        img = bg
+    elif img.mode != "RGB":
+        img = img.convert("RGB")
+    img.save(str(output_path), format="JPEG", quality=quality, optimize=True)
+
+
+def _compress_png(img: Image.Image, output_path: Path, quality: int):
+    if quality < 50:
+        if img.mode == "RGBA":
+            bg = Image.new("RGB", img.size, (255, 255, 255))
+            bg.paste(img, mask=img.split()[3])
+            img = bg
+        elif img.mode != "RGB":
+            img = img.convert("RGB")
+        colors = max(quality * 2, 16)
+        img = img.quantize(colors=colors, method=Image.Quantize.MEDIANCUT)
+        img.save(str(output_path), format="PNG", optimize=True)
+    else:
+        img.save(str(output_path), format="PNG", optimize=True)
+
+
+def _compress_webp(img: Image.Image, output_path: Path, quality: int):
+    img.save(str(output_path), format="WEBP", quality=quality)
+
+
+def _compress_other(img: Image.Image, output_path: Path, fmt: str, quality: int):
+    params = {"format": fmt}
+    if fmt == "GIF":
+        params["save_all"] = True
+    img.save(str(output_path), **params)
+
+
+def _fmt_size(size: int) -> str:
+    for unit in ("B", "KB", "MB"):
+        if size < 1024:
+            return f"{size:.0f} {unit}"
+        size /= 1024
+    return f"{size:.1f} GB"