[geometry-1] rotateSelf doesn't seem to be clearly defined

[bzbarsky]

https://www.w3.org/TR/geometry-1/#dom-dommatrix-rotateself step 6 says:

Post-multiply a rotation transformation on the current matrix around the vector 0, 1, 0 by the specified rotation rotY in degrees. The 3D rotation matrix is described in CSS Transforms with alpha = rotY in degrees. [CSS3-TRANSFORMS]

and the "described" text links to https://drafts.csswg.org/css-transforms-1/#RotateDefined which is a definition for a 2-d rotation, which is not what we are looking for here at all: I would have expected a definition of rotation around a given vector/axis by a given angle alpha.

I would have expected this to link to https://drafts.csswg.org/css-transforms-2/#Rotate3dDefined or something.

@zcorpan @dirkschulze

[trusktr]

It seems like this can be closed, as I see the following in CSS-Transforms today, which is a 4x4 matrix (which is 3D right?):

Maybe the spec text was at some point less accurate, but I recall back in 2015 that it linked me to the math to implement for my geometry-interfaces polyfill. Here's rotateSelf from back then:

    rotateSelf (angle, originX = 0, originY = 0) {
        this.translateSelf(originX, originY)

        // axis of rotation
        const [x,y,z] = [0,0,1] // We're rotating around the Z axis.

        this.rotateAxisAngleSelf(x, y, z, angle)

        this.translateSelf(-originX, -originY)
        return this
    }

which used rotateAxisAngleSelf:

    rotateAxisAngleSelf (x, y, z, angle) {
        const rotationMatrix = new DOMMatrix(rotateAxisAngleArray(x,y,z,angle))
        this.multiplySelf(rotationMatrix)
        return this
    }

where rotateAxisAngleArray had the formulas from that image:

export function rotateAxisAngleArray(x: number, y: number, z: number, angle: number) {
	const {sin, cos} = Math

	const halfAngle = degreesToRadians(angle / 2)

	return [
		1 - 2 * (y * y + z * z) * sin(halfAngle) ** 2,                            2 * (x * y * sin(halfAngle) ** 2 + z * sin(halfAngle) * cos(halfAngle)),  2 * (x * z * sin(halfAngle) ** 2 - y * sin(halfAngle) * cos(halfAngle)),  0,
		2 * (x * y * sin(halfAngle) ** 2 - z * sin(halfAngle) * cos(halfAngle)),  1 - 2 * (x * x + z * z) * sin(halfAngle) ** 2,                            2 * (y * z * sin(halfAngle) ** 2 + x * sin(halfAngle) * cos(halfAngle)),  0,
		2 * (x * z * sin(halfAngle) ** 2 + y * sin(halfAngle) * cos(halfAngle)),  2 * (y * z * sin(halfAngle) ** 2 - x * sin(halfAngle) * cos(halfAngle)),  1 - 2 * (x * x + y * y) * sin(halfAngle) ** 2,                            0,
		0,                                                                        0,                                                                        0,                                                                        1,
	]
}

[trusktr]

I've discovered that the spec does not mention that for axis-angle rotations, the given vector has to be normalized into a unit vector. Without that step, rotations will be incorrect. I'm writing unit tests in my polyfill.

After I perform unit-vector normalization, I can get my results to be close to those of Chrome's DOMMatrix.rotateAxisAngle self, but it is off by a small amount of precision. There's some small difference in the calculation by Chrome vs my JavaScript polyfill; I don't know what that is yet. In my unit tests, I'll check that values are equal to within a small epsilon difference.

Proposal

We need to update the rotateAxisAngle and rotateAxisAngleSelf methods to include this step.