Image Isometric Filter Effect Tool

/**
 * Applies an isometric filter effect to an image.
 * This specific effect projects the image onto a plane viewed isometrically,
 * commonly used for "floor" or "top-down" elements in isometric graphics.
 * The transformation skews and scales the image to create a parallelogram shape.
 *
 * @param {HTMLImageElement} originalImg The original image object. It should be fully loaded
 *                                       so that its width and height properties are accurate.
 * @param {number} [ySkewRatio=0.5] Determines the vertical perspective ("squashing").
 *                                  It's related to the tangent of the angle of the isometric
 *                                  axes to the horizontal.
 *                                  A common value is 0.5 (for 2:1 pixel art isometric style),
 *                                  which corresponds to an angle of atan(0.5) approx. 26.565 degrees.
 *                                  Another common value for a 30-degree isometric projection
 *                                  would be tan(30deg) which is 1/sqrt(3) approx. 0.57735.
 *                                  Negative values will flip the projection vertically.
 *                                  A value of 0 will collapse the image to a horizontal line.
 * @returns {HTMLCanvasElement} A new canvas element displaying the transformed image.
 */
function processImage(originalImg, ySkewRatio = 0.5) {
    const W = originalImg.width;
    const H = originalImg.height;

    // If the original image has no dimensions (e.g., not loaded or it's a 0x0 image),
    // return an empty (0x0) canvas.
    if (W === 0 && H === 0) {
        const canvas = document.createElement('canvas');
        canvas.width = 0;
        canvas.height = 0;
        return canvas;
    }
    
    const s = ySkewRatio;
    // Use the absolute value of s for calculating canvas dimensions, as height must be non-negative.
    const abs_s = Math.abs(s);

    const canvas = document.createElement('canvas');
    
    // Calculate the Axis-Aligned Bounding Box (AABB) dimensions for the transformed image.
    // The width of the resulting parallelogram will be W + H.
    // The height of the resulting parallelogram will be (W + H) * abs_s.
    canvas.width = W + H;
    canvas.height = (W + H) * abs_s;

    // If the calculated canvas height is 0 (e.g., ySkewRatio = 0, so abs_s = 0),
    // and W + H > 0 (i.e., the image is not 0x0), the projection is a flat horizontal line.
    // A canvas with 0 height is valid and correctly represents this.

    const ctx = canvas.getContext('2d');
    
    // Set image smoothing for better quality of the transformed (scaled/skewed) image.
    // These are often default, but explicit setting can ensure consistency.
    ctx.imageSmoothingEnabled = true;
    ctx.imageSmoothingQuality = 'high';

    // Determine translation offsets (e, f components of the transform matrix).
    // These ensure the transformed image is positioned correctly within the canvas bounds
    // (i.e., the top-left of the transformed image's AABB is at canvas coordinate (0,0)).
    
    // translationE (horizontal offset):
    // The original image point (0, H) (bottom-left corner, assuming origin is top-left)
    // is transformed by the matrix's skew component c=-1 to an x-coordinate of (1*0 - 1*H) = -H.
    // To bring this leftmost extent of the parallelogram to x=0 in the canvas, we translate by H.
    let translationE = H;
    
    // translationF (vertical offset):
    // This depends on the sign of s (ySkewRatio).
    let translationF = 0;
    if (s < 0) {
        // If s is negative, the y-coordinates are effectively flipped relative to the s > 0 case.
        // The original image point (W, H) (bottom-right) transforms to a y-coordinate of (s*W + s*H) = (W+H)*s.
        // Since s is negative, this y-coordinate is negative (assuming W,H > 0).
        // This y-coordinate represents the new "top" of the AABB in the transformed space when s is negative.
        // To shift this to y=0 in the canvas, we translate by -(W+H)*s.
        translationF = -(W + H) * s; // This is equivalent to (W + H) * abs_s
    }
    // If s is 0, all transformed y-coordinates will be 0. canvas.height is also 0. No vertical translation is needed.
    // If s > 0, the minimum transformed y-coordinate is already 0. No vertical translation is needed.

    // Apply the affine transformation using setTransform(a, b, c, d, e, f).
    // The matrix components are:
    // a = 1  (Term for x' from original x: x-scaling)
    // b = s  (Term for y' from original x: y-skew based on x)
    // c = -1 (Term for x' from original y: x-skew based on y)
    // d = s  (Term for y' from original y: y-scaling influenced by s)
    // e = translationE (Horizontal translation)
    // f = translationF (Vertical translation)
    // This transformation maps a point (px, py) from the original image to:
    // x_transformed = 1*px - 1*py + translationE
    // y_transformed = s*px + s*py + translationF
    ctx.setTransform(1, s, -1, s, translationE, translationF);
    
    // Draw the original image at (0,0) in its own coordinate system.
    // The transformation matrix set on the context will map it to the correct parallelogram shape
    // and position on the canvas.
    ctx.drawImage(originalImg, 0, 0);

    return canvas;
}