@kotaksurat/photobooth-frame-generator 1.0.0

package/README.md

@@ -0,0 +1,101 @@
+# Photobooth Frame Generator
+
+A fast and efficient TypeScript engine to automate placing user photos into a template frame's transparent slots. It analyzes the alpha channel of the frame to dynamically find transparent "slots" and creatively paints the user's photos underneath those areas.
+
+## Features
+
+- **Dynamic Slot Detection**: Automatically finds empty (transparent) slots in a template frame using Breadth-First Search (BFS).
+- **Auto Cover/Crop**: Intelligently fits your photos into the detected slots, preserving the aspect ratio (similar to `object-fit: cover`).
+- **Memory Management**: Includes a `reset()` method to free memory by revoking File object URLs and hinting garbage collection.
+- **Browser Ready**: Uses the HTML5 Canvas API and `ImageData` for fast, client-side processing.
+
+## Installation
+
+```sh
+npm install
+```
+
+## Basic Usage
+
+The engine supports inputs as `File` objects or `Base64` data URLs.
+
+```typescript
+import { PhotoboothFrameGenerator } from 'photobooth-frame-generator';
+
+// 1. Initialize the engine
+const engine = new PhotoboothFrameGenerator({
+    outputFormat: 'image/jpeg',
+    quality: 0.95
+});
+
+async function processPhotos(frameFile: File, userPhotos: File[]) {
+    try {
+        // 2. Generate the result
+        const result = await engine.create(frameFile, userPhotos);
+        
+        console.log(`Generated image with ${result.slotsFound} slots!`);
+        
+        // Use result.dataUrl as the src for an HTML Image element
+        const img = new Image();
+        img.src = result.dataUrl;
+        document.body.appendChild(img);
+        
+    } catch (error) {
+        console.error('Processing failed:', error);
+    } finally {
+        // 3. Clean up memory to avoid blobs piling up
+        engine.reset();
+    }
+}
+```
+
+## Configuration
+
+When instantiating `PhotoboothFrameGenerator`, you can pass an optional configuration object:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `alphaThreshold` | `number` | `10` | The alpha channel threshold (0-255) below which a pixel is considered transparent. |
+| `minSlotSize` | `number` | `50` | Minimum width/height in pixels to be considered a valid slot (avoids micro-artifacts being selected). |
+| `outputFormat` | `string` | `'image/png'` | The mime type of the generated image (`image/png`, `image/jpeg`, `image/webp`). |
+| `quality` | `number` | `0.92` | The image quality from `0.0` to `1.0` (applicable for jpeg/webp formats). |
+| `fillEmptySlots` | `boolean` | `true` | If true, intelligently loops through provided photos to fill any remaining empty frame slots. |
+| `slotExpansion` | `number` | `5` | Expansion in pixels added to each detected slot's edges to cover anti-aliased transparency gaps. |
+
+## How It Works
+1. **Load Assets:** Internally converts `File` objects to blob URLs to be drawn onto a virtual canvas.
+2. **Scan Alpha:** Performs a BFS scan over the `ImageData` to locate contiguous transparent regions (alpha < `alphaThreshold`).
+3. **Sort Slots:** Sorts detected regions topologically (top-to-bottom, left-to-right).
+4. **Draw Composition:** Draws the user photos onto the base layer positioned in the slots, and places the original frame natively as the top layer.
+
+## Packages & Dependencies Used
+
+This engine is lightweight and utilizes standard browser APIs internally, but relies on a few core packages for development:
+
+- **`typescript` & `@types/node`**: Enables strict static typings and smooth transpilation from `src/` to a publishable package.
+- **`vitest`**: A modern and extremely fast test runner tailored for TypeScript and built natively around Vite syntax.
+- **`jsdom`**: Used alongside Vitest to seamlessly mock essential HTML5 Browser environments (like `URL` & partial native APIs) during runtime testing.
+
+## Running the Example
+
+We have provided a demo implementation showcasing how the package works in action globally.
+You can find it under the `example/` directory. 
+
+To serve and test the example in your browser, run:
+```sh
+npx vite dev example
+```
+1. Open the local link (e.g., `http://localhost:5173/`) in the browser.
+2. Under "Select Frame", upload a `PNG` containing transparent rectangular slots matching your final format.
+3. Under "Select Photos", choose as many images as you need corresponding to the holes on the given frame.
+4. Hit **Generate Result** to fetch the composed canvas snapshot.
+
+## Running Tests
+
+We implement unit tests focusing on robust config parsers and safe memory resetting tools using `vitest`.
+
+To execute the entire test suite, make sure you have installed standard modules with `npm install`, then run:
+```sh
+npm run test
+```
+This will discover scripts inside the `test/` directory using the `vitest.config.ts` rules, executing assertions efficiently on the JSDOM mock environment.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { ImageSource, PhotoboothConfig, RenderResult } from './types';
+export declare class PhotoboothFrameGenerator {
+    private config;
+    private objectUrls;
+    constructor(config?: PhotoboothConfig);
+    /**
+     * Fungsi utama untuk memproses frame dan foto.
+     * Mendukung input berupa Base64 string atau File object.
+     */
+    create(frameSource: ImageSource, userPhotos: ImageSource[]): Promise<RenderResult>;
+    /**
+     * Fungsi Reset untuk Manajemen Memori.
+     * WAJIB dipanggil setelah proses selesai atau saat komponen di-unmount.
+     */
+    reset(): void;
+    private loadImage;
+    private findSlotsBFS;
+    private drawCover;
+}

