speckle-server/docs/viewer/README.md

Viewer & Objectloader Architecture

Đây là tài liệu tập trung vào trái tim của Speckle Web: Bộ hiển thị 3D (Viewer) và luồng tải dữ liệu (Objectloader).

1. Công nghệ sử dụng

• Engine chính: three (Three.js v0.140.0+).
• Hỗ trợ hình học toán học & xử lý lưới (Mesh processing):
  • three-mesh-bvh (Tính toán giao cắt Raycasting siêu tốc cho mô hình hàng triệu polygon).
  • earcut & polylabel (Polygon triangulation & tính toán tâm cho bề mặt).
• Render Text (Chữ trong 3D): troika-three-text.
• Dữ liệu mảng (Data Streaming): @speckle/objectloader2 (Được viết bằng plain TypeScript).

2. Objectloader (Giải mã Data Stream)

• Speckle KHÔNG gửi toàn bộ model 1 file .obj hay .gltf xuống client. Thay vào đó, API trả về 1 mảng các Object hashes.
• Objectloader chịu trách nhiệm gọi API /objects/ theo lô. Khi dữ liệu dạng Hash array về, nó giải nén và reconstruct (tái tạo lại) thành cây JSON theo đúng cấu trúc hình học.
• Dữ liệu này sau đó đẩy vào chuỗi queue cho Viewer đọc.

3. Viewer Core (Architecture)

1. Converter/Parsers: Trong viewer có các modules nhỏ nhận JSON từ Objectloader và dịch sang Geometry (BufferGeometry của Three.js). Do dữ liệu kiến trúc (BIM/CAD) rất đa dạng (Curves, Meshes, Breps, Points), Viewer có parser riêng cho từng loại data.
2. Batching & Instancing: Để render một tòa nhà 50.000 cái cửa sổ mà không làm lag trình duyệt web, Viewer thực hiện Mesh Batching hoặc InstancedMesh. Nghĩa là nó gộp tất cả các object có cùng vật liệu (material) vào chung 1 lưới Draw Call.
3. Filtering & Coloring: Viewer cung cấp API rất xịn xò để áp màu sắc dựa trên thuộc tính metadata (Ví dụ: tô màu tường theo Category tường, Cột theo Category cột). Kỹ thuật này đổi màu tại Shader hoặc thay đổi vertex colors trực tiếp trên Buffer.
4. Selections (Raycasting): Sử dụng BVH (three-mesh-bvh) nên tốc độ click chọn trúng 1 Object trong hàng triệu đối tượng diễn ra ở 60 FPS mà không hề giật lag.

4. Portability Note (Nhúng vào framework khác)

• @speckle/viewer được thiết kế dạng Framework-Agnostic (Không dính vào React, Vue hay Angular).
• Nó chỉ cần nhận một HTMLElement container để append thẻ <canvas> vào.
• Nếu muốn tích hợp lên App Mobile (React Native), hoàn toàn có thể dùng expo-gl và three.js nhưng cần tự thiết kế lại vòng lặp render, hoặc nhét Viewer vào WebView (cách rẻ và nhanh nhất).
• Nếu phát hành lại Viewer hoàn toàn bằng ngôn ngữ khác (C++ / Unreal / Unity) cho Game Engine: Tham khảo kỹ logic của Converter trong repo này, vì đó là phép màu giúp biến chuỗi Speckle JSON thành các lưới tam giác.