img2threejs là gì? Biến ảnh tham chiếu thành mô hình 3D procedural bằng Three.js

img2threejs: quy trình biến ảnh tham chiếu thành mô hình 3D procedural bằng Three.js — Minh họa workflow image-to-3D bằng code. Ảnh tạo bằng AI qua 9Router.

img2threejs là một dự án mã nguồn mở giúp coding agent tái dựng đối tượng trong ảnh tham chiếu thành mô hình 3D procedural bằng Three.js. Điểm khác biệt quan trọng: kết quả không phải file mesh tải về hay photogrammetry; dự án sinh mã TypeScript tạo THREE.Group, vật liệu, hierarchy và các điểm gắn để tiếp tục đưa vào cảnh web hoặc animation.

Repo chính thức mô tả đây là quy trình “image-to-3D bằng code”, có kiểm tra chất lượng theo từng giai đoạn. Mục tiêu là dùng token của agent cho việc phán đoán hình ảnh và viết code, còn các bước kiểm tra/sắp xếp lặp lại do script Python xử lý.

img2threejs là gì?

Bạn đưa vào một ảnh tham chiếu của đối tượng. Skill phân loại chủ thể, lập danh mục chi tiết nhận diện, tạo đặc tả, sinh factory Three.js theo từng pass và render để đối chiếu ảnh gốc. Khi điều kiện mạng cho phép, kết quả cuối là factory TypeScript trả về THREE.Group cùng metadata runtime.

Dự án phù hợp với asset 3D cho website, demo tương tác, prototype game hoặc sản phẩm cần mô hình được kiểm soát bằng code. Nó không nên được hiểu là lời hứa tái tạo chính xác tuyệt đối từ một ảnh duy nhất: góc khuất, kích thước thật và chi tiết không nhìn thấy vẫn phải được suy luận hoặc cần thêm ảnh tham chiếu.

Demo chính thức img2threejs: ảnh tham chiếu và mô hình Three.js procedural — Demo chính thức từ repository img2threejs: ảnh tham chiếu được tái dựng thành mô hình procedural chạy trong trình duyệt.

Điểm đáng chú ý

Code procedural thay vì mesh nhị phân

Đầu ra là TypeScript, JSON spec và các render/comparison sheet. Nhờ vậy đội ngũ có thể diff bằng Git, điều chỉnh primitive, vật liệu hoặc logic animation mà không phụ thuộc vào một asset nhị phân lớn.

Quy trình quality-gated

Pipeline đi theo các pass: blockout, structural, form refinement, materials, surface, lighting, interaction và optimization. Mỗi pass yêu cầu render/so sánh trước khi chuyển bước. Đây là cơ chế quy trình, không phải thước đo khách quan bảo đảm chất lượng cho mọi ảnh.

Hierarchy sẵn sàng cho runtime

Factory có thể đặt pivot, socket, collider và nhóm phá hủy trong root.userData.sculptRuntime. Các cấu trúc này hữu ích khi một bộ phận cần quay, gắn phụ kiện hoặc chạy animation.

Ưu tiên chi tiết nhận diện

Trước khi sinh mã, dự án yêu cầu liệt kê các chi tiết như bo cạnh, đường panel, fastener, độ bóng/mờ, vết mòn và đường nét trang trí. Ý tưởng là tránh tạo một khối 3D chung chung thiếu đặc trưng của vật mẫu.

Cài img2threejs

README hiện hướng dẫn đặt repo vào thư mục skills của coding agent. Ví dụ với Claude Code:

git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs

Sau đó đính kèm hoặc chỉ tới ảnh đối tượng và gọi:

/img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.

Repo nêu hỗ trợ Claude Code, Codex và OpenCode theo hướng agent-agnostic; agent host cần có cách đọc ảnh và xem preview/browser. Hãy đọc hướng dẫn của host agent trước khi kỳ vọng cú pháp slash command giống nhau ở mọi môi trường.

Các script có thể chạy độc lập

Tooling dùng Python 3.10+ standard library, không yêu cầu pip theo README. Một luồng rút gọn gồm probe ảnh, tạo assessment/spec, strict validation và sinh factory:

python3 forge/stage1_intake/probe_image.py <image>
python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json
python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts

Đầu ra nhận được

ObjectSculptSpec JSON: component tree, vật liệu, repetition system, socket và lịch sử review.
Factory TypeScript tạo THREE.Group.
Runtime metadata cho node, socket, collider và destruction group.
Render và comparison sheet giữa ảnh tham chiếu với kết quả.

Phù hợp với ai?

Frontend/creative developer đang xây trải nghiệm Three.js.
Người dùng Claude Code, Codex hoặc OpenCode muốn thử workflow image-to-3D bằng mã.
Nhóm prototype asset cần phiên bản hóa bằng Git.
Người làm interactive product muốn mô hình có pivot/socket thay vì một mesh tĩnh.

Giới hạn cần biết

Chất lượng đầu vào ảnh, góc chụp và mức độ phức tạp quyết định đáng kể kết quả.
Đây không phải photogrammetry hay công cụ xuất mesh có texture hoàn chỉnh từ một ảnh.
Model/agent vẫn phải đánh giá ảnh, render và sửa lặp; kết quả phụ thuộc năng lực agent host.
Đồ vật/nhân vật cụ thể có thể có phần bị suy luận; README khuyến nghị báo confidence theo vùng và xin thêm góc nhìn khi cần.
Kiểm tra quyền sử dụng ảnh tham chiếu, thương hiệu và thiết kế sản phẩm trước khi dùng trong dự án thương mại.

Kết luận

img2threejs đáng chú ý vì biến bài toán “từ ảnh đến 3D” thành một quy trình kỹ thuật minh bạch, diff được và có bước đánh giá thay vì một hộp đen xuất asset. Nếu đang làm Three.js với coding agent, đây là repo đáng thử nghiệm; hãy bắt đầu từ ảnh đối tượng đơn giản và demo chính thức trước khi đưa vào pipeline production.