Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/1TSnakers/ProgressiveImageLoader/llms.txt

Use this file to discover all available pages before exploring further.

The image_ruiner.py companion script automates the creation of progressively lower-quality PNG variants from a single source image. It works by repeatedly resizing the image downward using nearest-neighbour interpolation to produce a pixelation effect, then saving each step as a numbered PNG file. After all variants are generated, it writes an image_list.js file containing a JavaScript array of the output paths in the order that ProgressiveImageLoader expects — most degraded first, original quality last.

​
Requirements

  • Python 3 — the script uses f-strings and pathlib-style operations available in Python 3.6+.
  • Pillow — the PIL image processing library must be installed before running the script.
  • A TTF font file — the default label font is GoogleSansCode-Regular.ttf, which is included in the images/ directory of the repository. You can substitute any .ttf file by passing its path to the font_file parameter.
Install Pillow with pip: 
pip install pillow

​
Function Signature

from image_ruiner import pixel_degrade_png

pixel_degrade_png(
    image_path,
    output_dir="pixel_degraded_pngs",
    steps=8,
    label_size=60,
    font_file="GoogleSansCode-Regular.ttf",
    label_prefix="Quality reduced by: ",
    show_label=True,
)

​
Parameters

​
image_path
str
required
Path to the source image that will be degraded. The path should be relative to the images/ directory (the working directory from which the script is run). Supported formats are any image type that Pillow can open — PNG and JPEG work reliably.
image_path="sample.png"
​
output_dir
str
default:"pixel_degraded_pngs"
Directory (relative to the images/ working directory) into which the generated PNG files will be saved. The directory is created automatically if it does not exist.
output_dir="pixel_degraded_pngs"
If the output_dir already exists, the script deletes the entire directory and all its contents with shutil.rmtree before generating new images. Make sure you do not store anything in that directory that you want to keep.
​
steps
int
default:"8"
The number of degradation steps to generate. The script produces steps + 1 total images — one for each step plus the least-degraded (closest to original) variant. With the default of 8, you get 9 images: degraded_000.png through degraded_100.png at roughly equal quality intervals.
steps=8
​
label_size
int
default:"60"
Base font size (in points) for the quality-percentage label drawn in the bottom-left corner of each image. The actual rendered size scales dynamically with the output image dimensions so the label remains legible even on highly degraded (small) variants. This parameter has no effect when show_label=False.
label_size=40
​
font_file
str
default:"GoogleSansCode-Regular.ttf"
Path to the TrueType font (.ttf) file used to render the label overlay. The path is resolved relative to the images/ working directory. The repository ships with GoogleSansCode-Regular.ttf, so no extra download is needed when using the default.
font_file="GoogleSansCode-Regular.ttf"
If the specified font file cannot be found or loaded, the script does not abort — it prints a warning and falls back to Pillow’s built-in default bitmap font. The default font is very small and may look poor on high-resolution images, so it’s best to keep the TTF file in place.
​
label_prefix
str
default:"Quality reduced by: "
Text prepended to the percentage value in the label overlay. The full label rendered on each image is the prefix followed by the degradation percentage (for example Quality reduced by: 50%). Change this to suit your preferred wording or to localise the output. This parameter has no effect when show_label=False.
label_prefix="Quality reduced by: "
​
show_label
bool
default:"True"
Controls whether the quality-percentage label is drawn on each output image. Set to False to produce clean output images without any text overlay — useful when the degraded images will be displayed directly to end users rather than used for debugging.
show_label=False

​
Output

After a successful run, the script produces:
  • PNG files inside output_dir, named using a zero-padded three-digit quality percentage: degraded_000.png (most pixelated / lowest quality) through degraded_100.png (least degraded, closest to the source). With the default of steps=8, the filenames produced are: 
    degraded_000.png
degraded_012.png
degraded_025.png
degraded_037.png
degraded_050.png
degraded_062.png
degraded_075.png
degraded_087.png
degraded_100.png
  • image_list.js — written to the images/ working directory. It exports a default JavaScript array with the image paths in the order ProgressiveImageLoader requires (most degraded first): 
    const imageList = [
  "images/pixel_degraded_pngs/degraded_000.png",
  "images/pixel_degraded_pngs/degraded_012.png",
  // …
  "images/pixel_degraded_pngs/degraded_100.png",
];

export default imageList;
    Import this file directly into your HTML page’s module script and pass it as the images option to ProgressiveImageLoader.

​
Running the Script

1

Install Pillow

Install the required Python image library using pip. Python 3 must already be installed on your system.
pip install pillow
2

Place your source image and font file

Copy your source image (e.g. sample.png) and the GoogleSansCode-Regular.ttf font file into the images/ directory. The font file is already present if you cloned the repository — you only need to add your own image.
images/
├── GoogleSansCode-Regular.ttf   ← already in repo
├── image_ruiner.py              ← already in repo
└── sample.png                  ← add your image here
3

Run the script from the images/ directory

Change into the images/ directory and execute the script with Python. The working directory must be images/ so that relative paths for the font file and output resolve correctly.
cd images
python image_ruiner.py
On success, the terminal prints the number of images saved and the absolute path of the output directory:
Saved 9 images and image_list.js in '/path/to/project/images'

​
Usage Example

The following call matches the __main__ block at the bottom of image_ruiner.py and represents the standard invocation used in the project demo: 
pixel_degrade_png(
    image_path="sample.png",
    output_dir="pixel_degraded_pngs",
    steps=8,
    label_size=40,
    font_file="GoogleSansCode-Regular.ttf",
    label_prefix="Quality reduced by: ",
    show_label=True
)
This produces 9 PNG files (steps + 1) in images/pixel_degraded_pngs/ and writes images/image_list.js.

​
GitHub Actions Integration

The repository includes a workflow at .github/workflows/run-image-ruiner.yml that runs image_ruiner.py automatically and commits the generated PNG files and image_list.js back to the repository. This means you can update your source image, push to main or master, and have the full degraded image set regenerated without running anything locally. The workflow triggers on: 
on:
  workflow_dispatch:
  push:
    branches:
      - main
      - master
workflow_dispatch also allows you to trigger the workflow manually from the GitHub Actions UI without making a commit. After the script runs, the workflow stages and commits the generated assets: 
- name: Commit and push degraded images and JS list
  run: |
    git add images/pixel_degraded_pngs/*.png
    git add images/image_list.js
    git diff --cached --quiet || git commit -m "Add/update pixel-degraded images and JS list"
    git push origin HEAD:main
If you only want to regenerate images without changing any source code, use the Run workflow button on the Actions tab in GitHub to trigger the workflow_dispatch event manually.

Build docs developers (and LLMs) love

Get started for freeTalk to us