TypeScript'te 3D Sahneleri glTF/GLB Olarak Dışa Aktarma

Aspose.3D FOSS, glTF 2.0’ı hem içe aktarma hem de dışa aktarma formatı olarak destekler. Aynı Scene nesnesi bir OBJ, FBX, STL veya başka bir kaynak dosyadan doldurulabilir ve ardından .gltf (JSON + harici ikili) veya .glb (tek ikili kapsayıcı) olarak, GltfSaveOptions üzerinde bir bayrak ayarlanarak yazılabilir.

Adım Adım Kılavuz

Adım 1: @aspose/3d’yi kurun

npm install @aspose/3d

Node.js 18 veya daha yeni bir sürümün etkin olduğundan emin olun:

node --version   # must be >= 16.0.0

Adım 2: Scene, GltfSaveOptions ve GltfFormat’ı içe aktar

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

GltfFormat, scene.save()‘e geçirilen format tanımlayıcısıdır. GltfSaveOptions tüm dışa aktarma yapılandırmasını taşır.

Ayrıca bir kaynak dosyası (ör. OBJ) yüklüyorsanız, eşleşen yükleme seçeneklerini içe aktarın:

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

Adım 3: Bir sahne oluşturun veya yükleyin

Seçenek A: Mevcut bir dosyadan yükle (OBJ → GLB dönüşümü):

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

Seçenek B: Minimum bir sahneyi programlı olarak oluşturun:

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

Adım 4: GltfSaveOptions’ı yapılandır

GltfSaveOptions çıktı formatını ve kodlama ayrıntılarını kontrol eder.

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;

Ayarlayabileceğiniz ek seçenekler:

Özellik	Tür	Varsayılan	Etki
`binaryMode`	`boolean`	`false`	`true` → GLB, `false` → glTF JSON
`flipTexCoordV`	`boolean`	`true`	Motor uyumluluğu için UV dikey eksenini ters çevir

Adım 5: scene.save() kullanarak kaydedin

Çıktı yolunu, GltfFormat tanımlayıcısını ve yapılandırılmış seçenekleri iletin:

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

Bunun yerine bir JSON .gltf dosyası üretmek için:

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

Adım 6: Çıktı dosyasını doğrula

Çıktı dosyasının mevcut olduğunu ve sıfırdan farklı bir boyuta sahip olduğunu kontrol edin:

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

Yuvarlak dönüş doğrulaması için, GLB’yi yeniden yükleyin ve düğüm sayısını inceleyin:

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

Yaygın Sorunlar ve Çözümler

OBJ material file not found after export OBJ’ye scene.save('output.obj') aracılığıyla kaydederken, .mtl malzeme dosyası otomatik olarak .obj dosyasının yanına yazılır. Çıktı dizininin yazılabilir olduğundan ve her iki dosyanın da birlikte tutulduğundan emin olun.

Çıktı .glb beklenenden daha küçük / mesh’ler eksik
Yüklenen sahnede varlıkları olmayan düğümler varsa (ör. bir OBJ’den boş gruplar), GLB bu düğümlerin geometrisini içermeyecektir. Kaydetmeden önce giriş dosyanızın gerçek çokgen verisine sahip olduğunu mesh.controlPoints.length > 0 kullanarak doğrulayın.

Modül ‘@aspose/3d/formats/gltf’ bulunamıyor
Node.js 18+ sürümünü kullandığınızdan ve @aspose/3d‘in giriş noktanızla aynı node_modules içinde kurulu olduğundan emin olun. npm ls @aspose/3d‘i çalıştırarak sürümün 24.12.0 veya daha yeni olduğunu doğrulayın.

GltfFormat.getInstance() undefined döndürür
Bu, ana @aspose/3d paket ile önbelleğe alınmış eski bir sürüm arasındaki sürüm uyumsuzluğunu gösterir. node_modules ve package-lock.json‘i silin, ardından npm install‘yi tekrar çalıştırın.

Çıktı GLB’sinde dokular eksik
binaryMode = true‘nin kendinden bağımsız bir GLB üretmek üzere ayarlandığından emin olun. glTF JSON çıktısı için, doku görüntü dosyalarının çıktı dosyasının yanında bulunması gerekir, çünkü bunlar göreceli yol ile referans alınır.

Tip hatası: ‘GltfSaveOptions’ türündeki argüman atanamıyor
Scene ve GltfSaveOptions öğelerinin aynı kurulu paket örneğinden içe aktarıldığından emin olun. Karışık kurulumlar (global + yerel) arayüz uyuşmazlıklarına neden olabilir.

Sıkça Sorulan Sorular (SSS)

glTF ve GLB arasındaki fark nedir? glTF 2.0 JSON (.gltf) sahne grafiğini ayrı .bin tamponları ve görüntü dosyalarıyla insan tarafından okunabilir bir JSON dosyası olarak depolar. GLB (.glb) her şeyi tek bir ikili konteynıra paketler. GLB için binaryMode = true, JSON glTF için false ayarlayın.

Kodla tamamen oluşturulmuş bir sahneyi (kaynak dosyası olmadan) dışa aktarabilir miyim?
Evet. Bir Scene oluşturun, Node nesneleri ekleyin, Mesh veya diğer varlıkları ekleyin, ardından scene.save() çağırın. Sahne, yüklü bir dosyadan gelmek zorunda değildir.

glTF dışa aktarımı kayıpsız mı? Geometri ve dönüşümler için evet. Malzemeler mümkün olduğunca glTF PBR malzeme özelliklerine eşlenir. Sahipli FBX malzeme uzantıları mükemmel bir şekilde geri dönüşüm sağlamayabilir.

STL veya 3MF’ye dışa aktarabilir miyim? Evet. Desen aynı; ilgili formatın *SaveOptions ve *Format.getInstance() öğelerini içe aktarın:

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

scene.save() asenkron çalışıyor mu?
Hayır. scene.save() eşzamanlıdır. Büyük dışa aktarımlarda olay döngüsünü engellemekten kaçınmak istiyorsanız bir işçi iş parçacığında sarın.

Hangi Node.js sürümleri destekleniyor? Node.js 18, 20 ve 22+. Node.js 16 ve öncekileri desteklenmiyor.