3D-formatstöd

Aspose.3D FOSS för TypeScript läser och skriver sju stora 3D-filformat. Formatdetektering är automatisk vid inläsning: biblioteket inspekterar binära magiska tal så du behöver inte ange källformatet. Format‑specifika alternativklasser importeras från under‑sökvägar i @aspose/3d paketet.

Stödda format

OBJ (Wavefront)

OBJ stöder både import och export i @aspose/3d. När du sparar som OBJ, materialbiblioteket (.mtl) skrivs automatiskt bredvid .obj fil. Använd ObjLoadOptions för att kontrollera materialladdning och koordinatsystemets beteende.

Viktiga alternativ för 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)`);

För att konvertera en OBJ till något skrivbart format, läs in den och anropa scene.save() med målformatklassen.

glTF and GLB

glTF 2.0 är det rekommenderade utbytesformatet för webb- och spelmotoranvändning. Biblioteket använder samma GltfFormat klass för både .gltf (JSON + sidecar) och .glb (binär, självständig) utdata. Växla mellan dem med GltfSaveOptions.binaryMode.

Läs in 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

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

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

Använd binaryMode = true för produktionsleverans av tillgångar. En enda .glb laddas snabbare i webbläsare och motorer än det delade text + binary pair.

STL

STL är ett triangulerat mesh-format som används i CAD och 3D-utskrift. Både binära och ASCII STL stöds för in- och utdata. StlSaveOptions.binaryMode styr om utdata är binär (kompakt) eller ASCII (läsbar för människor).

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 lagrar endast triangulerad geometri och vertexnormaler. Material- och UV‑data bevaras inte 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

Varning: FBX-importör- och exportörklasser (FbxImporter, FbxExporter) finns i biblioteket, men automatisk detektering av FBX-format är inte ansluten till scene.open() eller scene.save(). Anropar scene.open('file.fbx') kommer inte att anropa FBX-importören — filen kommer att falla tillbaka på STL. scene.save('output.fbx', opts) kommer inte att anropa FBX-exportören. Formatstödtabellen ovan markerar FBX som No* av den anledningen. Använd GLB eller COLLADA för fullt funktionell import och export via scene.open() / scene.save().

COLLADA (DAE)

COLLADA är ett XML-baserat utbytesformat som stöds av ett brett spektrum av DCC-verktyg (Blender, Maya, Cinema 4D). Biblioteket använder den xmldom beroendet för XML‑parsing; det installeras automatiskt 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 innehålla enhets‑skalningsmetadata (<unit> element). Biblioteket tillämpar enhetskonvertering automatiskt vid inläsning.

Automatisk formatdetektering

När du laddar från en filsökväg försöker biblioteket att identifiera formatet med hjälp av binära magiska tal innan det faller tillbaka på filändelsen. Detta betyder att du kan ladda en GLB-fil som heter .bin eller en STL-fil som heter .model utan att specificera formatet explicit.

När du laddar från en Buffer med scene.openFromBuffer(), magisktaldetektering är den primära mekanismen:

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

Format med pålitliga magiska tal: GLB (glTF), STL binär (80-byte header + triangle count), 3MF (ZIP magic PK). OBJ och COLLADA är textbaserade och detekteras från filändelse eller via options‑klassen du skickar.

Tips

• OBJ stöder både import och export: när du sparar som OBJ, materialfilen .mtl skrivs automatiskt bredvid .obj filen.
• Använd GLB för webbdistribution: det självständiga binära formatet undviker CORS-problem med .bin sidecars och laddas snabbare i WebGL-renderare.
• Skicka format‑specifika alternativ: generisk scene.open(path) fungerar för de flesta format, men att skicka loader‑options‑klassen möjliggör format‑specifikt beteende såsom OBJ‑materialladdning eller STL‑koordinatnormalisering.
• xmldom krävs för COLLADA: det installeras automatiskt. Lägg inte till det i peerDependencies eller försök att ta bort det; COLLADA‑läsaren anropar det direkt.

Vanliga problem

Se även

• Funktioner och funktionaliteter: scengraf, mesh, material, animation och matematik-API:er.
• Scengraf: bygga och traversera nodträdet.
• Hur man bygger ett 3D-mesh programatiskt