Image Circular Crop Tool

/**
 * Creates a circular cropped version of an image.
 *
 * @param {HTMLImageElement} originalImg The original image object (must be loaded for naturalWidth/Height to be correct).
 * @param {string|number} [centerX = originalImg.naturalWidth / 2] X-coordinate of the crop center in the original image.
 * @param {string|number} [centerY = originalImg.naturalHeight / 2] Y-coordinate of the crop center in the original image.
 * @param {string|number} [radius = Math.min(originalImg.naturalWidth, originalImg.naturalHeight) / 2] Radius of the circular crop.
 * @returns {HTMLCanvasElement} A canvas element displaying the circularly cropped image.
 */
function processImage(
    originalImg,
    centerX = originalImg.naturalWidth / 2,
    centerY = originalImg.naturalHeight / 2,
    radius = Math.min(originalImg.naturalWidth, originalImg.naturalHeight) / 2
) {
    // Parse numeric parameters. These could be numbers or strings (e.g., "100").
    // parseFloat will convert valid numeric strings to numbers, and leave numbers as numbers.
    // If a parameter was not provided (i.e., it's `undefined`), its default value from the signature is used.
    // parseFloat on a numeric default value works fine.
    let numCenterX = parseFloat(centerX);
    let numCenterY = parseFloat(centerY);
    let numRadius = parseFloat(radius);

    // Fallback to default calculations if parsing failed (e.g., input was a non-numeric string like "abc")
    // or if the radius is invalid (e.g., negative).
    // The default values from the function signature are based on originalImg dimensions.
    if (isNaN(numCenterX)) {
        numCenterX = originalImg.naturalWidth / 2;
    }
    if (isNaN(numCenterY)) {
        numCenterY = originalImg.naturalHeight / 2;
    }
    // A radius of 0 is permissible (e.g., for a 0x0 source image), which will result in a 0x0 canvas.
    // A negative radius is invalid and should be reset to the default.
    if (isNaN(numRadius) || numRadius < 0) {
        numRadius = Math.min(originalImg.naturalWidth, originalImg.naturalHeight) / 2;
    }

    const canvas = document.createElement('canvas');
    // The canvas will be a square with side length equal to the diameter of the circle (2 * radius).
    canvas.width = numRadius * 2;
    canvas.height = numRadius * 2;

    const ctx = canvas.getContext('2d');

    // If context cannot be obtained (highly unlikely for '2d' in modern browsers)
    if (!ctx) {
        console.error("Could not get 2D rendering context for the canvas.");
        // Return an empty or minimal canvas as per error handling strategy
        return canvas; // Returns the 0x0 or un-drawable canvas
    }
    
    // If the radius is 0 (e.g., source image is 0x0, or user explicitly specified radius 0),
    // the canvas will be 0x0. No drawing operations are needed or effectively possible.
    if (numRadius === 0) {
        return canvas;
    }
    
    // Create a circular clipping path.
    // The center of the circle on the canvas is at (numRadius, numRadius)
    // because the canvas dimensions are (2*numRadius x 2*numRadius) and origin is (0,0).
    ctx.beginPath();
    ctx.arc(numRadius, numRadius, numRadius, 0, Math.PI * 2, true); // (cx_on_canvas, cy_on_canvas, r_on_canvas, startAngle, endAngle, anticlockwise)
    ctx.clip();

    // Calculate the source rectangle (sx, sy, sWidth, sHeight) from the original image.
    // This is a square region centered at (numCenterX, numCenterY) in the original image's coordinate system,
    // with side length equal to the diameter (2 * numRadius).
    const sx = numCenterX - numRadius; // Top-left X-coordinate of the source rectangle
    const sy = numCenterY - numRadius; // Top-left Y-coordinate of the source rectangle
    const sWidth = numRadius * 2;      // Width of the source rectangle
    const sHeight = numRadius * 2;     // Height of the source rectangle

    // Define the destination rectangle (dx, dy, dWidth, dHeight) on the canvas.
    // This covers the entire canvas.
    const dx = 0;                      // Top-left X-coordinate on the canvas
    const dy = 0;                      // Top-left Y-coordinate on the canvas
    const dWidth = canvas.width;       // Width of the destination rectangle on canvas (equal to 2*numRadius)
    const dHeight = canvas.height;     // Height of the destination rectangle on canvas (equal to 2*numRadius)

    // Draw the specified portion of the original image onto the (now clipped) canvas.
    // The drawImage method handles cases where the source rectangle (sx, sy, sWidth, sHeight)
    // extends beyond the actual dimensions of originalImg by rendering those areas as transparent.
    ctx.drawImage(originalImg, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight);

    return canvas;
}