Ciri-ciri dan Fungsi

Aspose.3D FOSS untuk TypeScript ialah perpustakaan Node.js berlesen MIT untuk memuat, membina, dan mengeksport adegan 3D. Ia disertakan dengan definisi jenis TypeScript yang lengkap, satu kebergantungan masa jalan (xmldom), dan sokongan untuk enam format fail 3D utama. Halaman ini merupakan rujukan utama bagi semua kawasan ciri dan termasuk contoh kod TypeScript yang boleh dijalankan untuk setiap satu.

Pemasangan dan Persediaan

Pasang pakej dari npm menggunakan satu arahan:

npm install @aspose/3d

Pakej ini menyasarkan CommonJS dan memerlukan Node.js 18 atau lebih baru. Selepas pemasangan, sahkan bahawa anda tsconfig.json menyertakan pilihan penyusun berikut untuk keserasian penuh:

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

Import kelas utama Scene dari akar pakej. Kelas pilihan khusus format diimport dari sub‑laluan masing‑masing:

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

Ciri-ciri dan Fungsi

Sokongan Format

Aspose.3D FOSS untuk TypeScript membaca dan menulis tujuh format fail 3D utama. Pengesanan format adalah automatik semasa memuatkan: perpustakaan memeriksa nombor sihir binari supaya anda tidak perlu menentukan format sumber. Kelas pilihan khusus format diimport dari sub-laluan pakej @aspose/3d.

Memuat OBJ dengan bahan:

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);

Menyimpan ke 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);

Graf Adegan

Semua kandungan 3D disusun sebagai pokok Node objek yang berakar pada scene.rootNode. Setiap nod boleh membawa satu Entity (sebuah Mesh, Camera, Light, atau lain SceneObject) dan satu Transform yang menempatkannya relatif kepada induknya.

Kelas utama graf‑skena:

• Scene: bekas peringkat atas; menyimpan rootNode dan animationClips
• Node: nod pokok bernama dengan childNodes, entity, transform, dan materials
• Entity: kelas asas untuk objek yang boleh dilampirkan (Mesh, Camera, Light)
• SceneObject: kelas asas yang dikongsi oleh Node dan Entity
• A3DObject: kelas asas akar dengan name dan beg sifat
• Transform: terjemahan setempat, putaran (Euler dan Quaternion), dan skala

Graf Adegan: membina dan menelusuri pokok nod.:

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);

Mencipta hierarki skena secara program:

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);

Geometri dan Mesh

Mesh adalah jenis geometri utama. Ia meluaskan Geometry dan mendedahkan titik kawalan (verteks), indeks poligon, serta elemen verteks untuk normal, UV, dan warna verteks.

Kelas geometri utama:

• Mesh:jaring poligon dengan controlPoints dan polygonCount
• Geometry: kelas asas dengan pengurusan elemen-verteks
• VertexElementNormal: normal per-verteks atau per-verteks-poligon
• VertexElementUV: koordinat tekstur (satu atau lebih saluran UV)
• VertexElementVertexColor: data warna per-verteks
• MappingMode: mengawal bagaimana data elemen dipetakan ke poligon (ByControlPoint, ByPolygonVertex, dll.)
• ReferenceMode:mengawal strategi pengindeksan (Direct, IndexToDirect)
• VertexElementType:mengenal pasti semantik elemen verteks
• TextureMapping:enumerasi saluran tekstur

Membaca data mesh daripada adegan yang dimuatkan:

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}`);
    }
  }
}

Sistem Bahan

Aspose.3D FOSS untuk TypeScript menyokong tiga jenis bahan yang merangkumi seluruh spektrum dari shading Phong warisan hingga rendering berasaskan fizikal:

• LambertMaterial:warna difus dan warna ambien; dipetakan kepada bahan OBJ/DAE ringkas
• PhongMaterial:menambah warna spekular, kilau, dan emisif; jenis bahan OBJ lalai
• PbrMaterial:model kasar/logam berasaskan-fizik; digunakan untuk import dan eksport glTF 2.0

Membaca bahan dari adegan OBJ yang dimuatkan:

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)}`);
    }
  }
}

