Image To Dot Outline Converter

/**
 * Converts an image into a dot outline by detecting edges using the Sobel operator.
 *
 * @param {HTMLImageElement} originalImg The original image element.
 * @param {string|number} dotSize The size (diameter) of each dot in pixels. Defaults to 1.
 * @param {string|number} spacing The spacing between grid points where dots can be placed. A smaller value means a denser outline. Defaults to 5.
 * @param {string|number} threshold The edge detection threshold (0-255). Higher values mean only stronger edges are drawn, resulting in a cleaner but less detailed outline. Defaults to 50.
 * @returns {Promise<HTMLCanvasElement>} A promise that resolves with a new canvas element containing the dot outline drawing.
 */
async function processImage(originalImg, dotSize = '1', spacing = '5', threshold = '50') {
    // 1. Parse and validate parameters
    const pDotSize = Math.max(1, Number(dotSize));
    const pSpacing = Math.max(1, Number(spacing));
    const pThreshold = Math.max(0, Math.min(255, Number(threshold)));

    const width = originalImg.naturalWidth;
    const height = originalImg.naturalHeight;

    // 2. Create a temporary canvas to access pixel data
    const tempCanvas = document.createElement('canvas');
    tempCanvas.width = width;
    tempCanvas.height = height;
    const tempCtx = tempCanvas.getContext('2d', {
        willReadFrequently: true
    });
    tempCtx.drawImage(originalImg, 0, 0);
    const imageData = tempCtx.getImageData(0, 0, width, height);
    const data = imageData.data;

    // 3. Convert image to grayscale for simpler edge detection
    const grayscaleData = new Uint8ClampedArray(width * height);
    for (let i = 0; i < data.length; i += 4) {
        const r = data[i];
        const g = data[i + 1];
        const b = data[i + 2];
        // Use the luminosity method for grayscale conversion
        const gray = 0.299 * r + 0.587 * g + 0.114 * b;
        grayscaleData[i / 4] = gray;
    }

    // Helper function to get grayscale value at (x, y), handling image borders
    const getGray = (x, y) => {
        if (x < 0 || x >= width || y < 0 || y >= height) {
            return 0; // Treat pixels outside the image as black
        }
        return grayscaleData[y * width + x];
    };

    // 4. Apply the Sobel operator to detect edges
    const edgeData = new Float32Array(width * height);
    let maxMagnitude = 0;

    for (let y = 0; y < height; y++) {
        for (let x = 0; x < width; x++) {
            // Sobel kernels for horizontal (gx) and vertical (gy) gradients
            const gx = (
                -getGray(x - 1, y - 1) + getGray(x + 1, y - 1) +
                -2 * getGray(x - 1, y) + 2 * getGray(x + 1, y) +
                -getGray(x - 1, y + 1) + getGray(x + 1, y + 1)
            );

            const gy = (
                -getGray(x - 1, y - 1) - 2 * getGray(x, y - 1) - getGray(x + 1, y - 1) +
                getGray(x - 1, y + 1) + 2 * getGray(x, y + 1) + getGray(x + 1, y + 1)
            );

            const magnitude = Math.sqrt(gx * gx + gy * gy);
            const index = y * width + x;
            edgeData[index] = magnitude;

            if (magnitude > maxMagnitude) {
                maxMagnitude = magnitude;
            }
        }
    }

    // 5. Create the final output canvas
    const outputCanvas = document.createElement('canvas');
    outputCanvas.width = width;
    outputCanvas.height = height;
    const outputCtx = outputCanvas.getContext('2d');

    // Fill the background with white
    outputCtx.fillStyle = 'white';
    outputCtx.fillRect(0, 0, width, height);
    outputCtx.fillStyle = 'black'; // Set dot color

    // 6. Draw the dots on the output canvas based on edge magnitude
    // Iterate through the image on a grid defined by pSpacing
    for (let y = 0; y < height; y += pSpacing) {
        for (let x = 0; x < width; x += pSpacing) {
            const index = Math.floor(y) * width + Math.floor(x);
            const magnitude = edgeData[index];

            // Normalize the magnitude to a 0-255 range for consistent thresholding
            const normalizedMagnitude = (magnitude / maxMagnitude) * 255;

            // If the normalized magnitude at this grid point is above the threshold, draw a dot
            if (normalizedMagnitude > pThreshold) {
                outputCtx.beginPath();
                outputCtx.arc(x, y, pDotSize / 2, 0, 2 * Math.PI);
                outputCtx.fill();
            }
        }
    }

    // 7. Return the final canvas element
    return outputCanvas;
}