Xây dựng và điều khiển mô hình hạt GPU với WonderSnap

WonderSnap là gì?

WonderSnap là trải nghiệm 3D trên trình duyệt, biến các mô hình dựng theo quy trình thành những đám mây phát sáng gồm tối đa 250.000 hạt được xử lý bằng GPU. Bạn có thể búng ngón tay để triệu hồi các hạt, tạo hình chúng thành các địa danh hoặc cấu trúc giải phẫu, xoay mô hình bằng tay và mở các cụm lắp ráp thành chế độ xem bung tách có gắn nhãn.

Ứng dụng kết hợp tính năng theo dõi bàn tay trên thiết bị, nhận diện cử chỉ tùy chỉnh, mô hình dựng theo quy trình và trình kết xuất WebGL2 được viết thủ công. Ứng dụng không sử dụng Three.js, game engine hay framework frontend. Video từ webcam vẫn ở trên máy của bạn và không được gửi đến máy chủ.

Webcam là tùy chọn. Mọi tương tác thiết yếu đều có thể thực hiện bằng các điều khiển trên màn hình, bàn phím và chuột.

Tính năng chính

• Kết xuất hạt bằng GPU: Vật lý hạt chạy thông qua transform feedback của WebGL2 và hỗ trợ tối đa 250.000 hạt.
• Theo dõi bàn tay trên thiết bị: MediaPipe Hand Landmarker theo dõi tối đa hai bàn tay, với 21 điểm mốc trên mỗi bàn tay.
• Nhận diện cử chỉ: Các bộ phân loại tùy chỉnh nhận diện động tác búng tay, nắm tay, mở bàn tay, chỉ, chụm ngón, ký hiệu hòa bình, xoay bàn tay và phóng to bằng hai tay.
• 33 mô hình dựng theo quy trình: Bộ sưu tập bao gồm địa danh, giải phẫu, sinh học, động cơ, phương tiện và máy móc.
• Các bộ phận tương tác: Những thành phần có tên có thể phát sáng, tách thành chế độ xem bung tách, hiển thị nhãn và được kéo ra để quan sát kỹ hơn.
• Giải phẫu động: Tim đập ở 72 nhịp/phút, trong khi phổi hô hấp theo chu kỳ 4,5 giây.
• Công cụ giáo dục: Chế độ đố vui yêu cầu bạn xác định các bộ phận, còn tính năng mô tả và giọng nói sẽ giải thích về chúng.
• Điều khiển bằng giọng nói: Chrome và Edge có thể xử lý các lệnh như show me the heart, zoom in và quiz.
• Hiển thị mặt cắt và ghi hình: Bạn có thể hiển thị các mặt cắt phát sáng và lưu cảnh dưới dạng video WebM.

Yêu cầu

Trước khi cài đặt WonderSnap, hãy đảm bảo bạn có những thành phần sau:

• Node.js 18 trở lên.
• Chrome hoặc Edge để có trải nghiệm trình duyệt như tài liệu hướng dẫn.
• Webcam nếu bạn muốn sử dụng điều khiển bằng cử chỉ.
• Trình duyệt và thiết bị hỗ trợ WebGL2.

Camera phải được truy cập từ localhost hoặc một địa chỉ HTTPS. Không khởi chạy ứng dụng bằng cách nhấp đúp vào index.html; hãy sử dụng máy chủ cục bộ đi kèm.

Cài đặt và khởi động WonderSnap

1. Sao chép kho lưu trữ

git clone https://github.com/AkbarSheikh-debug/wondersnap.git
cd wondersnap

2. Cài đặt các phần phụ thuộc

npm install

Bước này cũng cung cấp runtime theo dõi bàn tay từ node_modules. Nếu MediaPipe không bao giờ tải được, hãy kiểm tra xem quá trình cài đặt đã hoàn tất thành công chưa.

3. Khởi động máy chủ cục bộ

npm start

Mở http://localhost:5173 trong Chrome hoặc Edge. Chọn Start with camera để bật tính năng theo dõi bàn tay hoặc chọn Continue without camera để sử dụng chuột, bàn phím và các điều khiển trên màn hình.

4. Sử dụng cổng khác nếu cần

Nếu cổng 5173 đang được sử dụng, hãy truyền một cổng khác vào lệnh khởi động:

npm start -- 8080

Sau đó, bạn có thể mở http://localhost:8080.

Quy trình cử chỉ cơ bản

Sau khi cấp quyền truy cập camera, hãy đặt bàn tay ở vị trí webcam có thể nhìn thấy rõ. Một tương tác thông thường diễn ra theo trình tự sau:

1. Búng ngón tay để triệu hồi các hạt. Búng lần nữa sẽ làm mô hình hiện tại tan biến.
2. Nắm tay để tạo hình địa danh, cơ quan, phương tiện, động cơ hoặc máy móc đã chọn.
3. Đưa lên, vặn hoặc nghiêng bàn tay để xoay và nghiêng mô hình đã tạo hình.
4. Mở bàn tay để chuyển sang mô hình tiếp theo. Với cơ quan, động cơ và phương tiện, mở bàn tay sẽ điều khiển khoảng cách các bộ phận bung ra; khép tay sẽ đưa chúng lại với nhau.
5. Chỉ vào một bộ phận và giữ ngón tay trên đó để chọn. Bộ phận sẽ phát sáng và một thẻ thông tin mô tả vai trò của nó.
6. Chụm ngón để kéo bộ phận đã chọn về phía bạn. Chụm lần nữa để đưa bộ phận trở lại.
7. Sử dụng hai tay và thay đổi khoảng cách giữa chúng để phóng to hoặc thu nhỏ.
8. Tạo ký hiệu hòa bình để chuyển nhanh đến mô hình tiếp theo.

Sử dụng bàn phím và chuột

Nếu không có webcam hoặc muốn điều khiển chính xác hơn, hãy sử dụng bàn phím và chuột. Nhấp vào một bộ phận để chọn và kéo cảnh để xoay.

• Space: mô phỏng động tác búng ngón tay.
• F, O và V: kích hoạt các động tác nắm tay, mở bàn tay và ra dấu hòa bình.
• Left Arrow và Right Arrow: chọn mô hình trước hoặc tiếp theo.
• E, Up Arrow, Down Arrow hoặc con lăn chuột: điều chỉnh chế độ tách lớp.
• +, - và 0: thay đổi hoặc đặt lại mức thu phóng. Bạn cũng có thể dùng Control cùng con lăn chuột.
• C: bật hoặc tắt camera.
• L: bật hoặc tắt nhãn bộ phận.
• R: bật hoặc tắt xoay tự động.
• G: bật hoặc tắt xoay bằng tay.
• X: kích hoạt mặt cắt. Dùng , và . để dịch chuyển nhẹ mặt phẳng cắt.
• Q: bắt đầu chế độ câu hỏi.
• M: sử dụng lệnh thoại và tính năng đọc to.
• K: ghi video.
• D: phát bản demo tích hợp sẵn.
• I: mô tả bộ phận được chọn.
• Esc: bỏ chọn bộ phận hiện tại.
• H: hiển thị trợ giúp.

Khám phá Bộ sưu tập Mô hình

WonderSnap bao gồm 33 mô hình dựng theo quy trình, được phát triển từ các phép đo thực tế và tổ chức thành sáu nhóm:

• Kỳ quan: Mười một địa danh, gồm Tháp Eiffel, Đại kim tự tháp, Taj Mahal, Big Ben và Nhà hát Opera Sydney.
• Giải phẫu: Mười mô hình, gồm não, tim đang đập, phổi đang hô hấp, bộ xương và cơ thể người theo từng lớp.
• Sinh học: Một chuỗi xoắn kép DNA có thể tháo xoắn và một tế bào động vật.
• Động cơ: Động cơ 4 xi-lanh thẳng hàng, HEMI V8 tăng áp, động cơ phản lực turbofan và động cơ hướng tâm 9 xi-lanh.
• Phương tiện: Xe thể thao, xe máy, máy bay chở khách và Saturn V có mô phỏng tách tầng.
• Máy móc: Đồng hồ cơ đeo tay và bộ pin xe điện gồm các cell, thanh cái, hệ thống làm mát và hệ thống quản lý pin.

Sử dụng các Tính năng Giáo dục

Kiểm tra các bộ phận có nhãn

Di con trỏ lên hoặc nhấp vào một thành phần để chọn. Bộ phận được chọn sẽ phát sáng và thẻ thông tin giải thích chức năng của nó. Bật nhãn bằng L để hiển thị các đường nối từ tên đến từng bộ phận.

Bắt đầu câu hỏi

Nhấn Q để vào chế độ câu hỏi. WonderSnap hiển thị các yêu cầu như Tìm: Hồi hải mã. Di con trỏ lên hoặc nhấp vào thành phần được yêu cầu. Mỗi lượt hỏi gồm năm câu và tạo ra một điểm số.

Điều khiển cảnh bằng giọng nói

Nhấn M để truy cập lệnh thoại và tính năng đọc to. Các ví dụ được hỗ trợ gồm show me the heart, open it up, where is the right atrium, zoom in và quiz. Tính năng tổng hợp giọng nói được ghi nhận hỗ trợ trên Chrome và Edge.

Tạo mặt cắt

Nhấn X để bật chế độ xem mặt cắt. Mặt phẳng cắt có thể di chuyển theo bàn tay và để lộ một mặt cắt phát sáng. Khi không dùng cử chỉ, hãy sử dụng , và . để di chuyển mặt phẳng từng bước.

Ghi lại kết quả

Nhấn K để ghi cảnh và lưu dưới dạng video WebM.

Cấu hình WonderSnap bằng Tùy chọn URL