Menerapkan bahan PBR semasa membina adegan glTF:

import { Scene, Node, PbrMaterial } 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);   // 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);

Utiliti Matematik

Pustaka ini disertakan dengan set lengkap jenis matematik 3D, semuanya berjenis penuh:

• Vector3:vektor 3-komponen; menyokong add, subtract, scale, dot, cross, normalize, length
• Vector4:vektor 4-komponen untuk koordinat homogen
• Matrix4:matriks transformasi 4×4 dengan multiply, invert, transpose, decompose
• Quaternion:kuaternion putaran dengan fromEulerAngles, toEulerAngles, slerp, normalize
• BoundingBox:kotak sempadan selari paksi dengan min, max, center, size, merge
• FVector3:varian tepat-tunggal bagi Vector3 digunakan dalam data elemen verteks

Mengira kotak sempadan daripada verteks mesh:

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);

Membina transformasi daripada sudut 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));

Sistem Animasi

API animasi memodelkan klip, nod, saluran, dan urutan bingkai kunci:

• AnimationClip:koleksi bernama nod animasi; diakses melalui scene.animationClips
• AnimationNode:mengikat klip kepada nod adegan mengikut nama
• AnimationChannel: menyasar sifat khusus (contohnya, translation X) dalam nod animasi
• KeyFrame: sepasang masa/nilai tunggal
• KeyframeSequence: senarai teratur KeyFrame : objek dengan Interpolation dan Extrapolation tetapan
• Interpolation: mod interpolasi bingkai kunci: Linear, Constant, Cubic
• Extrapolation: kelakuan sebelum/selepas julat bingkai kunci: Constant, Cycle, Mirror

Membaca data animasi daripada adegan yang dimuatkan:

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

const scene = new Scene();
scene.open('animated.fbx');

for (const clip of scene.animationClips) {
  console.log(`Clip: "${clip.name}"`);
  for (const animNode of clip.nodes) {
    console.log(`  Node: ${animNode.name}`);
    for (const channel of animNode.channels) {
      const seq: KeyframeSequence = channel.keyframeSequence;
      console.log(`    Channel "${channel.name}": ${seq.keyFrames.length} keyframes`);
      console.log(`    Interpolation: ${seq.interpolation}`);
    }
  }
}

Sokongan Aliran dan Penimbal

Gunakan scene.openFromBuffer() untuk memuatkan adegan 3D secara langsung dari memori dalam Buffer. Ini adalah corak yang disyorkan untuk fungsi tanpa pelayan, paip penstriman, dan pemprosesan aset yang diambil melalui HTTP tanpa menulis ke cakera.

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);
  }
}

Pengesanan automatik format daripada nombor sihir binari berkuat kuasa semasa memuatkan daripada penimbal, jadi fail GLB, STL binari, dan 3MF dikenali tanpa perlu menyatakan parameter format.

Contoh Penggunaan

Contoh 1: Muat OBJ dan Eksport ke GLB

Contoh ini memuatkan fail Wavefront OBJ dengan bahan, kemudian mengeksport semula adegan sebagai fail glTF binari (GLB) yang sesuai untuk penggunaan web dan enjin permainan.

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');

Contoh 2: Pusingan Balik STL dengan Pengesahan Normal

Contoh ini memuatkan fail STL binari, mencetak maklumat normal per-vertex, kemudian mengeksport semula adegan sebagai STL ASCII dan mengesahkan pusingan balik.

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);

Contoh 3: Bina Adegan Secara Programatik dan Simpan sebagai glTF

Contoh ini membina sebuah adegan dengan bahan PBR dari awal dan menyimpannya sebagai fail JSON glTF.

import { Scene, Mesh, PbrMaterial, Vector4 } 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');

