Tính năng và Chức năng

Aspose.3D FOSS for TypeScript là một thư viện Node.js có giấy phép MIT dành cho TypeScript, dùng để tải, xây dựng và xuất các cảnh 3D. Nó đi kèm với các định nghĩa kiểu TypeScript đầy đủ, một phụ thuộc runtime duy nhất (xmldom).

Cài đặt và Thiết lập

Cài đặt gói từ npm bằng một lệnh duy nhất:

npm install @aspose/3d

Gói này nhắm tới CommonJS và yêu cầu Node.js 18 trở lên. Sau khi cài đặt, hãy xác minh tsconfig.json bao gồm các tùy chọn biên dịch sau để tương thích đầy đủ:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true
  }
}

Import phần chính Scene class từ gốc gói. Các lớp tùy chọn riêng cho từng định dạng được nhập từ các đường dẫn phụ tương ứng:

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

Tính năng và Chức năng

Hỗ trợ Định dạng

Aspose.3D FOSS for TypeScript đọc và ghi sáu định dạng tệp 3D chính. Việc phát hiện định dạng được thực hiện tự động dựa trên các số ma thuật nhị phân khi tải, vì vậy bạn không cần chỉ định định dạng nguồn một cách rõ ràng.

Tải OBJ kèm vật liệu:

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
options.flipCoordinateSystem = false;
options.scale = 1.0;
options.normalizeNormal = true;
scene.open('model.obj', options);

Lưu dưới dạng GLB (binary glTF):

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
// ... build or load scene content

const opts = new GltfSaveOptions();
opts.binaryMode = true;
scene.save('output.glb', GltfFormat.getInstance(), opts);

Đồ thị Cảnh

Tất cả nội dung 3D được tổ chức dưới dạng cây của Node đối tượng có gốc tại scene.rootNode. Mỗi nút có thể mang một Entity (một Mesh, Camera, Light, hoặc các SceneObject) và một Transform định vị nó tương đối so với phần cha của nó.

Các lớp chính của đồ thị cảnh:

• Scene: bộ chứa cấp cao nhất; chứa rootNode và animationClips
• Node: một nút cây có tên với childNodes, entity, transform, và materials
• Entity: lớp cơ sở cho các đối tượng có thể gắn (Mesh, Camera, Light)
• SceneObject: lớp cơ sở được chia sẻ bởi Node và Entity
• A3DObject: lớp cơ sở gốc với name và túi thuộc tính
• Transform: dịch chuyển cục bộ, quay (Euler và Quaternion), và tỉ lệ

Duyệt đồ thị cảnh:

import { Scene, Node, Mesh } from '@aspose/3d';

const scene = new Scene();
scene.open('model.obj');

function visit(node: Node, depth: number = 0): void {
  const indent = '  '.repeat(depth);
  console.log(`${indent}Node: ${node.name}`);
  if (node.entity) {
    console.log(`${indent}  Entity: ${node.entity.constructor.name}`);
  }
  for (const child of node.childNodes) {
    visit(child, depth + 1);
  }
}

visit(scene.rootNode);

Tạo cây phân cấp cảnh một cách lập trình:

import { Scene, Node } from '@aspose/3d';

const scene = new Scene();
const parent = scene.rootNode.createChildNode('chassis');
const wheel = parent.createChildNode('wheel_fl');
wheel.transform.translation.set(0.9, -0.3, 1.4);

Hình học và Mesh

Mesh là kiểu hình học chính. Nó mở rộng Geometry và cung cấp các điểm điều khiển (đỉnh), chỉ số đa giác, và các phần tử đỉnh cho pháp tuyến, UV, và màu đỉnh.

Các lớp hình học chính:

• Mesh: lưới đa giác với controlPoints và polygonCount
• Geometry: lớp cơ sở với quản lý phần tử đỉnh
• VertexElementNormal: normals per-vertex hoặc per-polygon-vertex
• VertexElementUV: texture coordinates (một hoặc nhiều kênh UV)
• VertexElementVertexColor: dữ liệu màu per-vertex
• MappingMode: kiểm soát cách dữ liệu phần tử được ánh xạ tới các đa giác (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: kiểm soát chiến lược lập chỉ mục (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: xác định ngữ nghĩa của một phần tử đỉnh
• TextureMapping: liệt kê kênh texture

Đọc dữ liệu lưới từ một cảnh đã tải:

import { Scene, Mesh, VertexElementType } from '@aspose/3d';

const scene = new Scene();
scene.open('model.stl');

for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    const mesh = node.entity as Mesh;
    console.log(`Mesh "${node.name}": ${mesh.controlPoints.length} vertices, ${mesh.polygonCount} polygons`);

    const normals = mesh.getElement(VertexElementType.NORMAL);
    if (normals) {
      console.log(`  Normal mapping: ${normals.mappingMode}`);
    }
  }
}

