Skip to content

README.md

Latest commit

 

History

History
230 lines (159 loc) · 5.22 KB

README.md

File metadata and controls

230 lines (159 loc) · 5.22 KB

🌟 stellar

High-quality image upscaling from the command line.

Python License: MIT PyPI version GitHub

Lanczos interpolation · Unsharp-mask sharpening · Parallel batch processing · tqdm progress bars

✨ Features

  • 🔍 Scale images by any factor (1×–16×) using Lanczos interpolation
  • 🖼 Supports PNG, JPG, JPEG input and output formats
  • ⚡ Multithreaded batch processing for large image sets
  • 📊 tqdm progress bar with per-image resolution and timing stats
  • 🔧 Modular code — clean load_image(), upscale_image(), save_image() API
  • 🛡 Graceful error handling — bad files are logged and skipped, not crashes
  • 📦 Installable as a global CLI tool via pip or wheel

📦 Installation

Option 1 — Install from PyPI (recommended)

pip install stellar

Option 2 — Install from source

git clone https://github.com/pro-grammer-SD/stellar.git
cd stellar
pip install .

Option 3 — Build & install a wheel locally

Prerequisites

pip install build

Build the wheel

# From the repository root:
python -m build

This produces two distribution artefacts inside dist/:

dist/
├── stellar-1.0.0-py3-none-any.whl   ← wheel (preferred)
└── stellar-1.0.0.tar.gz             ← sdist

Install the wheel

pip install dist/stellar-1.0.0-py3-none-any.whl

Or use a glob to pick up whichever version was built:

pip install dist/stellar-*.whl

Upgrade an existing install from a new wheel

pip install --upgrade dist/stellar-*.whl

Uninstall

pip uninstall stellar

After installation the stellar command will be available on your PATH.

🚀 Usage

Basic upscale (2× default)

stellar --input ./photos

Custom scale factor

stellar --input ./photos --scale 4

Custom output folder

stellar --input ./raw --output ./hd

Force PNG output format

stellar -i ./shots -o ./out --format PNG

Verbose mode (per-image resolution + timing)

stellar -i ./photos --verbose

Use 8 parallel workers for large batches

stellar -i ./large_batch -o ./upscaled -s 2 -w 8

All options at once

stellar \
  --input  ./raw_photos \
  --output ./upscaled \
  --scale  3 \
  --format PNG \
  --workers 6 \
  --verbose

📖 CLI Reference

Usage: stellar [OPTIONS]

  🌟 Upscale all images in INPUT_DIR and write them to OUTPUT_DIR.

  Supported source formats: PNG, JPG, JPEG.

Options:
  -i, --input   PATH     📂 Input folder containing images to upscale. [required]
  -o, --output  PATH     📁 Output folder for upscaled images. [default: upscaled]
  -s, --scale   FLOAT    🔍 Scale factor (e.g. 2 doubles the resolution). [default: 2.0]
  -f, --format  TEXT     🖼  Output format override: PNG, JPG, JPEG.
  -w, --workers INTEGER  ⚡ Number of parallel worker threads. [default: 4]
  -v, --verbose          🔊 Print per-image resolution and timing details.
      --help             Show this message and exit.

Output filenames are the original name with _upscaled appended:

photos/sunset.jpg  →  upscaled/sunset_upscaled.jpg

🧰 Dependencies

Package Purpose
Pillow Image format detection
opencv-python Image I/O and Lanczos resize
scikit-learn Optional interpolation utilities
typer CLI framework
tqdm Progress bars
numpy Array operations

🗂 Project Structure

stellar/
├── stellar.py            # Main script (load / upscale / save / CLI)
├── pyproject.toml        # Build config & metadata
├── README.md
├── LICENSE               # MIT
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── .github/
    ├── ISSUE_TEMPLATE/
    │   ├── bug_report.md
    │   └── feature_request.md
    └── PULL_REQUEST_TEMPLATE.md

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

🔒 Security

To report a security vulnerability, please see SECURITY.md.

📄 License

This project is licensed under the MIT License.
Copyright © 2025 Soumalya Das

Made with ❤️ by Soumalya Das