package/dist/index.js

@@ -0,0 +1,164 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PhotoboothFrameGenerator = void 0;
+class PhotoboothFrameGenerator {
+    constructor(config) {
+        var _a, _b, _c, _d, _e, _f;
+        this.objectUrls = []; // Track untuk manajemen memori
+        this.config = {
+            alphaThreshold: (_a = config === null || config === void 0 ? void 0 : config.alphaThreshold) !== null && _a !== void 0 ? _a : 10,
+            minSlotSize: (_b = config === null || config === void 0 ? void 0 : config.minSlotSize) !== null && _b !== void 0 ? _b : 50,
+            outputFormat: (_c = config === null || config === void 0 ? void 0 : config.outputFormat) !== null && _c !== void 0 ? _c : 'image/png',
+            quality: (_d = config === null || config === void 0 ? void 0 : config.quality) !== null && _d !== void 0 ? _d : 0.92,
+            fillEmptySlots: (_e = config === null || config === void 0 ? void 0 : config.fillEmptySlots) !== null && _e !== void 0 ? _e : true,
+            slotExpansion: (_f = config === null || config === void 0 ? void 0 : config.slotExpansion) !== null && _f !== void 0 ? _f : 5,
+        };
+    }
+    /**
+     * Fungsi utama untuk memproses frame dan foto.
+     * Mendukung input berupa Base64 string atau File object.
+     */
+    create(frameSource, userPhotos) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const frame = yield this.loadImage(frameSource);
+                const canvas = document.createElement('canvas');
+                const ctx = canvas.getContext('2d', { willReadFrequently: true });
+                if (!ctx)
+                    throw new Error("Canvas context 2D not found");
+                canvas.width = frame.width;
+                canvas.height = frame.height;
+                // 1. Deteksi Slot
+                ctx.drawImage(frame, 0, 0);
+                const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+                const slots = this.findSlotsBFS(imageData);
+                // 2. Render Final
+                ctx.clearRect(0, 0, canvas.width, canvas.height);
+                // Gambar foto user (Layer bawah)
+                for (let i = 0; i < slots.length; i++) {
+                    let photoSource = userPhotos[i];
+                    // Jika fillEmptySlots true dan foto yang disuplai lebih sedikit dari slot
+                    if (!photoSource && this.config.fillEmptySlots && userPhotos.length > 0) {
+                        photoSource = userPhotos[i % userPhotos.length];
+                    }
+                    if (photoSource) {
+                        const photo = yield this.loadImage(photoSource);
+                        this.drawCover(ctx, photo, slots[i]);
+                    }
+                }
+                // Gambar frame (Layer atas)
+                ctx.drawImage(frame, 0, 0);
+                return {
+                    dataUrl: canvas.toDataURL(this.config.outputFormat, this.config.quality),
+                    slotsFound: slots.length,
+                    width: canvas.width,
+                    height: canvas.height
+                };
+            }
+            catch (error) {
+                throw new Error(`PhotoboothFrameGenerator Error: ${error}`);
+            }
+        });
+    }
+    /**
+     * Fungsi Reset untuk Manajemen Memori.
+     * WAJIB dipanggil setelah proses selesai atau saat komponen di-unmount.
+     */
+    reset() {
+        // Revoke semua Object URL yang dibuat dari File untuk mengosongkan RAM
+        this.objectUrls.forEach(url => URL.revokeObjectURL(url));
+        this.objectUrls = [];
+        // Memberi sinyal ke GC bahwa referensi bisa dihapus
+        console.log("PhotoboothFrameGenerator: Memory cleared.");
+    }
+    loadImage(source) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => {
+                const img = new Image();
+                let url;
+                if (source instanceof File) {
+                    url = URL.createObjectURL(source);
+                    this.objectUrls.push(url); // Simpan untuk di-reset nanti
+                }
+                else {
+                    url = source; // Base64 atau URL string
+                }
+                img.onload = () => resolve(img);
+                img.onerror = () => reject("Failed to load image source");
+                img.src = url;
+            });
+        });
+    }
+    findSlotsBFS(imageData) {
+        const { width, height, data } = imageData;
+        const visited = new Uint8Array(width * height);
+        const slots = [];
+        for (let i = 0; i < width * height; i++) {
+            if (data[i * 4 + 3] < this.config.alphaThreshold && !visited[i]) {
+                const queue = [i];
+                visited[i] = 1;
+                let minX = i % width, maxX = minX, minY = Math.floor(i / width), maxY = minY;
+                let head = 0;
+                while (head < queue.length) {
+                    const curr = queue[head++];
+                    const cx = curr % width, cy = Math.floor(curr / width);
+                    const neighbors = [[cx + 1, cy], [cx - 1, cy], [cx, cy + 1], [cx, cy - 1]];
+                    for (const [nx, ny] of neighbors) {
+                        if (nx >= 0 && nx < width && ny >= 0 && ny < height) {
+                            const nIdx = ny * width + nx;
+                            if (!visited[nIdx] && data[nIdx * 4 + 3] < this.config.alphaThreshold) {
+                                visited[nIdx] = 1;
+                                queue.push(nIdx);
+                                if (nx < minX)
+                                    minX = nx;
+                                if (nx > maxX)
+                                    maxX = nx;
+                                if (ny < minY)
+                                    minY = ny;
+                                if (ny > maxY)
+                                    maxY = ny;
+                            }
+                        }
+                    }
+                }
+                if (maxX - minX > this.config.minSlotSize) {
+                    slots.push({ x: minX, y: minY, width: maxX - minX, height: maxY - minY });
+                }
+            }
+        }
+        return slots.sort((a, b) => (a.y - b.y) || (a.x - b.x));
+    }
+    drawCover(ctx, img, slot) {
+        const expansion = this.config.slotExpansion;
+        const targetX = slot.x - expansion;
+        const targetY = slot.y - expansion;
+        const targetW = slot.width + (expansion * 2);
+        const targetH = slot.height + (expansion * 2);
+        const imgRatio = img.width / img.height;
+        const slotRatio = targetW / targetH;
+        let sw, sh, sx, sy;
+        if (imgRatio > slotRatio) {
+            sw = img.height * slotRatio;
+            sh = img.height;
+            sx = (img.width - sw) / 2;
+            sy = 0;
+        }
+        else {
+            sw = img.width;
+            sh = img.width / slotRatio;
+            sx = 0;
+            sy = (img.height - sh) / 2;
+        }
+        ctx.drawImage(img, sx, sy, sw, sh, targetX, targetY, targetW, targetH);
+    }
+}
+exports.PhotoboothFrameGenerator = PhotoboothFrameGenerator;

