restyle-sprites 0.1.0

package/dist/PixelArtPostProcessor.js

@@ -0,0 +1,404 @@
+import sharp from 'sharp';
+import * as iq from 'image-q';
+export class PixelArtPostProcessor {
+    static DEFAULT_MAX_COLORS = 24;
+    static DEFAULT_ALPHA_THRESHOLD = 128;
+    async process(rawBuffer, targetWidth, targetHeight, options) {
+        const alphaThreshold = options?.alphaThreshold ?? PixelArtPostProcessor.DEFAULT_ALPHA_THRESHOLD;
+        const maxColors = options?.maxColors ?? PixelArtPostProcessor.DEFAULT_MAX_COLORS;
+        const isLayoutSensitiveCategory = options?.category === 'font' || options?.category === 'scene';
+        const binarized = await this.binarizeAlpha(rawBuffer, alphaThreshold);
+        const processedBase = isLayoutSensitiveCategory ? binarized : await this.alphaTightCrop(binarized);
+        const quantized = await this.quantizeColors(processedBase, maxColors);
+        const resized = isLayoutSensitiveCategory
+            ? await this.resizeNearest(quantized, targetWidth, targetHeight)
+            : await this.resizeWithReferenceGeometry({
+                content: quantized,
+                targetWidth,
+                targetHeight,
+                sourceReference: options?.sourceReference,
+                alphaThreshold,
+            });
+        const cleaned = await this.finalAlphaCleanup(resized, alphaThreshold);
+        if (!isLayoutSensitiveCategory && options?.sourceReference) {
+            const masked = await this.applySourceMask(cleaned, options.sourceReference, targetWidth, targetHeight);
+            return this.zeroRgbOnTransparent(masked);
+        }
+        return this.zeroRgbOnTransparent(cleaned);
+    }
+    async extractPalette(sourceBuffer, maxColors = PixelArtPostProcessor.DEFAULT_MAX_COLORS) {
+        const quantized = await this.quantizeColors(sourceBuffer, maxColors);
+        const raw = await this.toRawImage(quantized);
+        const colors = new Set();
+        for (let index = 0; index < raw.data.length; index += 4) {
+            const alpha = raw.data[index + 3];
+            if (alpha === 0) {
+                continue;
+            }
+            const red = raw.data[index];
+            const green = raw.data[index + 1];
+            const blue = raw.data[index + 2];
+            colors.add(this.rgbToHex(red, green, blue));
+            if (colors.size >= maxColors) {
+                break;
+            }
+        }
+        return Array.from(colors);
+    }
+    async stripLegacyBackground(sourceBuffer, tolerance = 34) {
+        const raw = await this.toRawImage(sourceBuffer);
+        if (!this.isFullyOpaque(raw)) {
+            return this.zeroRgbOnTransparent(sourceBuffer);
+        }
+        const keyColor = this.estimateBackgroundColor(raw.data, raw.width, raw.height);
+        for (let index = 0; index < raw.data.length; index += 4) {
+            const red = raw.data[index];
+            const green = raw.data[index + 1];
+            const blue = raw.data[index + 2];
+            const distance = Math.sqrt((red - keyColor.r) ** 2 + (green - keyColor.g) ** 2 + (blue - keyColor.b) ** 2);
+            if (distance > tolerance) {
+                raw.data[index + 3] = 255;
+                continue;
+            }
+            raw.data[index + 3] = 0;
+            raw.data[index] = 0;
+            raw.data[index + 1] = 0;
+            raw.data[index + 2] = 0;
+        }
+        return this.fromRawImage(raw);
+    }
+    async binarizeAlpha(buffer, threshold = PixelArtPostProcessor.DEFAULT_ALPHA_THRESHOLD) {
+        const raw = await this.toRawImage(buffer);
+        for (let index = 3; index < raw.data.length; index += 4) {
+            raw.data[index] = raw.data[index] < threshold ? 0 : 255;
+        }
+        return this.fromRawImage(raw);
+    }
+    async alphaTightCrop(buffer) {
+        const raw = await this.toRawImage(buffer);
+        let minX = raw.width;
+        let minY = raw.height;
+        let maxX = -1;
+        let maxY = -1;
+        for (let y = 0; y < raw.height; y += 1) {
+            for (let x = 0; x < raw.width; x += 1) {
+                const pixelOffset = (y * raw.width + x) * 4;
+                const alpha = raw.data[pixelOffset + 3];
+                if (alpha === 0) {
+                    continue;
+                }
+                if (x < minX) {
+                    minX = x;
+                }
+                if (y < minY) {
+                    minY = y;
+                }
+                if (x > maxX) {
+                    maxX = x;
+                }
+                if (y > maxY) {
+                    maxY = y;
+                }
+            }
+        }
+        if (maxX < minX || maxY < minY) {
+            return this.createTransparentPixel();
+        }
+        return sharp(buffer)
+            .extract({
+            left: minX,
+            top: minY,
+            width: maxX - minX + 1,
+            height: maxY - minY + 1,
+        })
+            .png()
+            .toBuffer();
+    }
+    async quantizeColors(buffer, maxColors = PixelArtPostProcessor.DEFAULT_MAX_COLORS) {
+        const raw = await this.toRawImage(buffer);
+        const pointContainer = iq.utils.PointContainer.fromUint8Array(raw.data, raw.width, raw.height);
+        const palette = iq.buildPaletteSync([pointContainer], {
+            colors: maxColors,
+            paletteQuantization: 'wuquant',
+            colorDistanceFormula: 'euclidean',
+        });
+        const quantized = iq.applyPaletteSync(pointContainer, palette, {
+            imageQuantization: 'nearest',
+            colorDistanceFormula: 'euclidean',
+        });
+        const quantizedData = Buffer.from(quantized.toUint8Array());
+        return this.fromRawImage({
+            data: quantizedData,
+            width: raw.width,
+            height: raw.height,
+        });
+    }
+    async resizeNearest(buffer, width, height) {
+        return sharp(buffer)
+            .resize(width, height, {
+            fit: 'contain',
+            position: 'centre',
+            background: { r: 0, g: 0, b: 0, alpha: 0 },
+            kernel: sharp.kernel.nearest,
+        })
+            .png()
+            .toBuffer();
+    }
+    async finalAlphaCleanup(buffer, threshold = PixelArtPostProcessor.DEFAULT_ALPHA_THRESHOLD) {
+        return this.binarizeAlpha(buffer, threshold);
+    }
+    async resizeWithReferenceGeometry(params) {
+        if (!params.sourceReference) {
+            return this.resizeNearest(params.content, params.targetWidth, params.targetHeight);
+        }
+        const sourceBinarized = await this.binarizeAlpha(params.sourceReference, params.alphaThreshold);
+        const sourceRaw = await this.toRawImage(sourceBinarized);
+        const sourceBounds = this.getSourceContentBounds(sourceRaw);
+        if (!sourceBounds) {
+            return this.resizeNearest(params.content, params.targetWidth, params.targetHeight);
+        }
+        const desiredWidth = Math.max(1, Math.round((sourceBounds.width / sourceRaw.width) * params.targetWidth));
+        const desiredHeight = Math.max(1, Math.round((sourceBounds.height / sourceRaw.height) * params.targetHeight));
+        const xRatio = sourceBounds.x / sourceRaw.width;
+        const yRatio = sourceBounds.y / sourceRaw.height;
+        const fitted = await sharp(params.content)
+            .resize(desiredWidth, desiredHeight, {
+            fit: 'fill',
+            kernel: sharp.kernel.nearest,
+        })
+            .png()
+            .toBuffer();
+        const left = this.clamp(Math.round(xRatio * params.targetWidth), 0, Math.max(0, params.targetWidth - desiredWidth));
+        const top = this.clamp(Math.round(yRatio * params.targetHeight), 0, Math.max(0, params.targetHeight - desiredHeight));
+        return sharp({
+            create: {
+                width: params.targetWidth,
+                height: params.targetHeight,
+                channels: 4,
+                background: { r: 0, g: 0, b: 0, alpha: 0 },
+            },
+        })
+            .composite([{ input: fitted, left, top }])
+            .png()
+            .toBuffer();
+    }
+    getAlphaBounds(raw) {
+        let minX = raw.width;
+        let minY = raw.height;
+        let maxX = -1;
+        let maxY = -1;
+        for (let y = 0; y < raw.height; y += 1) {
+            for (let x = 0; x < raw.width; x += 1) {
+                const pixelOffset = (y * raw.width + x) * 4;
+                if (raw.data[pixelOffset + 3] === 0) {
+                    continue;
+                }
+                if (x < minX) {
+                    minX = x;
+                }
+                if (y < minY) {
+                    minY = y;
+                }
+                if (x > maxX) {
+                    maxX = x;
+                }
+                if (y > maxY) {
+                    maxY = y;
+                }
+            }
+        }
+        if (maxX < minX || maxY < minY) {
+            return null;
+        }
+        return {
+            x: minX,
+            y: minY,
+            width: maxX - minX + 1,
+            height: maxY - minY + 1,
+        };
+    }
+    getSourceContentBounds(raw) {
+        const alphaBounds = this.getAlphaBounds(raw);
+        if (!alphaBounds) {
+            return null;
+        }
+        const allOpaque = this.isFullyOpaque(raw);
+        if (!allOpaque) {
+            return alphaBounds;
+        }
+        const keyColor = this.estimateBackgroundColor(raw.data, raw.width, raw.height);
+        const keyedBounds = this.getColorKeyBounds(raw, keyColor, 16);
+        return keyedBounds ?? alphaBounds;
+    }
+    isFullyOpaque(raw) {
+        for (let index = 3; index < raw.data.length; index += 4) {
+            if (raw.data[index] !== 255) {
+                return false;
+            }
+        }
+        return true;
+    }
+    getColorKeyBounds(raw, keyColor, tolerance) {
+        let minX = raw.width;
+        let minY = raw.height;
+        let maxX = -1;
+        let maxY = -1;
+        for (let y = 0; y < raw.height; y += 1) {
+            for (let x = 0; x < raw.width; x += 1) {
+                const pixelOffset = (y * raw.width + x) * 4;
+                const red = raw.data[pixelOffset];
+                const green = raw.data[pixelOffset + 1];
+                const blue = raw.data[pixelOffset + 2];
+                const distance = Math.sqrt((red - keyColor.r) ** 2 + (green - keyColor.g) ** 2 + (blue - keyColor.b) ** 2);
+                if (distance <= tolerance) {
+                    continue;
+                }
+                if (x < minX) {
+                    minX = x;
+                }
+                if (y < minY) {
+                    minY = y;
+                }
+                if (x > maxX) {
+                    maxX = x;
+                }
+                if (y > maxY) {
+                    maxY = y;
+                }
+            }
+        }
+        if (maxX < minX || maxY < minY) {
+            return null;
+        }
+        return {
+            x: minX,
+            y: minY,
+            width: maxX - minX + 1,
+            height: maxY - minY + 1,
+        };
+    }
+    clamp(value, min, max) {
+        return Math.max(min, Math.min(max, value));
+    }
+    async applySourceMask(rendered, sourceReference, targetWidth, targetHeight) {
+        const resizedSource = await sharp(sourceReference)
+            .resize(targetWidth, targetHeight, {
+            fit: 'fill',
+            kernel: sharp.kernel.nearest,
+        })
+            .ensureAlpha()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        const renderedRaw = await sharp(rendered)
+            .resize(targetWidth, targetHeight, {
+            fit: 'fill',
+            kernel: sharp.kernel.nearest,
+        })
+            .ensureAlpha()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        let hasTransparentSourcePixels = false;
+        for (let index = 3; index < resizedSource.data.length; index += 4) {
+            if (resizedSource.data[index] === 0) {
+                hasTransparentSourcePixels = true;
+                break;
+            }
+        }
+        const keyColor = this.estimateBackgroundColor(resizedSource.data, resizedSource.info.width, resizedSource.info.height);
+        const tolerance = 34;
+        const output = Buffer.from(renderedRaw.data);
+        for (let index = 0; index < resizedSource.data.length; index += 4) {
+            if (hasTransparentSourcePixels) {
+                output[index + 3] = resizedSource.data[index + 3] === 0 ? 0 : 255;
+                continue;
+            }
+            const sr = resizedSource.data[index];
+            const sg = resizedSource.data[index + 1];
+            const sb = resizedSource.data[index + 2];
+            const distance = Math.sqrt((sr - keyColor.r) ** 2 + (sg - keyColor.g) ** 2 + (sb - keyColor.b) ** 2);
+            output[index + 3] = distance <= tolerance ? 0 : 255;
+        }
+        return sharp(output, {
+            raw: {
+                width: resizedSource.info.width,
+                height: resizedSource.info.height,
+                channels: 4,
+            },
+        })
+            .png()
+            .toBuffer();
+    }
+    estimateBackgroundColor(data, width, height) {
+        const samples = [];
+        const points = [
+            [0, 0],
+            [width - 1, 0],
+            [0, height - 1],
+            [width - 1, height - 1],
+            [Math.floor(width / 2), 0],
+            [Math.floor(width / 2), height - 1],
+            [0, Math.floor(height / 2)],
+            [width - 1, Math.floor(height / 2)],
+        ];
+        for (const [x, y] of points) {
+            const index = (y * width + x) * 4;
+            samples.push({ r: data[index], g: data[index + 1], b: data[index + 2] });
+        }
+        const r = Math.round(samples.reduce((sum, color) => sum + color.r, 0) / samples.length);
+        const g = Math.round(samples.reduce((sum, color) => sum + color.g, 0) / samples.length);
+        const b = Math.round(samples.reduce((sum, color) => sum + color.b, 0) / samples.length);
+        return { r, g, b };
+    }
+    async zeroRgbOnTransparent(buffer) {
+        const raw = await this.toRawImage(buffer);
+        for (let index = 0; index < raw.data.length; index += 4) {
+            if (raw.data[index + 3] !== 0) {
+                continue;
+            }
+            raw.data[index] = 0;
+            raw.data[index + 1] = 0;
+            raw.data[index + 2] = 0;
+        }
+        return this.fromRawImage(raw);
+    }
+    async toRawImage(buffer) {
+        const result = await sharp(buffer)
+            .ensureAlpha()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        return {
+            data: result.data,
+            width: result.info.width,
+            height: result.info.height,
+        };
+    }
+    async fromRawImage(image) {
+        return sharp(image.data, {
+            raw: {
+                width: image.width,
+                height: image.height,
+                channels: 4,
+            },
+        })
+            .png()
+            .toBuffer();
+    }
+    async createTransparentPixel() {
+        return sharp({
+            create: {
+                width: 1,
+                height: 1,
+                channels: 4,
+                background: { r: 0, g: 0, b: 0, alpha: 0 },
+            },
+        })
+            .png()
+            .toBuffer();
+    }
+    rgbToHex(red, green, blue) {
+        return `#${this.toHex(red)}${this.toHex(green)}${this.toHex(blue)}`;
+    }
+    toHex(value) {
+        return value.toString(16).padStart(2, '0');
+    }
+}