Hệ thống Vật liệu

Aspose.3D FOSS cho TypeScript hỗ trợ ba loại vật liệu bao phủ toàn bộ phạm vi từ shading Phong cổ điển đến rendering dựa trên vật lý:

• LambertMaterial: màu khuếch tán và màu môi trường; ánh xạ tới các vật liệu OBJ/DAE đơn giản
• PhongMaterial: thêm màu phản chiếu, độ bóng, và phát sáng; loại vật liệu OBJ mặc định
• PbrMaterial: mô hình độ nhám/kim loại dựa trên vật lý; được sử dụng cho việc nhập và xuất glTF 2.0

Đọc vật liệu từ một cảnh OBJ đã tải:

import { Scene, PhongMaterial, LambertMaterial } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
scene.open('model.obj', options);

for (const node of scene.rootNode.childNodes) {
  for (const mat of node.materials) {
    if (mat instanceof PhongMaterial) {
      const phong = mat as PhongMaterial;
      console.log(`  Phong: diffuse=${JSON.stringify(phong.diffuseColor)}, shininess=${phong.shininess}`);
    } else if (mat instanceof LambertMaterial) {
      console.log(`  Lambert: diffuse=${JSON.stringify((mat as LambertMaterial).diffuseColor)}`);
    }
  }
}

Áp dụng vật liệu PBR khi xây dựng cảnh glTF:

import { Scene, Node, PbrMaterial } from '@aspose/3d';
import { Vector3 } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
const node = scene.rootNode.createChildNode('sphere');
const mat = new PbrMaterial();
mat.albedo = new Vector3(0.8, 0.2, 0.2);   // red-tinted albedo; albedo starts null, must assign
mat.metallicFactor = 0.0;
mat.roughnessFactor = 0.5;
node.material = mat;

const opts = new GltfSaveOptions();
opts.binaryMode = false;
scene.save('output.gltf', GltfFormat.getInstance(), opts);

Tiện ích Toán học

Thư viện đi kèm với một bộ đầy đủ các kiểu toán học 3D, tất cả đều được khai báo kiểu đầy đủ:

• Vector3: vector 3 thành phần; hỗ trợ minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: vector 4 thành phần cho tọa độ đồng nhất
• Matrix4: ma trận biến đổi 4×4 với concatenate(), transpose, decompose, setTRS
• Quaternion: quaternion quay với fromEulerAngle() (tĩnh, đơn), eulerAngles() (phương thức thể hiện), slerp(), normalize()
• BoundingBox: hộp bao trục căn trục với minimum, maximum, center, size, merge
• FVector3: biến thể độ chính xác đơn của Vector3 được sử dụng trong dữ liệu phần tử đỉnh

Tính hộp bao từ các đỉnh lưới:

import { Scene, Mesh, Vector3, BoundingBox } from '@aspose/3d';

const scene = new Scene();
scene.open('model.obj');

let box = new BoundingBox();
for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    for (const pt of (node.entity as Mesh).controlPoints) {
      box.merge(new Vector3(pt.x, pt.y, pt.z));
    }
  }
}
console.log('Center:', box.center);
console.log('Extents:', box.size);

Xây dựng phép biến đổi từ các góc Euler:

import { Quaternion, Vector3, Matrix4 } from '@aspose/3d';

const rot = Quaternion.fromEulerAngle(0, Math.PI / 4, 0); // 45° around Y
const mat = new Matrix4();
mat.setTRS(new Vector3(0, 0, 0), rot, new Vector3(1, 1, 1));

Hệ thống Hoạt hình

API hoạt hình mô hình hoá các clip, node, kênh và chuỗi keyframe:

• AnimationClip: bộ sưu tập có tên của các nút hoạt hình; truy cập qua scene.animationClips; công khai animations: AnimationNode[]
• AnimationNode: nhóm được đặt tên của BindPoints; được tạo qua clip.createAnimationNode(name), truy cập qua clip.animations
• BindPoint: gắn một AnimationNode : vào một thuộc tính cụ thể trên đối tượng cảnh; cho phép property : và channelsCount
• AnimationChannel: kế thừa KeyframeSequence; giữ một riêng biệt keyframeSequence; truy cập qua bindPoint.getChannel(name)
• KeyFrame: một cặp thời gian/giá trị duy nhất; mang theo mỗi khung chính interpolation: Interpolation
• KeyframeSequence: danh sách có thứ tự của KeyFrame đối tượng qua keyFrames; có preBehavior và postBehavior (Extrapolation)
• Interpolation: liệt kê: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: lớp với type: ExtrapolationType và repeatCount: number
• ExtrapolationType: liệt kê: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Đọc dữ liệu hoạt hình từ một cảnh đã tải:

import { Scene, AnimationNode, BindPoint } from '@aspose/3d';