package/dist/src/index.d.ts

@@ -0,0 +1,19 @@
+import { ImageSource, PhotoboothConfig, RenderResult } from './types';
+export declare class PhotoboothFrameGenerator {
+    private config;
+    private objectUrls;
+    constructor(config?: PhotoboothConfig);
+    /**
+     * Fungsi utama untuk memproses frame dan foto.
+     * Mendukung input berupa Base64 string atau File object.
+     */
+    create(frameSource: ImageSource, userPhotos: ImageSource[]): Promise<RenderResult>;
+    /**
+     * Fungsi Reset untuk Manajemen Memori.
+     * WAJIB dipanggil setelah proses selesai atau saat komponen di-unmount.
+     */
+    reset(): void;
+    private loadImage;
+    private findSlotsBFS;
+    private drawCover;
+}

package/dist/src/index.js

@@ -0,0 +1,164 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PhotoboothFrameGenerator = void 0;
+class PhotoboothFrameGenerator {
+    constructor(config) {
+        var _a, _b, _c, _d, _e, _f;
+        this.objectUrls = []; // Track untuk manajemen memori
+        this.config = {
+            alphaThreshold: (_a = config === null || config === void 0 ? void 0 : config.alphaThreshold) !== null && _a !== void 0 ? _a : 10,
+            minSlotSize: (_b = config === null || config === void 0 ? void 0 : config.minSlotSize) !== null && _b !== void 0 ? _b : 50,
+            outputFormat: (_c = config === null || config === void 0 ? void 0 : config.outputFormat) !== null && _c !== void 0 ? _c : 'image/png',
+            quality: (_d = config === null || config === void 0 ? void 0 : config.quality) !== null && _d !== void 0 ? _d : 0.92,
+            fillEmptySlots: (_e = config === null || config === void 0 ? void 0 : config.fillEmptySlots) !== null && _e !== void 0 ? _e : true,
+            slotExpansion: (_f = config === null || config === void 0 ? void 0 : config.slotExpansion) !== null && _f !== void 0 ? _f : 5,
+        };
+    }
+    /**
+     * Fungsi utama untuk memproses frame dan foto.
+     * Mendukung input berupa Base64 string atau File object.
+     */
+    create(frameSource, userPhotos) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const frame = yield this.loadImage(frameSource);
+                const canvas = document.createElement('canvas');
+                const ctx = canvas.getContext('2d', { willReadFrequently: true });
+                if (!ctx)
+                    throw new Error("Canvas context 2D not found");
+                canvas.width = frame.width;
+                canvas.height = frame.height;
+                // 1. Deteksi Slot
+                ctx.drawImage(frame, 0, 0);
+                const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+                const slots = this.findSlotsBFS(imageData);
+                // 2. Render Final
+                ctx.clearRect(0, 0, canvas.width, canvas.height);
+                // Gambar foto user (Layer bawah)
+                for (let i = 0; i < slots.length; i++) {
+                    let photoSource = userPhotos[i];
+                    // Jika fillEmptySlots true dan foto yang disuplai lebih sedikit dari slot
+                    if (!photoSource && this.config.fillEmptySlots && userPhotos.length > 0) {
+                        photoSource = userPhotos[i % userPhotos.length];
+                    }
+                    if (photoSource) {
+                        const photo = yield this.loadImage(photoSource);
+                        this.drawCover(ctx, photo, slots[i]);
+                    }
+                }
+                // Gambar frame (Layer atas)
+                ctx.drawImage(frame, 0, 0);
+                return {
+                    dataUrl: canvas.toDataURL(this.config.outputFormat, this.config.quality),
+                    slotsFound: slots.length,
+                    width: canvas.width,
+                    height: canvas.height
+                };
+            }
+            catch (error) {
+                throw new Error(`PhotoboothFrameGenerator Error: ${error}`);
+            }
+        });
+    }
+    /**
+     * Fungsi Reset untuk Manajemen Memori.
+     * WAJIB dipanggil setelah proses selesai atau saat komponen di-unmount.
+     */
+    reset() {
+        // Revoke semua Object URL yang dibuat dari File untuk mengosongkan RAM
+        this.objectUrls.forEach(url => URL.revokeObjectURL(url));
+        this.objectUrls = [];
+        // Memberi sinyal ke GC bahwa referensi bisa dihapus
+        console.log("PhotoboothFrameGenerator: Memory cleared.");
+    }
+    loadImage(source) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => {
+                const img = new Image();
+                let url;
+                if (source instanceof File) {
+                    url = URL.createObjectURL(source);
+                    this.objectUrls.push(url); // Simpan untuk di-reset nanti
+                }
+                else {
+                    url = source; // Base64 atau URL string
+                }
+                img.onload = () => resolve(img);
+                img.onerror = () => reject("Failed to load image source");
+                img.src = url;
+            });
+        });
+    }
+    findSlotsBFS(imageData) {
+        const { width, height, data } = imageData;
+        const visited = new Uint8Array(width * height);
+        const slots = [];
+        for (let i = 0; i < width * height; i++) {
+            if (data[i * 4 + 3] < this.config.alphaThreshold && !visited[i]) {
+                const queue = [i];
+                visited[i] = 1;
+                let minX = i % width, maxX = minX, minY = Math.floor(i / width), maxY = minY;
+                let head = 0;
+                while (head < queue.length) {
+                    const curr = queue[head++];
+                    const cx = curr % width, cy = Math.floor(curr / width);
+                    const neighbors = [[cx + 1, cy], [cx - 1, cy], [cx, cy + 1], [cx, cy - 1]];
+                    for (const [nx, ny] of neighbors) {
+                        if (nx >= 0 && nx < width && ny >= 0 && ny < height) {
+                            const nIdx = ny * width + nx;
+                            if (!visited[nIdx] && data[nIdx * 4 + 3] < this.config.alphaThreshold) {
+                                visited[nIdx] = 1;
+                                queue.push(nIdx);
+                                if (nx < minX)
+                                    minX = nx;
+                                if (nx > maxX)
+                                    maxX = nx;
+                                if (ny < minY)
+                                    minY = ny;
+                                if (ny > maxY)
+                                    maxY = ny;
+                            }
+                        }
+                    }
+                }
+                if (maxX - minX > this.config.minSlotSize) {
+                    slots.push({ x: minX, y: minY, width: maxX - minX, height: maxY - minY });
+                }
+            }
+        }
+        return slots.sort((a, b) => (a.y - b.y) || (a.x - b.x));
+    }
+    drawCover(ctx, img, slot) {
+        const expansion = this.config.slotExpansion;
+        const targetX = slot.x - expansion;
+        const targetY = slot.y - expansion;
+        const targetW = slot.width + (expansion * 2);
+        const targetH = slot.height + (expansion * 2);
+        const imgRatio = img.width / img.height;
+        const slotRatio = targetW / targetH;
+        let sw, sh, sx, sy;
+        if (imgRatio > slotRatio) {
+            sw = img.height * slotRatio;
+            sh = img.height;
+            sx = (img.width - sw) / 2;
+            sy = 0;
+        }
+        else {
+            sw = img.width;
+            sh = img.width / slotRatio;
+            sx = 0;
+            sy = (img.height - sh) / 2;
+        }
+        ctx.drawImage(img, sx, sy, sw, sh, targetX, targetY, targetW, targetH);
+    }
+}
+exports.PhotoboothFrameGenerator = PhotoboothFrameGenerator;

