Anatomy: Đồ họa Isometric SVG và WebGL cho AI Agent

Tóm tắt nhanh
Anatomy là engine minh họa kỹ thuật mã nguồn mở và kỹ năng đa agent phát hành theo giấy phép MIT trong kho lưu trữ Anatomy. Vận hành hoàn toàn không phụ thuộc thư viện npm ngoài trên Node.js 20.10+, Anatomy chuyển hóa các khái niệm phần mềm trừu tượng thành cỗ máy cơ khí isometric gồm hàng chục chi tiết đặc. Hệ thống kết hợp nhân chiếu isometric và đổ bóng 4 sắc độ (kit/iso-kit.mjs), vật thể tròn xoay đa trục (kit/lathe.mjs), đường dẫn ống lưu chất (kit/tube.mjs), shader WebGL đồng bộ camera (kit/gl.mjs) và runtime 3D xoay khối (kit/turn.mjs). Bộ kiểm định hình học (kit/audit.mjs) cùng script Chrome headless (scripts/lines.mjs) chứng minh toán học rằng không có chi tiết nào va chạm xuyên thấu và mọi nét vẽ đều neo chuẩn xác vào bề mặt.

Tài liệu kỹ thuật thường dựa vào sơ đồ khối và mũi tên nối. Dù Mermaid hay Graphviz nắm bắt tốt đồ thị phụ thuộc logic, chúng khó truyền tải thực tế vận hành như giới hạn tốc độ, trạng thái bền vững hay va chạm không gian.

Các điểm nghẽn ở sơ đồ do AI sinh tự do:

• Tách rời cơ chế: Hộp chữ nhật “Cache Store” không mô tả được cách thức tác vụ xếp hàng hay đồng bộ hóa.
• Nét vẽ trôi nổi: Mô hình sinh nét vector lơ lửng giữa khoảng trống hoặc cắt ngang thân chi tiết.
• Số liệu giả lập: Nhãn tĩnh hiển thị thông số không gắn kết với mô hình trạng thái.
• Lỗi thứ tự chiều sâu: Dây nối phía sau vẽ đè lên vỏ máy phía trước do thiếu painter’s order.

[Sơ Đồ AI Sinh Dựa Trên Prompt Tự Do]
  │
  ├── Prompt thiếu ràng buộc ──> Hộp khối trừu tượng & mũi tên trôi nổi
  ├── Thứ tự hiển thị lỗi ────> Dây cáp phía sau đè lên vỏ máy phía trước
  └── Nhãn hiển thị giả định ──> Số liệu tách rời khỏi mô hình tính toán

==================================== VS ====================================

[Quy Trình Cơ Khí Thực Nghiệm Của Anatomy]
  │
  ├── Ẩn dụ cơ khí vật lý ────> Khái niệm logic chuyển thành cỗ máy hữu hình
  ├── Toán học thuần Node.js ──> Đổ bóng 4 sắc độ & vector pháp tuyến Hermite
  ├── Shader WebGL khóa góc ───> Hiệu ứng thể tích lồng trong mặt phẳng isometric
  └── Kiểm định hình học ─────> Đo đạc khoảng hở & kiểm tra nét vẽ qua Chrome

Ẩn dụ cơ khí: hiện thực hóa thuật toán thành cỗ máy hữu hình

Anatomy định hướng coding agent (Claude Code, Antigravity, OpenCode, Codex, MiniMax Code) tạo cỗ máy cơ khí mô phỏng thuật toán:

• Cache key lookup: Ổ khóa pin-tumbler chỉ xoay khi toàn bộ chốt lò xo nâng đúng đường cắt shear line.
• GPU context multiplexer: Máy vẽ gantry trục kép đưa đầu in cơ học qua khay 16 giếng phản ứng.
• Giao thoa sóng: Bể tạo sóng 4 chân với hai cần rung tạo vân và ánh sáng tụ quang xuống mặt giấy.
• Token bucket rate limiter: Phễu chứa chất lỏng nạp liên tục cùng van xả định lượng theo chu kỳ.

Mọi số đo trên khung hiển thị đều liên kết trực tiếp với vòng lặp vật lý điều khiển chuyển động.

Nhân toán học isometric và camera chiếu hình

Tại trung tâm Anatomy là thư viện kit/iso-kit.mjs, viết hoàn toàn bằng Node.js thuần. Engine chuyển đổi tọa độ 3D [x, y, z] (x, y trên sàn, z hướng lên) thành tọa độ màn hình 2D [sx, sy] trong viewBox SVG.

Camera mặc định góc xoay ngang 45 độ và góc nâng 30 độ. Thuật toán tính toán tọa độ chiếu và chiều sâu:

// Tính toán phép chiếu camera và độ sâu trong kit/iso-kit.mjs
export function cameraOf({ scale, azimuth = 45, elevation = 30 }) {
  const a = azimuth * (Math.PI / 180);
  const e = elevation * (Math.PI / 180);
  return {
    sinA: Math.sin(a),
    cosA: Math.cos(a),
    sinE: Math.sin(e),
    cosE: Math.cos(e),
    k: scale * Math.sqrt(1.6)
  };
}

export function iso([x, y, z], projection) {
  const { origin } = projection;
  const { sinA, cosA, sinE, cosE, k } = cameraOf(projection);
  return [
    origin[0] + (x * sinA - y * cosA) * k,
    origin[1] + ((x * cosA + y * sinA) * sinE - z * cosE) * k
  ];
}

export function depthOf([x, y, z], projection) {
  const { sinA, cosA, sinE, cosE } = cameraOf(projection);
  return (x * cosA + y * sinA) * cosE + z * sinE;
}

Anatomy sử dụng bảng màu đổ bóng 4 sắc độ (hi, mid, lo, faint), phân nhóm theo góc giữa vector pháp tuyến bề mặt và nguồn sáng cố định theo camera (normalize([-sinA, cosA, 1.2])).

Khi dựng khối qua slabOf, cylinder hay extrude, hệ thống xuất các đường nét cấu trúc: fill (thân nền che khuất lớp sau), shades[0..3] (các mặt bên theo dải sáng), top (mặt đỉnh đón sáng), crease (đường giao đỉnh và mặt bên), bevel (vát mép đón sáng) và outline (đường viền bao ngoài). Để triệt tiêu khe hở răng cưa hiển thị, Anatomy bật paths.seamless = true với nét viền cùng màu 0.4 pixel.

Vật thể tròn xoay và trường vector pháp tuyến mượt mà

Kỹ thuật đùn khối thẳng phù hợp khung máy, nhưng để lại vết gãy góc trên chi tiết cong như buồng đốt tên lửa. Module kit/lathe.mjs định nghĩa vật thể tròn xoay quanh hệ trục 3D F = { o, a, u, v }, áp dụng spline Fritsch-Carlson đơn điệu:

// Tính toán dải bề mặt mượt mà trong kit/lathe.mjs
export function bandsOf(profile, cuts, F, P, {
  slope = null,
  radius = null,
  steps = 96,
  rows = 8,
  samples = 72
} = {}) {
  // Đánh giá trường vector pháp tuyến liên tục qua các mặt phân cắt
  // Chia sẻ chung pháp tuyến giúp dải bóng chuyển màu không bị gãy góc
}

Tùy chọn smooth: { slope } tính vector pháp tuyến trực tiếp từ đạo hàm dr/ds, giúp ranh giới bóng chuyển tiếp êm qua mối nối. Hàm bandsOf hỗ trợ cắt thân chi tiết theo chiều sâu để sắp xếp xen kẽ chuẩn xác với đường ống bao quanh.

Điều phối đường ống dẫn chất lưu và cáp tín hiệu

Trong kit/tube.mjs, Anatomy chia nhỏ đường trục 3D thành các dải vector:

• Phân đoạn có gối đầu: Đường ống chia đoạn dài tối đa 30 đơn vị qua tubePieces, gối đầu 0.5 đơn vị để tránh khuyết góc khi khử răng cưa.
• Xử lý giao cắt (crossingsOf): Tự tính tọa độ cắt nhau trên màn hình để ống gần luôn hiển thị phía trên.
• Khoảng hở phụ kiện: Khi ống qua cổ siết, khai báo gaps = [[from, to]] để ẩn thân và sinh nắp đậy elip chuẩn xác.

// Chia nhỏ đường ống và sắp xếp chiều sâu giao cắt
const pieces = tubePieces(routePoints, 1.2, P, {
  maxLength: 30,
  gaps: [[14, 22]],
  caps: [true, true]
});

pieces.forEach((chunk) => {
  R.put({
    piece: "hydraulic_circuit",
    at: chunk.mid,
    bias: 0.1,
    svg: tubeSvg(chunk, { tone: "hi" }),
    shapes: [A.tube(chunk.points, chunk.radii)]
  });
});

Tích hợp shader WebGL khóa góc nhìn isometric

Những hiện tượng vật lý như luồng lửa phản lực hay sóng nước đòi hỏi hiệu ứng thể tích liên tục. Anatomy giải quyết qua module kit/gl.mjs với canvas WebGL kẹp giữa lớp SVG nền (.iso-back) và SVG nổi (.iso-front), chia sẻ chung ma trận chiếu:

// Hệ tọa độ chiếu isometric trong kit/gl.mjs
precision highp float;
uniform vec2 uCanvas;
uniform vec2 uView;
uniform vec2 uOrigin;
uniform float uK;
uniform vec4 uCam; // sinA, cosA, sinE, cosE

