@visualizevalue/img-grid 0.1.2 → 0.1.4

package/README.md

@@ -30,6 +30,10 @@ const highlightedBuffer = await grid(images, {
   highlight: ['img2', 'img3'], // Images with these IDs will be 2×2
   maxWidth: 1920, // Maximum width of output image
   concurrency: 10, // Maximum concurrent downloads
+  background: '#000', // Fills background, padding, gutters, and letterboxing
+  padding: 16, // Space around the whole grid, in pixels
+  gutter: 8, // Gap between cells (rows and columns), in pixels
+  pixelated: true, // Nearest-neighbour resize — keeps pixel art crisp
   format: 'webp', // Output as png (default), jpeg, or webp
   quality: 80, // Quality for jpeg/webp
   onError: (img, err) => console.warn(`failed: ${img.url}`, err),
@@ -43,6 +47,8 @@ writeFileSync('grid.png', buffer)
 
 - Packs images into a compact, near-square grid
 - Supports highlighting specific images (makes them 2×2)
+- Configurable `background` color, `padding` around the grid, and `gutter` between cells
+- Optional nearest-neighbour scaling to keep pixel art crisp (`pixelated`)
 - Downloads images concurrently (with a configurable limit)
 - Leaves a blank cell for failed downloads instead of failing the grid
 - Output as PNG, JPEG, or WebP
@@ -55,7 +61,10 @@ writeFileSync('grid.png', buffer)
 | `highlight`   | `[]`        | Array of image IDs to highlight (make 2×2)         |
 | `maxWidth`    | `1920`      | Maximum width of output image in pixels            |
 | `concurrency` | `10`        | Maximum concurrent image downloads                 |
-| `background`  | `'#000'`    | Background and letterbox color (any sharp color)   |
+| `background`  | `'#000'`    | Fills background, padding, gutters, letterboxing   |
+| `padding`     | `0`         | Space around the whole grid, in pixels             |
+| `gutter`      | `0`         | Gap between cells (rows and columns), in pixels     |
+| `pixelated`   | `false`     | Nearest-neighbour resize; keeps pixel art crisp    |
 | `format`      | `'png'`     | Output format: `'png'`, `'jpeg'`, or `'webp'`      |
 | `quality`     | sharp's     | Quality (1–100) for `jpeg`/`webp`; ignored for png |
 | `onError`     | `undefined` | `(img, error) => void` called when an image fails  |

package/dist/index.d.ts

@@ -10,8 +10,21 @@ export interface GridOptions {
     maxWidth?: number;
     /** Maximum number of images downloaded at once. */
     concurrency?: number;
-    /** Background and letterbox color (any sharp-compatible color). */
+    /**
+     * Color filling the background, padding, gutters, and image letterboxing
+     * (any sharp-compatible color).
+     */
     background?: string;
+    /** Space around the whole grid, in pixels. Filled with `background`. */
+    padding?: number;
+    /** Gap between cells (rows and columns), in pixels. Filled with `background`. */
+    gutter?: number;
+    /**
+     * Resize with nearest-neighbour instead of the default smooth (lanczos)
+     * kernel. Keeps pixel art (e.g. NFTs) crisp instead of blurring it when
+     * scaled up. Like CSS `image-rendering: pixelated`.
+     */
+    pixelated?: boolean;
     /** Output image format. */
     format?: ImageFormat;
     /** Quality (1–100) for lossy formats (`jpeg`, `webp`); ignored for `png`. */

package/dist/index.js

@@ -8,6 +8,8 @@ const sharp_1 = __importDefault(require("sharp"));
 const DEFAULT_MAX_WIDTH = 1920;
 const DEFAULT_CONCURRENCY = 10;
 const DEFAULT_BACKGROUND = '#000';
+const DEFAULT_PADDING = 0;
+const DEFAULT_GUTTER = 0;
 const DEFAULT_FORMAT = 'png';
 const FETCH_TIMEOUT_MS = 15_000;
 const HIGHLIGHT_SPAN = 2;
@@ -19,26 +21,39 @@ const HIGHLIGHT_SPAN = 2;
  * `onError`) instead of failing the whole grid.
  */
 async function grid(images, opts = {}) {
-    const { highlight = [], maxWidth = DEFAULT_MAX_WIDTH, concurrency = DEFAULT_CONCURRENCY, background = DEFAULT_BACKGROUND, format = DEFAULT_FORMAT, quality, onError, } = opts;
+    const { highlight = [], maxWidth = DEFAULT_MAX_WIDTH, concurrency = DEFAULT_CONCURRENCY, background = DEFAULT_BACKGROUND, pixelated = false, format = DEFAULT_FORMAT, quality, onError, } = opts;
+    const padding = Math.max(0, Math.floor(opts.padding ?? DEFAULT_PADDING));
+    const gutter = Math.max(0, Math.floor(opts.gutter ?? DEFAULT_GUTTER));
     const highlightIds = new Set(highlight);
     const isHighlighted = (img) => img.id !== undefined && highlightIds.has(img.id);
     const highlighted = images.filter(isHighlighted);
     const normal = images.filter((img) => !isHighlighted(img));
     const totalCells = normal.length + highlighted.length * HIGHLIGHT_SPAN ** 2;
-    if (totalCells === 0)
-        return encode(blankCanvas(1, 1, background), format, quality);
+    if (totalCells === 0) {
+        const side = Math.max(1, 2 * padding);
+        return encode(blankCanvas(side, side, background), format, quality);
+    }
     const { columns, rows, placements } = chooseLayout(highlighted, normal);
-    const cellSize = Math.max(1, Math.floor(maxWidth / columns));
+    // Carve padding and inter-column gutters out of the width budget before
+    // dividing what's left among the columns, so the output never exceeds maxWidth.
+    const available = maxWidth - 2 * padding - (columns - 1) * gutter;
+    const cellSize = Math.max(1, Math.floor(available / columns));
+    // Top-left pixel of cell (col, row); a span-N block also covers the N−1
+    // gutters between the cells it spans, so it reads as one solid larger tile.
+    const offset = (index) => padding + index * (cellSize + gutter);
+    const spanSize = (span) => span * cellSize + (span - 1) * gutter;
     const layers = await mapWithConcurrency(placements, concurrency, async (placement) => {
-        const size = cellSize * placement.span;
-        const cell = await renderCell(placement.img, size, background, onError);
+        const size = spanSize(placement.span);
+        const cell = await renderCell(placement.img, size, background, pixelated, onError);
         return {
             input: cell,
-            left: placement.col * cellSize,
-            top: placement.row * cellSize,
+            left: offset(placement.col),
+            top: offset(placement.row),
         };
     });
-    const canvas = blankCanvas(columns * cellSize, rows * cellSize, background).composite(layers);
+    const width = 2 * padding + columns * cellSize + (columns - 1) * gutter;
+    const height = 2 * padding + rows * cellSize + (rows - 1) * gutter;
+    const canvas = blankCanvas(width, height, background).composite(layers);
     return encode(canvas, format, quality);
 }
 /**
@@ -117,7 +132,7 @@ function pack(highlighted, normal, columns) {
     return { placements, rows: occupied.length };
 }
 /** Fetch and resize a single image; fall back to a blank cell on any failure. */
-async function renderCell(img, size, background, onError) {
+async function renderCell(img, size, background, pixelated, onError) {
     try {
         const response = await fetch(img.url, {
             signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
@@ -127,7 +142,11 @@ async function renderCell(img, size, background, onError) {
             throw new Error(`HTTP ${response.status} for ${img.url}`);
         const data = Buffer.from(await response.arrayBuffer());
         return await (0, sharp_1.default)(data)
-            .resize(size, size, { fit: 'contain', background })
+            .resize(size, size, {
+            fit: 'contain',
+            background,
+            ...(pixelated ? { kernel: 'nearest' } : {}),
+        })
             .png()
             .toBuffer();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visualizevalue/img-grid",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Generate an image grid (PNG, JPEG, or WebP) from image URLs (and highlight images).",
   "license": "MIT",
   "author": "Visualize Value",