Aspose.3D FOSS
TypeScript
開発者ガイド
Loading Models

3Dモデルの読み込み

@aspose/3d は、2つのロード方法を提供します Scene クラス: open() ファイルパスによるロード用と openFromBuffer() メモリ内データ用です。フォーマット検出はバイナリのマジックナンバーまたはファイル拡張子から自動的に行われるため、ソースフォーマットを明示的に指定する必要はほとんどありません。.

ファイルパスからのロード

ファイルパス文字列を渡す scene.open().。ライブラリはファイル拡張子からフォーマットを検出し、バイナリ形式の場合はマジックバイトから検出します:

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

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

console.log(`Root children: ${scene.rootNode.childNodes.length}`);
console.log(`Animation clips: ${scene.animationClips.length}`);

open() 既存のシーン内容を置き換えます。複数のファイルをロードする必要がある場合は、別々の Scene インスタンスを作成してください。.

マテリアル付きOBJのロード

OBJ ファイルはサイドカーファイルを介してマテリアルを参照します .mtl ファイルです。マテリアルのロードは デフォルトで有効です (ObjLoadOptions.enableMaterials = true). 渡す ObjLoadOptions これと他のロード時オプションを制御するには:

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

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;       // load the .mtl sidecar
options.flipCoordinateSystem = false; // keep original Y-up orientation
options.normalizeNormal = true;       // fix degenerate normals
options.scale = 1.0;                  // unit scale multiplier

scene.open('character.obj', options);

// Inspect materials on the first node
const first = scene.rootNode.childNodes[0];
if (first) {
    console.log(`Materials on ${first.name}: ${first.materials.length}`);
}

バッファからのロード

使用 openFromBuffer() ファイルデータがすでにメモリ上にある場合、たとえば HTTP 取得、データベース BLOB、または zip アーカイブの抽出からです。これによりディスクへの書き込みを回避できます:

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

const buffer: Buffer = fs.readFileSync('model.obj');
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;

scene.openFromBuffer(buffer, options);
console.log(`Loaded ${scene.rootNode.childNodes.length} root nodes`);

バイナリ形式 (GLB、STL binary、3MF) の場合、ライブラリはバッファからマジックバイトを読み取り、フォーマットを自動的に検出するため、次のように渡すことができます undefined をオプション引数として:

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

const glbBuffer: Buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(glbBuffer); // format auto-detected from GLB magic bytes

HTTP からのロード (Node.js 18+)

リモートアセットを取得し、ファイルシステムに触れずにロードします:

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

async function loadFromUrl(url: string): Promise<Scene> {
    const response = await fetch(url);
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(arrayBuffer);

    const scene = new Scene();
    scene.openFromBuffer(buffer);
    return scene;
}

const scene = await loadFromUrl('https://example.com/model.glb');
console.log(`Loaded scene: ${scene.rootNode.childNodes.length} root nodes`);

ロードされたシーンの検査

ロード後、シーングラフを走査してノードを列挙し、ジオメトリを特定します:

import { Scene, Mesh, Node } from '@aspose/3d';

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

function inspect(node: Node, depth: number = 0): void {
    const indent = '  '.repeat(depth);
    const entityType = node.entity ? node.entity.constructor.name : '(none)';
    console.log(`${indent}${node.name} [${entityType}]`);

    if (node.entity instanceof Mesh) {
        const mesh = node.entity as Mesh;
        console.log(`${indent}  vertices: ${mesh.controlPoints.length}, polygons: ${mesh.polygonCount}`);
    }

    for (const child of node.childNodes) {
        inspect(child, depth + 1);
    }
}

inspect(scene.rootNode);

アセットメタデータの読み取り

この assetInfo プロパティはファイルレベルのメタデータを公開します:

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

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

const info = scene.assetInfo;
if (info) {
    console.log(`Creator: ${info.creator}`);
    console.log(`Unit name: ${info.unitName}`);
    console.log(`Unit scale: ${info.unitScaleFactor}`);
}

すべての形式が情報を設定するわけではありません assetInfo. FBX と COLLADA には豊富なメタデータがありますが、OBJ と STL には通常ありません。.

フォーマット固有のロードオプションリファレンス

フォーマットオプションクラスインポートパスキーオプション
OBJObjLoadOptions@aspose/3d/formats/objenableMaterials, flipCoordinateSystem, scale, normalizeNormal
glTF / GLB(不要)N/A自動検出; オプションクラスは不要
STLStlLoadOptions@aspose/3d/formats/stl(現在のバージョンでは設定可能なオプションはありません)
FBXFbxLoadOptions@aspose/3d/formats/fbx(現在のバージョンでは設定可能なオプションはありません)
COLLADAColladaLoadOptions@aspose/3d/formats/collada(現在のバージョンでは設定可能なオプションはありません)
3MF(不要)N/A自動検出

共通ロードエラー

症状原因修正
Error: Cannot find module '@aspose/3d/formats/obj'moduleResolution に設定されていない node追加 "moduleResolution": "node" へ tsconfig.json
OBJ 読み込み後のノードリストが空です.mtl サイドカーが欠落しているか、 enableMaterials 設定されていない設定 options.enableMaterials = true そして確認 .mtl は同じディレクトリにあります
シーンはロードされますが rootNode.childNodes は空ですフォーマットは単一のルートメッシュを使用し、子ノードは使用しませんアクセス scene.rootNode.entity 直接
openFromBuffer バイナリ STL で例外がスローされますバッファが不正にスライスされました（末尾のバイトが欠落しています）完全版を使用 readFileSync() スライスせずに出力
FBX 読み込み後、アニメーションクリップ配列が空ですFBX ファイルはベイク済みの変換を使用し、クリップは使用しませんアニメーションはフレームごとにベイクされます；クリップ配列は空になります

関連項目

 日本語