Image Sugar Crystal Filter Effect Tool

function processImage(originalImg, crystalSizeParam = 8, sparkleDensityParam = 0.05, sparkleBrightnessParam = 255) {
    // Parameter validation and casting:
    // Ensure crystalSize is an integer and at least 1.
    const crystalSize = Math.max(1, Math.floor(Number(crystalSizeParam)));
    // Ensure sparkleDensity is a number between 0 and 1.
    const sparkleDensity = Math.max(0, Math.min(1, Number(sparkleDensityParam)));
    // Ensure sparkleBrightness is an integer between 0 and 255.
    const sparkleBrightness = Math.max(0, Math.min(255, Math.floor(Number(sparkleBrightnessParam))));

    const canvas = document.createElement('canvas');
    // Using { willReadFrequently: true } can be an optimization hint for contexts
    // from which pixel data is read back frequently.
    const ctx = canvas.getContext('2d', { willReadFrequently: true });

    // originalImg is expected to be a loaded JavaScript Image object.
    // Its width and height properties should reflect the image dimensions.
    canvas.width = originalImg.width;
    canvas.height = originalImg.height;

    // If the image has no dimensions (e.g., not loaded or invalid),
    // return an empty canvas to prevent errors.
    if (canvas.width === 0 || canvas.height === 0) {
        console.error("Image has zero width or height. Ensure the image is loaded and valid.");
        return canvas;
    }

    // Draw the original image onto the canvas to access its pixel data.
    ctx.drawImage(originalImg, 0, 0, canvas.width, canvas.height);

    let imageData;
    try {
        // Attempt to get the pixel data from the entire canvas.
        imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
    } catch (e) {
        // This error can occur if the image source is cross-origin and the canvas becomes "tainted".
        console.error("Could not get image data from canvas. This might be due to cross-origin restrictions.", e);
        // Return the canvas with the original image drawn if processing is not possible.
        return canvas;
    }
    
    const data = imageData.data; // This is a Uint8ClampedArray: [R1,G1,B1,A1, R2,G2,B2,A2, ...]
    const width = imageData.width;
    const height = imageData.height;

    // Iterate over the image in blocks defined by crystalSize.
    // Each block will be filled with a single color to create the "crystal" effect.
    for (let y = 0; y < height; y += crystalSize) {
        for (let x = 0; x < width; x += crystalSize) {
            // Pick the color from the top-left pixel of the current block.
            // This color will represent the entire crystal block.
            const sampleX = x;
            const sampleY = y;
            
            // Calculate the index in the flat 'data' array for the sample pixel.
            // Each pixel consists of 4 values (R, G, B, A).
            const baseIndex = (sampleY * width + sampleX) * 4;
            const rSrc = data[baseIndex];
            const gSrc = data[baseIndex + 1];
            const bSrc = data[baseIndex + 2];
            const aSrc = data[baseIndex + 3]; // Preserve original alpha for the block.

            // Determine the actual boundaries for the current block,
            // ensuring they don't exceed image dimensions.
            const yEnd = Math.min(y + crystalSize, height);
            const xEnd = Math.min(x + crystalSize, width);

            // Fill all pixels within this crystal block.
            for (let blockY = y; blockY < yEnd; blockY++) {
                for (let blockX = x; blockX < xEnd; blockX++) {
                    const targetIndex = (blockY * width + blockX) * 4;

                    // Decide whether to apply a "sparkle" or the block color.
                    if (Math.random() < sparkleDensity) {
                        // Apply sparkle: a bright, typically white or grey pixel.
                        data[targetIndex]     = sparkleBrightness; // Red
                        data[targetIndex + 1] = sparkleBrightness; // Green
                        data[targetIndex + 2] = sparkleBrightness; // Blue
                        data[targetIndex + 3] = 255;               // Alpha (sparkles are opaque)
                    } else {
                        // Apply the representative crystal block color.
                        data[targetIndex]     = rSrc;
                        data[targetIndex + 1] = gSrc;
                        data[targetIndex + 2] = bSrc;
                        data[targetIndex + 3] = aSrc;
                    }
                }
            }
        }
    }

    // Write the modified pixel data back to the canvas.
    ctx.putImageData(imageData, 0, 0);

    // Return the canvas element containing the processed image.
    return canvas;
}