singular-particular-space/Images/script-guide.md

thumbnail.py — Script Guide

Resizes images to a max width, preserving aspect ratio, no cropping. Outputs compressed JPEGs to thumbnails/ subfolders within each collection folder.

---

Virtual Environment

python3 -m venv .venv

Requirements

pip install Pillow

---

Usage

From the repo root:

python Images/thumbnail.py

From inside the Images folder:

python thumbnail.py

---

What it does

1. Iterates over each collection folder (WayBack, YourNomadSoul, MysterWizzard, Exopraxist)
2. Finds all .jpg, .jpeg, .png files (case-insensitive)
3. Resizes any image wider than MAX_WIDTH — narrower images are passed through unchanged
4. Converts to RGB JPEG (handles PNG transparency, palette mode, etc.)
5. Saves to {collection}/thumbnails/{original_stem}.jpg at quality 85
6. Prints a before/after size summary

---

Adapting for different uses

Change the output size

Edit MAX_WIDTH at the top of the script:

MAX_WIDTH = 360   # current — web gallery thumbnails
MAX_WIDTH = 880   # larger thumbnails or preview images
MAX_WIDTH = 1920  # full-width web images, still compressed

Change JPEG quality

Edit QUALITY at the top:

QUALITY = 85   # current — good balance of size and sharpness
QUALITY = 75   # smaller files, slight quality loss (fine for thumbnails)
QUALITY = 92   # near-lossless, larger files

Change which folders are processed

Edit the COLLECTIONS list:

COLLECTIONS = ["WayBack", "YourNomadSoul", "MysterWizzard", "Exopraxist"]

Add, remove, or rename entries to match your folder structure.

Run on a different folder entirely

Change base in the main() function:

base = Path("/path/to/your/images")

Or pass it as a command-line argument — see the adaptation note below.

Process a flat folder (no subfolders)

Replace the collection loop with a direct scan:

images = sorted(f for f in base.iterdir() if f.suffix in EXTENSIONS and f.is_file())
thumb_dir = base / "thumbnails"
for src in images:
    dest = thumb_dir / (src.stem + ".jpg")
    make_thumbnail(src, dest)

Accept a path argument from the command line

Add to main() before the loop:

import sys
if len(sys.argv) > 1:
    base = Path(sys.argv[1])

Then run as:

python thumbnail.py /path/to/images

---

Output structure

Images/
  WayBack/
    IMG_0001.JPG          ← original (can delete after upload)
    thumbnails/
      IMG_0001.jpg        ← resized thumbnail → upload this
  YourNomadSoul/
    ...

---

After running

1. Commit the thumbnails/ folders to git — these are small enough to live in the repo
2. Delete the originals from the local repo — do not commit large image files to git
3. Full-res originals stay on FileBrowser (already uploaded) — the gallery lightbox and download button pull from there