README.md

metadata

title: Image Processor Pro
emoji: 🖼️
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

Image Processor Pro

A command-line tool that downloads images from URLs, converts them to JPEG, optimizes them, and saves them locally with date-bucketed output. A local web UI (webapp.py) is also included, and the repo ships a Dockerfile for one-click deploy to Hugging Face Spaces.

The YAML block above is only used by Hugging Face Spaces to configure the container (Docker SDK, port 7860). It is ignored everywhere else.

Features

• Concurrent multi-threaded downloads with retry & backoff
• Supports AVIF, JPG, JPEG, PNG, WEBP inputs
• Converts everything to optimized progressive JPEG
• Transparency flattened over a configurable background (default white)
• Optional resize (max-width / max-height) preserving aspect ratio
• Strips metadata by default for smaller files
• Date-bucketed output: output/YYYY-MM-DD/
• Separate success/failure log files plus rich console output
• Unique filenames derived from the original image ID
• Progress bar for batch runs, summary table at the end
• Clean OOP design, type-hinted throughout

Project Structure

image_processor/
├── main.py            # CLI entrypoint
├── downloader.py      # Downloader (retries, MIME validation)
├── converter.py       # Decode + RGB normalization (AVIF, PNG, WEBP, ...)
├── optimizer.py       # Resize + JPEG encode/strip
├── pipeline.py        # Orchestrates the download→convert→optimize flow
├── config.py          # Config dataclass and supported formats
├── utils.py           # Logging, URL parsing, naming helpers
├── requirements.txt
├── config.sample.json
├── urls.example.txt
├── output/            # Created at runtime: output/YYYY-MM-DD/*.jpg
└── logs/              # success.log, failure.log

Installation

Requires Python 3.12+.

cd image_processor
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Usage

Single image

python main.py --url "https://images.meesho.com/images/products/195946861/25gkh_512.avif?width=512"

Batch from file

python main.py --file urls.example.txt

Tune JPEG quality (1–95)

python main.py --file urls.txt --quality 90

Resize (cap width)

python main.py --url "$URL" --max-width 1200

Full example

python main.py \
  --file urls.txt \
  --quality 88 \
  --max-width 1600 \
  --workers 16 \
  --timeout 45 \
  --retries 5 \
  --output output \
  --logs logs \
  --verbose

Use a config file

python main.py --file urls.txt --config config.sample.json

CLI flags override values from --config.

CLI Options

Flag	Description
--url URL	Single image URL
--file PATH	Text file with one URL per line (# comments allowed)
--config PATH	JSON config file (see config.sample.json)
--output PATH	Output root (default output)
--logs PATH	Logs directory (default logs)
--quality N	JPEG quality 1–95 (default 85)
--max-width N	Resize so width ≤ N
--max-height N	Resize so height ≤ N
--workers N	Concurrent download workers (default 8)
--timeout N	Per-request timeout seconds (default 30)
--retries N	Max retries per URL (default 3)
--keep-metadata	Preserve EXIF metadata
-v / --verbose	Verbose logging

Output Layout

output/
└── 2026-06-18/
    ├── 25gkh_512.jpg
    └── 25gkh_512-1.jpg   # duplicate-safe naming
logs/
├── success.log
└── failure.log

Error Handling

The pipeline categorizes and logs each failure separately. Handled cases:

• Invalid / malformed URL
• Network timeout / connection error (retried with backoff)
• Unsupported MIME type returned by server
• Corrupted or undecodable image
• Permission errors when writing output
• HTTP non-2xx responses

A failed item never aborts the batch — it's recorded in logs/failure.log and in the final summary table.

Programmatic Use

from config import Config
from pipeline import ImagePipeline

config = Config(jpeg_quality=90, max_width=1200, max_workers=16)
with ImagePipeline(config) as p:
    results = p.process_many(["https://example.com/a.png", "https://example.com/b.avif"])
    for r in results:
        print(r.url, r.success, r.output_path)

Performance Notes

• Tested architecture scales to 1000+ URLs by tuning --workers (I/O bound).
• Downloads stream into memory in 16 KB chunks; large files are handled without spilling to temp disk.
• A single requests.Session with a pooled HTTPAdapter is reused across workers.