Image Pack Collection Round Renderer

/**
 * Renders an image into a circle, optionally with a border.
 * This is useful for creating round avatars, icons, or tokens for a "pack collection".
 *
 * @param {Image} originalImg The original Image object to process.
 * @param {number} size The diameter of the final circular image in pixels, including the border.
 * @param {number} borderWidth The width of the border in pixels. Set to 0 for no border.
 * @param {string} borderColor A CSS color string for the border (e.g., 'black', '#FF5733').
 * @param {string} backgroundColor A CSS color string for the background of the circle, visible if the source image has transparency.
 * @returns {HTMLCanvasElement} A canvas element containing the round image.
 */
function processImage(originalImg, size = 256, borderWidth = 8, borderColor = 'black', backgroundColor = 'rgba(0,0,0,0)') {
    // Create a new canvas element
    const canvas = document.createElement('canvas');
    canvas.width = size;
    canvas.height = size;
    const ctx = canvas.getContext('2d');

    // Define geometric properties
    const centerX = size / 2;
    const centerY = size / 2;
    
    // The radius for the image area, which is inside the border
    const imageRadius = (size / 2) - borderWidth;

    // Edge case: if the border is too thick, just draw a solid circle
    if (imageRadius <= 0) {
        ctx.beginPath();
        ctx.arc(centerX, centerY, size / 2, 0, 2 * Math.PI);
        ctx.fillStyle = borderColor;
        ctx.fill();
        return canvas;
    }
    
    // 1. Draw the background color for the main image area
    // This will be visible behind transparent areas of the source image.
    ctx.beginPath();
    ctx.arc(centerX, centerY, imageRadius, 0, 2 * Math.PI, false);
    ctx.fillStyle = backgroundColor;
    ctx.fill();

    // 2. Create a circular clipping path for the image
    ctx.save(); // Save the current context state
    ctx.beginPath();
    ctx.arc(centerX, centerY, imageRadius, 0, 2 * Math.PI, false);
    ctx.closePath();
    ctx.clip(); // All subsequent drawing will be confined to this circle

    // 3. Calculate image scaling to 'cover' the circular area without distortion
    const imgWidth = originalImg.naturalWidth;
    const imgHeight = originalImg.naturalHeight;
    const imgAspectRatio = imgWidth / imgHeight;
    
    const circleDiameter = imageRadius * 2;
    
    let drawWidth, drawHeight, drawX, drawY;

    // Check if the image is wider than it is tall
    if (imgAspectRatio >= 1) {
        // Scale the image so its height matches the circle's diameter
        drawHeight = circleDiameter;
        drawWidth = drawHeight * imgAspectRatio;
        // Center the image horizontally
        drawX = centerX - (drawWidth / 2);
        drawY = centerY - (drawHeight / 2);
    } else {
        // Scale the image so its width matches the circle's diameter
        drawWidth = circleDiameter;
        drawHeight = drawWidth / imgAspectRatio;
        // Center the image vertically
        drawX = centerX - (drawWidth / 2);
        drawY = centerY - (drawHeight / 2);
    }

    // Draw the scaled and centered image onto the canvas (it will be clipped)
    ctx.drawImage(originalImg, drawX, drawY, drawWidth, drawHeight);

    ctx.restore(); // Restore the context, removing the clipping path

    // 4. Draw the border on top of everything
    if (borderWidth > 0) {
        ctx.beginPath();
        // The stroke is centered on the path. To make the border fit snugly between
        // the image circle and the canvas edge, we set its radius halfway.
        const borderPathRadius = imageRadius + (borderWidth / 2);
        ctx.arc(centerX, centerY, borderPathRadius, 0, 2 * Math.PI, false);
        ctx.strokeStyle = borderColor;
        ctx.lineWidth = borderWidth;
        ctx.stroke();
    }

    return canvas;
}