🌟 stellar

High-quality image upscaling from the command line.

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