Aspose.3D FOSS
TypeScript
개발자 가이드
Loading Models

3D 모델 로드

@aspose/3d 에 두 가지 로딩 방법을 제공합니다 Scene 클래스: open() 파일 경로 로딩용 및 openFromBuffer() 메모리 내 데이터용. 포맷 감지는 바이너리 매직 넘버 또는 파일 확장자를 통해 자동으로 이루어지므로, 소스 포맷을 명시적으로 지정할 필요가 거의 없습니다.

파일 경로에서 로드하기

파일 경로 문자열을 전달하세요 scene.open(). 라이브러리는 파일 확장자에서 포맷을 감지하고, 바이너리 포맷의 경우 매직 바이트에서 감지합니다:

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() 기존 씬 내용을 모두 교체합니다. 여러 파일을 로드해야 하는 경우, 별도의 Scene 인스턴스를 생성하세요.

재질이 포함된 OBJ 로드

OBJ 파일은 사이드카 .mtl 파일을 사용합니다. 재질 로딩은 기본적으로 활성화됩니다 (ObjLoadOptions.enableMaterials = true). 전달하세요 ObjLoadOptions 이를 및 기타 로드 시 옵션을 제어하려면:

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

버퍼에서 로드하기

사용하세요 openFromBuffer() 파일 데이터가 이미 메모리에 있는 경우, 예를 들어 HTTP fetch, 데이터베이스 BLOB, 또는 zip 아카이브 추출에서 가져온 경우에 사용합니다. 이렇게 하면 디스크에 쓰는 것을 피할 수 있습니다:

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

바이너리 포맷(GLB, STL binary, 3MF)의 경우, 라이브러리는 버퍼에서 매직 바이트를 읽어 포맷을 자동으로 감지하므로, 전달할 수 있습니다 undefined 옵션 인수로:

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

HTTP에서 로드하기 (Node.js 18+)

원격 에셋을 가져와 파일 시스템에 접근하지 않고 로드합니다:

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

로드된 씬 검사하기

로드 후, 씬 그래프를 순회하여 노드를 열거하고 지오메트리를 식별합니다:

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

에셋 메타데이터 읽기

그 assetInfo 속성은 파일 수준 메타데이터를 노출합니다:

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

모든 포맷이 채워지는 것은 아닙니다 assetInfo. FBX와 COLLADA는 풍부한 메타데이터를 가지고 있습니다; OBJ와 STL은 일반적으로 그렇지 않습니다.

포맷별 로드 옵션 참조

포맷옵션 클래스가져오기 경로핵심 옵션
OBJObjLoadOptions@aspose/3d/formats/objenableMaterials, flipCoordinateSystem, scale, normalizeNormal
glTF / GLB(필요 없음)N/A자동 감지; 옵션 클래스가 필요하지 않음
STLStlLoadOptions@aspose/3d/formats/stl(현재 버전에서는 구성 가능한 옵션이 없습니다)
FBXFbxLoadOptions@aspose/3d/formats/fbx(현재 버전에서는 구성 가능한 옵션이 없습니다)
COLLADAColladaLoadOptions@aspose/3d/formats/collada(현재 버전에서는 구성 가능한 옵션이 없습니다)
3MF(필요 없음)N/A자동 감지

일반적인 로드 오류

증상원인수정
Error: Cannot find module '@aspose/3d/formats/obj'moduleResolution 다음으로 설정되지 않음 node추가 "moduleResolution": "node" 에 tsconfig.json
OBJ 로드 후 노드 목록이 비어 있음.mtl 사이드카가 없거나 enableMaterials 설정되지 않음설정 options.enableMaterials = true 그리고 확인 .mtl 같은 디렉터리에 있음
씬이 로드되지만 rootNode.childNodes 비어 있음포맷은 단일 루트 메시를 사용하며, 자식 노드를 사용하지 않음접근 scene.rootNode.entity 직접
openFromBuffer binary STL에서 예외 발생버퍼가 잘못 슬라이스되었습니다 (뒤쪽 바이트 누락)전체 사용 readFileSync() 슬라이스하지 않은 출력
FBX 로드 후 애니메이션 클립 배열이 비어 있습니다FBX 파일은 클립이 아닌 베이크된 변환을 사용합니다애니메이션이 프레임별로 베이크됩니다; 클립 배열은 비게 됩니다

또 보기

 한국어