Podpora 3D formátů

Aspose.3D FOSS pro TypeScript čte a zapisuje sedm hlavních 3D formátů souborů. Detekce formátu je při načítání automatická: knihovna kontroluje binární magické čísla, takže není nutné zadávat zdrojový formát. Třídy možností specifické pro formát jsou importovány z podcest @aspose/3d balíčku.

Podporované formáty

OBJ (Wavefront)

OBJ podporuje jak import, tak export v @aspose/3d. Při ukládání jako OBJ je knihovna materiálů (.mtl) se zapíše automaticky vedle .obj souboru. Použijte ObjLoadOptions k řízení načítání materiálu a chování souřadnicového systému.

Klíčové volby pro 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)`);

Pro převod OBJ do libovolného zapisovatelného formátu jej načtěte a zavolejte scene.save() s třídou cílového formátu.

glTF and GLB

glTF 2.0 je doporučený výměnný formát pro web a herní enginy. Knihovna používá stejný GltfFormat třídu pro oba .gltf (JSON + sidecar) a .glb (binární, samostatný) výstup. Přepínejte mezi nimi pomocí GltfSaveOptions.binaryMode.

Načíst glTF nebo 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

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

Exportovat jako binární 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žít binaryMode = true pro produkční doručení aktiv. Jedna .glb se načítá rychleji v prohlížečích a enginech než rozdělená textová + binární dvojice.

STL

STL je formát triangulované sítě používaný v CAD a 3D tisku. Jak binární, tak ASCII STL jsou podporovány pro vstup i výstup. StlSaveOptions.binaryMode řídí, zda je výstup binární (kompaktní) nebo ASCII (čitelné pro člověka).

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 ukládá pouze triangulovanou geometrii a normály vrcholů. Materiálová a UV data v STL nejsou zachována.

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

Varování: Třídy importéru a exportéru FBX (FbxImporter, FbxExporter) existují v knihovně, ale automatické rozpoznání formátu FBX je nepřipojeno do scene.open() nebo scene.save(). Volání scene.open('file.fbx') nevyvolá importér FBX — soubor přejde na záložní STL. scene.save('output.fbx', opts) nevyvolá exportér FBX. Tabulka podpory formátů výše označuje FBX jako No* z tohoto důvodu. Použijte GLB nebo COLLADA pro plně funkční import a export přes scene.open() / scene.save().

COLLADA (DAE)

COLLADA je na XML založený výměnný formát podporovaný širokou škálou DCC nástrojů (Blender, Maya, Cinema 4D). Knihovna používá xmldom závislost pro parsování XML; je instalována automaticky 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);

Soubory COLLADA mohou obsahovat metadata o škálování jednotek (<unit> prvek). Knihovna automaticky provádí převod jednotek při načítání.

Automatické rozpoznání formátu

Při načítání z cesty k souboru se knihovna nejprve pokusí o detekci formátu pomocí binárních magických čísel, než se vrátí k příponě souboru. To znamená, že můžete načíst soubor GLB pojmenovaný .bin nebo soubor STL pojmenovaný .model bez explicitního zadání formátu.

Při načítání z Buffer s scene.openFromBuffer(), detekce magic-number je hlavní mechanismus:

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 spolehlivými magic numbers: GLB (glTF), binární STL (80-byte hlavička + počet trojúhelníků), 3MF (ZIP magic PK). OBJ a COLLADA jsou textové a jsou detekovány podle přípony souboru nebo podle třídy možností, kterou předáte.

Tipy

• OBJ podporuje jak import, tak export: při ukládání jako OBJ se .mtl soubor materiálu je automaticky zapsán vedle .obj souboru.
• Použijte GLB pro webové doručení: samostatný binární formát zabraňuje problémům CORS s .bin vedlejšími soubory a načítá se rychleji ve WebGL rendererech.
• Předávejte formátově specifické možnosti: obecné scene.open(path) funguje pro většinu formátů, ale předání třídy možností načítače umožňuje formátově specifické chování, jako je načítání materiálu OBJ nebo normalizace souřadnic STL.
• xmldom je vyžadováno pro COLLADA: je nainstalováno automaticky. Nepřidávejte jej do peerDependencies nebo se ho pokuste odstranit; čtečka COLLADA jej volá přímo.

Běžné problémy

Viz také

• Funkce a vlastnosti: graf scény, síť, materiály, animace a matematické API.
• Graf scény: vytváření a procházení stromu uzlů.
• Jak programově vytvořit 3D mesh