Özellikler ve İşlevsellikler

Aspose.3D FOSS for TypeScript, MIT lisanslı bir Node.js kütüphanesidir ve 3D sahneleri yükleme, oluşturma ve dışa aktarma işlevi sağlar. Tam TypeScript tip tanımlamaları, tek bir çalışma zamanı bağımlılığı ile birlikte gelir (xmldom).

Kurulum ve Ayarlama

Paketi npm üzerinden tek bir komutla kurun:

npm install @aspose/3d

Paket, CommonJS hedefler ve Node.js 18 veya daha yeni bir sürüm gerektirir. Kurulumdan sonra, sizin tsconfig.json tam uyumluluk için aşağıdaki derleyici seçeneklerini içerir:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true
  }
}

Ana Scene sınıfını paket kökünden içe aktarın. Biçim‑özel seçenek sınıfları, ilgili alt yollarından içe aktarılır:

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

Özellikler ve İşlevsellikler

Format Desteği

Aspose.3D FOSS for TypeScript, altı büyük 3D dosya formatını okur ve yazar. Yükleme sırasında ikili sihirli sayılardan format algılaması otomatik olduğundan, kaynak formatı açıkça belirtmeniz gerekmez.

Malzemelerle OBJ yükleme:

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

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
options.flipCoordinateSystem = false;
options.scale = 1.0;
options.normalizeNormal = true;
scene.open('model.obj', options);

GLB’ye (ikili glTF) kaydetme:

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

const scene = new Scene();
// ... build or load scene content

const opts = new GltfSaveOptions();
opts.binaryMode = true;
scene.save('output.glb', GltfFormat.getInstance(), opts);

Sahne Grafiği

Tüm 3D içerik bir ağaç yapısı olarak düzenlenir Node nesneler … kökünde scene.rootNode. Her düğüm bir Entity (bir Mesh, Camera, Light, ya da diğer SceneObject) ve bir Transform bu, ebeveynine göre konumlandırır.

Ana sahne grafiği sınıfları:

• Scene: üst düzey kapsayıcı; tutar rootNode ve animationClips
• Node: adlandırılmış bir ağaç düğümü, şunları içeren childNodes, entity, transform, ve materials
• Entity: eklenebilir nesneler için temel sınıf (Mesh, Camera, Light)
• SceneObject: paylaşılan temel sınıf Node ve Entity
• A3DObject: kök temel sınıf, şunları içeren name ve özellik çantası
• Transform: yerel çeviri, dönüş (Euler ve Quaternion) ve ölçek

Sahne grafiğinde gezinme:

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

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

function visit(node: Node, depth: number = 0): void {
  const indent = '  '.repeat(depth);
  console.log(`${indent}Node: ${node.name}`);
  if (node.entity) {
    console.log(`${indent}  Entity: ${node.entity.constructor.name}`);
  }
  for (const child of node.childNodes) {
    visit(child, depth + 1);
  }
}

visit(scene.rootNode);

Programlı olarak bir sahne hiyerarşisi oluşturma:

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

const scene = new Scene();
const parent = scene.rootNode.createChildNode('chassis');
const wheel = parent.createChildNode('wheel_fl');
wheel.transform.translation.set(0.9, -0.3, 1.4);

Geometri ve Mesh

Mesh : birincil geometri tipidir. Şunu genişletir Geometry : ve kontrol noktalarını (köşeler), çokgen indekslerini ve normaller, UV’ler ve köşe renkleri için köşe öğelerini ortaya çıkarır.

Ana geometri sınıfları:

• Mesh: çokgen örgüsü ile controlPoints : ve polygonCount
• Geometry: köşe öğesi yönetimi olan temel sınıf
• VertexElementNormal: köşe başına veya çokgen‑köşe başına normaller
• VertexElementUV: doku koordinatları (bir veya daha fazla UV kanalı)
• VertexElementVertexColor: köşe başına renk verisi
• MappingMode: öğe verisinin çokgenlere nasıl eşlendiğini kontrol eder (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: indeksleme stratejisini kontrol eder (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: bir köşe öğesinin semantiğini tanımlar
• TextureMapping: doku kanal sayımı

Yüklenmiş bir sahneden mesh verisini okuma:

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

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

for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    const mesh = node.entity as Mesh;
    console.log(`Mesh "${node.name}": ${mesh.controlPoints.length} vertices, ${mesh.polygonCount} polygons`);

    const normals = mesh.getElement(VertexElementType.NORMAL);
    if (normals) {
      console.log(`  Normal mapping: ${normals.mappingMode}`);
    }
  }
}

Malzeme Sistemi

