Χαρακτηριστικά και Λειτουργίες

Aspose.3D FOSS για TypeScript είναι μια βιβλιοθήκη Node.js αδειοδοτημένη με MIT για τη φόρτωση, κατασκευή και εξαγωγή 3D σκηνών. Συμπεριλαμβάνει πλήρεις ορισμούς τύπων TypeScript, μια μοναδική εξάρτηση χρόνου εκτέλεσης (xmldom), και υποστήριξη για έξι κύριες μορφές αρχείων 3D. Αυτή η σελίδα είναι η κύρια αναφορά για όλες τις περιοχές λειτουργιών και περιλαμβάνει εκτελέσιμα παραδείγματα κώδικα TypeScript για το καθένα.

Εγκατάσταση και Ρύθμιση

Εγκαταστήστε το πακέτο από το npm χρησιμοποιώντας μία εντολή:

npm install @aspose/3d

Το πακέτο στοχεύει στο CommonJS και απαιτεί Node.js 18 ή νεότερο. Μετά την εγκατάσταση, επαληθεύστε το. tsconfig.json περιλαμβάνει τις ακόλουθες επιλογές μεταγλωττιστή για πλήρη συμβατότητα:

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

Εισαγωγή του main Scene κλάση από τη ρίζα του πακέτου. Οι κλάσεις επιλογών ειδικές για μορφή εισάγονται από τις αντίστοιχες υποδιαδρομές τους:

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

Χαρακτηριστικά και Λειτουργίες

Υποστήριξη Μορφών

Το Aspose.3D FOSS for TypeScript διαβάζει και γράφει έξι κύριες μορφές αρχείων 3D. Η ανίχνευση μορφής είναι αυτόματη από τους δυαδικούς magic numbers κατά τη φόρτωση, οπότε δεν χρειάζεται να καθορίσετε ρητά τη μορφή προέλευσης.

Φόρτωση OBJ με υλικά:

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 (δυαδικό 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);

Γράφημα Σκηνής

Όλο το 3D περιεχόμενο οργανώνεται ως δέντρο από Node αντικείμενα με ρίζα στο scene.rootNode. Κάθε κόμβος μπορεί να μεταφέρει ένα Entity (ένα Mesh, Camera, Light, ή άλλο SceneObject) και ένα Transform που το τοποθετεί σχετικά με τον γονέα του.

Κύριες κλάσεις γραφήματος σκηνής:

• Scene: το κοντέινερ ανώτερου επιπέδου· περιέχει rootNode και animationClips
• Node: ένας ονομαστικός κόμβος δέντρου με childNodes, entity, transform, και materials
• Entity: βασική κλάση για συνδεόμενα αντικείμενα (Mesh, Camera, Light)
• SceneObject: βασική κλάση που μοιράζεται από Node και Entity
• A3DObject: βασική κλάση ρίζας με name και τσάντα ιδιοτήτων
• Transform: τοπική μετάφραση, περιστροφή (Euler και Quaternion) και κλίμακα

Διαπέραση του γραφήματος σκηνής:

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

Δημιουργία ιεραρχίας σκηνής προγραμματιστικά:

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

Γεωμετρία και Mesh

Mesh είναι ο κύριος τύπος γεωμετρίας. Επεκτείνει Geometry και εκθέτει σημεία ελέγχου (κορυφές), δείκτες πολυγώνων και στοιχεία κορυφών για κανονικές, UV και χρώματα κορυφών.

Κύριες κλάσεις γεωμετρίας:

• Mesh: πλέγμα πολυγώνων με controlPoints και polygonCount
• Geometry: βασική κλάση με διαχείριση στοιχείων κορυφών
• VertexElementNormal: κανονικές ανά κορυφή ή ανά κορυφή-πολύγωνο
• VertexElementUV: συντεταγμένες υφής (ένα ή περισσότερα κανάλια UV)
• VertexElementVertexColor: δεδομένα χρώματος ανά κορυφή
• MappingMode: ελέγχει πώς τα δεδομένα στοιχείων αντιστοιχούν σε πολύγωνα (ByControlPoint, ByPolygonVertex, κ.λπ.)
• ReferenceMode: ελέγχει τη στρατηγική δεικτοδότησης (Direct, IndexToDirect)
• VertexElementType: προσδιορίζει τη σημασιολογία ενός στοιχείου κορυφής
• TextureMapping: απαρίθμηση καναλιού υφής

Ανάγνωση δεδομένων πλέγματος από μια φορτωμένη σκηνή:

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

Σύστημα Υλικών

Aspose.3D FOSS για TypeScript υποστηρίζει τρεις τύπους υλικών που καλύπτουν όλο το φάσμα από την κληρονομική σκίαση Phong μέχρι την φυσικά-βασισμένη απόδοση:

• LambertMaterial: χρώμα διάχυσης και χρώμα περιβάλλοντος; αντιστοιχεί σε απλά υλικά OBJ/DAE
• PhongMaterial: προσθέτει χρώμα κατοπτρισμού, λάμψη και εκπομπή; ο προεπιλεγμένος τύπος υλικού OBJ
• PbrMaterial: μοντέλο τραχύτητας/μεταλλικότητας βασισμένο στη φυσική; χρησιμοποιείται για εισαγωγή και εξαγωγή glTF 2.0

