Image Diagonal Golden Ratio Overlay Tool

/**
 * Creates a "Dynamic Symmetry" grid overlay on an image. This is a diagonal-based
 * compositional guide related to the Golden Ratio, often called the Armature of the Rectangle.
 * The grid consists of the two main diagonals and perpendicular lines ("reciprocal lines")
 * drawn from each corner to the opposite diagonal. It's a powerful tool for creating
 * dynamic and balanced compositions.
 *
 * @param {HTMLImageElement} originalImg The original image object to process.
 * @param {string} [lineColor='rgba(255, 255, 0, 0.75)'] The color of the overlay lines.
 * @param {number} [lineWidth=2] The width of the overlay lines in pixels.
 * @returns {HTMLCanvasElement} A new canvas element with the original image and the overlay.
 */
function processImage(originalImg, lineColor = 'rgba(255, 255, 0, 0.75)', lineWidth = 2) {
    // 1. Create a canvas and get its 2D rendering context.
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    // 2. Set the canvas dimensions to match the image.
    const W = originalImg.width;
    const H = originalImg.height;
    canvas.width = W;
    canvas.height = H;

    // 3. Draw the original image onto the canvas.
    ctx.drawImage(originalImg, 0, 0);

    // 4. Set the properties for the overlay lines.
    ctx.strokeStyle = lineColor;
    ctx.lineWidth = lineWidth;
    ctx.lineCap = 'round';

    // 5. Pre-calculate values used for finding intersection points.
    // This avoids recalculating these values repeatedly.
    const W2 = W * W;
    const H2 = H * H;
    const D = W2 + H2;

    // Avoid division by zero if the image has no area.
    if (D === 0) {
        return canvas;
    }

    // 6. Begin drawing the overlay path.
    ctx.beginPath();

    // --- Draw the two main diagonals ("Baroque" and "Sinister" diagonals) ---
    // Diagonal from top-left (0,0) to bottom-right (W,H)
    ctx.moveTo(0, 0);
    ctx.lineTo(W, H);
    // Diagonal from top-right (W,0) to bottom-left (0,H)
    ctx.moveTo(W, 0);
    ctx.lineTo(0, H);

    // --- Draw the four perpendicular "reciprocal" lines ---
    // These lines are drawn from a corner to intersect the opposite main diagonal at 90 degrees.

    // Perpendiculars to the diagonal from top-left -> bottom-right:
    // From corner (W, 0)
    const p1x = W * W2 / D;
    const p1y = W2 * H / D;
    ctx.moveTo(W, 0);
    ctx.lineTo(p1x, p1y);

    // From corner (0, H)
    const p2x = H2 * W / D;
    const p2y = H * H2 / D;
    ctx.moveTo(0, H);
    ctx.lineTo(p2x, p2y);

    // Perpendiculars to the diagonal from top-right -> bottom-left:
    // From corner (0, 0)
    const p3x = W * H2 / D;
    const p3y = W2 * H / D;
    ctx.moveTo(0, 0);
    ctx.lineTo(p3x, p3y);

    // From corner (W, H)
    const p4x = W * W2 / D;
    const p4y = H * H2 / D;
    ctx.moveTo(W, H);
    ctx.lineTo(p4x, p4y);

    // 7. Render all the lines on the canvas.
    ctx.stroke();

    // 8. Return the final canvas element.
    return canvas;
}