const scene = new Scene();
scene.open('animated.dae');   // COLLADA animation import is supported

for (const clip of scene.animationClips) {
  console.log(`Clip: "${clip.name}"`);
  for (const animNode of clip.animations) {          // clip.animations, not clip.nodes
    console.log(`  AnimationNode: ${animNode.name}`);
    for (const bp of animNode.bindPoints) {           // animNode.bindPoints, not animNode.channels
      console.log(`  BindPoint: property="${bp.property.name}", channels=${bp.channelsCount}`);
    }
  }
}

Hỗ trợ Stream và Buffer

Sử dụng scene.openFromBuffer() để tải một cảnh 3D trực tiếp từ bộ nhớ trong Buffer. Đây là mẫu được khuyến nghị cho các hàm serverless, các pipeline streaming, và việc xử lý tài nguyên được lấy qua HTTP mà không ghi ra đĩa.

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import * as fs from 'fs';

// Load file into memory, then parse from buffer
const buffer: Buffer = fs.readFileSync('model.obj');
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
scene.openFromBuffer(buffer, options);

for (const node of scene.rootNode.childNodes) {
  if (node.entity) {
    console.log(node.name, node.entity.constructor.name);
  }
}

Việc tự động phát hiện định dạng dựa trên magic number nhị phân áp dụng khi tải từ buffer, vì vậy các tệp GLB, STL binary và 3MF được nhận dạng mà không cần chỉ định tham số định dạng.

Ví dụ Sử dụng

Ví dụ 1: Tải OBJ và Xuất ra GLB

Ví dụ này tải một tệp Wavefront OBJ có vật liệu, sau đó xuất lại cảnh dưới dạng tệp glTF nhị phân (GLB) phù hợp cho việc sử dụng trên web và các engine game.

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

function convertObjToGlb(inputPath: string, outputPath: string): void {
  const scene = new Scene();

  const loadOpts = new ObjLoadOptions();
  loadOpts.enableMaterials = true;
  loadOpts.flipCoordinateSystem = false;
  loadOpts.normalizeNormal = true;
  scene.open(inputPath, loadOpts);

  // Report what was loaded
  for (const node of scene.rootNode.childNodes) {
    if (node.entity) {
      console.log(`Loaded: ${node.name} (${node.entity.constructor.name})`);
    }
  }

  const saveOpts = new GltfSaveOptions();
  saveOpts.binaryMode = true; // write .glb instead of .gltf + .bin
  scene.save(outputPath, GltfFormat.getInstance(), saveOpts);

  console.log(`Exported GLB to: ${outputPath}`);
}

convertObjToGlb('input.obj', 'output.glb');

Ví dụ 2: Vòng quay STL với Kiểm tra Normal

Ví dụ này tải một tệp STL nhị phân, in thông tin normal cho mỗi đỉnh, sau đó xuất lại cảnh dưới dạng STL ASCII và xác minh quá trình vòng quay.

import { Scene, Mesh, VertexElementNormal, VertexElementType } from '@aspose/3d';
import { StlLoadOptions, StlSaveOptions } from '@aspose/3d/formats/stl';

const scene = new Scene();
const loadOpts = new StlLoadOptions();
scene.open('model.stl', loadOpts);

let totalPolygons = 0;
for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    const mesh = node.entity as Mesh;
    totalPolygons += mesh.polygonCount;

    const normElem = mesh.getElement(VertexElementType.NORMAL) as VertexElementNormal | null;
    if (normElem) {
      console.log(`  Normals: ${normElem.data.length} entries, mapping=${normElem.mappingMode}`);
    }
  }
}
console.log(`Total polygons: ${totalPolygons}`);

// Re-export as ASCII STL
const saveOpts = new StlSaveOptions();
saveOpts.binaryMode = false; // ASCII output
scene.save('output_ascii.stl', saveOpts);

Ví dụ 3: Xây dựng một Cảnh bằng cách lập trình và Lưu dưới dạng glTF

Ví dụ này tạo một cảnh với vật liệu PBR từ đầu và lưu nó dưới dạng tệp JSON glTF.

import { Scene, Mesh, PbrMaterial, Vector4, Vector3 } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
const node = scene.rootNode.createChildNode('floor');

// Build a simple quad mesh (two triangles)
// controlPoints are Vector4 (x, y, z, w) where w=1 for positions
const mesh = new Mesh();
mesh.controlPoints.push(
  new Vector4(-1, 0, -1, 1),
  new Vector4( 1, 0, -1, 1),
  new Vector4( 1, 0,  1, 1),
  new Vector4(-1, 0,  1, 1),
);
mesh.createPolygon([0, 1, 2]);
mesh.createPolygon([0, 2, 3]);
node.entity = mesh;

