Obsługa formatów 3D

Aspose.3D FOSS dla TypeScript odczytuje i zapisuje siedem głównych formatów plików 3D. Wykrywanie formatu jest automatyczne podczas ładowania: biblioteka sprawdza binarne liczby magiczne, więc nie musisz podawać formatu źródłowego. Klasy opcji specyficznych dla formatu są importowane z pod‑ścieżek pakietu. @aspose/3d pakietu.

Obsługiwane formaty

OBJ (Wavefront)

OBJ obsługuje zarówno import, jak i eksport w @aspose/3d. Podczas zapisywania jako OBJ, biblioteka materiałów (.mtl) jest zapisywane automatycznie obok .obj pliku. Użyj ObjLoadOptions do kontrolowania ładowania materiału i zachowania systemu współrzędnych.

Kluczowe opcje dla 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)`);

Aby przekonwertować plik OBJ na dowolny format zapisywalny, wczytaj go i wywołaj scene.save() z klasą formatu docelowego.

glTF and GLB

glTF 2.0 jest zalecanym formatem wymiany do użytku w sieci i silnikach gier. Biblioteka używa tego samego GltfFormat klasy dla obu .gltf (JSON + sidecar) i .glb (binary, self-contained) output. Przełączaj je za pomocą GltfSaveOptions.binaryMode.

Wczytaj glTF lub 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

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

Eksportuj jako binarny 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);

Użyj binaryMode = true do dostarczania zasobów w środowisku produkcyjnym. Jeden .glb wczytuje się szybciej w przeglądarkach i silnikach niż rozdzielona para tekst + binarny.

STL

STL jest formatem siatki trójkątowej używanym w CAD i druku 3D. Obsługiwane są zarówno binarne, jak i ASCII STL do wejścia i wyjścia. StlSaveOptions.binaryMode kontroluje, czy wyjście jest binarne (kompaktowe) czy ASCII (czytelne dla człowieka).

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 przechowuje tylko trójkątną geometrię i wektory normalne wierzchołków. Dane materiałów i UV nie są zachowywane w 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

Ostrzeżenie: Klasy importera i eksportera FBX (FbxImporter, FbxExporter) istnieją w bibliotece, ale automatyczne wykrywanie formatu FBX jest nie podłączone do scene.open() lub scene.save(). Wywołanie scene.open('file.fbx') nie wywoła importera FBX — plik przejdzie do awaryjnego STL. Wywołanie scene.save('output.fbx', opts) nie wywoła eksportera FBX. Tabela wsparcia formatów powyżej oznacza FBX jako No* z tego powodu. Użyj GLB lub COLLADA do w pełni funkcjonalnego importu i eksportu za pomocą scene.open() / scene.save().

COLLADA (DAE)

COLLADA jest formatem wymiany opartym na XML, obsługiwanym przez szeroką gamę narzędzi DCC (Blender, Maya, Cinema 4D). Biblioteka używa xmldom zależności do parsowania XML; jest instalowana automatycznie wraz z 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);

Pliki COLLADA mogą zawierać metadane skalowania jednostek (<unit> element). Biblioteka automatycznie stosuje konwersję jednostek podczas ładowania.

Automatyczne wykrywanie formatu

Podczas ładowania z ścieżki pliku biblioteka najpierw próbuje wykryć format na podstawie binarnych liczb magicznych, zanim przejdzie do rozszerzenia pliku. Oznacza to, że możesz załadować plik GLB o nazwie .bin lub plik STL o nazwie .model bez konieczności jawnego określania formatu.

Podczas ładowania z Buffer z scene.openFromBuffer(), wykrywanie magicznego numeru jest podstawowym mechanizmem:

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

Formaty z niezawodnymi numerami magicznymi: GLB (glTF), STL binarny (80‑bajtowy nagłówek + liczba trójkątów), 3MF (ZIP magic PK). OBJ i COLLADA są oparte na tekście i są wykrywane na podstawie rozszerzenia pliku lub klasy opcji, którą przekazujesz.

Wskazówki

• OBJ obsługuje zarówno import, jak i eksport: przy zapisywaniu jako OBJ, .mtl plik materiału jest zapisywany automatycznie obok .obj pliku.
• Użyj GLB do dostarczania w sieci:samodzielny format binarny unika problemów CORS z .bin sidecarów i ładuje się szybciej w rendererach WebGL.
• Przekaż opcje specyficzne dla formatu: ogólne scene.open(path) działa dla większości formatów, ale przekazanie klasy opcji loadera umożliwia zachowanie specyficzne dla formatu, takie jak ładowanie materiałów OBJ lub normalizację współrzędnych STL.
• xmldom jest wymagane dla COLLADA: jest instalowane automatycznie. Nie dodawaj go do peerDependencies lub nie próbuj go usuwać; czytnik COLLADA wywołuje go bezpośrednio.

Typowe problemy

Zobacz także

• Funkcje i możliwości: graf sceny, siatka, materiały, animacja i API matematyczne.
• Graf sceny: budowanie i przeglądanie drzewa węzłów.
• Jak programowo zbudować siatkę 3D.