Ανάγνωση υλικών από μια φορτωμένη σκηνή 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)}`);
    }
  }
}

Εφαρμογή υλικού PBR κατά την κατασκευή μιας σκηνής glTF:

import { Scene, Node, PbrMaterial } 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);   // 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);

Βοηθητικά Μαθηματικών

Η βιβλιοθήκη παρέχει ένα πλήρες σύνολο τύπων 3D μαθηματικών, όλοι πλήρως τυποποιημένοι:

• Vector3: διάνυσμα 3-συστατικών; υποστηρίζει add, subtract, scale, dot, cross, normalize, length
• Vector4: διάνυσμα 4-συστατικών για ομογενείς συντεταγμένες
• Matrix4: πίνακας μετασχηματισμού 4×4 με multiply, invert, transpose, decompose
• Quaternion: quaternion περιστροφής με fromEulerAngles, toEulerAngles, slerp, normalize
• BoundingBox: κουτί περιβάλλοντος ευθυγραμμισμένο με άξονες με min, max, center, size, merge
• FVector3: παραλλαγή μονής ακρίβειας του Vector3 χρησιμοποιείται σε δεδομένα στοιχείου κορυφής

Υπολογισμός πλαισίου περιβάλλουσας από τις κορυφές του πλέγματος:

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:

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

Σύστημα Κίνησης

Το API κίνησης μοντελοποιεί κλιπ, κόμβους, κανάλια και ακολουθίες καρέ-κλειδιού:

• AnimationClip: ονομαστική συλλογή κόμβων animation; προσπελάζεται μέσω scene.animationClips
• AnimationNode: συνδέει ένα κλιπ με έναν κόμβο σκηνής με όνομα
• AnimationChannel: στοχεύει μια συγκεκριμένη ιδιότητα (π.χ., translation X) μέσα σε έναν κόμβο animation
• KeyFrame: ένα μοναδικό ζεύγος χρόνου/τιμής
• KeyframeSequence: διατεταγμένη λίστα KeyFrame : αντικείμενα με Interpolation και Extrapolation ρυθμίσεις
• Interpolation: λειτουργία παρεμβολής καρέ-κλειδιού: Linear, Constant, Cubic
• Extrapolation: συμπεριφορά πριν/μετά το εύρος των καρέ-κλειδιών: Constant, Cycle, Mirror

Ανάγνωση δεδομένων κίνησης από μια φορτωμένη σκηνή:

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

const scene = new Scene();
scene.open('animated.fbx');

for (const clip of scene.animationClips) {
  console.log(`Clip: "${clip.name}"`);
  for (const animNode of clip.nodes) {
    console.log(`  Node: ${animNode.name}`);
    for (const channel of animNode.channels) {
      const seq: KeyframeSequence = channel.keyframeSequence;
      console.log(`    Channel "${channel.name}": ${seq.keyFrames.length} keyframes`);
      console.log(`    Interpolation: ${seq.interpolation}`);
    }
  }
}

Υποστήριξη Ροής και Buffer

Χρησιμοποιήστε scene.openFromBuffer() για να φορτώσετε μια 3D σκηνή απευθείας από μνήμη Buffer. Αυτό είναι το προτεινόμενο πρότυπο για λειτουργίες χωρίς διακομιστή, αγωγούς ροής και επεξεργασία πόρων που λαμβάνονται μέσω HTTP χωρίς εγγραφή στο δίσκο.

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, έτσι τα αρχεία GLB, STL binary και 3MF αναγνωρίζονται χωρίς να χρειάζεται να καθοριστεί παράμετρος μορφής.

Παραδείγματα Χρήσης

Παράδειγμα 1: Φόρτωση OBJ και Εξαγωγή σε GLB

Αυτό το παράδειγμα φορτώνει ένα αρχείο Wavefront OBJ με υλικά, στη συνέχεια εξάγει ξανά τη σκηνή ως δυαδικό αρχείο glTF (GLB) κατάλληλο για χρήση στο web και σε μηχανές παιχνιδιών.

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

Παράδειγμα 2: Round-Trip STL με Επικύρωση Κανονικών

Αυτό το παράδειγμα φορτώνει ένα δυαδικό αρχείο STL, εκτυπώνει πληροφορίες κανονικών ανά κορυφή, και στη συνέχεια εξάγει ξανά τη σκηνή ως ASCII STL και επαληθεύει το roundtrip.

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

Παράδειγμα 3: Δημιουργία Σκηνής Προγραμματιστικά και Αποθήκευση ως glTF

Αυτό το παράδειγμα δημιουργεί μια σκηνή με υλικό PBR από το μηδέν και την αποθηκεύει ως αρχείο JSON glTF.

import { Scene, Mesh, PbrMaterial, Vector4 } 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');

Συμβουλές και Καλές Πρακτικές

• Χρησιμοποιήστε ObjLoadOptions.enableMaterials = true όποτε χρειάζεστε δεδομένα υλικού από αρχεία .mtl. Χωρίς αυτό, η λίστα υλικών σε κάθε κόμβο θα είναι κενή.
• Προτιμήστε binaryMode = true για GLB όταν παράγετε πόρους για ιστό ή μηχανές παιχνιδιών. Το δυαδικό GLB είναι ένα ενιαίο αυτόνομο αρχείο και φορτώνεται πιο γρήγορα σε προγράμματα περιήγησης και μηχανές από το διαχωρισμένο JSON + .bin.
• Χρησιμοποιήστε openFromBuffer() σε περιβάλλοντα χωρίς διακομιστή για να αποφύγετε προσωρινή I/O αρχείων. Ανακτήστε τον πόρο, περάστε το Buffer απευθείας, και γράψτε το αποτέλεσμα σε ροή ή σε άλλο buffer.
• Έλεγχος node.entity πριν από τη μετατροπή: δεν όλοι οι κόμβοι φέρουν μια οντότητα. Πάντα προστατεύστε με ένα instanceof έλεγχος πριν από την πρόσβαση Mesh-συγκεκριμένες ιδιότητες όπως controlPoints.
• Ορισμός normalizeNormal = true σε ObjLoadOptions όταν τα πηγαία αρχεία OBJ προέρχονται από μη αξιόπιστες πηγές. Αυτό αποτρέπει την εξάπλωση εκφυλισμένων κανονικών σε επόμενα βήματα απόδοσης ή επικύρωσης.
• Διατηρήστε strict: true στο tsconfig.json: η βιβλιοθήκη είναι γραμμένη με noImplicitAny και strictNullChecks. strict Απενεργοποίηση.
• καλύπτει πραγματικά σφάλματα τύπου και αναιρεί την αξία του τυποποιημένου API. childNodes,Περιηγηθείτε μέσω:, όχι βρόχο δείκτη childNodes : το.

Συνηθισμένα Προβλήματα

Συχνές Ερωτήσεις

Απαιτεί η βιβλιοθήκη κάποιον εγγενή πρόσθετο ή πακέτα συστήματος;? Όχι. Aspose.3D FOSS for TypeScript έχει μια μόνο εξάρτηση χρόνου εκτέλεσης: xmldom, η οποία είναι καθαρή JavaScript και εγκαθίσταται αυτόματα από το npm. Δεν υπάρχουν .node εγγενή πρόσθετα και κανένα πακέτο συστήματος προς εγκατάσταση.

Ποιες εκδόσεις του Node.js υποστηρίζονται;? Node.js 18, 20 και 22 LTS. Η βιβλιοθήκη στοχεύει σε έξοδο CommonJS και χρησιμοποιεί εσωτερικά χαρακτηριστικά γλώσσας ES2020.

Μπορώ να χρησιμοποιήσω τη βιβλιοθήκη σε πακέτο προγράμματος περιήγησης (webpack/esbuild);? Η βιβλιοθήκη στοχεύει στο Node.js και χρησιμοποιεί το Node.js fs και Buffer API. Η δημιουργία πακέτου για πρόγραμμα περιήγησης δεν υποστηρίζεται επίσημα. Για χρήση σε πρόγραμμα περιήγησης, φορτώστε τη σκηνή από την πλευρά του διακομιστή και μεταδώστε το αποτέλεσμα (π.χ., ως GLB) στον πελάτη.

Ποια είναι η διαφορά μεταξύ GltfSaveOptions.binaryMode = true και false? binaryMode = false παράγει ένα .gltf αρχείο JSON συν ένα ξεχωριστό .bin δυαδικό buffer sidecar. binaryMode = true παράγει ένα ενιαίο αυτό-συμπεριλαμβανόμενο .glb αρχείο. Χρησιμοποιήστε true για την παράδοση περιουσιακών στοιχείων παραγωγής.

Μπορώ να φορτώσω ένα αρχείο από μια HTTP απόκριση χωρίς να το αποθηκεύσω στο δίσκο;? Ναι. Λάβετε την απόκριση ως ένα Buffer (π.χ., χρησιμοποιώντας node-fetch ή το ενσωματωμένο fetch σε Node 18+), στη συνέχεια καλέστε scene.openFromBuffer(buffer, options).

Είναι η υποστήριξη FBX πλήρης;? Η ανάγνωση και η εγγραφή FBX υποστηρίζονται για την ιεραρχία σκηνής, τα δεδομένα πλέγματος και γεωμετρίας, τα κλιπ κίνησης και τα υλικά. Πολύ σύνθετα αρχεία FBX με ενσωματωμένα μέσα ενδέχεται να παράγουν μερικά αποτελέσματα· δοκιμάστε με το συγκεκριμένο σύνολο περιουσιακών στοιχείων σας.

Η βιβλιοθήκη υποστηρίζει το TypeScript 4.x;? Συνιστάται το TypeScript 5.0+. Το TypeScript 4.7+ θα πρέπει να λειτουργεί στην πράξη, αλλά η βιβλιοθήκη δοκιμάζεται και αναπτύσσεται εναντίον του 5.0+.

Σύνοψη Αναφοράς API