Image To Black Charcoal Sketch Converter

/**
 * Converts an image to a black charcoal sketch effect.
 *
 * @param {HTMLImageElement} originalImg The original image element to process.
 * @param {number} blurAmount The radius of the blur filter, which affects line thickness. Default is 8.
 * @param {number} contrast The final contrast adjustment to enhance the sketch's darkness. Default is 160.
 * @param {number} noiseAmount The intensity of the noise texture for a more realistic charcoal feel. Set to 0 to disable. Default is 30.
 * @returns {HTMLCanvasElement} A new canvas element with the charcoal sketch drawn on it.
 */
function processImage(originalImg, blurAmount = 8, contrast = 160, noiseAmount = 30) {
    // 1. Setup canvases
    const canvas = document.createElement('canvas');
    // Using willReadFrequently is an optimization for frequent getImageData/putImageData calls
    const ctx = canvas.getContext('2d', { willReadFrequently: true });
    const w = originalImg.naturalWidth;
    const h = originalImg.naturalHeight;
    canvas.width = w;
    canvas.height = h;

    const offscreenCanvas = document.createElement('canvas');
    const offscreenCtx = offscreenCanvas.getContext('2d');
    offscreenCanvas.width = w;
    offscreenCanvas.height = h;

    // 2. Create the top "dodge" layer: a blurred, inverted, grayscale version of the image.
    // The blur amount is key to determining the thickness and detail of the final sketch lines.
    offscreenCtx.filter = `grayscale(1) invert(1) blur(${blurAmount}px)`;
    offscreenCtx.drawImage(originalImg, 0, 0, w, h);
    offscreenCtx.filter = 'none'; // Reset filter

    // 3. Create the bottom "base" layer: a simple grayscale version of the image on the main canvas.
    ctx.filter = 'grayscale(1)';
    ctx.drawImage(originalImg, 0, 0, w, h);
    ctx.filter = 'none'; // Reset filter

    // 4. Blend the two layers.
    // 'color-dodge' divides the bottom layer by the inverted top layer.
    // This blend mode is the core of the sketch effect, creating white areas and dark lines.
    ctx.globalCompositeOperation = 'color-dodge';
    ctx.drawImage(offscreenCanvas, 0, 0, w, h);
    ctx.globalCompositeOperation = 'source-over'; // Reset blend mode

    // 5. Final adjustments for a "charcoal" look.
    // The color-dodge can result in a very bright image, so we adjust brightness and contrast
    // to bring back the dark, charcoal-like tones.
    ctx.filter = `brightness(95%) contrast(${contrast}%)`;
    // To apply a filter to the existing canvas content, we must draw the canvas onto itself.
    ctx.drawImage(canvas, 0, 0);
    ctx.filter = 'none'; // Reset filter

    // 6. Add noise for texture to make it look less digital and more like charcoal on paper.
    if (noiseAmount > 0) {
        const imageData = ctx.getImageData(0, 0, w, h);
        const pixels = imageData.data;
        for (let i = 0; i < pixels.length; i += 4) {
            // Add a random value to each color channel.
            // (Math.random() - 0.5) generates a value between -0.5 and 0.5.
            const noise = (Math.random() - 0.5) * noiseAmount;
            pixels[i]   += noise; // Red
            pixels[i+1] += noise; // Green
            pixels[i+2] += noise; // Blue
        }
        ctx.putImageData(imageData, 0, 0);
    }

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