Pruner.js

Overview

Inspired by the practice of horticultural pruning—the targeted removal of unhealthy or unwanted parts to promote growth—Pruning addresses the inefficiencies of HTML5.1 responsive images. Traditional responsive image delivery relies on multiple versions for specific viewports but often leads to errors, complex markup, and pixel waste—image data extending beyond the visible aperture. A study, Understanding and Mitigating Webpage Data Bloat: Causes and Preventive Measures (see Section 5.2), reveals that over 90% of loaded pixels go unused on average, with a median waste of 30% on desktops and 50% on mobile, where images are often loaded at desktop resolutions but displayed much smaller.

Pruning takes a tile-based approach, dividing a base image into smaller sections (tiles) that are dynamically assembled, like a jigsaw puzzle, based on the viewport size. This viewport-based rendering (VBR) method loads only the portions of an image that are needed, reducing unnecessary data transfer and improving efficiency. By calculating and serving tiled images optimised for a range of common viewport sizes, Pruning eliminates reliance on predefined breakpoints, offering a more adaptable and resource-efficient solution for responsive image delivery.

Features

• Loads Only What's Needed: Delivers just the visible parts of an image.
• Smart Cropping: Dynamically adjusts images across various screen sizes, without fixed breakpoints.
• Easy Setup: Tile Maker handles formatting, compression, and HTML snippet generation.
• Custom Focal Points: Define a focal point and custom scaling breakpoints for smaller devices and art direction.
• Screen Density: Automatically adjusts for 1x and 2x screen densities.
• Client-Side Processing: Operates directly in the browser to generate responsive images based on viewport size.

Install

Download

Download the minified or unminified version of Pruner.js:

• Minified: Available in the distributable (dist) folder.
• Unminified: Available in the source (src) folder.

CDN

Use this script element to include the minified version of Pruner.js directly in your project:

<script async src="https://unpkg.com/prunerjs/dist/pruner.min.js"></script>

Package Managers

You can also install Pruner.js using npm:

npm install prunerjs

Or using yarn:

yarn add prunerjs

How it Works

Instead of the src attribute within the <img> tag, the data-pruner attribute is used. This attribute contains JSON-formatted parameters that are interpreted by Pruner.js to assemble the tiles, determine their positioning, and enable additional customisation. The table below outlines all the names of the parameters within the data-pruner attribute in JSON format, their description, requirement and their functions.

Parameters

⭐️ Denotes which parameters are optional.

| | Parameter | Value | Purpose | Example | |---|-----------|---------------|---------------------------------------------------------------|------------------------------------| | | tile | Integer | Number of columns and rows the image is split into. | 14 6 (14 columns, 6 rows) | | ⭐️ | roi | Integer | Region of Interest: Defines the focal point within the image. | 5 (banks-of-the-seine-5.webp) | | ⭐️ | scale | Float Integer | Enlarges the image when viewport is below a breakpoint. | 1.2 750 (120% at 750px width) | | | path | String | File path where the tiles are stored. | assets/media/banks-of-the-seine/ |

How to Use

1. Tile Maker: Use the Tile Maker web application to generate the tiles and HTML snippet.

2. Update HTML Snippet: Update the path parameter in the HTML snippet to point to your tiles, along with optional parameters like roi and scale. Remember to update the image alt text as well.

3. Include Pruner.js: To include the utility in your project. Add either option before the closing </html> tag in your HTML file.

   • Option 1: Download.

     <script async src="/YOUR-PATH-HERE/pruner.min.js"></script>

   • Option 2: CDN.

     <script async src="https://unpkg.com/prunerjs/dist/pruner.min.js"></script>

Demo

→ Open Demo

The painting Banks of the Seine, Vétheuil, by Claude Monet was processed using the Tile Maker web application, which calculated that the image should be split into an 14x6 grid. Each tile measuring 137x180px, resulting in a total of 84 tiles and an average pixel waste of 12.47% across common screen resolutions. The generated HTML <img> tag snippet for this image is as follows:

<img data-pruner='{"name": "banks-of-the-seine", "tile": "14 6", "roi": 5, "path": "YOUR-PATH-HERE/"}' alt="YOUR-ALT-TEXT-HERE">

The path and the optional scale parameter, along with the alt attribute, were then updated afterwards.

<img data-pruner='{"name": "banks-of-the-seine", "tile": "14 6", "roi": 5, "scale": "1.2 750", "path": "assets/media/banks-of-the-seine/"}' alt="Banks of the Seine, Vétheuil, 1880 by Claude Monet">

Research

We are preparing a research paper evaluating Pruner.js against HTML5.1 responsive image techniques. The results will be added to this README once published.

Contributing

Contributions are welcome. Please feel free to submit an issue or a pull request.

License

Pruner.js is released under the MIT license. Feel free to use and modify it as needed.