Aspose.3D TypeScript için FOSS, eski Phong gölgelendirmesinden fiziksel tabanlı renderlamaya kadar tam kapsamı kapsayan üç malzeme türünü destekler:

• LambertMaterial: dağılma rengi ve ortam rengi; basit OBJ/DAE materyallerine eşlenir
• PhongMaterial: yansıma rengi, parlaklık ve ışık yayılımı ekler; varsayılan OBJ materyal türü
• PbrMaterial: fiziksel temelli pürüzlülük/metalik modeli; glTF 2.0 içe ve dışa aktarma için kullanılır

Yüklenmiş bir OBJ sahnesinden malzemeleri okuma:

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

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

for (const node of scene.rootNode.childNodes) {
  for (const mat of node.materials) {
    if (mat instanceof PhongMaterial) {
      const phong = mat as PhongMaterial;
      console.log(`  Phong: diffuse=${JSON.stringify(phong.diffuseColor)}, shininess=${phong.shininess}`);
    } else if (mat instanceof LambertMaterial) {
      console.log(`  Lambert: diffuse=${JSON.stringify((mat as LambertMaterial).diffuseColor)}`);
    }
  }
}

Bir glTF sahnesi oluşturulurken PBR malzemesi uygulama:

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

const scene = new Scene();
const node = scene.rootNode.createChildNode('sphere');
const mat = new PbrMaterial();
mat.albedo = new Vector3(0.8, 0.2, 0.2);   // red-tinted albedo; albedo starts null, must assign
mat.metallicFactor = 0.0;
mat.roughnessFactor = 0.5;
node.material = mat;

const opts = new GltfSaveOptions();
opts.binaryMode = false;
scene.save('output.gltf', GltfFormat.getInstance(), opts);

Matematik Yardımcı Araçları

Kütüphane, tam bir 3D matematik tipi setiyle birlikte gelir, hepsi tam tipli:

• Vector3: 3 bileşenli vektör; destekler minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: homojen koordinatlar için 4 bileşenli vektör
• Matrix4: 4×4 dönüşüm matrisi ile concatenate(), transpose, decompose, setTRS
• Quaternion: dönüşüm kuaterniyonu ile fromEulerAngle() : (statik, tekil), eulerAngles() : (örnek yöntemi), slerp(), normalize()
• BoundingBox: eksen hizalı sınırlayıcı kutu ile minimum, maximum, center, size, merge
• FVector3: tek duyarlıklı varyantı Vector3 : köşe öğesi verilerinde kullanılır

Mesh vertex’lerinden bir sınırlayıcı kutu hesaplama:

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

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

let box = new BoundingBox();
for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    for (const pt of (node.entity as Mesh).controlPoints) {
      box.merge(new Vector3(pt.x, pt.y, pt.z));
    }
  }
}
console.log('Center:', box.center);
console.log('Extents:', box.size);

Euler açılarıyla bir dönüşüm oluşturma:

import { Quaternion, Vector3, Matrix4 } from '@aspose/3d';

const rot = Quaternion.fromEulerAngle(0, Math.PI / 4, 0); // 45° around Y
const mat = new Matrix4();
mat.setTRS(new Vector3(0, 0, 0), rot, new Vector3(1, 1, 1));

Animasyon Sistemi

Animasyon API’si klipleri, düğümleri, kanalları ve anahtar kare dizilerini modeller:

• AnimationClip: adlandırılmış animasyon düğümü koleksiyonu; şu aracılığıyla erişilir scene.animationClips; gösterir animations: AnimationNode[]
• AnimationNode: adlandırılmış grup BindPoints; oluşturuldu clip.createAnimationNode(name), erişildi clip.animations
• BindPoint: bağlar bir AnimationNode : bir sahne nesnesindeki belirli bir özelliğe; gösterir property : ve channelsCount
• AnimationChannel: genişletir KeyframeSequence; ayrı bir keyframeSequence; ile erişilir bindPoint.getChannel(name)
• KeyFrame: tek bir zaman/değer çifti; anahtar kare başına taşır interpolation: Interpolation
• KeyframeSequence: sıralı listesi KeyFrame nesneler aracılığıyla keyFrames; sahiptir preBehavior ve postBehavior (Extrapolation)
• Interpolation: enum: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: sınıfı type: ExtrapolationType ve repeatCount: number
• ExtrapolationType: enum: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Yüklenmiş bir sahneden animasyon verilerini okuma:

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

const scene = new Scene();
scene.open('animated.dae');   // COLLADA animation import is supported