Petua dan Amalan Terbaik

• Gunakan ObjLoadOptions.enableMaterials = true bila-bila anda memerlukan data bahan daripada fail .mtl. Tanpa ia, senarai bahan pada setiap nod akan kosong.
• Utamakan binaryMode = true untuk GLB ketika menghasilkan aset untuk web atau enjin permainan. GLB binari ialah satu fail berdiri sendiri dan dimuatkan lebih cepat dalam pelayar dan enjin berbanding pecahan JSON + .bin.
• Gunakan openFromBuffer() dalam persekitaran tanpa pelayan untuk mengelakkan I/O fail sementara. Dapatkan aset, serahkan Buffer secara langsung, dan tulis output ke aliran atau penampan lain.
• Semak node.entity sebelum menukar jenis: tidak semua nod membawa entiti. Sentiasa lindungi dengan instanceof semak sebelum mengakses Mesh-sifat khusus seperti controlPoints.
• Tetapkan normalizeNormal = true dalam ObjLoadOptions apabila fail OBJ sumber anda datang daripada sumber yang tidak dipercayai. Ini menghalang normal yang cacat daripada tersebar ke langkah rendering atau pengesahan seterusnya.
• Kekalkan strict: true dalam tsconfig.json: perpustakaan ini ditulis dengan noImplicitAny dan strictNullChecks. Menyahaktifkan strict menyembunyikan ralat jenis sebenar dan menjejaskan nilai API berjenis.
• Lalui melalui childNodes, bukan gelung indeks: yang childNodes sifat mengembalikan iterable; elakkan bergantung pada pengindeksan berangka untuk keserasian ke hadapan.

Isu Umum

Soalan Lazim

Adakah perpustakaan memerlukan sebarang add‑on asli atau pakej sistem? Tidak. Aspose.3D FOSS untuk TypeScript mempunyai satu kebergantungan masa jalan: xmldom, yang merupakan JavaScript tulen dan dipasang secara automatik oleh npm. Tiada .node add‑on asli dan tiada pakej sistem untuk dipasang.

Versi Node.js mana yang disokong? Node.js 18, 20, dan 22 LTS. Perpustakaan menyasarkan output CommonJS dan menggunakan ciri bahasa ES2020 secara dalaman.

Bolehkah saya menggunakan perpustakaan dalam bundle pelayar (webpack/esbuild)? Perpustakaan menyasarkan Node.js dan menggunakan Node.js fs dan Buffer API. Pembungkusan pelayar tidak disokong secara rasmi. Untuk penggunaan pelayar, muatkan adegan di sisi pelayan dan hantar hasilnya (contoh, sebagai GLB) kepada klien.

Apakah perbezaan antara GltfSaveOptions.binaryMode = true dan false? binaryMode = false menghasilkan satu .gltf fail JSON plus satu .bin penyerta penimbal binari. binaryMode = true menghasilkan satu fail tunggal yang berdiri sendiri .glb fail. Gunakan true untuk penghantaran aset produksi.

Bolehkah saya memuatkan fail daripada respons HTTP tanpa menyimpannya ke cakera? Ya. Dapatkan respons sebagai Buffer (contohnya, menggunakan node-fetch atau yang terbina dalam fetch dalam Node 18+), kemudian panggil scene.openFromBuffer(buffer, options).

Adakah sokongan FBX lengkap? Pembacaan dan penulisan FBX disokong untuk hierarki adegan, data mesh dan geometri, klip animasi, dan bahan. Fail FBX yang sangat kompleks dengan media terbenam mungkin menghasilkan keputusan separa; ujilah dengan korpus aset khusus anda.

Adakah perpustakaan ini menyokong TypeScript 4.x? TypeScript 5.0+ disarankan. TypeScript 4.7+ sepatutnya berfungsi dalam amalan, tetapi perpustakaan ini diuji dan ditulis berbanding 5.0+.

Ringkasan Rujukan API