3D-formatunderstøttelse

Aspose.3D FOSS for TypeScript læser og skriver syv store 3D‑filformater. Formatdetektering er automatisk ved indlæsning: biblioteket inspicerer binære magiske tal, så du ikke behøver at angive kildeformatet. Format‑specifikke optionsklasser importeres fra under‑stier af @aspose/3d pakke.

Understøttede formater

OBJ (Wavefront)

OBJ understøtter både import og eksport i @aspose/3d. Når du gemmer som OBJ, er materialebiblioteket (.mtl) skrives automatisk ved siden af .obj fil. Brug ObjLoadOptions til at kontrollere materialelæsning og koordinatsystemets opførsel.

Vigtige indstillinger for ObjLoadOptions:

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const scene = new Scene();
const opts = new ObjLoadOptions();
opts.enableMaterials = true;
opts.normalizeNormal = true;

scene.open('model.obj', opts);
console.log(`Loaded ${scene.rootNode.childNodes.length} top-level node(s)`);

For at konvertere en OBJ til et hvilket som helst skrivbart format, indlæs den og kald scene.save() med målformatklassen.

glTF and GLB

glTF 2.0 er det anbefalede udvekslingsformat til web- og spilmotorbrug. Biblioteket bruger den samme GltfFormat klasse til både .gltf (JSON + sidecar) og .glb (binær, selvstændig) output. Skift mellem dem med GltfSaveOptions.binaryMode.

Indlæs glTF eller GLB:

import { Scene } from '@aspose/3d';
import { GltfLoadOptions } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('model.gltf', new GltfLoadOptions());
// or
scene.open('model.glb');  // format detected from magic bytes

Eksporter som JSON glTF (.gltf + .bin):

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

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

const opts = new GltfSaveOptions();
opts.binaryMode = false;  // produces output.gltf + output.bin
scene.save('output.gltf', GltfFormat.getInstance(), opts);

Eksporter som binær GLB (.glb):

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

const scene = new Scene();
scene.open('input.obj');

const opts = new GltfSaveOptions();
opts.binaryMode = true;  // single self-contained file
scene.save('output.glb', GltfFormat.getInstance(), opts);

Brug binaryMode = true til produktionslevering af asset. En enkelt .glb indlæses hurtigere i browsere og motorer end det opdelt tekst + binary-par.

STL

STL er et trianguleret mesh-format, der bruges i CAD og 3D-print. Både binær og ASCII STL understøttes til ind- og uddata. StlSaveOptions.binaryMode styrer om output er binær (kompakt) eller ASCII (menneskelæselig).

import { Scene } from '@aspose/3d';
import { StlLoadOptions, StlSaveOptions } from '@aspose/3d/formats/stl';

const scene = new Scene();
scene.open('model.stl', new StlLoadOptions());

// Export as binary STL (default, compact)
const binaryOpts = new StlSaveOptions();
binaryOpts.binaryMode = true;
scene.save('output_binary.stl', binaryOpts);

// Export as ASCII STL (human-readable)
const asciiOpts = new StlSaveOptions();
asciiOpts.binaryMode = false;
scene.save('output_ascii.stl', asciiOpts);

STL gemmer kun trianguleret geometri og vertex‑normals. Materiale‑ og UV‑data bevares ikke i STL.

3MF (3D Manufacturing Format)

3MF is an XML-based format designed for additive manufacturing. It supports color and material metadata alongside geometry. Use it when exchanging files with 3D printing slicers or manufacturing workflows.

import { Scene } from '@aspose/3d';
import { ThreeMfSaveOptions } from '@aspose/3d/formats/3mf';

const scene = new Scene();
scene.open('model.3mf');

// Re-export as 3MF
scene.save('output.3mf', new ThreeMfSaveOptions());

3MF files are ZIP archives internally. The library handles archive creation and extraction automatically.

FBX

Advarsel: FBX-import- og -eksportklasser (FbxImporter, FbxExporter) findes i biblioteket, men automatisk genkendelse af FBX-format er ikke indkoblet i scene.open() eller scene.save(). Kald scene.open('file.fbx') vil ikke aktivere FBX-importøren — filen vil falde igennem til STL-reserven. scene.save('output.fbx', opts) vil ikke aktivere FBX-eksportøren. Formatunderstøttelsestabellen ovenfor markerer FBX som No* af denne grund. Brug GLB eller COLLADA for fuldt funktionel import og eksport via scene.open() / scene.save().

COLLADA (DAE)

COLLADA er et XML-baseret udvekslingsformat, der understøttes af en bred vifte af DCC-værktøjer (Blender, Maya, Cinema 4D). Biblioteket bruger xmldom afhængighed til XML-parsing; den installeres automatisk med npm install @aspose/3d.

import { Scene } from '@aspose/3d';
import { ColladaSaveOptions } from '@aspose/3d/formats/collada';

const scene = new Scene();
scene.open('model.dae');

// Re-export as COLLADA
const saveOpts = new ColladaSaveOptions();
scene.save('output.dae', saveOpts);

COLLADA-filer kan indeholde metadata for enhedsskala (<unit> element). Biblioteket anvender automatisk enhedskonvertering ved indlæsning.

Automatisk formatgenkendelse

Når du indlæser fra en filsti, forsøger biblioteket at detektere formatet ud fra binære magiske tal, før det falder tilbage på filendelsen. Det betyder, at du kan indlæse en GLB-fil med navnet .bin eller en STL-fil med navnet .model uden at angive formatet eksplicit.

Når du indlæser fra en Buffer med scene.openFromBuffer(), magic-number-detektion er den primære mekanisme:

import { Scene } from '@aspose/3d';
import * as fs from 'fs';

const buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(buffer);  // format detected from magic bytes: 'glTF'

console.log(`Root has ${scene.rootNode.childNodes.length} child node(s)`);

Formater med pålidelige magic numbers: GLB (glTF), STL binær (80-byte header + trekantsantal), 3MF (ZIP magic PK). OBJ og COLLADA er tekstbaserede og detekteres ud fra filendelse eller via den options-klasse du sender.

Tips

• OBJ understøtter både import og eksport: når du gemmer som OBJ, .mtl materialfilen skrives automatisk ved siden af den .obj filen.
• Brug GLB til weblevering: det selvstændige binære format undgår CORS-problemer med .bin sidecars og indlæses hurtigere i WebGL-renderere.
• Send format-specifikke indstillinger: generisk scene.open(path) virker for de fleste formater, men ved at sende loader‑options‑klassen aktiveres format‑specifik adfærd såsom OBJ‑materialelæsning eller STL‑koordinatnormalisering.
• xmldom kræves for COLLADA: den installeres automatisk. Tilføj den ikke til peerDependencies eller prøv at fjerne den; COLLADA‑læseren kalder den direkte.

Almindelige problemer

Se også

• Funktioner og funktionaliteter: scene graph, mesh, materials, animation, and math APIs.
• Scenegraf: opbygning og traversering af nodetræet.
• Hvordan man bygger en 3D Mesh programmatisk.