Aspose.3D FOSS
TypeScript
TypeScriptで3Dモデルをロードする方法

TypeScriptで3Dモデルをロードする方法

この @aspose/3d このパッケージは、TypeScript および Node.js アプリケーションに、3D シーンファイルを開くためのシンプルな API を提供します。. Scene はルートオブジェクトです: 呼び出します scene.open() ファイルパスとオプションのフォーマット固有ロードオプションを指定して呼び出し、次にトラバースします scene.rootNode ジオメトリ、マテリアル、変換にアクセスします。.

ステップバイステップ ガイド

ステップ 1: npm で @aspose/3d をインストールする

パッケージをプロジェクトに追加します。ネイティブバイナリやプラットフォーム固有のビルドツールは不要で、Node.js 18 以降さえあれば動作します。.

npm install @aspose/3d

TypeScript プロジェクトの場合、型定義はパッケージに同梱されています：:

##tsconfig.json: minimum required settings
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true
  }
}

ステップ 2: Scene とフォーマット固有のオプションをインポートする

各フォーマットはサブパス以下に独自のローダークラスとオプションオブジェクトを公開しています。必要なものだけをインポートしてください：:

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

他のフォーマットでもパターンは同じです：:

import { GltfLoadOptions } from '@aspose/3d/formats/gltf';
import { FbxLoadOptions } from '@aspose/3d/formats/fbx';
import { StlLoadOptions } from '@aspose/3d/formats/stl';

ステップ 3: scene.open() を使って 3D ファイルを開く

作成します Scene インスタンスを作成し、次に呼び出します scene.open() ファイルパスとオプションのロードオプションオブジェクトを指定します。呼び出しは同期的です。.

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

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;

scene.open('model.obj', options);
console.log('Scene loaded successfully');

からロードするには Buffer メモリ内に既にある（サーバーレスやストリーミング環境で便利です）:

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

const buffer = fs.readFileSync('model.obj');
const scene = new Scene();
scene.openFromBuffer(buffer, new ObjLoadOptions());

ステップ 4: シーンノードをイテレートする

シーングラフは、次をルートとするツリーです scene.rootNode. 各 Node は子ノードを含むことができ、オプションの entity (メッシュ、カメラ、ライト等)。.

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

const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());

function visitNode(node: any, depth: number = 0): void {
    const indent = '  '.repeat(depth);
    console.log(`${indent}Node: ${node.name}`);
    if (node.entity) {
        console.log(`${indent}  Entity type: ${node.entity.constructor.name}`);
    }
    for (const child of node.childNodes) {
        visitNode(child, depth + 1);
    }
}

visitNode(scene.rootNode);

ステップ 5: controlPoints を使ってメッシュの頂点データにアクセスする

ノードのエンティティが Mesh,、生の制御点（頂点）を から読み取ることができます controlPoints 配列です。各エントリは Vector4 を持つ x, y, z,、および w コンポーネントです。.

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

const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());

for (const node of scene.rootNode.childNodes) {
    if (!node.entity) continue;
    const entity = node.entity;
    // Check if the entity is a Mesh by duck-typing controlPoints
    if ('controlPoints' in entity) {
        const mesh = entity as any;
        console.log(`Mesh "${node.name}": ${mesh.controlPoints.length} vertices`);
        // Print first three vertices
        for (let i = 0; i < Math.min(3, mesh.controlPoints.length); i++) {
            const v = mesh.controlPoints[i];
            console.log(`  v[${i}]: x=${v.x.toFixed(4)}, y=${v.y.toFixed(4)}, z=${v.z.toFixed(4)}`);
        }
    }
}

ステップ 6: マテリアル読み込みのために ObjLoadOptions を設定する

ObjLoadOptions は、付随する .mtl マテリアルファイルとテクスチャが解決される方法を制御するプロパティを公開します。.

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

const options = new ObjLoadOptions();
options.enableMaterials = true;   // parse .mtl file if present

const scene = new Scene();
scene.open('model.obj', options);

// Inspect materials attached to nodes
for (const node of scene.rootNode.childNodes) {
    if (node.material) {
        console.log(`Material on "${node.name}": ${node.material.constructor.name}`);
    }
}

一般的な問題と対策

エラー: モジュール ‘@aspose/3d/formats/obj’ が見つかりません フォーマットのサブパスは Node.js 12.7 以降のパッケージエクスポートが必要です。Node.js 18 以降を使用していることを確認してください。TypeScript を使用している場合は、set "moduleResolution": "node16" または "bundler" で tsconfig.json.

scene.rootNode.childNodes は open() 後に空です 一部の OBJ ファイルは非標準の改行コードを使用しているか、末尾の改行がありません。テキストエディタで開いてファイルが有効な OBJ であることを確認してください。また、渡したのが ObjLoadOptions 汎用的なものではなく LoadOptions:：フォーマット固有のオプションが正しいディスパッチに必要です。.

controlPoints 配列の長さが 0 です メッシュはロードされたかもしれませんが、ジオメトリが含まれていません（例: OBJ の空のグループ）。Use mesh.polygonCount 頂点を反復処理する前にチェックするために使用してください。.

大きなファイルではメモリ使用量が高くなります バッファからロードする際に scene.openFromBuffer() ピークメモリは削減されません：ファイル全体を解析する必要があります。100 MB 超の大きなファイルの場合、Node.js プロセスに十分なヒープが確保されていることを確認してください：: node --max-old-space-size=4096 yourScript.js.

型エラー: ’entity’ は ‘unknown’ 型です その entity プロパティは広く型付けされています。次のようにキャストしてください any または特定のクラス（Mesh, Camera,など）シーンで期待するものに応じて。.

よくある質問 (FAQ)

scene.open()でロードできるフォーマットはどれですか？? OBJ、glTF 2.0（.gltf + .bin）、GLB、STL、3MF、FBX、そして COLLADA（.dae）はすべてインポートがサポートされています。対応する *LoadOptions クラスを各フォーマットに対して指定してください。.

オプションを指定せずにファイルをロードできますか？? はい。. scene.open('model.glb') 特別な設定を必要としないフォーマットでは、オプションなしで動作します。OBJ ではマテリアルの解像度が…に依存するため、オプションを渡すことが推奨されます。 enableMaterials.

ロードは非同期で実行されますか？? いいえ。. scene.open() および scene.openFromBuffer() は同期的です。ワーカースレッドでラップするか、 setImmediate イベントループを応答性のままに保つ必要がある場合は。.

OBJ エクスポートはサポートされていますか？? はい。OBJ エクスポートは以下を通じてサポートされています scene.save('output.obj').。The .mtl マテリアルファイルは自動的に同じ場所に書き込まれます .obj ファイル。.

OBJ を読み込む際、.mtl ファイルはどこにあることが期待されていますか？? デフォルトでは、パーサは次のものを探します .mtl OBJ 内で参照されているファイル（mtllib ディレクティブ）は OBJ ファイルのディレクトリを基準にします。両方のファイルが同じフォルダーにあることを確認してください。.

関連項目

 日本語