Funkcje i możliwości

Aspose.3D FOSS for TypeScript to biblioteka Node.js na licencji MIT służąca do ładowania, konstruowania i eksportowania scen 3D. Dostarcza pełne definicje typów TypeScript oraz jedną zależność w czasie wykonywania (xmldom).

Instalacja i konfiguracja

Zainstaluj pakiet z npm używając jednego polecenia:

npm install @aspose/3d

Pakiet jest przeznaczony dla CommonJS i wymaga Node.js 18 lub nowszego. Po instalacji sprawdź, czy Twój tsconfig.json zawiera następujące opcje kompilatora, aby zapewnić pełną kompatybilność:

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

Zaimportuj główny Scene klasę z katalogu głównego pakietu. Klasy opcji specyficzne dla formatu są importowane z ich odpowiednich podścieżek:

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

Funkcje i możliwości

Obsługa formatów

Aspose.3D FOSS for TypeScript odczytuje i zapisuje sześć głównych formatów plików 3D. Wykrywanie formatu odbywa się automatycznie na podstawie binarnych liczb magicznych podczas ładowania, więc nie musisz jawnie podawać formatu źródłowego.

Ładowanie OBJ z materiałami:

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

Zapisywanie do GLB (binary glTF):

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

Graf sceny

Cała zawartość 3D jest organizowana jako drzewo Node obiektów z korzeniem w scene.rootNode. Każdy węzeł może nosić Entity (a Mesh, Camera, Light, lub inny SceneObject) i Transform który pozycjonuje go względem jego rodzica.

Kluczowe klasy grafu sceny:

• Scene: kontener najwyższego poziomu; zawiera rootNode i animationClips
• Node: nazwany węzeł drzewa z childNodes, entity, transform, i materials
• Entity: klasa bazowa dla obiektów dołączalnych (Mesh, Camera, Light)
• SceneObject: klasa bazowa współdzielona przez Node i Entity
• A3DObject: główna klasa bazowa z name i zestaw właściwości
• Transform:lokalne przesunięcie, rotacja (Euler i Quaternion) i skala

Przechodzenie grafu sceny:

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

Tworzenie hierarchii sceny programowo:

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

Geometria i Mesh

Mesh jest podstawowym typem geometrii. Rozszerza Geometry i udostępnia punkty kontrolne (wierzchołki), indeksy wielokątów oraz elementy wierzchołków dla normalnych, UV i kolorów wierzchołków.

Kluczowe klasy geometrii:

• Mesh:siatka wielokątowa z controlPoints i polygonCount
• Geometry: klasa bazowa z zarządzaniem elementami wierzchołków
• VertexElementNormal: normalne per-wierzchołkowe lub per-wierzchołek-polygonu
• VertexElementUV: współrzędne tekstury (jeden lub więcej kanałów UV)
• VertexElementVertexColor: dane koloru per-wierzchołkowego
• MappingMode: kontroluje, jak dane elementu mapują się na wielokąty (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: kontroluje strategię indeksowania (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: identyfikuje semantykę elementu wierzchołka
• TextureMapping: enumeracja kanałów tekstury

Odczytywanie danych siatki z załadowanej sceny:

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

System materiałów

Aspose.3D FOSS dla TypeScript obsługuje trzy typy materiałów obejmujące pełny zakres od starszego cieniowania Phong po renderowanie fizycznie poprawne:

• LambertMaterial: kolor rozpraszający i kolor otoczenia; mapuje się na proste materiały OBJ/DAE
• PhongMaterial: dodaje kolor odbicia, połysk i emisję; domyślny typ materiału OBJ
• PbrMaterial: model fizycznie oparty na chropowatości/metaliczności; używany do importu i eksportu glTF 2.0

Odczytywanie materiałów z załadowanej sceny OBJ:

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

Stosowanie materiału PBR podczas budowania sceny glTF:

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

Narzędzia matematyczne

Biblioteka dostarcza kompletny zestaw typów matematyki 3D, wszystkie w pełni typowane:

• Vector3: wektor 3-składnikowy; obsługuje minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: wektor 4-składnikowy dla współrzędnych jednorodnych
• Matrix4: macierz przekształcenia 4×4 z concatenate(), transpose, decompose, setTRS
• Quaternion: kwaternion rotacji z fromEulerAngle() : (statyczny, pojedynczy), eulerAngles() : (metoda instancji), slerp(), normalize()
• BoundingBox: pudełko ograniczające wyrównane do osi z minimum, maximum, center, size, merge
• FVector3: wariant pojedynczej precyzji Vector3 używany w danych elementów wierzchołka

Obliczanie prostopadłościanu ograniczającego z wierzchołków siatki:

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

Tworzenie transformacji z kątów Eulera:

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

System animacji

API animacji modeluje klipy, węzły, kanały i sekwencje klatek kluczowych:

• AnimationClip: nazwana kolekcja węzłów animacji; dostępna przez scene.animationClips; udostępnia animations: AnimationNode[]
• AnimationNode: nazwana grupa BindPoints; utworzona przez clip.createAnimationNode(name), dostępna przez clip.animations
• BindPoint: wiąże AnimationNode do określonej właściwości obiektu sceny; udostępnia property i channelsCount
• AnimationChannel: rozszerza KeyframeSequence; przechowuje osobny keyframeSequence; dostępny przez bindPoint.getChannel(name)
• KeyFrame: pojedyncza para czas/wartość; przenosi per-keyframe interpolation: Interpolation
• KeyframeSequence: uporządkowana lista KeyFrame obiektów przez keyFrames; ma preBehavior i postBehavior (Extrapolation)
• Interpolation: enum: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: class z type: ExtrapolationType i repeatCount: number
• ExtrapolationType: enum: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Odczytywanie danych animacji z załadowanej sceny:

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

Obsługa strumieni i buforów

Użyj scene.openFromBuffer() do załadowania sceny 3D bezpośrednio z pamięci Buffer. Jest to zalecany wzorzec dla funkcji serverless, potoków strumieniowych i przetwarzania zasobów pobranych przez HTTP bez zapisywania ich na dysk.

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

Automatyczne wykrywanie formatu na podstawie binarnych liczb magicznych działa przy ładowaniu z bufora, więc pliki GLB, binarne STL i 3MF są rozpoznawane bez podawania parametru formatu.

Przykłady użycia

Przykład 1: Wczytaj OBJ i wyeksportuj do GLB

Ten przykład wczytuje plik Wavefront OBJ z materiałami, a następnie ponownie eksportuje scenę jako binarny plik glTF (GLB) odpowiedni do użycia w sieci i silnikach gier.

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

Przykład 2: Pełny cykl STL z weryfikacją normalnych

Ten przykład wczytuje binarny plik STL, wypisuje informacje o normalnych dla każdego wierzchołka, a następnie ponownie eksportuje scenę jako ASCII STL i weryfikuje poprawność pełnego cyklu.

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

Przykład 3: Tworzenie sceny programowo i zapisywanie jako glTF

Ten przykład tworzy scenę z materiałem PBR od podstaw i zapisuje ją jako plik JSON glTF.

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

Wskazówki i najlepsze praktyki

• Użyj ObjLoadOptions.enableMaterials = true za każdym razem, gdy potrzebujesz danych materiałowych z plików .mtl. Bez nich lista materiałów na każdym węźle będzie pusta.
• Preferuj binaryMode = true dla GLB przy tworzeniu zasobów dla sieci lub silników gier. Binarny GLB to pojedynczy, samodzielny plik i ładuje się szybciej w przeglądarkach i silnikach niż podział JSON + .bin.
• Użyj openFromBuffer() w środowiskach bezserwerowych aby uniknąć tymczasowego I/O plików. Pobierz zasób, przekaż Buffer bezpośrednio i zapisz wynik do strumienia lub innego bufora.
• Sprawdź node.entity przed rzutowaniem: nie wszystkie węzły zawierają encję. Zawsze zabezpieczaj się z instanceof sprawdź przed dostępem Mesh-specyficzne właściwości, takie jak controlPoints.
• Ustaw normalizeNormal = true w ObjLoadOptions gdy twoje pliki OBJ pochodzą z niepewnych źródeł. To zapobiega propagacji zdegradowanych wektorów normalnych do kolejnych etapów renderowania lub walidacji.
• Zachowaj strict: true w tsconfig.json:biblioteka jest napisana w noImplicitAny i strictNullChecks. Wyłączanie strict maskuje rzeczywiste błędy typów i podważa wartość typowanego API.
• Przechodź przez childNodes, nie pętlą indeksującą: ten childNodes właściwość zwraca iterowalny obiekt; unikaj polegania na indeksowaniu numerycznym w celu zachowania kompatybilności w przyszłości.

Typowe problemy

Najczęściej zadawane pytania

Czy biblioteka wymaga jakichkolwiek natywnych dodatków lub pakietów systemowych? Nie. Aspose.3D FOSS for TypeScript ma jedną zależność w czasie wykonywania: xmldom, które jest czystym JavaScriptem i jest instalowane automatycznie przez npm. Nie ma .node natywnych dodatków i żadnych pakietów systemowych do zainstalowania.

Jakie wersje Node.js są wspierane? Node.js 18, 20 i 22 LTS. Biblioteka celuje w wyjście CommonJS i wewnętrznie używa funkcji językowych ES2020.

Czy mogę używać biblioteki w pakiecie przeglądarkowym (webpack/esbuild)? Biblioteka celuje w Node.js i używa Node.js fs i Buffer API. Pakowanie do przeglądarki nie jest oficjalnie wspierane. Do użytku w przeglądarce, załaduj scenę po stronie serwera i przekaż wynik (np. jako GLB) do klienta.

Jaka jest różnica między GltfSaveOptions.binaryMode = true i false? binaryMode = false tworzy .gltf plik JSON oraz oddzielny .bin plik pomocniczy z buforem binarnym. binaryMode = true tworzy pojedynczy, samodzielny .glb plik. Użyj true do dostarczania zasobów w środowisku produkcyjnym.

Czy mogę załadować plik z odpowiedzi HTTP bez zapisywania go na dysku? Tak. Pobierz odpowiedź jako Buffer (np. używając node-fetch lub wbudowanego fetch w Node 18+), a następnie wywołaj scene.openFromBuffer(buffer, options).

Czy obsługa FBX jest kompletna? Nie. Klasy importera i eksportera FBX istnieją w bibliotece, ale FBX nie jest podłączony do Scene.open() lub Scene.save() automatycznego wykrywania. Wywołanie scene.open('file.fbx') nie wywoła importera FBX; plik zostanie obsłużony przez ścieżkę awaryjną STL. Użyj bezpośrednio klas importera/eksportera specyficznych dla FBX, jeśli potrzebujesz I/O FBX. Zobacz powyższą tabelę wsparcia formatów, w której FBX jest oznaczony jako No*.

Czy biblioteka obsługuje TypeScript 4.x? Zalecony jest TypeScript 5.0+. TypeScript 4.7+ powinien działać w praktyce, ale biblioteka jest testowana i tworzona pod wersję 5.0+.

Podsumowanie referencji API