Các tùy chọn chuỗi truy vấn cho phép thay đổi hành vi khởi động và tinh chỉnh việc kết xuất mà không cần chỉnh sửa tệp mã nguồn.

• ?n=250000: đặt số lượng hạt.
• ?model=12: khởi động với số mô hình được chỉ định.
• ?autostart=camera: bỏ qua màn hình bắt đầu và yêu cầu chế độ camera.
• ?autostart=nocamera: bỏ qua màn hình bắt đầu và chạy mà không dùng camera.
• ?trails=0: tắt vệt hạt.
• ?dpr=1: buộc tỷ lệ điểm ảnh thiết bị bằng 1, có thể hữu ích trên GPU chậm hơn.

Có thể kết hợp các tùy chọn. Ví dụ, địa chỉ này khởi động mà không dùng camera, sử dụng 100,000 hạt, buộc tỷ lệ điểm ảnh thiết bị bằng 1 và tắt vệt hạt:

http://localhost:5173/?autostart=nocamera&n=100000&dpr=1&trails=0

Mẹo Nâng cao

Cải thiện hiệu suất trên phần cứng chậm hơn

Số lượng hạt và tỷ lệ điểm ảnh thiết bị tác động trực tiếp đến tải kết xuất. Hãy bắt đầu với cấu hình tốc độ khung hình thấp được đề xuất trong README:

http://localhost:5173/?n=100000&dpr=1

Nếu cần, hãy thêm trails=0 để tắt vệt hạt.

Sử dụng liên kết khởi động xác định

Để trình diễn hoặc kiểm thử có thể lặp lại, hãy kết hợp model với chế độ autostart. Cách này tránh phải điều hướng thủ công qua màn hình bắt đầu và danh sách mô hình mỗi lần.

Tìm hiểu kiến trúc ứng dụng

Vòng lặp kết xuất chính, tính năng chọn đối tượng, thu phóng, chế độ tách lớp, nhãn, câu hỏi, mặt cắt và bản demo nằm trong src/app.js. Tích hợp webcam và MediaPipe nằm trong src/hands.js, còn điều khiển bằng giọng nói, tính năng đọc to và ghi hình được triển khai trong src/features.js.

Thư mục src/gl/ chứa các shader WebGL2 và trình kết xuất transform-feedback. Logic cử chỉ, máy trạng thái, các bộ điều khiển và phiên bản tương đương CPU của vật lý hạt nằm trong src/logic/. Các tiện ích hình học dựng theo quy trình nằm trong src/lib/, còn định nghĩa mô hình được nhóm trong src/models/.

Chạy Bộ kiểm thử

WonderSnap bao gồm 36 bài kiểm thử end-to-end và kiểm thử đơn vị được xây dựng bằng Playwright. Các bài kiểm thử điều khiển ứng dụng thực bằng bàn tay tổng hợp và đồng hồ xác định.

Cài đặt trình duyệt Chromium của Playwright một lần:

npx playwright install chromium

Sau đó chạy các bài kiểm thử:

npm test

Bộ kiểm thử bao quát toàn bộ luồng cử chỉ, mọi mô hình, chế độ xem tách rời, điều khiển bằng bàn phím và con lăn chuột, bố cục đáp ứng, hoạt ảnh nhịp tim và hô hấp, thao tác thu phóng bằng hai tay, chọn bộ phận, tương tác chụm, câu đố, lệnh thoại, chế độ cắt lớp, ghi hình, hành vi dự phòng của camera, bộ phân loại tư thế, chuyển đổi trạng thái, tính hợp lệ của mô hình thủ tục và vật lý GPU. Shader GPU cũng được so sánh với phiên bản CPU tương ứng, đạt độ chính xác xấp xỉ 1e-7 trong mọi chế độ.

Khắc phục sự cố

• Camera không khởi động: Mở ứng dụng thông qua http://localhost:5173 thay vì mở trực tiếp index.html, rồi cấp quyền camera khi được yêu cầu.
• Không tải được tính năng theo dõi bàn tay: Chạy npm install. Môi trường chạy tính năng theo dõi được cung cấp từ node_modules.
• Tốc độ khung hình thấp: Hãy thử http://localhost:5173/?n=100000&dpr=1.
• Cổng 5173 đang được sử dụng: Chạy npm start -- 8080 và mở http://localhost:8080.

Kết luận

WonderSnap cho thấy tính năng theo dõi bàn tay trên thiết bị, các bộ phân loại cử chỉ tùy chỉnh, mô hình hóa thủ tục và vật lý hạt GPU có thể cùng tạo nên một trải nghiệm giáo dục tương tác hoàn toàn trong trình duyệt. Hãy bắt đầu với thiết lập cục bộ tiêu chuẩn, làm quen với các tương tác búng, nắm tay, mở bàn tay, chỉ và chụm, sau đó khám phá các tùy chỉnh URL, điều khiển bằng giọng nói, câu đố, mặt cắt, ghi hình và bộ kiểm thử tự động.