Ominaisuudet ja toiminnot

Aspose.3D FOSS for TypeScript on MIT-lisenssiä käyttävä Node.js-kirjasto 3D‑kohtauksien lataamiseen, rakentamiseen ja viemiseen. Se toimitetaan täydellisten TypeScript-tyyppimäärittelyjen, yhden ajoympäristön riippuvuuden (xmldom), ja tuki kuudelle tärkeimmälle 3D-tiedostomuodolle. Tämä sivu on ensisijainen viite kaikille ominaisuusalueille ja sisältää suoritettavia TypeScript-koodiesimerkkejä jokaiselle.

Asennus ja käyttöönotto

Asenna paketti npm:stä yhdellä komennolla:

npm install @aspose/3d

Paketti kohdistuu CommonJS:ään ja vaatii Node.js 18:n tai uudemman. Asennuksen jälkeen tarkista, että sinun tsconfig.json sisältää seuraavat kääntäjäasetukset täyden yhteensopivuuden varmistamiseksi:

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

Tuo pää Scene luokka paketin juuresta. Formaattiin spesifiset asetusluokat tuodaan niiden vastaavista alipoluista:

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

Ominaisuudet ja toiminnot

Formaattituen

Aspose.3D FOSS for TypeScript lukee ja kirjoittaa kuutta tärkeintä 3D‑tiedostomuotoa. Formaattien tunnistus tapahtuu automaattisesti binääristen taikamerkkien perusteella latauksen yhteydessä, joten sinun ei tarvitse määrittää lähdeformaattia erikseen.

OBJ:n lataaminen materiaaleilla:

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

Tallentaminen GLB:ksi (binäärinen 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);

Scene Graph

Kaikki 3D-sisältö on järjestetty puuna, jossa on Node objekteja, joiden juuri on scene.rootNode. Jokainen solmu voi kantaa Entity (yksi Mesh, Camera, Light, tai muuta SceneObject) ja Transform joka asettaa sen suhteessa sen vanhempaan.

Keskeiset kohtausgrafiikkaluokat:

• Scene: ylimmän tason säiliö; sisältää rootNode ja animationClips
• Node: nimetty puun solmu, jossa on childNodes, entity, transform, ja materials
• Entity: perusluokka liitettäville objekteille (Mesh, Camera, Light)
• SceneObject: perusluokka, jonka jakavat Node ja Entity
• A3DObject: juuriperusluokka, jossa on name ja property bag
• Transform: paikallinen siirto, kierto (Euler ja Quaternion) ja skaalaus

Kohtausgrafiikan läpikäynti:

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

Luodaan kohtauksen hierarkia ohjelmallisesti:

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 ja Mesh

Mesh on ensisijainen geometria-tyyppi. Se laajentaa Geometry ja paljastaa ohjauspisteet (solmut), polygonin indeksit ja solmu-elementit normaalivektoreille, UV-koordinaateille ja solmuväreille.

Keskeiset geometria-luokat:

• Mesh: polygoniverkko, jossa on controlPoints ja polygonCount
• Geometry: perusluokka, jossa on solmu-elementtien hallinta
• VertexElementNormal: kärjen tai monikulmion kärjen normaalit
• VertexElementUV: tekstuurikoordinaatit (yksi tai useampi UV-kanava)
• VertexElementVertexColor: kärjen väritiedot
• MappingMode: ohjaa, miten elementtien tiedot kartoittuvat monikulmioihin (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: ohjaa indeksointistrategiaa (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: tunnistaa vertex-elementin semantiikan
• TextureMapping: tekstuurikanavan luettelo

Mesh-datan lukeminen ladatusta kohtauksesta:

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

Materiaalijärjestelmä

Aspose.3D FOSS for TypeScript tukee kolmea materiaalityyppiä, jotka kattavat koko skaalan perinteisestä Phong-varjostuksesta fysikaalisesti perustuvaan renderöintiin:

• LambertMaterial: diffuusiväri ja ambienttiväri; kartoittaa yksinkertaisiin OBJ/DAE-materiaaleihin
• PhongMaterial: lisää spekulaarivärin, kiillon ja emissiivisyyden; oletus OBJ-materiaalityyppi
• PbrMaterial: fysiikkaan perustuva roughness/metallic-malli; käytetään glTF 2.0 -tuontiin ja -vientiin

Materiaalien lukeminen ladatusta OBJ‑kohtauksesta:

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‑materiaalin soveltaminen glTF‑kohtauksen rakentamisessa:

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

Matematiikka-apuohjelmat

Kirjasto toimitetaan täydellisen 3D‑matematiikkatyyppien kokoelman kanssa, kaikki täysin tyypitettyinä:

• Vector3: 3-komponenttinen vektori; tukee minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: 4-komponenttinen vektori homogeenisille koordinaateille
• Matrix4: 4×4-muunnosmatriisi, jossa on concatenate(), transpose, decompose, setTRS
• Quaternion: kiertoskvaternion, jossa on fromEulerAngle() (staattinen, yksittäinen), eulerAngles() (instanssimenetelmä), slerp(), normalize()
• BoundingBox: akselikohtainen raja-ala, jossa on minimum, maximum, center, size, merge
• FVector3: yksittäistarkkuusversio Vector3 : käytetään vertex-elementin datassa

Rajaustilan laskeminen verkon vertexeista:

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

Muunnoksen rakentaminen Euler‑kulmista:

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

Animaatiojärjestelmä

Animaatio‑API mallintaa leikkeet, solmut, kanavat ja avainruutusekvenssit:

• AnimationClip: nimetty kokoelma animaatiosolmuja; käytettävissä kautta scene.animationClips; paljastaa animations: AnimationNode[]
• AnimationNode: nimetty ryhmä BindPoints; luotu kautta clip.createAnimationNode(name), käytetty kautta clip.animations
• BindPoint:sidontaa AnimationNode tiettyyn ominaisuuteen kohtausobjektissa; paljastaa property ja channelsCount
• AnimationChannel:laajentaa KeyframeSequence; pitää erillisen keyframeSequence; käytettävissä kautta bindPoint.getChannel(name)
• KeyFrame: yksi aika/arvo-pari; kantaa avainruutua kohti interpolation: Interpolation
• KeyframeSequence: järjestetty luettelo KeyFrame objekteja kautta keyFrames; sisältää preBehavior ja postBehavior (Extrapolation)
• Interpolation: enum: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: luokka, jossa type: ExtrapolationType ja repeatCount: number
• ExtrapolationType: enum: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Animaatiotietojen lukeminen ladatusta kohtauksesta:

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

Suoratoisto- ja puskurituki

Käytä scene.openFromBuffer() ladata 3D‑kohtaus suoraan muistissa olevasta Buffer. Tämä on suositeltu malli serverittömille funktioille, suoratoistoputkille ja HTTP:n kautta haettujen resurssien käsittelyyn ilman kirjoittamista levylle.

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

Muodon automaattinen tunnistus binääristen taikamerkkien perusteella pätee, kun ladataan puskurista, joten GLB-, STL‑binääri- ja 3MF‑tiedostot tunnistetaan ilman, että formaattiparametria täytyy määrittää.

Käyttöesimerkit

Esimerkki 1: Lataa OBJ ja vie GLB‑muotoon

Tässä esimerkissä ladataan Wavefront‑OBJ‑tiedosto materiaaleineen, jonka jälkeen kohtaus viedään binäärisenä glTF‑ (GLB) -tiedostona, joka soveltuu web‑ ja pelimoottorikäyttöön.

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

Esimerkki 2: Kiertomatka STL‑tiedostolle normaalien tarkistuksella

Tässä esimerkissä ladataan binäärinen STL‑tiedosto, tulostetaan jokaisen kärjen normaalitiedot, jonka jälkeen kohtaus viedään ASCII‑STL‑muotoon ja tarkistetaan kiertomatkan onnistuminen.

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

Esimerkki 3: Rakenna kohtaus ohjelmallisesti ja tallenna glTF-muodossa

Tämä esimerkki rakentaa kohtauksen PBR-materiaalilla alusta alkaen ja tallentaa sen JSON glTF -tiedostona.

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

Vinkkejä ja parhaita käytäntöjä

• Käytä ObjLoadOptions.enableMaterials = true kun tarvitset materiaalitietoja .mtl‑tiedostoista. Ilman sitä jokaisen solmun materiaaliluettelo on tyhjä.
• Suosi binaryMode = true GLB:lle kun tuotetaan omaisuuksia verkkoon tai pelimoottoreihin. Binäärinen GLB on yksi itsenäinen tiedosto ja latautuu nopeammin selaimissa ja moottoreissa kuin JSON + .bin -jako.
• Käytä openFromBuffer() palvelimettomissa ympäristöissä välttääkseen tilapäisiä tiedosto‑I/O-toimintoja. Hae omaisuus, välitä Buffer suoraan, ja kirjoita tulos virtaan tai toiseen puskuriin.
• Tarkista node.entity ennen muuntamista: kaikki solmut eivät sisällä entiteettiä. Suojaa aina instanceof tarkistuksella ennen pääsyä Mesh-spesifisiä ominaisuuksia kuten controlPoints.
• Aseta normalizeNormal = true kohteessa ObjLoadOptions kun lähde‑OBJ‑tiedostosi tulevat epäluotettavista lähteistä. Tämä estää degeneraattorien normaalien leviämisen myöhemmiin renderöinti- tai validointivaiheisiin.
• Säilytä strict: true tsconfig.jsonissa: kirjasto on kirjoitettu käyttäen noImplicitAny ja strictNullChecks. Poistetaan käytöstä strict peittää todelliset tyyppivirheet ja heikentää tyypitetyn API:n arvoa.
• Kulje kautta childNodes, ei indeksointisilmukkaa: childNodes ominaisuus palauttaa iteroitavan; vältä numeeriseen indeksointiin turvautumista etukäteisyhteensopivuuden vuoksi.

Yleisiä ongelmia

Usein kysytyt kysymykset

Vaatiiko kirjasto mitään natiiveja lisäosia tai järjestelmäpaketteja? Ei. Aspose.3D FOSS for TypeScriptilla on yksi ajoympäristön riippuvuus: xmldom, joka on puhdasta JavaScriptiä ja asennetaan automaattisesti npm:n kautta. Ei ole .node natiiveja lisäosia eikä asennettavia järjestelmäpaketteja.

Mitä Node.js-versioita tuetaan? Node.js 18, 20 ja 22 LTS. Kirjasto kohdistuu CommonJS‑tulosteeseen ja käyttää sisäisesti ES2020‑kieliominaisuuksia.

Voinko käyttää kirjastoa selaimen pakettina (webpack/esbuild)? Kirjasto kohdistuu Node.js:ään ja käyttää Node.js:ää fs ja Buffer API:t. Selaimen pakkaamista ei tueta virallisesti. Selaimessa käytettäväksi lataa kohtaus palvelinpuolella ja lähetä tulos (esim. GLB) asiakkaalle.

Mikä on ero GltfSaveOptions.binaryMode = true ja false? binaryMode = false tuottaa .gltf JSON-tiedoston sekä erillisen .bin binääripuskuri‑sivukappaleen. binaryMode = true tuottaa yhden itsenäisen .glb tiedoston. Käytä true tuotantokohteiden toimitukseen.

Voinko ladata tiedoston HTTP‑vastauksesta tallentamatta sitä levylle? Kyllä. Hae vastaus muodossa Buffer (esim. käyttäen node-fetch tai sisäänrakennettua fetch Node 18+:ssa), ja kutsu sitten scene.openFromBuffer(buffer, options).

Onko FBX‑tuki täydellinen? Ei. FBX‑tuonti‑ ja vientiluokat ovat kirjastossa, mutta FBX ei ole kytketty Scene.open() tai Scene.save() automaattinen tunnistus. Kutsuminen scene.open('file.fbx') ei käynnistä FBX-tuontijaa; tiedosto käsitellään STL-varmistuspolun kautta. Käytä FBX-spesifisiä tuonti-/vientiluokkia suoraan, jos tarvitset FBX I/O:ta. Katso yllä oleva formaattituen taulukko, jossa FBX on merkitty No*.

Tukeeko kirjasto TypeScript 4.x:ää? TypeScript 5.0+ on suositeltu. TypeScript 4.7+ pitäisi toimia käytännössä, mutta kirjasto on testattu ja kirjoitettu 5.0+:n kanssa.

API-viitteiden yhteenveto