https://github.com/yaph/wim
A command-line tool for creating and optimizing images for the web with text overlays, watermarks, and more.
https://github.com/yaph/wim
cli command-line-tools image image-manipulation image-optimization image-processing image-processing-python image-resize image-watermark pillow python-package text-overlay watermark web-images
Last synced: 27 days ago
JSON representation
A command-line tool for creating and optimizing images for the web with text overlays, watermarks, and more.
- Host: GitHub
- URL: https://github.com/yaph/wim
- Owner: yaph
- License: mit
- Created: 2015-01-10T22:26:19.000Z (about 11 years ago)
- Default Branch: main
- Last Pushed: 2026-02-02T21:23:07.000Z (about 1 month ago)
- Last Synced: 2026-02-03T10:32:39.526Z (29 days ago)
- Topics: cli, command-line-tools, image, image-manipulation, image-optimization, image-processing, image-processing-python, image-resize, image-watermark, pillow, python-package, text-overlay, watermark, web-images
- Language: Python
- Homepage:
- Size: 84 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# WIM - Web Image Maker
A command-line tool for creating and optimizing images for the web with text overlays, watermarks, and more.
## Installation
```bash
pipx install wim
```
Or install from source:
```bash
git clone https://github.com/yaph/wim.git
cd wim
pip install -e .
```
## Quick Start
```bash
# Add text overlay
wim input.jpg -t "Hello World"
# Add watermark
wim input.jpg -w logo.png
# Scale and add text
wim input.jpg -s 800 -t "Resized Image"
# Add semi-transparent watermark in top-right corner
wim photo.jpg -w logo.png --watermark-position top-right --watermark-opacity 128
```
## Features
### Text Overlays
- Add text with semi-transparent backgrounds
- Customize font, size, and position
- Automatic text centering and padding
### Watermarks & Overlays
- Blend images over your photos
- Adjust opacity for subtle watermarks
- Scale overlays to any size
- Position overlays anywhere (corners, center)
### Image Optimization
- Scale images to maximum dimensions
- Quantize to reduce file size
- Convert between formats (PNG, JPEG)
- Automatic RGBA to RGB conversion for JPEG
### Smart Defaults
- Non-destructive by default (adds `-wim` to file name stems)
- RGBA support with proper alpha blending
- High-quality image resampling
## Usage Examples
```bash
# Add text with custom font and size
wim input.jpg -t "Caption" --font times.ttf --font-size 24
# Add watermark with 50% opacity in bottom-right
wim photo.jpg -w logo.png --watermark-opacity 128
# Scale watermark to specific size
wim photo.jpg -w logo.png --watermark-scale 150 150
# Multiple operations at once
wim input.jpg -s 1200 -t "Summer 2024" -w logo.png --watermark-position top-right
# Edit image in place
wim input.jpg -i -t "Updated"
# Reduce file size with quantization
wim input.png -q
```
## Command Line Options
```bash
wim --help
```
```text
usage: wim [-h] [-i | -o OUTDIR] [--strip] [--trim] [--version] [--format {ico,jpg,png,webp,jpeg,bmp,gif}]
[--output-label OUTPUT_LABEL] [--quality QUALITY] [--quantize QUANTIZE] [-s WIDTH HEIGHT]
[--font FONT] [--font-size FONT_SIZE] [-t TEXT] [-w WATERMARK]
[--watermark-opacity WATERMARK_OPACITY] [--watermark-scale WIDTH HEIGHT]
[--watermark-position {top-left,top-right,bottom-left,bottom-right,center}]
filename [filename ...]
Edit, optimize, and watermark images from the command line.
positional arguments:
filename Input image filename. Use wildcard to process multiple files.
options:
-h, --help show this help message and exit
-i, --inplace Edit the image in place (overwrites original).
-o OUTDIR, --outdir OUTDIR
Output directory for processed images.
--strip Strip image of all metadata.
--trim Trim uniform-color borders from image edges.
--version show program's version number and exit
--format {ico,jpg,png,webp,jpeg,bmp,gif}
Set the output format. If not set, original format is used.
--output-label OUTPUT_LABEL
Label to append to the output file name. Ignored if --inplace is used.
--quality QUALITY Output quality 1-100 (lower = smaller file). Works with JPEG and WebP.
--quantize QUANTIZE Quantize the image with the desired number of colors, <= 256.
-s WIDTH HEIGHT, --scale WIDTH HEIGHT
Set the maximum width and height as integer values.
--font FONT Font name (e.g., DejaVuSans, Arial) or path to TrueType font file (.ttf), requires font size setting.
Falls back to system default if not specified or found.
--font-size FONT_SIZE
Set the font size, requires font setting.
-t TEXT, --text TEXT Set the text to add to the image.
-w WATERMARK, --watermark WATERMARK
Path to watermark/overlay image to add to the image.
--watermark-opacity WATERMARK_OPACITY
Opacity of watermark 0-255 (default: 255).
--watermark-scale WIDTH HEIGHT
Scale watermark to WIDTH HEIGHT in pixels.
--watermark-position {top-left,top-right,bottom-left,bottom-right,center}
Position of watermark (default: bottom-right).
```
## Requirements
- Python ≥ 3.10
- Pillow
## Development
```bash
# Clone repository
git clone https://github.com/yaph/wim.git
cd wim
# Run in development mode
hatch shell wim-dev
# Run tests
hatch run qa
# Clean build artifacts
hatch run clean
```
## License
MIT License - see LICENSE file for details
## Author
Ramiro Gómez ([@yaph](https://github.com/yaph))
## Links
- **Documentation**: https://github.com/yaph/wim#readme
- **Issues**: https://github.com/yaph/wim/issues
- **Source Code**: https://github.com/yaph/wim