for (const clip of scene.animationClips) {
  console.log(`Clip: "${clip.name}"`);
  for (const animNode of clip.animations) {          // clip.animations, not clip.nodes
    console.log(`  AnimationNode: ${animNode.name}`);
    for (const bp of animNode.bindPoints) {           // animNode.bindPoints, not animNode.channels
      console.log(`  BindPoint: property="${bp.property.name}", channels=${bp.channelsCount}`);
    }
  }
}

Akış ve Buffer Desteği

Kullan scene.openFromBuffer() bellek içi bir konumdan doğrudan bir 3D sahne yüklemek için Buffer. Bu, sunucusuz işlevler, akış boru hatları ve HTTP üzerinden alınan varlıkları diske yazmadan işlemek için önerilen desendir.

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

// Load file into memory, then parse from buffer
const buffer: Buffer = fs.readFileSync('model.obj');
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
scene.openFromBuffer(buffer, options);

for (const node of scene.rootNode.childNodes) {
  if (node.entity) {
    console.log(node.name, node.entity.constructor.name);
  }
}

Buffer’dan yükleme yaparken ikili sihirli sayılardan format otomatik algılama uygulanır; bu sayede GLB, STL binary ve 3MF dosyaları format parametresi belirtilmeden tanınır.

Kullanım Örnekleri

Örnek 1: OBJ’yi Yükle ve GLB’ye Dışa Aktar

Bu örnek, malzemelerle birlikte bir Wavefront OBJ dosyasını yükler ve ardından sahneyi web ve oyun motoru kullanımı için uygun bir ikili glTF (GLB) dosyası olarak yeniden dışa aktarır.

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

function convertObjToGlb(inputPath: string, outputPath: string): void {
  const scene = new Scene();

  const loadOpts = new ObjLoadOptions();
  loadOpts.enableMaterials = true;
  loadOpts.flipCoordinateSystem = false;
  loadOpts.normalizeNormal = true;
  scene.open(inputPath, loadOpts);

  // Report what was loaded
  for (const node of scene.rootNode.childNodes) {
    if (node.entity) {
      console.log(`Loaded: ${node.name} (${node.entity.constructor.name})`);
    }
  }

  const saveOpts = new GltfSaveOptions();
  saveOpts.binaryMode = true; // write .glb instead of .gltf + .bin
  scene.save(outputPath, GltfFormat.getInstance(), saveOpts);

  console.log(`Exported GLB to: ${outputPath}`);
}

convertObjToGlb('input.obj', 'output.glb');

Örnek 2: Normal Doğrulamalı Round-Trip STL

Bu örnek, ikili bir STL dosyasını yükler, her köşe için normal bilgilerini yazdırır, ardından sahneyi ASCII STL olarak yeniden dışa aktarır ve roundtrip’i doğrular.

import { Scene, Mesh, VertexElementNormal, VertexElementType } from '@aspose/3d';
import { StlLoadOptions, StlSaveOptions } from '@aspose/3d/formats/stl';

const scene = new Scene();
const loadOpts = new StlLoadOptions();
scene.open('model.stl', loadOpts);

let totalPolygons = 0;
for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    const mesh = node.entity as Mesh;
    totalPolygons += mesh.polygonCount;

    const normElem = mesh.getElement(VertexElementType.NORMAL) as VertexElementNormal | null;
    if (normElem) {
      console.log(`  Normals: ${normElem.data.length} entries, mapping=${normElem.mappingMode}`);
    }
  }
}
console.log(`Total polygons: ${totalPolygons}`);

// Re-export as ASCII STL
const saveOpts = new StlSaveOptions();
saveOpts.binaryMode = false; // ASCII output
scene.save('output_ascii.stl', saveOpts);

Örnek 3: Bir Sahneyi Programlı Olarak Oluştur ve glTF Olarak Kaydet

Bu örnek, sıfırdan bir PBR malzemesiyle bir sahne oluşturur ve bunu JSON glTF dosyası olarak kaydeder.

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

const scene = new Scene();
const node = scene.rootNode.createChildNode('floor');

// Build a simple quad mesh (two triangles)
// controlPoints are Vector4 (x, y, z, w) where w=1 for positions
const mesh = new Mesh();
mesh.controlPoints.push(
  new Vector4(-1, 0, -1, 1),
  new Vector4( 1, 0, -1, 1),
  new Vector4( 1, 0,  1, 1),
  new Vector4(-1, 0,  1, 1),
);
mesh.createPolygon([0, 1, 2]);
mesh.createPolygon([0, 2, 3]);
node.entity = mesh;

// Apply a PBR material
const mat = new PbrMaterial();
mat.albedo = new Vector3(0.6, 0.6, 0.6);   // albedo starts null, must assign
mat.metallicFactor = 0.0;
mat.roughnessFactor = 0.8;
node.material = mat;

