Merlin: Smart Watermarks + Web-Ready Photos from the CLI ๐Ÿง™โ€โ™‚๏ธโœจ

A Bash-powered image wizard that batch resizes, converts, and applies a smart black/white watermark based on background brightness.

TL;DR ๐ŸŽฏ

Want a dead-simple, CLI-first way to turn a folder of photos into web-ready JPGs? With a watermark that doesnโ€™t disappear into bright skies? Merlinโ€™s your wizard ๐Ÿง™โ€โ™‚๏ธ๐Ÿฎ


I built a little Bash tool called Merlin ๐Ÿง™โ€โ™‚๏ธ. It turns a folder of โ€œraw-ishโ€ photos into web-ready images. Resized, converted to JPG, and watermarked with the right logo color, black or white, based on the brightness behind it. Minimal effort. Maximum โœจ.

๐Ÿ‘‰ GitHub repo: https://github.com/corbtastik/merlin

Before / After ๐Ÿ–ผ๏ธ

Same shot โ€” one without the watermark, one with it:

Before (no watermark)
Before (no watermark)
After (Merlin watermark)
After (Merlin watermark)

What Merlin does (a.k.a. โ€œthe spell listโ€) ๐Ÿช„

Merlin is a Bash script that uses ImageMagick to batch process images in a directory:

  • Batch processing: handles jpg, png, and heic files ๐Ÿ“ธ
    (HEIC = High Efficiency Image Container)
  • Web optimization: converts everything to JPG (quality 85) โœ…
  • Resize modes:
    • fit (default): resize to a target width while keeping aspect ratio
    • cover: center-crop + resize to a 4:5-ish frame (social-friendly) ๐Ÿ“ฑ
      (See: Aspect ratio)
  • Smart watermarking: samples the bottom-right corner and picks:
    • Light background โ†’ black logo
    • Dark background โ†’ white logo
  • Non-destructive: creates new files like IMG_1234-merlin.jpg (originals stay untouched) ๐Ÿงผโœจ

Prerequisites โœ…

You need ImageMagick v7+ installed, and the magick command with it.

macOS (Homebrew) ๐Ÿบ

Install on macOScopy_all
brew install imagemagick

Ubuntu / Debian ๐Ÿง

Install on Ubuntucopy_all
sudo apt-get install imagemagick

Quick sanity check:

Sanity checkcopy_all
magick -version

If that prints a version and doesnโ€™t complain, youโ€™re in business ๐Ÿ˜„

Install ๐Ÿงฐ

  1. Download merlin.sh into your project folder.
  2. Make it executable:
Make it executablecopy_all
chmod +x merlin.sh
  1. Optional: move it into your PATH so you can run it anywhere:
Put it on your PATHcopy_all
mv merlin.sh /usr/local/bin/merlin

Usage ๐Ÿš€

Basic (default width + fit)

The simplest way to run Merlin. It uses the default width (1600px) and fit.

Basic runcopy_all
./merlin.sh \
  --input ./photos \
  --logo-white ./assets/logo-white.png \
  --logo-black ./assets/logo-black.png

Advanced (custom output, width, and cover)

Specify an output directory, a custom width, and use cover crop.

Advanced runcopy_all
./merlin.sh \
  --input ./raw-photos \
  --output ./web-ready \
  --width 1080 \
  --style cover \
  --logo-white ./assets/logo-white.png \
  --logo-black ./assets/logo-black.png

Flags ๐Ÿ“‹

Flag Description Required? Default
-i, --input Directory containing source images โœ… โ€”
--logo-white Path to white watermark logo โœ… โ€”
--logo-black Path to black watermark logo โœ… โ€”
-o, --output Output directory โŒ same as input
-w, --width Target width in pixels โŒ 1600
--style fit or cover โŒ fit
--suffix String appended to filenames โŒ merlin

How it works (the โ€œrealโ€ magic) ๐Ÿง โœจ

1) Auto-orient first ๐Ÿ”„

Phones love storing rotation in metadata (thanks, Exif ๐Ÿ˜…). Merlin runs -auto-orient first, so the bottom-right in the file matches the bottom-right you see.

2) Resize mode ๐Ÿ“

  • fit: resize to width, preserve aspect ratio
  • cover: crop + resize to fill a 4:5-ish output (great for social posts) ๐Ÿ“ฑ

3) Brightness sampling โ˜€๏ธ๐ŸŒ‘

Merlin crops a small region in the bottom-right, 20% wide by 15% tall. It converts that to grayscale and computes mean brightness. Brightness above 0.4 means a light background, so Merlin picks the black logo.

4) Composite watermark ๐ŸŽจ

Merlin overlays the chosen logo in the bottom-right with a little padding.

Important: Merlin does not resize your logo. It uses the logo at its native pixel size.
Make your logo files the size you want them to appear on the final image (ex: 100x45px).

Output naming ๐Ÿท๏ธ

Merlin avoids overwriting originals by appending a suffix:

  • Source: IMG_1234.HEIC
  • Output: IMG_1234-merlin.jpg