https://github.com/neg4n/image-square-wizard
image square wizard pads rectangular or panoramic images to a square canvas using libvips, auto measuring the domimant color with options to customize
https://github.com/neg4n/image-square-wizard
c cli cli-tool heif image-manipulation image-utility jpeg jpg libvips png vips webp
Last synced: 4 days ago
JSON representation
image square wizard pads rectangular or panoramic images to a square canvas using libvips, auto measuring the domimant color with options to customize
- Host: GitHub
- URL: https://github.com/neg4n/image-square-wizard
- Owner: neg4n
- Created: 2025-10-19T04:06:52.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-07-06T23:06:31.000Z (9 days ago)
- Last Synced: 2026-07-07T01:06:07.396Z (8 days ago)
- Topics: c, cli, cli-tool, heif, image-manipulation, image-utility, jpeg, jpg, libvips, png, vips, webp
- Language: C
- Homepage: https://neg4n.dev/explore/image-square-wizard/overview
- Size: 14.6 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
https://github.com/user-attachments/assets/c9a5fca3-eff5-4efd-a837-e5e621018e7d
# image-square-wizard
**isw** _(image square wizard)_ pads rectangular or panoramic images to a
square canvas using [`libvips`][libvips]. It measures the dominant colour (or
accepts a user-provided colour / transparent fill) and expands the image evenly
on each side. It can also build an opt-in blurred background from the image
itself, which is useful for thumbnails, previews, and social posts where solid
padding would look too flat.
## Features
- Fast. Built in C.
- JPEG, PNG, WebP, HEIF/HEIC, TIFF, AVIF support out of the box.
- Only one command. Specify input & output along with extensions and thats it.
- Automatic detection of aspect ratio.
- Probing of the dominant color of the image to be used for padding (by default).
- Customization options, e.g. provide your own colors.
### Prerequisites
- [`libvips`][libvips] 8.12 – 8.18 (tested with 8.17.2). Install via your package manager,
e.g. `brew install vips` on macOS or `apt install libvips-dev` on Debian/Ubuntu.
- Meson (>= 1.1) and Ninja for the build.
- A C11 toolchain (e.g. clang or gcc) with pkg-config.
### Build Steps
1. Clone the repository: `git clone https://github.com/neg4n/image-square-wizard isw && cd isw`
2. Configure the build directory: `meson setup build`
3. Compile: `meson compile -C build`
### Installation
Run `meson install -C build` inside the repository's root in order to install the `isw` binary and man page. Adjust
`DESTDIR` or `--prefix` during `meson setup` if you need a custom location.
### Usage
Run `isw input.jpg output.png` for the default solid dominant-colour padding.
Use `isw --blur input.jpg output.png` to generate the square canvas from the
image itself:
- The image is resized to cover the square canvas.
- The covered image is centre-cropped, heavily blurred, and subtly toned.
- The original image is inserted back in the centre unchanged.
- For alpha-capable outputs, the generated blur padding is opaque while the
original image keeps its own alpha.
Manual backgrounds still use `--rcb`; `--blur` and `--rcb` are mutually
exclusive.
Inspect options with `isw --help` or `man isw`.
## License
MIT
[libvips]: https://github.com/libvips/libvips