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

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

Εγκατάσταση και εγκατάστασης

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

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

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

Η εισαγωγή του κύριου Scene Οι κατηγορίες επιλογών που ειδικεύονται σε μορφή εισάγονται από τις αντίστοιχες υπο-δρόμοι τους:

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

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

Στήριξη μορφοποίησης

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

Κατεβάστε 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 (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);

Σκηνή Γκράφι

Όλα τα 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 είναι το κύριο είδος γεωμετρίας. επεκτείνεται Geometry και εκθέτει σημεία ελέγχου (αποκλίες), δείκτες πολυγόνου, και στοιχεία κατώφλισης για τα φυσιολογικά, UVs, καθώς και χρώματα κατωφής.

Κλειδιά της γεωμετρικής:

• Mesh:Πολυγώνιο με controlPoints και polygonCount
• Geometry:• Η διαχείριση των στοιχείων vertex-element
• VertexElementNormal:• Ο κανονικός πολλαπλός/πολιγών/βερτεξ
• VertexElementUV:• Συντονισμοί υφάσματος (ένα ή περισσότερα κανάλια UV)
• VertexElementVertexColor:Πληροφορίες χρωμάτων per-vertex
• MappingMode: ελέγχει πώς τα στοιχεία δεδομένων χάρτη σε πολυγόνους (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode:Η ΕΠΙΤΡΟΦΗ ΤΗΣ ΔΙΑΔΙΚΑΣΤΙΚΗΣ ΠΡΟΣΟΧΗΣ (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType:• Αναγνωρίζει την σημαντική ενός στοιχείου vertex.
• 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 { 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);

Μαθηματικά χρήματα

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

• Vector3:3ο τμήμα του εμβέτη, υποστηρίζει minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4:4ο βέκτορα για ομοιογενείς συντονιστές
• Matrix4:4×4 μετασχηματισμός με concatenate(), transpose, decompose, setTRS
• Quaternion:• Κύκλος περιστροφής με fromEulerAngle() (Στοπική και μοναδική), eulerAngles() (η μέθοδος της υπόθεσης), slerp(), normalize()
• BoundingBox: οξυ-αλληλογημένο δεξαμενόπλοιο με minimum, maximum, center, size, merge
• FVector3:• Μοναδική επιλογή από την Vector3 Η χρήση των στοιχείων Vertex

Υπολογισμός ενός κουτιού συνόρων από τις κατώτερες σκαλοπάτες:

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

Συστήματα Animation

Τα μοντέλα API animation κλιπ, κόμβοι, κανάλια και ακολουθίες κλειδιά:

• AnimationClip: ονομαστική συλλογή των κόμβων animation. προσβάλλεται μέσω scene.animationClips;· Εκθέσεις animations: AnimationNode[]
• AnimationNode:Ονομαστική ομάδα των BindPointΣ. Δημιουργήθηκε μέσω clip.createAnimationNode(name),Η πρόσβαση μέσω clip.animations
• BindPoint:• Συνδέει ένα AnimationNode σε ένα συγκεκριμένο ακίνητο σε αντικείμενο σκηνής· εκθέσεις property και channelsCount
• AnimationChannel:• Επέκταση KeyframeSequence;· Διατηρεί ξεχωριστό keyframeSequence;• Διαθέσιμο μέσω bindPoint.getChannel(name)
• KeyFrame: ένα ζευγάρι χρόνου / αξίας, φέρει ανά κλειδί interpolation: Interpolation
• KeyframeSequence:Η παραγγελία λίστα των KeyFrame Πληροφορίες μέσω keyFrames;· έχει preBehavior και postBehavior (Extrapolation)
• Interpolation:Ο ΕΝΟΜ: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation:• Η τάξη με type: ExtrapolationType και repeatCount: number
• ExtrapolationType:Ο ΕΝΟΜ: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Διαβάστε τα δεδομένα κινουμένων σχεδίων από μια φορτισμένη σκηνή:

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

Στήριξη Stream & Buffer

Χρησιμοποιήστε scene.openFromBuffer() να φορτίσετε μια σκηνή 3D απευθείας από ένα in-memory Buffer.Αυτό είναι το συνιστώμενο πρότυπο για λειτουργίες χωρίς διακομιστή, σωλήνες streaming και περιουσιακά στοιχεία επεξεργασίας που συλλέγονται μέσω 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: Στρογγυλό STL με κανονική επικύρωση

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

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

Συμβουλές και βέλτιστες πρακτικές

• Χρησιμοποιήστε ObjLoadOptions.enableMaterials = true Όποτε χρειάζεστε δεδομένα υλικού από αρχεία .mtl. Χωρίς αυτό, η λίστα υλικά σε κάθε κόμβο θα είναι άδειο.
• Προτιμώ binaryMode = true Για την GLB Όταν παράγουμε περιουσιακά στοιχεία για web ή κινητήρες παιχνιδιών.Binary GLB είναι ένα μοναδικό αυτό-συμπεριλαμβανόμενο αρχείο και φορτώνει ταχύτερα σε προγράμματα περιήγησης και μηχανές από το JSON + .bin split.
• Χρησιμοποιήστε openFromBuffer() Σε περιβάλλον χωρίς server για να αποφύγετε προσωρινά αρχεία I/O. Fetch το περιουσιακό στοιχείο, περάστε την Buffer απευθείας, και γράψτε την έκδοση σε ένα ρεύμα ή άλλο buffer.
• Ελέγξτε node.entity Πριν το casting:Δεν είναι όλα τα κόμβα που φέρουν μια οντότητα.Πάντα να φροντίζετε με ένα instanceof Ελέγξτε πριν από την πρόσβαση Mesh- ειδικές ιδιότητες όπως controlPoints.
• ΣΕΤΙΔΑ normalizeNormal = true Σε ObjLoadOptions όταν τα αρχεία OBJ προέρχονται από μη αξιόπιστες πηγές. αυτό εμποδίζει την αποσύνδεση των κανονικών να εξαπλωθεί σε βήματα παραπομπής ή επικύρωσης.
• Κρατήστε strict: true Στον Τσκόρ.JSON:Η βιβλιοθήκη είναι γραμμένη με noImplicitAny και strictNullChecks.Απαλλαγή strict Μασκάρετε τα πραγματικά σφάλματα τύπου και χάνετε την αξία του τυποποιημένου API.
• Περνάμε μέσω childNodes,Όχι ένα index loop.:• Το childNodes Η ιδιοκτησία επιστρέφει ένα μη αναγνωρίσιμο. αποφεύγοντας να βασιστείτε στην αριθμητική ενσωμάτωση για προοδευτική συμβατότητα.

κοινά ζητήματα

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

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

Ποια εκδόσεις Node.js υποστηρίζονται;? Node.js 18, 20, and 22 LTS. The library targets CommonJS output and uses ES2020 language features internally.

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

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

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

Η υποστήριξη του FBX είναι πλήρης;? Δεν υπάρχουν FBX εισαγωγείς και εξαγωγητές τάξεις στη βιβλιοθήκη, αλλά το FB X δεν είναι συνδεδεμένο σε Scene.open() ή Scene.save() Αυτοαποκαλύψεις - Καλέστε scene.open('file.fbx') δεν θα επικαλεστεί το εισαγωγέα FBX· το αρχείο θα χειριστεί από την οδό αποχώρησης STL. Χρησιμοποιήστε τις κατηγορίες εισαγορά/εξαγωγής που είναι ειδικές για το FBx απευθείας εάν χρειάζεστε το FbX I/O. Δείτε τον πίνακα υποστήριξης μορφής παραπάνω στον οποίο σημειώνεται το fbx ως: No*.

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

Συνοπτική αναφορά API