《游戏引擎实现原理》8.3 变换复合与逆变换

M = T * R * S

// file: src/core/transform.ts
// tier: L1
// verify: npx vitest run src/core/transform.test.ts
//
// helio 内核：TRS 变换与其逆。复合顺序固定 M = T * R * S
// （列向量：先缩放、再旋转、最后平移）。逆变换由分量直接构造，不做通用 4x4 求逆。

import {
  type Mat4,
  fromScale,
  fromTranslation,
  identity,
  multiply,
  transpose,
} from './mat4.ts';
import { normalize, type Vec3 } from './vec3.ts';

/** 平移 / 旋转 / 缩放三元组。rotation 只用左上 3x3（正交矩阵）。 */
export type Transform = {
  readonly translation: Vec3;
  readonly rotation: Mat4;
  readonly scale: Vec3;
};

/** 绕任意轴 angle 弧度的旋转矩阵（Rodrigues 公式，列主序）。 */
export function rotationFromAxisAngle(axis: Vec3, angle: number): Mat4 {
  const [x, y, z] = normalize(axis);
  const c = Math.cos(angle);
  const s = Math.sin(angle);
  const t = 1 - c;
  const m = identity();
  m[0] = t * x * x + c;
  m[1] = t * x * y + s * z;
  m[2] = t * x * z - s * y;
  m[4] = t * x * y - s * z;
  m[5] = t * y * y + c;
  m[6] = t * y * z + s * x;
  m[8] = t * x * z + s * y;
  m[9] = t * y * z - s * x;
  m[10] = t * z * z + c;
  return m;
}

/** 把 TRS 复合成单个 4x4：M = T * R * S。 */
export function composeTRS(t: Transform): Mat4 {
  const s = fromScale(t.scale[0], t.scale[1], t.scale[2]);
  const tr = fromTranslation(t.translation[0], t.translation[1], t.translation[2]);
  const rs = multiply(identity(), t.rotation, s);
  return multiply(identity(), tr, rs);
}

/** 逆变换：M⁻¹ = S⁻¹ * Rᵀ * T(-t)。 */
export function invertTRS(t: Transform): Mat4 {
  const invS = fromScale(1 / t.scale[0], 1 / t.scale[1], 1 / t.scale[2]);
  const invR = transpose(t.rotation); // 正交矩阵的逆 = 转置
  const invT = fromTranslation(-t.translation[0], -t.translation[1], -t.translation[2]);
  const invRT = multiply(identity(), invR, invT);
  return multiply(identity(), invS, invRT);
}

/** 方向变换：只取 4x4 的左上 3x3，忽略平移。 */
export function transformDirection(m: Mat4, d: Vec3): Vec3 {
  return [
    m[0]! * d[0] + m[4]! * d[1] + m[8]! * d[2],
    m[1]! * d[0] + m[5]! * d[1] + m[9]! * d[2],
    m[2]! * d[0] + m[6]! * d[1] + m[10]! * d[2],
  ];
}

/** 法线矩阵的左上 3x3：对 TRS 而言 = R * S⁻¹（列主序 9 个数）。 */
export function normalMatrix3(t: Transform): Float32Array {
  const out = new Float32Array(9);
  const invS: Vec3 = [1 / t.scale[0], 1 / t.scale[1], 1 / t.scale[2]];
  for (let c = 0; c < 3; c++) {
    for (let r = 0; r < 3; r++) {
      out[c * 3 + r] = t.rotation[c * 4 + r]! * invS[c]!;
    }
  }
  return out;
}

/** 用 3x3 法线矩阵变换一个法线（不归一化，由调用方决定）。 */
export function transformNormal3(nm: Float32Array, n: Vec3): Vec3 {
  return [
    nm[0]! * n[0] + nm[3]! * n[1] + nm[6]! * n[2],
    nm[1]! * n[0] + nm[4]! * n[1] + nm[7]! * n[2],
    nm[2]! * n[0] + nm[5]! * n[1] + nm[8]! * n[2],
  ];
}

// file: src/core/transform.test.ts
// tier: L1
// verify: npx vitest run src/core/transform.test.ts

import { describe, expect, it } from 'vitest';
import { identity, multiply, transformPoint } from './mat4.ts';
import {
  composeTRS,
  invertTRS,
  normalMatrix3,
  rotationFromAxisAngle,
  transformDirection,
  transformNormal3,
  type Transform,
} from './transform.ts';
import { dot, normalize, type Vec3 } from './vec3.ts';

const SAMPLE: Transform = {
  translation: [3, -2, 5],
  rotation: rotationFromAxisAngle([1, 1, 0], 0.7),
  scale: [2, 0.5, 1.5],
};

function maxAbsDiff(a: Float32Array, b: Float32Array): number {
  let m = 0;
  for (let i = 0; i < a.length; i++) m = Math.max(m, Math.abs(a[i]! - b[i]!));
  return m;
}

describe('TRS 复合与逆', () => {
  it('M * M⁻¹ 约等于单位阵', () => {
    const m = composeTRS(SAMPLE);
    const inv = invertTRS(SAMPLE);
    const prod = multiply(identity(), m, inv);
    const err = maxAbsDiff(prod, identity());
    expect(err).toBeLessThan(1e-5);
  });

  it('点经 M 再经 M⁻¹ 回到原处', () => {
    const m = composeTRS(SAMPLE);
    const inv = invertTRS(SAMPLE);
    const p: Vec3 = [1.5, -0.5, 2];
    const fwd = transformPoint(m, p[0], p[1], p[2]);
    const back = transformPoint(inv, fwd[0], fwd[1], fwd[2]);
    expect(back[0]).toBeCloseTo(p[0], 4);
    expect(back[1]).toBeCloseTo(p[1], 4);
    expect(back[2]).toBeCloseTo(p[2], 4);
  });
});

describe('法线变换：非均匀缩放下必须用 R * S⁻¹', () => {
  const t: Transform = {
    translation: [0, 0, 0],
    rotation: identity(),
    scale: [2, 1, 1],
  };
  const m = composeTRS(t);
  const n = normalize([1, 0, 1]);
  const tangent = normalize([1, 0, -1]);

  it('正确法线：与变换后的切线垂直', () => {
    const t2 = transformDirection(m, tangent);
    const n2 = normalize(transformNormal3(normalMatrix3(t), n));
    expect(Math.abs(dot(t2, n2))).toBeLessThan(1e-5);
  });

  it('朴素法线（直接用 M 变换）不再垂直', () => {
    const t2 = transformDirection(m, tangent);
    const naive = normalize(transformDirection(m, n));
    expect(Math.abs(dot(t2, naive))).toBeGreaterThan(0.5);
  });
});