package/dist/src/types.d.ts

@@ -0,0 +1,21 @@
+export type ImageSource = string | File;
+export interface Slot {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PhotoboothConfig {
+    alphaThreshold?: number;
+    minSlotSize?: number;
+    outputFormat?: 'image/png' | 'image/jpeg' | 'image/webp';
+    quality?: number;
+    fillEmptySlots?: boolean;
+    slotExpansion?: number;
+}
+export interface RenderResult {
+    dataUrl: string;
+    slotsFound: number;
+    width: number;
+    height: number;
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export type ImageSource = string | File;
+export interface Slot {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PhotoboothConfig {
+    alphaThreshold?: number;
+    minSlotSize?: number;
+    outputFormat?: 'image/png' | 'image/jpeg' | 'image/webp';
+    quality?: number;
+    fillEmptySlots?: boolean;
+    slotExpansion?: number;
+}
+export interface RenderResult {
+    dataUrl: string;
+    slotsFound: number;
+    width: number;
+    height: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@kotaksurat/photobooth-frame-generator",
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ahdja/photobooth-frame-generator"
+  },
+  "description": "A fast and efficient engine to automate placing user photos into a frame's transparent slots.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "photobooth",
+    "canvas",
+    "image-processing",
+    "typescript"
+  ],
+  "author": "Arief Hidayat Djauhar",
+  "license": "ISC",
+  "type": "commonjs",
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "jsdom": "^29.0.1",
+    "tslib": "^2.8.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}