Merkmale und Funktionalität

Aspose.3D FOSS für TypeScript ist eine mit MIT lizenzierte Node.js-Bibliothek zum Laden, Konstruktion und Export von 3D-Szenen. Es wird mit kompletten Typdefinitionen von Type Script geliefert, einer einzigen Laufzeitabhängigkeit (xmldomDiese Seite ist die primäre Referenz für alle Feature-Bereiche und enthält laufbare TypeScript-Code-Beispiele für jeden einzelnen.

Installation und Einrichtung

Installieren Sie das Paket von npm mit einem einzigen Befehl:

Das Paket richtet sich an CommonJS und erfordert Node.js 18 oder höher. Nach der Installation überprüfen Sie Ihre tsconfig.json enthält die folgenden Kompilatoroptionen für volle Verträglichkeit:

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

Import der Haupt- Scene Die Format-spezifischen Optionsklassen werden aus ihren jeweiligen Unterwegen importiert:

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

Merkmale und Funktionalität

Formatunterstützung

Aspose.3D FOSS für TypeScript liest und schreibt sechs wichtige 3D-Dateiformate. Die Formaterkennung erfolgt automatisch aus binären Zauberzahlen beim Laden, so dass Sie das Quellformat nicht explizit angeben müssen.

Beförderung des OBJ mit Materialien:

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

Einsparungen auf GLB (binärer 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);

Schauplatz

Alle 3D-Inhalte sind als Baum von Node Objekte, die auf der scene.rootNode.Jeder Knoten kann eine Entity (a) Mesh, Camera, Light, oder andere SceneObject) und a Transform Das positioniert es relativ zu seinem Elternteil.

Schlüssel-Szenengrafikklassen:

• Scene: der oberste Behälter; rootNode und animationClips
• Node: ein benannter Baumknoten mit childNodes, entity, transform, und materials
• Entity: Basisklasse für Anschlussobjekte (Mesh, Camera, Light)
• SceneObject: Basisklasse geteilt durch Node und Entity
• A3DObject: Wurzel-Basisklasse mit name und Sachtasche
• Transform:Die Schwerpunkte sind: Lokalübersetzung, Rotation (Euler und Quaternion) sowie Skala.

Durch die Szene graphisch:

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

Schaffung einer Szenenhierarchie programmatisch:

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

Geometrie und Netzwerk

Mesh ist der primäre Geometrie-Typ. Es erstreckt sich Geometry und zeigt Kontrollpunkte (Wertschnitte), Polygonindizes und Wertelemente für Normalwerte, UV-Strahlen und Wertschnittfarben.

Schlüsselgeometrie-Klassen:

• Mesh: Mehrseilmaschine mit controlPoints und . polygonCount
• Geometry: Basisklasse mit Vertex-Elementverwaltung
• VertexElementNormal: Normalen pro Höhenpunkt oder normalen per Polygon-Höhenbereich
• VertexElementUV: Texturkoordinaten (einer oder mehrere UV-Kanäle)
• VertexElementVertexColor: Farbdaten pro Spitze
• MappingMode: steuert, wie die Elemente zu Polygonen (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: die Indexstrategie kontrolliert (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: Identifiziert die Semantik eines Wertelementes.
• TextureMapping: Aufzählung der Texturkanäle

Lesen von Maschendaten aus einer geladenen Szene:

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

Materialsystem

Aspose.3D FOSS für TypeScript unterstützt drei Materialtypen, die das gesamte Spektrum von Phong-Verlag bis hin zu physikalisch basierender Darstellung abdecken:

• LambertMaterial: diffuse Farbe und Umgebungsfarbe; Karten zu einfachen OBJ/DAE-Materialien
• PhongMaterial: fügt Spiegelfarbe, Glanz und Emissionskraft hinzu; der Standard-OBJ-Materialtyp
• PbrMaterial: physikalisch basierte Rauheit/Metallmodell; für den Import und die Ausfuhr von glTF 2.0 verwendet.

Lesematerialien aus einer geladenen OBJ-Szene:

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

Anwendung eines PBR-Materials beim Bau einer glTF-Szene:

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

Mathematik-Dienste

Die Bibliothek liefert eine komplette Reihe von 3D-Mathematiktypen, alle vollständig eingegeben:

• Vector3: 3-Komponenten-Vektor; Stützungen minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: Vier-Komponentenvektor für homogene Koordinaten
• Matrix4: 4×4 Transformationsmatrix mit concatenate(), transpose, decompose, setTRS
• Quaternion: Rotationsquaternion mit fromEulerAngle() (statisch, in der Einheit), eulerAngles() (Instanzverfahren), slerp(), normalize()
• BoundingBox: Achsenbereinigte Grenzschachtel mit: minimum, maximum, center, size, merge
• FVector3: Einzelpräzisionsvariante von: Vector3 in Vertex-Elementdaten verwendet werden

Berechnung einer Grenzfläche aus Maschenwinkel:

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

Erstellung einer Transformation aus Euler-Winkeln:

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

Animationssystem

Die Animations-API modelliert Clips, Knoten, Kanäle und Keyframe Sequenzen:

• AnimationClip: benannte Sammlung von Animationsknoten; über scene.animationClips;, zeigt auf animations: AnimationNode[]
• AnimationNode: benannte Gruppe von BindPoints; erstellt über clip.createAnimationNode(name), über die Internetverbindung zugegriffen werden kann. clip.animations
• BindPoint: verbindet eine AnimationNode auf eine bestimmte Eigenschaft eines Szenenobjekts; zeigt die property und . channelsCount
• AnimationChannel: erstreckt sich auf: KeyframeSequence;Die Kommission hat eine gesonderte Liste der keyframeSequence; über die Internetverbindung zugegriffen werden. bindPoint.getChannel(name)
• KeyFrame: ein einzelnes Zeit-/Wertpaar; trägt pro Schlüsselrahmen. interpolation: Interpolation
• KeyframeSequence: geordnete Liste der KeyFrame Objekte über die keyFrames;hat; preBehavior und . postBehavior (Extrapolation)
• Interpolation:Ich bin nicht hier.: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation:Klasse mit: type: ExtrapolationType und . repeatCount: number
• ExtrapolationType:Ich bin nicht hier.: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Animationsdaten aus einer geladenen Szene lesen:

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

Unterstützung für Streaming und Puffer

Verwendung scene.openFromBuffer() Um eine 3D-Szene direkt aus einem In-Memory zu laden. Buffer.Dies ist das empfohlene Muster für serverlose Funktionen, Streaming-Pipelines und Verarbeitungsaktiva, die über HTTP abgerufen werden, ohne auf Festplatte zu schreiben.

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

Die automatische Erkennung von Formate aus binären Zauberzahlen findet beim Laden vom Puffer statt, so dass GLB-, STL-Binär- und 3MF-Dateien ohne Angabe eines Formatparameters erkannt werden.

Verwendungsbeispiele

Beispiel 1: OBJ-Ladung und Export nach GLB

Dieses Beispiel lädt eine Wavefront OBJ-Datei mit Materialien und exportiert die Szene dann als binäre glTF (GLB) -Date, die für den Einsatz im Web und in Spielmotoren geeignet ist.

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

Beispiel 2: Rundfahrt-STL mit normaler Validierung

Dieses Beispiel lädt eine binäre STL-Datei, druckt per Vertex normale Informationen und exportiert die Szene dann als ASCII ST L wieder aus und überprüft den Rundgang.

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

Beispiel 3: Programmatisch eine Szene erstellen und als glTF speichern

Dieses Beispiel konstruiert eine Szene mit einem PBR-Material von Grund auf und speichert sie als JSON glTF Datei.

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

Tipps und beste Praktiken

• Verwendung ObjLoadOptions.enableMaterials = true Wenn Sie Materialdaten aus .mtl-Dateien benötigen, wird die Materialliste auf jedem Knoten leer sein.
• Vorzug nehmen. binaryMode = true für GLB Binary GLB ist eine einzelne, in sich geschlossene Datei und lädt schneller in Browsern und Engines als die JSON + .bin Split.
• Verwendung openFromBuffer() in Serverlosen Umgebungen Um vorübergehende Datei-Ein- und Ausgänge zu vermeiden. Holen Sie den Asset, geben Sie die Buffer direkt und schreiben Sie den Ausgang in einen Stream oder anderen Puffer.
• Überprüfung node.entity vor dem Gießen: nicht alle Knoten tragen eine Entität. Immer mit einem Schutz zu bewachen instanceof Überprüfen Sie vor dem Zugriff. Mesh- spezifische Eigenschaften wie z.B. controlPoints.
• Setz normalizeNormal = true in der ObjLoadOptions Dies verhindert, dass sich degenerierte Normale in nachgelagerte Renderings- oder Validierungsschritte ausbreiten.
• Halten Sie es. strict: true in tsconfig.json:Die Bibliothek ist mit: noImplicitAny und . strictNullChecks.- Auslösung . strict Maskiert echte Typfehler und überschreitet den Wert der eingegebenen API.
• Durchschnittsweg childNodes, nicht eine Indexschleife:Die: childNodes Die Eigenschaft gibt eine Iterable zurück; vermeiden Sie die Abhängigkeit von numerischer Indexierung für die Kompatibilität mit der Zukunft.

Häufige Probleme

Häufig gestellte Fragen

Ist die Bibliothek benötigt irgendwelche native Addons oder Systempakete? Aspose.3D FOSS für TypeScript hat eine einzige Laufzeit-Abhängigkeit: xmldom, das reine JavaScript ist und automatisch von npm installiert wird. Es gibt keine .node Native Addons und keine Systempakete zu installieren.

Welche Node.js-Versionen werden unterstützt? Node.js 18, 20, and 22 LTS. The library targets CommonJS output and uses ES2020 language features internally.

Kann ich die Bibliothek in einem Browser-Bundle (webpack/esbuild) verwenden? Die Bibliothek richtet sich an Node.js und verwendet die Node .js fs und . Buffer APIs. Browser-Bundling wird nicht offiziell unterstützt. Für die Verwendung des Browsers, laden Sie die Szene auf der Serverseite und übermitteln das Ergebnis (z. B. als GLB) an den Client.

Was ist der Unterschied zwischen GltfSaveOptions.binaryMode = true und . false? binaryMode = false produziert eine .gltf JSON-Datei plus eine separate Datei .bin Binär-Bufferseitenwagen. binaryMode = true produziert eine einzelne, in sich geschlossene .glb Die Datei. true für die Lieferung von Produktionsgütern.

Kann ich eine Datei aus einer HTTP-Antwort laden, ohne sie auf Festplatte zu speichern? Ja, hol die Antwort als eine Buffer (z. B. mit Hilfe von node-fetch oder der eingebaute fetch in Knoten 18+), dann aufrufen scene.openFromBuffer(buffer, options).

Ist der FBX-Support abgeschlossen? Nein. FBX-Importeur und -Exporter gibt es in der Bibliothek, aber FBx ist nicht mit dem System verbunden. Scene.open() oder Scene.save() - Ich rufe. scene.open('file.fbx') wird den FBX-Importeur nicht aufrufen; die Datei wird vom STL-Fallback-Pfad verarbeitet. Verwenden Sie direkt die FBx-spezifischen Importer/Exporter-Klassen, wenn Sie FB X E / O benötigen. Sehen Sie die Tabelle über das Formatunterstützung oben, in der FB x als markiert ist No*.

Unterstützt die Bibliothek TypeScript 4.x? TypScript 5.0+ wird empfohlen. TypeScript 4.7+ sollte in der Praxis funktionieren, aber die Bibliothek ist gegen 5. 0+ getestet und verfasst.

Zusammenfassung der API-Referenzen