// Apply a PBR material
const mat = new PbrMaterial();
mat.albedo = new Vector3(0.6, 0.6, 0.6);   // albedo starts null, must assign
mat.metallicFactor = 0.0;
mat.roughnessFactor = 0.8;
node.material = mat;

// Save as JSON glTF
const opts = new GltfSaveOptions();
opts.binaryMode = false;
scene.save('floor.gltf', GltfFormat.getInstance(), opts);
console.log('Scene written to floor.gltf');

Mẹo và Thực hành Tốt nhất

• Sử dụng ObjLoadOptions.enableMaterials = true bất cứ khi nào bạn cần dữ liệu vật liệu từ các tệp .mtl. Nếu không, danh sách vật liệu trên mỗi nút sẽ trống.
• Ưu tiên binaryMode = true cho GLB khi tạo tài sản cho web hoặc các engine game. GLB nhị phân là một tệp duy nhất tự chứa và tải nhanh hơn trong trình duyệt và engine so với việc tách JSON + .bin.
• Sử dụng openFromBuffer() trong môi trường không máy chủ để tránh I/O tệp tạm thời. Lấy tài sản, truyền Buffer trực tiếp, và ghi đầu ra vào một luồng hoặc bộ đệm khác.
• Kiểm tra node.entity trước khi ép kiểu: không phải mọi nút đều mang một thực thể. Luôn bảo vệ bằng một instanceof kiểm tra trước khi truy cập Meshcác thuộc tính đặc thù như controlPoints.
• Đặt normalizeNormal = true trong ObjLoadOptions khi các tệp OBJ nguồn của bạn đến từ nguồn không đáng tin cậy. Điều này ngăn các vector pháp tuyến suy giảm lan truyền vào các bước render hoặc xác thực tiếp theo.
• Giữ strict: true trong tsconfig.json: thư viện được viết bằng noImplicitAny và strictNullChecks. Vô hiệu hoá strict che giấu các lỗi kiểu thực và làm mất giá trị của typed API.
• Duyệt qua childNodes, không phải vòng lặp chỉ mục: cái childNodes thuộc tính trả về một iterable; tránh dựa vào chỉ mục số để đảm bảo khả năng tương thích về phía trước.

Các vấn đề thường gặp

Câu hỏi thường gặp

Thư viện có yêu cầu bất kỳ addon gốc nào hoặc gói hệ thống không? Không. Aspose.3D FOSS cho TypeScript có một phụ thuộc thời gian chạy duy nhất: xmldom, đây là JavaScript thuần và được cài đặt tự động bởi npm. Không có .node addon gốc và không có gói hệ thống nào cần cài đặt.

Phiên bản Node.js nào được hỗ trợ? Node.js 18, 20 và 22 LTS. Thư viện nhắm mục tiêu đầu ra CommonJS và sử dụng các tính năng ngôn ngữ ES2020 nội bộ.

Tôi có thể sử dụng thư viện trong một bundle trình duyệt (webpack/esbuild) không? Thư viện nhắm mục tiêu Node.js và sử dụng Node.js fs và Buffer APIs. Việc đóng gói cho trình duyệt không được hỗ trợ chính thức. Đối với việc sử dụng trên trình duyệt, hãy tải cảnh phía máy chủ và truyền kết quả (ví dụ, dưới dạng GLB) tới client.

Sự khác biệt giữa GltfSaveOptions.binaryMode = true và false? binaryMode = false tạo ra một .gltf tệp JSON cộng với một .bin tệp phụ bộ đệm nhị phân. binaryMode = true tạo ra một tệp duy nhất tự chứa .glb tệp. Sử dụng true để phân phối tài sản trong môi trường sản xuất.

Tôi có thể tải một tệp từ phản hồi HTTP mà không lưu vào đĩa không? Có. Lấy phản hồi dưới dạng một Buffer (ví dụ, sử dụng node-fetch hoặc tích hợp sẵn fetch trong Node 18+), sau đó gọi scene.openFromBuffer(buffer, options).

Hỗ trợ FBX có đầy đủ không? Không. Các lớp nhập và xuất FBX tồn tại trong thư viện, nhưng FBX chưa được tích hợp vào Scene.open() hoặc Scene.save() tự động phát hiện. Gọi scene.open('file.fbx') sẽ không kích hoạt trình nhập FBX; tệp sẽ được xử lý bằng đường dẫn dự phòng STL. Sử dụng trực tiếp các lớp nhập/xuất chuyên dụng cho FBX nếu bạn cần I/O FBX. Xem bảng hỗ trợ định dạng ở trên, trong đó đánh dấu FBX là No*.

Thư viện có hỗ trợ TypeScript 4.x không? TypeScript 5.0+ được khuyến nghị. TypeScript 4.7+ nên hoạt động trong thực tế, nhưng thư viện đã được kiểm tra và phát triển dựa trên 5.0+.

Tóm tắt Tham chiếu API