@visualizevalue/img-grid 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# img-grid
+
+Generate image grids from URLs (and highlight images).
+
+## Installation
+
+```bash
+npm install @visualizevalue/img-grid
+```
+
+## Usage
+
+```javascript
+import { grid } from '@visualizevalue/img-grid'
+import { writeFileSync } from 'fs'
+
+// Define image URLs with optional IDs
+const images = [
+  { url: 'https://example.com/image1.jpg', id: 'img1' },
+  { url: 'https://example.com/image2.jpg', id: 'img2' },
+  { url: 'https://example.com/image3.jpg', id: 'img3' },
+  { url: 'https://example.com/image4.jpg', id: 'img4' },
+]
+
+// Create a grid with default options
+const buffer = await grid(images)
+
+// Or highlight specific images (makes them 2×2)
+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
+})
+
+// Save to file
+writeFileSync('grid.png', buffer)
+```
+
+## Features
+
+- Arranges images in an optimal grid layout
+- Supports highlighting specific images (makes them 2×2)
+- Handles failed image downloads with placeholders
+- Limits concurrent downloads
+- Resizes all images to fit grid cells
+
+## Options
+
+| Option        | Default | Description                                |
+| ------------- | ------- | ------------------------------------------ |
+| `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         |

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export interface Img {
+    url: string;
+    id?: string;
+}
+export interface GridOptions {
+    highlight?: string[];
+    maxWidth?: number;
+    concurrency?: number;
+}
+export declare function grid(images: Img[], opts?: GridOptions): Promise<Buffer>;

package/dist/index.js

@@ -0,0 +1,129 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.grid = grid;
+const sharp_1 = __importDefault(require("sharp"));
+async function grid(images, opts = {}) {
+    const highlightIds = new Set(opts.highlight ?? []);
+    const concurrency = opts.concurrency ?? 10;
+    const highlightScale = 2;
+    const maxWidth = opts.maxWidth ?? 1920;
+    const highlightedImages = images.filter((img) => img.id && highlightIds.has(img.id));
+    const normalImages = images.filter((img) => !highlightIds.has(img.id ?? ''));
+    const totalCells = normalImages.length + highlightedImages.length * highlightScale * highlightScale;
+    const gridSize = Math.ceil(Math.sqrt(totalCells));
+    const cellSize = Math.floor(maxWidth / gridSize);
+    const highlightedCellSize = cellSize * highlightScale;
+    const gridWidth = Math.max(gridSize, Math.ceil(Math.sqrt(totalCells * 1.5)));
+    const gridHeight = gridSize * highlightScale;
+    const grid = Array(gridHeight)
+        .fill(0)
+        .map(() => Array(gridWidth).fill(false));
+    function isFree(x, y, width, height) {
+        for (let dy = 0; dy < height; dy++) {
+            for (let dx = 0; dx < width; dx++) {
+                if (y + dy >= gridHeight || x + dx >= gridWidth || grid[y + dy][x + dx]) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    function markOccupied(x, y, width, height) {
+        for (let dy = 0; dy < height; dy++) {
+            for (let dx = 0; dx < width; dx++) {
+                grid[y + dy][x + dx] = true;
+            }
+        }
+    }
+    function findSpot(width, height) {
+        for (let y = 0; y <= gridHeight - height; y++) {
+            for (let x = 0; x <= gridWidth - width; x++) {
+                if (isFree(x, y, width, height)) {
+                    return [x, y];
+                }
+            }
+        }
+        return null;
+    }
+    let inFlight = 0;
+    async function fetchImage(url, size) {
+        while (inFlight >= concurrency) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        inFlight++;
+        try {
+            const response = await fetch(url, {
+                signal: AbortSignal.timeout(15000),
+                headers: { Accept: 'image/*' },
+            });
+            if (!response.ok)
+                throw new Error(`HTTP error ${response.status}`);
+            const data = await response.arrayBuffer();
+            return (0, sharp_1.default)(Buffer.from(data))
+                .resize(size, size, { fit: 'contain', background: '#000' })
+                .toBuffer();
+        }
+        catch (error) {
+            // return placeholder if error
+            return (0, sharp_1.default)({
+                create: {
+                    width: size,
+                    height: size,
+                    channels: 3,
+                    background: '#007F00',
+                },
+            })
+                .png()
+                .toBuffer();
+        }
+        finally {
+            inFlight--;
+        }
+    }
+    const compositeLayers = [];
+    let maxY = 0;
+    for (const img of highlightedImages) {
+        const spot = findSpot(highlightScale, highlightScale);
+        if (!spot)
+            continue;
+        const [x, y] = spot;
+        markOccupied(x, y, highlightScale, highlightScale);
+        const imageBuffer = await fetchImage(img.url, highlightedCellSize);
+        compositeLayers.push({
+            input: imageBuffer,
+            left: x * cellSize,
+            top: y * cellSize,
+        });
+        maxY = Math.max(maxY, y + highlightScale);
+    }
+    for (const img of normalImages) {
+        const spot = findSpot(1, 1);
+        if (!spot)
+            break;
+        const [x, y] = spot;
+        markOccupied(x, y, 1, 1);
+        const imageBuffer = await fetchImage(img.url, cellSize);
+        compositeLayers.push({
+            input: imageBuffer,
+            left: x * cellSize,
+            top: y * cellSize,
+        });
+        maxY = Math.max(maxY, y + 1);
+    }
+    const outputHeight = Math.max(1, maxY) * cellSize;
+    const outputWidth = gridWidth * cellSize;
+    return (0, sharp_1.default)({
+        create: {
+            width: outputWidth,
+            height: outputHeight,
+            channels: 3,
+            background: '#000',
+        },
+    })
+        .composite(compositeLayers)
+        .png()
+        .toBuffer();
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@visualizevalue/img-grid",
+  "version": "0.1.0",
+  "description": "Generate a PNG grid from image URLs (and highlight images).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "packageManager": "npm@11.4.0",
+  "scripts": {
+    "build": "tsc",
+    "format": "prettier --write",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "sharp": "^0.33"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "prettier": "^3.5.3",
+    "tsx": "^4",
+    "typescript": "^5"
+  }
+}