Aspose.3D FOSS
TypeScript
TypeScript에서 3D 씬을 glTF/GLB로 내보내는 방법

TypeScript에서 3D 씬을 glTF/GLB로 내보내는 방법

Aspose.3D FOSS는 glTF 2.0을 가져오기 및 내보내기 형식으로 지원합니다. 동일한 Scene 객체는 OBJ, FBX, STL 또는 다른 소스 파일에서 채워진 다음 .gltf(JSON + 외부 바이너리) 또는 .glb(단일 바이너리 컨테이너)로, GltfSaveOptions에 하나의 플래그를 설정하여 기록할 수 있습니다.

단계별 가이드

1단계: @aspose/3d 설치 

npm install @aspose/3d

Node.js 18 이상이 활성화되어 있는지 확인하십시오:

node --version   # must be >= 16.0.0

2단계: Scene, GltfSaveOptions 및 GltfFormat 가져오기 

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

GltfFormat은 scene.save()에 전달되는 포맷 설명자입니다. GltfSaveOptions은 모든 내보내기 구성을 포함합니다.

소스 파일(예: OBJ)을 로드하는 경우, 해당 로드 옵션을 가져오세요:

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

3단계: 장면 만들기 또는 로드

옵션 A: 기존 파일 로드 (OBJ → GLB 변환):

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

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

Option B: 최소 장면을 프로그래밍 방식으로 구축:

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

const scene = new Scene();
const childNode = new Node('cube');
scene.rootNode.addChildNode(childNode);
// Attach geometry to childNode as needed

4단계: GltfSaveOptions 구성

GltfSaveOptions는 출력 형식 및 인코딩 세부 정보를 제어합니다.

const saveOpts = new GltfSaveOptions();

// Set to true for a single binary .glb file
// Set to false (default) for JSON .gltf + separate .bin
saveOpts.binaryMode = true;

설정할 수 있는 추가 옵션:

속성유형기본값효과
binaryModebooleanfalsetrue → GLB, false → glTF JSON
flipTexCoordVbooleantrue엔진 호환성을 위해 UV 수직 축을 뒤집음

Step 5: scene.save()를 사용하여 저장

출력 경로와 GltfFormat 디스크립터 및 구성된 옵션을 전달하십시오:

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

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

const saveOpts = new GltfSaveOptions();
saveOpts.binaryMode = true;   // produce .glb

scene.save('output.glb', GltfFormat.getInstance(), saveOpts);
console.log('Converted to GLB successfully');

대신 JSON .gltf 파일을 생성하려면:

saveOpts.binaryMode = false;
scene.save('output.gltf', GltfFormat.getInstance(), saveOpts);
console.log('Exported to glTF JSON successfully');

단계 6: 출력 파일 확인

출력 파일이 존재하고 크기가 0이 아닌지 확인하십시오:

import * as fs from 'fs';

const outputPath = 'output.glb';
const stats = fs.statSync(outputPath);
console.log(`Output file size: ${stats.size} bytes`);

if (stats.size === 0) {
    throw new Error('Export produced an empty file: check scene content');
}

라운드 트립 검증을 위해 GLB를 다시 로드하고 노드 수를 확인하십시오:

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

const verify = new Scene();
verify.open('output.glb', new GltfLoadOptions());

let nodeCount = 0;
function countNodes(node: any): void {
    nodeCount++;
    for (const child of node.childNodes) countNodes(child);
}
countNodes(verify.rootNode);

console.log(`Round-trip verification: ${nodeCount} node(s) in output`);

일반적인 문제 및 해결 방법

OBJ material file not found after export
scene.save('output.obj')를 사용하여 OBJ로 저장할 때, .mtl 소재 파일이 .obj 파일과 함께 자동으로 기록됩니다. 출력 디렉터리에 쓰기 권한이 있는지 확인하고 두 파일을 함께 보관하십시오.

출력 .glb 파일이 예상보다 작음 / 메쉬가 누락됨
로드된 씬에 엔터티가 없는 노드(예: OBJ에서 빈 그룹)가 있는 경우, GLB에는 해당 노드의 기하학이 포함되지 않습니다. 저장하기 전에 mesh.controlPoints.length > 0를 사용하여 입력 파일에 실제 폴리곤 데이터가 있는지 확인하십시오.

모듈 ‘@aspose/3d/formats/gltf’을(를) 찾을 수 없습니다
Node.js 18+를 사용하고 있으며 @aspose/3d이(가) 진입점과 동일한 node_modules에 설치되어 있는지 확인하십시오. npm ls @aspose/3d을 실행하여 버전이 24.12.0 이상인지 확인하십시오.

GltfFormat.getInstance()가 undefined를 반환합니다
이는 메인 @aspose/3d 패키지와 캐시된 이전 버전 사이에 버전 불일치가 있음을 나타냅니다. node_modules와 package-lock.json을 삭제한 다음, npm install를 다시 실행하십시오.

출력 GLB에 텍스처가 누락되었습니다 binaryMode = true가 자체 포함된 GLB를 생성하도록 설정되어 있는지 확인하십시오. glTF JSON 출력의 경우, 텍스처 이미지 파일이 출력 파일과 같은 위치에 존재해야 합니다. 이는 상대 경로로 참조되기 때문입니다.

형식 오류: ‘GltfSaveOptions’ 유형의 인수를 할당할 수 없습니다
Scene와 GltfSaveOptions가 동일한 설치된 패키지 인스턴스에서 가져와졌는지 확인하십시오. 전역 및 로컬 설치가 혼합되면 인터페이스 불일치가 발생할 수 있습니다.

자주 묻는 질문 (FAQ)

glTF와 GLB의 차이점은 무엇인가요?
glTF 2.0 JSON (.gltf)은 장면 그래프를 인간이 읽을 수 있는 JSON 파일로 저장하고, 별도의 .bin 버퍼와 이미지 파일을 사용합니다. GLB (.glb)는 모든 것을 단일 바이너리 컨테이너에 패키징합니다. GLB의 경우 binaryMode = true를, JSON glTF의 경우 false를 설정하십시오.

코드만으로 완전히 구축된 씬을 내보낼 수 있나요 (소스 파일 없음)?
예. Scene을 생성하고, Node 객체를 추가하고, Mesh 또는 다른 엔터티를 연결한 다음 scene.save()를 호출합니다. 씬은 로드된 파일에서 시작될 필요가 없습니다.

glTF 내보내기가 무손실인가요? 기하학과 변환에 대해서는 예. 가능한 경우 재질은 glTF PBR 재질 속성에 매핑됩니다. 독점적인 FBX 재질 확장은 완벽하게 라운드트립되지 않을 수 있습니다.

STL 또는 3MF로 대신 내보낼 수 있나요? 예. 패턴은 동일합니다; 해당 형식의 *SaveOptions 및 *Format.getInstance()을 가져오세요:

import { StlSaveOptions, StlFormat } from '@aspose/3d/formats/stl';
const opts = new StlSaveOptions();
scene.save('output.stl', StlFormat.getInstance(), opts);

scene.save()는 비동기적으로 실행되나요?
아니요. scene.save()는 동기식입니다. 대규모 내보내기 중에 이벤트 루프가 차단되는 것을 방지하려면 워커 스레드에 래핑하십시오.

지원되는 Node.js 버전은 무엇인가요? Node.js 18, 20, 및 22+. Node.js 16 및 이전 버전은 지원되지 않습니다.

관련 항목

 한국어