@minecraft/creator-tools/lib/local/ImageGenerationUtilities.d.ts

Minecraft Creator Tools command line and libraries.

import { IAtlasRegion } from "../minecraft/ModelDesignUtilities";
import { IMcpModelDesign } from "../minecraft/IMcpModelDesign";
/**
 * Texture swatch information for rendering.
 */
export interface ITextureSwatch {
    /** Label/name to display with the swatch */
    label: string;
    /** Color value (hex string) */
    color?: string;
    /** SVG content */
    svg?: string;
}
/**
 * Static utility class for PNG generation and image manipulation.
 * Provides methods for encoding RGBA pixel data to PNG, rendering SVG to PNG,
 * generating textures from atlas regions, and stitching images together.
 */
export default class ImageGenerationUtilities {
    private static _crc32Table;
    private static _cachedBrowser;
    /**
     * Encode RGBA pixel data to PNG format.
     * Delegates to ImageCodec for cross-platform encoding.
     *
     * @param pixels RGBA pixel data (4 bytes per pixel)
     * @param width Image width in pixels
     * @param height Image height in pixels
     * @returns PNG data as Uint8Array, or undefined on error
     */
    static encodeRgbaToPng(pixels: Uint8Array, width: number, height: number): Uint8Array | undefined;
    /**
     * Create a PNG chunk with type, data, and CRC.
     *
     * @param type 4-character chunk type (e.g., "IHDR", "IDAT", "IEND")
     * @param data Chunk data
     * @returns Complete chunk including length, type, data, and CRC
     */
    static createPngChunk(type: string, data: Uint8Array): Uint8Array;
    /**
     * Calculate CRC32 checksum for PNG chunk validation.
     *
     * @param data Data to calculate CRC32 for
     * @returns CRC32 checksum as unsigned 32-bit integer
     */
    static crc32(data: Uint8Array): number;
    /**
     * Get the CRC32 lookup table, generating it on first call.
     *
     * @returns CRC32 lookup table
     */
    static getCrc32Table(): Uint32Array;
    /**
     * Render an SVG string to a PNG data URL using resvg-js.
     * This enables SVG support including gradients, shapes, and complex graphics.
     *
     * @param svgContent SVG content as a string
     * @param width Output image width in pixels
     * @param height Output image height in pixels
     * @returns PNG as data URL, or undefined if rendering fails
     */
    static renderSvgToDataUrl(svgContent: string, width: number, height: number): Promise<string | undefined>;
    /**
     * Close the cached browser instance.
     * Call this when done with rendering to clean up resources.
     */
    static closeCachedBrowser(): Promise<void>;
    /**
     * Ensure the cached browser is available.
     * Initializes the browser if not already running.
     * If the browser has disconnected, creates a new one.
     */
    static ensureCachedBrowser(): Promise<void>;
    /**
     * Generate a PNG texture from atlas regions.
     * Uses Playwright to render SVG content, falls back to simple color fill for color-only regions.
     *
     * @param atlasRegions Array of atlas regions with position, size, and content
     * @param textureSize Texture dimensions as [width, height]
     * @param pixelsPerUnit Pixels per Minecraft unit for pixel art scaling. Default: 2
     * @returns PNG as data URL, or undefined if generation fails
     */
    static generateTextureFromAtlas(atlasRegions: IAtlasRegion[], textureSize: [number, number], pixelsPerUnit?: number): Promise<string | undefined>;
    /**
     * Stitch multiple images together with labels in a grid layout.
     * Uses Playwright to compose images and add text labels.
     *
     * @param images Array of images with labels and PNG data (may include isWide property for pyramid layout)
     * @param singleWidth Width of each individual image (half-width for pyramid layout)
     * @param singleHeight Height of each individual image
     * @param cols Number of columns in grid (default: images.length for horizontal row)
     * @param rows Number of rows in grid (default: 1 for horizontal row)
     * @param layout Optional layout mode: "pyramid" for 2-on-top, 1-spanning-bottom layout
     * @returns Stitched image as PNG data, or first image on failure
     */
    static stitchImagesWithLabels(images: {
        label: string;
        imageData: Uint8Array;
        isWide?: boolean;
    }[], singleWidth: number, singleHeight: number, cols?: number, rows?: number, layout?: "pyramid" | undefined): Promise<Uint8Array | undefined>;
    /**
     * Convert PNG image data to JPEG format with optional quality setting.
     * Uses browser canvas for encoding.
     *
     * @param pngData PNG image data as Uint8Array
     * @param quality JPEG quality 1-100 (default: 80)
     * @returns JPEG image data as Uint8Array, or original PNG on failure
     */
    static convertPngToJpeg(pngData: Uint8Array, quality?: number): Promise<Uint8Array>;
    /**
     * Recompress a PNG image with maximum compression level (9).
     * Decodes the PNG, then re-encodes with higher compression.
     * This can significantly reduce file size for screenshots.
     *
     * @param pngData PNG image data as Uint8Array
     * @returns Recompressed PNG data, or original on failure
     */
    static recompressPng(pngData: Uint8Array): Uint8Array;
    /**
     * Parse a PNG file to extract width, height, and pixel data.
     * Supports only 8-bit RGBA (color type 6) non-interlaced PNGs.
     *
     * @param pngData PNG file data
     * @returns Parsed data or undefined on failure
     */
    static parsePng(pngData: Uint8Array): {
        width: number;
        height: number;
        pixels: Uint8Array;
    } | undefined;
    /**
     * Paeth predictor function for PNG decompression.
     */
    private static paethPredictor;
    /**
     * Extract texture swatches from a model design.
     * Collects all named textures from the textures dictionary,
     * plus unique solid colors used on faces.
     *
     * @param design The model design to extract swatches from
     * @returns Array of texture swatches with labels and content
     */
    static extractTextureSwatches(design: IMcpModelDesign): ITextureSwatch[];
    /**
     * Generate a swatch strip and append it to the main image in a single browser session.
     * This is more efficient than calling generateSwatchStrip and appendSwatchStrip separately.
     *
     * @param mainImage The main image PNG data
     * @param swatches Array of texture swatches to render
     * @param mainWidth Width of the main image
     * @param mainHeight Height of the main image
     * @param swatchesPerRow Number of swatches per row (default: 6)
     * @returns Combined image with swatches below, or original image on failure
     */
    static generateAndAppendSwatchStrip(mainImage: Uint8Array, swatches: ITextureSwatch[], mainWidth: number, mainHeight: number, swatchesPerRow?: number): Promise<Uint8Array>;
    /**
     * Generate a swatch strip image showing labeled texture samples.
     * Renders swatches in rows of up to \`swatchesPerRow\`.
     *
     * @param swatches Array of texture swatches to render
     * @param stripWidth Total width of the swatch strip
     * @param swatchesPerRow Number of swatches per row (default: 4)
     * @returns PNG data as Uint8Array, or undefined on failure
     */
    static generateSwatchStrip(swatches: ITextureSwatch[], stripWidth: number, swatchesPerRow?: number): Promise<Uint8Array | undefined>;
    /**
     * Append a swatch strip below an existing image.
     *
     * @param mainImage The main image PNG data
     * @param swatchStrip The swatch strip PNG data
     * @param mainWidth Width of the main image
     * @param mainHeight Height of the main image
     * @returns Combined image with swatches below, or original image on failure
     */
    static appendSwatchStrip(mainImage: Uint8Array, swatchStrip: Uint8Array, mainWidth: number, mainHeight: number): Promise<Uint8Array>;
}