Aspose.3D FOSS
TypeScript
Panduan Pengembang
Loading Models

Memuat Model 3D

@aspose/3d menyediakan dua metode pemuatan pada Scene kelas: open() untuk pemuatan berbasis jalur file dan openFromBuffer() untuk data dalam memori. Deteksi format otomatis dari nomor magis biner atau ekstensi file, sehingga Anda jarang perlu menentukan format sumber secara eksplisit.

Memuat dari Jalur File

Berikan string jalur file ke scene.open(). Perpustakaan mendeteksi format dari ekstensi file dan, untuk format biner, dari byte magis:

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

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

console.log(`Root children: ${scene.rootNode.childNodes.length}`);
console.log(`Animation clips: ${scene.animationClips.length}`);

open() mengganti semua konten scene yang ada. Jika Anda perlu memuat beberapa file, buatlah terpisah Scene instance.

Memuat OBJ dengan Material

File OBJ merujuk material melalui file sidecar .mtl file. Pemuatan material diaktifkan secara default (ObjLoadOptions.enableMaterials = true). Berikan ObjLoadOptions untuk mengontrol ini dan opsi waktu muat lainnya:

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

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;       // load the .mtl sidecar
options.flipCoordinateSystem = false; // keep original Y-up orientation
options.normalizeNormal = true;       // fix degenerate normals
options.scale = 1.0;                  // unit scale multiplier

scene.open('character.obj', options);

// Inspect materials on the first node
const first = scene.rootNode.childNodes[0];
if (first) {
    console.log(`Materials on ${first.name}: ${first.materials.length}`);
}

Memuat dari Buffer

Gunakan openFromBuffer() ketika data file sudah berada di memori, misalnya dari pengambilan HTTP, BLOB basis data, atau ekstraksi arsip zip. Ini menghindari penulisan ke disk:

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

const buffer: Buffer = fs.readFileSync('model.obj');
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;

scene.openFromBuffer(buffer, options);
console.log(`Loaded ${scene.rootNode.childNodes.length} root nodes`);

Untuk format biner (GLB, STL binary, 3MF), perpustakaan membaca byte magis dari buffer untuk mendeteksi format secara otomatis, sehingga Anda dapat memberikan undefined sebagai argumen options:

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

const glbBuffer: Buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(glbBuffer); // format auto-detected from GLB magic bytes

Memuat dari HTTP (Node.js 18+)

Ambil aset remote dan muat tanpa menyentuh sistem file:

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

async function loadFromUrl(url: string): Promise<Scene> {
    const response = await fetch(url);
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(arrayBuffer);

    const scene = new Scene();
    scene.openFromBuffer(buffer);
    return scene;
}

const scene = await loadFromUrl('https://example.com/model.glb');
console.log(`Loaded scene: ${scene.rootNode.childNodes.length} root nodes`);

Memeriksa Scene yang Dimuat

Setelah memuat, telusuri grafik scene untuk mendaftar node dan mengidentifikasi geometri:

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

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

function inspect(node: Node, depth: number = 0): void {
    const indent = '  '.repeat(depth);
    const entityType = node.entity ? node.entity.constructor.name : '(none)';
    console.log(`${indent}${node.name} [${entityType}]`);

    if (node.entity instanceof Mesh) {
        const mesh = node.entity as Mesh;
        console.log(`${indent}  vertices: ${mesh.controlPoints.length}, polygons: ${mesh.polygonCount}`);
    }

    for (const child of node.childNodes) {
        inspect(child, depth + 1);
    }
}

inspect(scene.rootNode);

Membaca Metadata Aset

The assetInfo properti mengekspos metadata tingkat file:

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

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

const info = scene.assetInfo;
if (info) {
    console.log(`Creator: ${info.creator}`);
    console.log(`Unit name: ${info.unitName}`);
    console.log(`Unit scale: ${info.unitScaleFactor}`);
}

Tidak semua format mengisi assetInfo. FBX dan COLLADA memiliki metadata yang kaya; OBJ dan STL biasanya tidak.

Referensi Opsi Muat Spesifik Format

FormatKelas OpsiJalur ImporOpsi Kunci
OBJObjLoadOptions@aspose/3d/formats/objenableMaterials, flipCoordinateSystem, scale, normalizeNormal
glTF / GLB(tidak diperlukan)N/ADeteksi otomatis; tidak memerlukan kelas opsi
STLStlLoadOptions@aspose/3d/formats/stl(tidak ada opsi yang dapat dikonfigurasi di versi saat ini)
FBXFbxLoadOptions@aspose/3d/formats/fbx(tidak ada opsi yang dapat dikonfigurasi di versi saat ini)
COLLADAColladaLoadOptions@aspose/3d/formats/collada(tidak ada opsi yang dapat dikonfigurasi di versi saat ini)
3MF(tidak diperlukan)N/ADeteksi otomatis

Kesalahan Muat Umum

GejalaPenyebabPerbaikan
Error: Cannot find module '@aspose/3d/formats/obj'moduleResolution tidak diatur ke nodeTambah "moduleResolution": "node" ke tsconfig.json
Daftar node kosong setelah memuat OBJ.mtl sidecar tidak ada atau enableMaterials tidak disetelSetel options.enableMaterials = true dan pastikan .mtl ada di direktori yang sama
Adegan dimuat tetapi rootNode.childNodes kosongFormat menggunakan satu mesh root, bukan node anakAkses scene.rootNode.entity langsung
openFromBuffer menimbulkan error dengan binary STLBuffer dipotong secara tidak tepat (byte akhir hilang)Gunakan seluruh readFileSync() output tanpa pemotongan
Array klip animasi kosong setelah memuat FBXFile FBX menggunakan baked transforms, bukan klipAnimasi dibakar per frame; array klip akan kosong

Lihat Juga

 Bahasa Indonesia