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

옵션 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 재질 파일을 내보낸 후 찾을 수 없습니다
scene.save('output.obj')를 통해 OBJ로 저장할 때, .mtl 재질 파일이 .obj 파일과 함께 자동으로 기록됩니다. 출력 디렉터리에 쓰기 권한이 있는지 확인하고 두 파일을 함께 보관하십시오.

Output .glb is smaller than expected / meshes are missing
로드된 씬에 엔터티가 없는 노드가 있는 경우(예: 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 출력의 경우, 텍스처 이미지 파일이 출력 파일과 같은 위치에 존재해야 합니다. 이는 상대 경로로 참조되기 때문입니다.

Type error: Argument of type ‘GltfSaveOptions’ is not assignable
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 및 이전 버전은 지원되지 않습니다.

참조

 한국어