Image Analysis For ‘Баллада о пастилине’

/**
 * Applies a "plastilin" (modeling clay) effect to an image, inspired by the
 * Russian poem "Баллада о пастилине" (The Ballad of Pastilina/Marshmallow),
 * which plays on the words for marshmallow (pastila) and modeling clay (plastilin).
 * The effect desaturates the image, reduces its color levels (posterization) to
 * create a flattened, sculpted look, and adds subtle noise for texture.
 *
 * @param {Image} originalImg The original JavaScript Image object. Must be fully loaded.
 * @param {number} [grayLevels=5] The number of gray levels for the posterization effect. A lower number creates a more abstract, blocky look. Must be 2 or greater.
 * @param {number} [noiseAmount=20] The intensity of the noise texture applied. Set to 0 to disable.
 * @returns {HTMLCanvasElement} A new canvas element displaying the processed image.
 */
function processImage(originalImg, grayLevels = 5, noiseAmount = 20) {
    // Create a new canvas element
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    // Set canvas dimensions to match the source image
    // Using naturalWidth/Height is safer for images that might be scaled by CSS
    canvas.width = originalImg.naturalWidth;
    canvas.height = originalImg.naturalHeight;

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

    // Get the ImageData object, which contains the raw pixel data (in a flat RGBA array)
    let imageData;
    try {
        imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
    } catch (e) {
        // This error can happen if the image is from a different origin (CORS issue)
        console.error("Could not get image data. Ensure the image is from the same origin or served with appropriate CORS headers.", e);
        
        // Return a canvas with a user-friendly error message drawn on it
        ctx.fillStyle = '#f0f0f0';
        ctx.fillRect(0, 0, canvas.width, canvas.height);
        ctx.fillStyle = 'red';
        ctx.font = `bold ${Math.min(24, canvas.width / 20)}px sans-serif`;
        ctx.textAlign = 'center';
        ctx.textBaseline = 'middle';
        ctx.fillText('Error: Could not process image.', canvas.width / 2, canvas.height / 2 - 20);
        ctx.font = `normal ${Math.min(16, canvas.width / 30)}px sans-serif`;
        ctx.fillText('Cross-origin security policy prevents modification.', canvas.width / 2, canvas.height / 2 + 20);
        return canvas;
    }

    const data = imageData.data;
    
    // Sanitize parameters
    const numLevels = Math.max(2, Math.floor(grayLevels));
    const cleanNoiseAmount = Math.max(0, noiseAmount);

    // Calculate the factor for quantization based on the number of levels
    // This defines the "step" between each available shade of gray
    const factor = 255 / (numLevels - 1);

    // Iterate over every pixel in the image. The loop increments by 4 because
    // each pixel is represented by four values: Red, Green, Blue, and Alpha.
    for (let i = 0; i < data.length; i += 4) {
        const r = data[i];
        const g = data[i + 1];
        const b = data[i + 2];

        // Step 1: Convert the pixel to grayscale using the standard luminance formula
        const gray = 0.299 * r + 0.587 * g + 0.114 * b;

        // Step 2: Apply posterization to quantize the gray value into discrete levels
        // This creates the "flattened clay" or "blocky" appearance
        const posterizedGray = Math.round(gray / factor) * factor;

        // Step 3: Add random noise to simulate texture
        // The noise is centered around 0
        const noise = (Math.random() - 0.5) * cleanNoiseAmount;
        
        // Apply the noise and clamp the final value between 0 and 255
        const finalGray = Math.max(0, Math.min(255, posterizedGray + noise));

        // Set the Red, Green, and Blue channels to the new gray value
        data[i] = finalGray;
        data[i + 1] = finalGray;
        data[i + 2] = finalGray;
        // The alpha channel (data[i + 3]) is left unchanged
    }

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

    // Return the final canvas element
    return canvas;
}