Podpora 3D formátov

Aspose.3D FOSS pre TypeScript číta a zapisuje sedem hlavných 3D formátov súborov. Detekcia formátu je pri načítaní automatická: knižnica kontroluje binárne magické čísla, takže nie je potrebné špecifikovať zdrojový formát. Triedy možností špecifické pre formát sa importujú z podcestiek balíka @aspose/3d balíka.

Podporované formáty

OBJ (Wavefront)

OBJ podporuje import aj export v @aspose/3d. Pri ukladaní ako OBJ je knižnica materiálov (.mtl) sa zapíše automaticky vedľa .obj súbor. Použite ObjLoadOptions na kontrolu načítania materiálu a správania súradnicového systému.

Kľúčové možnosti pre 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)`);

Na konverziu OBJ do akéhokoľvek zapisovateľného formátu ho načítajte a zavolajte scene.save() s triedou cieľového formátu.

glTF and GLB

glTF 2.0 je odporúčaný výmenný formát pre použitie na webe a v herných enginoch. Knižnica používa rovnaký GltfFormat triedu pre oba .gltf (JSON + sidecar) a .glb (binárny, samostatný) výstup. Prepínajte medzi nimi pomocou GltfSaveOptions.binaryMode.

Načítajte glTF alebo 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

Exportovať ako 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);

Exportovať ako binárny 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);

Použiť binaryMode = true pre produkčné doručovanie aktív. Jeden .glb sa načítava rýchlejšie v prehliadačoch a enginoch než rozdelený text + binárny pár.

STL

STL je formát triangulovanej siete používaný v CAD a 3D tlači. Pre vstup aj výstup sú podporované binárne aj ASCII STL. StlSaveOptions.binaryMode ovláda, či je výstup binárny (kompaktný) alebo ASCII (čitateľný pre človeka).

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 ukladá iba triangulovanú geometriu a normály vrcholov. Materiál a UV dáta nie sú v STL zachované.

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

Upozornenie: Triedy importéra a exportéra FBX (FbxImporter, FbxExporter) existujú v knižnici, ale automatická detekcia formátu FBX je neimplementovaná do scene.open() alebo scene.save(). Volanie scene.open('file.fbx') nevyvolá importér FBX — súbor prejde na záložný STL. scene.save('output.fbx', opts) nevyvolá exportér FBX. Tabuľka podpory formátov vyššie označuje FBX ako No* z tohto dôvodu. Použite GLB alebo COLLADA pre plne funkčný import a export cez scene.open() / scene.save().

COLLADA (DAE)

COLLADA je XML‑založený výmenný formát podporovaný širokou škálou DCC nástrojov (Blender, Maya, Cinema 4D). Knižnica používa xmldom závislosť na parsovanie XML; je automaticky nainštalovaná s 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);

Súbory COLLADA môžu obsahovať metadáta o škálovaní jednotiek (<unit> element). Knižnica automaticky aplikuje konverziu jednotiek pri načítaní.

Automatická detekcia formátu

Pri načítavaní z cesty k súboru sa knižnica najprv pokúša o detekciu formátu pomocou binárnych magických čísel, predtým než sa vráti k príponke súboru. To znamená, že môžete načítať súbor GLB s názvom .bin alebo súbor STL s názvom .model bez explicitného zadania formátu.

Pri načítavaní z Buffer s scene.openFromBuffer(), detekcia magic-number je primárny mechanizmus:

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

Formáty s spoľahlivými magic-number: GLB (glTF), binárny STL (80-byte hlavička + počet trojuholníkov), 3MF (ZIP magic PK). OBJ a COLLADA sú textové a sú detekované podľa prípony súboru alebo triedou možností, ktorú zadáte.

Tipy

• OBJ podporuje import aj export: pri ukladaní ako OBJ sa .mtl súbor materiálu zapíše automaticky vedľa .obj súboru.
• Použite GLB pre webové doručenie: samostatný binárny formát zabraňuje problémom CORS s .bin prílohami a načítava sa rýchlejšie v rendereroch WebGL.
• Poskytnite možnosti špecifické pre formát: všeobecné scene.open(path) funguje pre väčšinu formátov, ale odovzdanie triedy možností načítača umožní správanie špecifické pre formát, ako je načítanie materiálu OBJ alebo normalizácia súradníc STL.
• xmldom je potrebné pre COLLADA: je nainštalovaný automaticky. Nepridávajte ho do peerDependencies alebo sa ho pokúste odstrániť; čítač COLLADA ho volá priamo.

Bežné problémy

Pozri tiež

• Funkcie a vlastnosti: graf scény, sieť, materiály, animácia a matematické API.
• Graf scény: vytváranie a prechádzanie stromom uzlov.
• Ako programovo zostaviť 3D mesh.