Image Edge Detection And Posterization Tool For Frame Processing

/**
 * Processes an image to apply a posterization effect and then overlays a Sobel edge detection map.
 * This function is designed to be used for single frame processing, as might be done with video.
 *
 * @param {Image} originalImg The source Image object. The image must be fully loaded.
 * @param {number} [edgeThreshold=50] The sensitivity for edge detection. Higher values mean fewer, more prominent edges are detected. Range: 0-255.
 * @param {number} [posterizeLevels=4] The number of color levels for the posterization effect. Must be 2 or greater. Lower numbers produce a more abstract effect.
 * @returns {HTMLCanvasElement} A new canvas element with the processed image.
 */
function processImage(originalImg, edgeThreshold = 50, posterizeLevels = 4) {
    // --- 1. Parameter Validation ---
    // Ensure posterizeLevels is a safe value to prevent division by zero and nonsensical results.
    if (posterizeLevels < 2) posterizeLevels = 2;
    if (posterizeLevels > 255) posterizeLevels = 255;

    // --- 2. Canvas & Context Setup ---
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d', { willReadFrequently: true });
    const width = originalImg.naturalWidth;
    const height = originalImg.naturalHeight;
    canvas.width = width;
    canvas.height = height;
    ctx.drawImage(originalImg, 0, 0);

    // --- 3. Image Data Preparation ---
    const originalImageData = ctx.getImageData(0, 0, width, height);
    const finalImageData = ctx.createImageData(width, height);
    const originalData = originalImageData.data;
    const finalData = finalImageData.data;

    // A temporary array to hold the grayscale values of the posterized image for the edge detection step.
    const grayscaleData = new Uint8ClampedArray(width * height);

    // --- 4. First Pass: Posterization & Grayscale Conversion ---
    // This loop calculates the posterized color for each pixel and also creates a grayscale
    // version of the posterized image, which will be used for edge detection.
    const numAreas = 256 / posterizeLevels;
    const numValues = 255 / (posterizeLevels - 1);

    for (let i = 0; i < originalData.length; i += 4) {
        const r = originalData[i];
        const g = originalData[i + 1];
        const b = originalData[i + 2];

        // Apply posterization to each color channel
        const pr = Math.floor(Math.floor(r / numAreas) * numValues);
        const pg = Math.floor(Math.floor(g / numAreas) * numValues);
        const pb = Math.floor(Math.floor(b / numAreas) * numValues);

        // Store the posterized color in the final image data array.
        finalData[i] = pr;
        finalData[i + 1] = pg;
        finalData[i + 2] = pb;
        finalData[i + 3] = 255; // Alpha channel

        // Calculate and store the grayscale value of the posterized pixel.
        // Using the standard luminosity formula.
        const gray = Math.round(0.299 * pr + 0.587 * pg + 0.114 * pb);
        grayscaleData[i / 4] = gray;
    }

    // --- 5. Second Pass: Sobel Edge Detection ---
    // This loop convolves the grayscale image with Sobel kernels to find edges.
    // Where an edge is found, the corresponding pixel in the final image is turned black.
    const Gx = [
        -1, 0, 1, 
        -2, 0, 2, 
        -1, 0, 1
    ];
    const Gy = [
        -1, -2, -1, 
         0,  0,  0, 
         1,  2,  1
    ];

    // Iterate over each pixel, skipping the 1px border to avoid out-of-bounds checks.
    for (let y = 1; y < height - 1; y++) {
        for (let x = 1; x < width - 1; x++) {
            let pixelX = 0;
            let pixelY = 0;
            let kernelIndex = 0;

            // Apply the 3x3 convolution kernels
            for (let ky = -1; ky <= 1; ky++) {
                for (let kx = -1; kx <= 1; kx++) {
                    const grayValue = grayscaleData[(y + ky) * width + (x + kx)];
                    pixelX += grayValue * Gx[kernelIndex];
                    pixelY += grayValue * Gy[kernelIndex];
                    kernelIndex++;
                }
            }

            // Calculate the magnitude of the gradient
            const magnitude = Math.sqrt(pixelX * pixelX + pixelY * pixelY);

            // If the magnitude is above the threshold, it's an edge.
            if (magnitude > edgeThreshold) {
                const idx = (y * width + x) * 4;
                // Set the pixel in the final image to black
                finalData[idx] = 0;
                finalData[idx + 1] = 0;
                finalData[idx + 2] = 0;
            }
        }
    }

    // --- 6. Finalize and Return Canvas ---
    // Draw the final processed image data onto the canvas.
    ctx.putImageData(finalImageData, 0, 0);
    return canvas;
}