vec2 project(vec3 p) {
  return uOrigin + uK * vec2(
    p.x * uCam.x - p.y * uCam.y,
    (p.x * uCam.y + p.y * uCam.x) * uCam.z - p.z * uCam.w
  );
}

vec3 towardViewer() {
  return vec3(uCam.y * uCam.w, uCam.x * uCam.w, uCam.z);
}

Shader duyệt tia dọc towardViewer() trong tọa độ thế giới, giúp chùm lửa khớp chuẩn mép loa SVG. Canvas giới hạn devicePixelRatio ở mức 1.5 để bảo vệ GPU, tự tạm dừng render khi cuộn khỏi màn hình và chuyển sang hình tĩnh khi bật prefers-reduced-motion.

Chuyển động học vật thể cứng 3D và mặt phẳng phân tách

Đối với mô hình xoay, Anatomy cung cấp runtime 3D (kit/turn.mjs, kit/turn-build.mjs) hỗ trợ 4 nhóm chuyển động: turn (xoay tròn), slide (tịnh tiến), hinge (khớp xoay góc) và free (lật nhào tự do).

Thay vì dựng cây BSP tốn kém từng frame, turn-build.mjs giải quyết thứ tự vẽ từ trước bằng các mặt phẳng phân tách. Do nguồn sáng khóa theo camera, xoay cụm chi tiết góc $\theta$ quanh trục đứng tương đương quan sát mô hình tĩnh ở góc azimuth $a – \theta$, cho phép áp dụng toàn bộ kiểm định 2D lên vật thể đang xoay.

Kiểm định hình học và rà soát va chạm thực nghiệm

Mô hình Anatomy phải tự chứng minh tính hợp lệ qua kit/audit.mjs. Lệnh node build.mjs --audit đánh giá toàn bộ ranh giới:

• Khoảng hở va chạm: Đảm bảo không có đường ống hay dây dẫn đâm xuyên dầm kim loại hay vỏ máy.
• Kiểm định mô hình phân rã: Quét khoảng cách ở trạng thái tĩnh và xuyên suốt từng frame tách khối (explodeStates).
• Neo giữ đầu mối: Mọi đường ống phải kết thúc tại mặt bích hay mối hàn thực tế; loại bỏ nét trôi nổi.
• Giới hạn uốn cong: Tính bán kính uốn cong biểu kiến; nếu góc uốn tạo nếp gấp ($R < 2r / \sin^2(e – \theta)$), bài test sẽ dừng.

# Thực thi kiểm định hình học trên mô hình động cơ Raptor
node examples/raptor-engine/build.mjs --audit

Kiểm tra nét vẽ qua Chrome Headless

Anatomy tích hợp script kiểm tra qua Chrome (scripts/lines.mjs, scripts/capture.mjs, scripts/drive.mjs) qua WebSocket CDP không cần Puppeteer:

• Mọi nhánh mở của .iso-line phải chạm vào nét vẽ khác, chốt tròn hoặc chìm dưới mặt phẳng vẽ sau; nét cố ý dừng ở mặt phẳng trống phải khai báo data-free.
• Script tự chụp ảnh độ phân giải cao và cắt phóng to 4x tại từng mối nối ở cả giao diện sáng lẫn tối.

# Kiểm tra các đầu mút nét vẽ trên hình SVG xuất bản
node scripts/lines.mjs examples/dial-indicator/dial-indicator.html --tolerance 1

Phân phối đa nền tảng: HTML, React, PDF A4 và thư viện cộng đồng

Anatomy hỗ trợ nhiều định dạng xuất bản:

1. Trang HTML độc lập: Dùng pageHtml nhúng sẵn CSS (ISO_CSS) và JavaScript (kitScript(), glScript()), tạo tệp đơn lẻ sẵn sàng lưu trữ web.
2. Component React 18+ TSX: Thẻ server (<Solid>, <Line>, <Wire>, <Plate>) trong kit/react/draw.tsx, kết hợp hook animation client (useLoop, useReadout, spring, follow) trong kit/react/live.tsx.
3. Bản vẽ kỹ thuật A4/Letter: Tệp sheet.mjs định nghĩa góc chụp và chú thích; lệnh node scripts/print.mjs sheet.mjs --format all xuất PDF poster, bản vẽ kỹ thuật hoặc hướng dẫn lắp ráp.
4. Đóng góp cộng đồng: Lệnh node scripts/publish.mjs <folder> --submit tự động tạo PR gửi tác phẩm lên wheresryan22/anatomy-community.

Lựa chọn công cụ: tiêu chí áp dụng giải pháp đồ họa

So sánh các tiêu chí kỹ thuật:

Khi tài liệu kỹ thuật đòi hỏi sự tường minh trực quan, Anatomy cung cấp nền tảng đồ họa không phụ thuộc thư viện, biến những dòng code trừu tượng thành cỗ máy cơ học vận hành chuẩn xác.