// Save as JSON glTF
const opts = new GltfSaveOptions();
opts.binaryMode = false;
scene.save('floor.gltf', GltfFormat.getInstance(), opts);
console.log('Scene written to floor.gltf');

İpuçları ve En İyi Uygulamalar

• Kullanın ObjLoadOptions.enableMaterials = true .mtl dosyalarından malzeme verisine ihtiyacınız olduğunda. Olmazsa, her düğümdeki malzeme listesi boş olacaktır.
• Tercih edin binaryMode = true GLB için web veya oyun motorları için varlıklar üretirken. Binary GLB tek bir kendi içinde barındıran dosyadır ve tarayıcılarda ve motorlarda JSON + .bin bölünmesinden daha hızlı yüklenir.
• Kullanın openFromBuffer() sunucusuz ortamlarda geçici dosya I/O’sundan kaçınmak için. Varlığı al, geç Buffer doğrudan, ve çıktıyı bir akışa ya da başka bir tampon’a yaz.
• Kontrol et node.entity dönüştürmeden önce: tüm düğümler bir varlık taşımaz. Her zaman bir instanceof erişmeden önce kontrol Mesh-spesifik özellikler gibi controlPoints.
• Ayarla normalizeNormal = true içinde ObjLoadOptions kaynak OBJ dosyalarınız güvenilmeyen kaynaklardan geldiğinde. Bu, bozulmuş normallerin aşağı akış renderleme veya doğrulama adımlarına yayılmasını önler.
• Sakla strict: true tsconfig.json içinde: kütüphane şununla yazılmıştır noImplicitAny ve strictNullChecks. Devre dışı bırakma strict gerçek tip hatalarını gizler ve tiplenmiş API’nin değerini ortadan kaldırır.
• Şu üzerinden geç childNodes, bir indeks döngüsü değil: bu childNodes özellik bir yinelenebilir döndürür; ileri uyumluluk için sayısal indekslemeye güvenmekten kaçının.

Yaygın Sorunlar

Sık Sorulan Sorular

Kütüphane herhangi bir yerel eklenti veya sistem paketi gerektiriyor mu? Hayır. Aspose.3D FOSS for TypeScript tek bir çalışma zamanı bağımlılığına sahiptir: xmldom, bu saf JavaScript’tir ve npm tarafından otomatik olarak kurulur. Hiç .node yerel eklenti ve kurulacak sistem paketi yok.

Hangi Node.js sürümleri destekleniyor? Node.js 18, 20 ve 22 LTS. Kütüphane CommonJS çıktısını hedefler ve dahili olarak ES2020 dil özelliklerini kullanır.

Kütüphaneyi bir tarayıcı paketi (webpack/esbuild) içinde kullanabilir miyim? Kütüphane Node.js’i hedefler ve Node.js’i kullanır fs ve Buffer API’ler. Tarayıcı paketlemesi resmi olarak desteklenmiyor. Tarayıcıda kullanım için, sahneyi sunucu tarafında yükleyin ve sonucu (ör. GLB olarak) istemciye iletin.

Arasındaki fark nedir GltfSaveOptions.binaryMode = true ve false? binaryMode = false bir … üretir .gltf JSON dosyası ve ayrı bir .bin ikili tampon yan dosyası. binaryMode = true tek bir bağımsız … üretir .glb dosya. Kullan true üretim varlık teslimi için.

Bir dosyayı diske kaydetmeden HTTP yanıtından yükleyebilir miyim? Evet. Yanıtı şu şekilde al: Buffer (örneğin, kullanarak node-fetch veya yerleşik fetch Node 18+ içinde), ardından çağır scene.openFromBuffer(buffer, options).

FBX desteği tam mı? Hayır. FBX içe aktarma ve dışa aktarma sınıfları kütüphanede bulunuyor, ancak FBX şu şekilde bağlanmamış Scene.open() veya Scene.save() otomatik algılama. Çağırma scene.open('file.fbx') FBX içe aktarıcısını tetiklemez; dosya STL yedek yoluyla işlenecektir. FBX I/O’ya ihtiyacınız varsa FBX’e özgü içe aktarma/dışa aktarma sınıflarını doğrudan kullanın. Yukarıdaki format destek tablosuna bakın; bu tablo FBX’i olarak işaretler. No*.

Kütüphane TypeScript 4.x’i destekliyor mu? TypeScript 5.0+ önerilir. TypeScript 4.7+ pratikte çalışmalıdır, ancak kütüphane 5.0+ üzerine test edilmiş ve geliştirilmiştir.

API Referans Özeti