package/dist/StyleExplorer.d.ts

@@ -0,0 +1,24 @@
+import { ImageProcessor } from './ImageProcessor.js';
+import { OpenAIImageClient } from './OpenAIImageClient.js';
+export interface StyleExplorerResult {
+    prompt: string;
+    styleReferencePath: string;
+}
+interface StyleExplorerOptions {
+    workspaceRoot: string;
+    sampleSprites: string[];
+    imageProcessor: ImageProcessor;
+}
+export declare class StyleExplorer {
+    private readonly client;
+    private readonly options;
+    private static readonly SAMPLE_CELL_SIZE;
+    private static readonly DEFAULT_SAMPLE_COLS;
+    constructor(client: OpenAIImageClient, options: StyleExplorerOptions);
+    static buildSampleSheetFromSources(workspaceRoot: string, imageProcessor: ImageProcessor, sampleSprites: string[]): Promise<Buffer>;
+    runInteractive(packDir: string): Promise<StyleExplorerResult>;
+    static buildStyleReferencePrompt(styleDirection: string): string;
+    private writeSampleSheet;
+    private askInitialStyleDirection;
+}
+export {};

package/dist/StyleExplorer.js

@@ -0,0 +1,134 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import inquirer from 'inquirer';
+import sharp from 'sharp';
+export class StyleExplorer {
+    client;
+    options;
+    static SAMPLE_CELL_SIZE = 128;
+    static DEFAULT_SAMPLE_COLS = 3;
+    constructor(client, options) {
+        this.client = client;
+        this.options = options;
+    }
+    static async buildSampleSheetFromSources(workspaceRoot, imageProcessor, sampleSprites) {
+        if (sampleSprites.length === 0) {
+            throw new Error('sampleSprites must contain at least one source path.');
+        }
+        const cols = Math.min(StyleExplorer.DEFAULT_SAMPLE_COLS, sampleSprites.length);
+        const rows = Math.ceil(sampleSprites.length / cols);
+        const sampleSources = sampleSprites.map((sourceFile, index) => {
+            const col = index % cols;
+            const row = Math.floor(index / cols);
+            return {
+                sourceFile,
+                left: col * StyleExplorer.SAMPLE_CELL_SIZE,
+                top: row * StyleExplorer.SAMPLE_CELL_SIZE,
+            };
+        });
+        const composites = await Promise.all(sampleSources.map(async (sample) => {
+            const absoluteSourcePath = path.join(workspaceRoot, sample.sourceFile);
+            const cellImage = await imageProcessor.fitToExactSize(absoluteSourcePath, StyleExplorer.SAMPLE_CELL_SIZE, StyleExplorer.SAMPLE_CELL_SIZE);
+            return {
+                input: cellImage,
+                left: sample.left,
+                top: sample.top,
+            };
+        }));
+        const width = StyleExplorer.SAMPLE_CELL_SIZE * cols;
+        const height = StyleExplorer.SAMPLE_CELL_SIZE * rows;
+        return sharp({
+            create: {
+                width,
+                height,
+                channels: 4,
+                background: { r: 0, g: 0, b: 0, alpha: 0 },
+            },
+        })
+            .composite(composites)
+            .png()
+            .toBuffer();
+    }
+    async runInteractive(packDir) {
+        let styleDirection = await this.askInitialStyleDirection();
+        let currentPrompt = StyleExplorer.buildStyleReferencePrompt(styleDirection);
+        let attempt = 1;
+        const sampleSheetPath = await this.writeSampleSheet(packDir);
+        while (true) {
+            const styleResult = await this.client.generateStyleReference(currentPrompt, sampleSheetPath);
+            const previewPath = path.join(packDir, `style-preview-${attempt}.png`);
+            await fs.mkdir(packDir, { recursive: true });
+            await fs.writeFile(previewPath, styleResult.image);
+            console.log(`Preview saved to ${previewPath}`);
+            if (styleResult.revisedPrompt) {
+                console.log(`Revised prompt: ${styleResult.revisedPrompt}`);
+            }
+            const decision = await inquirer.prompt([
+                {
+                    type: 'list',
+                    name: 'action',
+                    message: 'Approve style reference?',
+                    choices: [
+                        { name: 'Approve and continue', value: 'approve' },
+                        { name: 'Refine prompt', value: 'refine' },
+                        { name: 'Retry same prompt', value: 'retry' },
+                    ],
+                },
+            ]);
+            if (decision.action === 'approve') {
+                const styleReferencePath = path.join(packDir, 'style-reference.png');
+                await fs.writeFile(styleReferencePath, styleResult.image);
+                return { prompt: currentPrompt, styleReferencePath };
+            }
+            if (decision.action === 'refine') {
+                const refineAnswer = await inquirer.prompt([
+                    {
+                        type: 'input',
+                        name: 'refinement',
+                        message: 'How should the style direction be changed?',
+                        validate: (value) => (value.trim().length > 0 ? true : 'Please provide a refinement hint.'),
+                    },
+                ]);
+                styleDirection = `${styleDirection}. Refinement: ${refineAnswer.refinement.trim()}`;
+                currentPrompt = StyleExplorer.buildStyleReferencePrompt(styleDirection);
+            }
+            attempt += 1;
+        }
+    }
+    static buildStyleReferencePrompt(styleDirection) {
+        return [
+            'The attached image is a sample sheet of actual game sprites arranged in a grid.',
+            'Each sprite is upscaled with nearest-neighbor so the original pixel structure is clearly visible.',
+            'TASK: Redraw this exact sample sheet in a new consistent style.',
+            `STYLE DIRECTION: ${styleDirection}.`,
+            'RULES:',
+            '- Keep the same grid layout with the same subjects in the same positions.',
+            '- Preserve each sprite silhouette, proportions, and identity exactly.',
+            '- Apply the style direction uniformly across all sprites.',
+            '- Pixel art constraints: hard edges, no anti-aliasing, no blur, no gradients, 16-24 colors max.',
+            '- Transparent background.',
+            '- Never draw a checkerboard, grid, or fake transparency pattern into the image.',
+            '- No text, no labels, no UI elements.',
+            '- Every sprite must stay readable at small final sizes.',
+            'Return exactly one PNG image.',
+        ].join(' ');
+    }
+    async writeSampleSheet(packDir) {
+        const sampleSheet = await StyleExplorer.buildSampleSheetFromSources(this.options.workspaceRoot, this.options.imageProcessor, this.options.sampleSprites);
+        const sampleSheetPath = path.join(packDir, 'style-source-sample.png');
+        await fs.mkdir(packDir, { recursive: true });
+        await fs.writeFile(sampleSheetPath, sampleSheet);
+        return sampleSheetPath;
+    }
+    async askInitialStyleDirection() {
+        const answer = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'stylePrompt',
+                message: 'Describe your target sprite style',
+                validate: (value) => (value.trim().length > 0 ? true : 'A style prompt is required.'),
+            },
+        ]);
+        return answer.stylePrompt.trim();
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};