mcpField
G
glbforge

glbforge

ローカル
github.com/glbforgeメディア・デザイン34 週間前に更新

glbforge について

glbforge は、AI 生成の 3D アセットをウェブ配信用に整える、エージェントと CI ワークフロー向けの決定論的なツール群です。性能予算に基づく検査・最適化、SSIM による視覚的忠実度の測定、2D 画像の 3D 化と書き出しに対応します。

主な機能

  1. 01メッシュ構造と編集上の問題を検査
  2. 02モデルの変更と回帰を比較
  3. 03性能予算に基づいて分析・最適化
  4. 04SSIM で視覚的忠実度を検証
  5. 05画像を 3D 化して STL または USDZ に書き出し
  6. 06アセットを生成し React Three Fiber ビューアーを作成

活用シーン

  1. 01編集時にメッシュの問題を検出
  2. 02CI で予算に基づき 3D アセットを判定
  3. 03視覚的忠実度を確認しながらモデルを軽量化
  4. 04ロゴやグラフィックを水密な 3D アセットに変換

MCP 対応

@glbforge/mcp サーバーは、3D アセットの検証、検査、レンダリング、最適化、出荷、造形、書き出し、生成のツールを MCP クライアントに提供します。設定済みのローカルサーバーを通じて接続できます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
"mcpServers": {
"dev-glbforge-glbforge": {
"command": "npx",
"args": [
"-y",
"@glbforge/mcp"
],
"env": {
"MESHY_API_KEY": "<MESHY_API_KEY>"
}
}
}
}
起動コマンドnpx -y @glbforge/mcp
設定が必要な環境変数
MESHY_API_KEYシークレットOptional Meshy API key enabling the meshy_* generation tools

ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
npm@glbforge/mcp0.8.0

ツール

27

掲載時のツール一覧 · 2 週間前に更新

パラメーター型必須説明
pathstringはい.glb、.gltf、.usdz、.usda、.usdc、または .usd ファイルの絶対パス
packsarrayいいえprofile の代わりに実行するルールパック:core-geometry | core-scene | intent(@N でバージョンを固定)
expectanyいいえ制作する意図を自由テキスト("chair, Z-up, single-shell, 0.4-1.2m tall, front -Y")または構造化データで指定します。intent@1 パックが追加され、解析できないトークンは報告されます。
paramsobjectいいえルールパックのパラメーター上書き。例:{ "core-geometry": { "fragmentFraction": 0.02 } }
lineagestringいいえ名前変更後もアセットを識別するための任意の ID。ローカルのオプトイン使用カウンターに使用されます(外部に送信されることはありません)。
profilestringいいえルールプロファイル:authoring、または予算プロファイル mobile-hero | desktop-hero | product-configurator(@N でバージョンを固定)
topologybooleanいいえ溶接空間のトポロジーパス(シェル、ウォータータイト性、非多様体)。三角形 15 万個あたり約 70 ms。false の場合、トポロジールールは `skipped` に一覧表示されます。

詳細

GLBForge — AI 生成 3D のウェブ対応レイヤー

glbforge.dev · AI 生成メッシュを入力し、出荷可能なアセットを出力

3D 生成後に処理を行う、エージェントと CI 向けの決定論的レイヤーです。役割は 2 つあります。メッシュ編集中にエージェントが状況を把握するための機能(inspect は数十ミリ秒で意味的に読み取り、diff は直前の編集で壊れた箇所を示します)と、出荷前のゲート(analyze → optimize → verify。バージョン管理されたパフォーマンス予算を CI で使用できる契約として扱い、「視覚的な損失なし」を SSIM 値で測定します)。2D アートワークから水密な 3D を生成したり、写真を生成ツールに振り分けたり、GLB / STL / USDZ をエクスポートしたりすることもできます。

ステータス

  • ✅ glbforge inspect — 編集ループでの読み取り(1 秒未満):単一シェルか断片か、水密か穴/重なりがあるか、サイズ(メートル単位)、上方向の軸、原点の配置、未適用/ミラー変換を検出します。それぞれの検出結果には、測定値またはヒューリスティックによる確度を含むバージョン管理済みルール ID(core-geometry@1 の topo/open-edges など)、確信度付きの推定原因、具体的な修正方法が示されます。front は決して推測されません。MCP の inspect ツールと同じ機能です。編集のたびに呼び出してください。
  • ✅ glbforge diff <before> <after> — 直前の編集からの変更点と、その編集で壊れた箇所を表示します。パーツごとのサイズ差分(「'legs' の X 軸方向の幅が 30% 狭くなっています」)、三角形とシェルの差分、トポロジーの悪化(以前は水密だったものが、現在は 3 つの開いたループを持つなど)、原点のずれ、ノード変換、追加または削除されたメッシュのほか、カメラを変更前のフレーミングに固定した --visual の正面/側面/上面/斜視 SSIM を表示します。MCP の diff ツールと同じ機能です。
  • ✅ glbforge analyze — 予算の評価レポートと名前付き lint ルール
  • ✅ glbforge optimize — 溶接/簡略化/LOD/圧縮により予算を達成
  • ✅ glbforge scaffold — 最適化済みアセット用の React Three Fiber ビューアーを出力
  • ✅ glbforge meshy — Meshy REST API 経由で生成/ダウンロード(画像/テキスト → 3D、--optimize による連携)
  • ✅ glbforge ship <input> — GLB、ロゴ、写真から、予算ゲートを通過するアセットを 1 回の呼び出しで生成します。ルート選択(最適化/生成/生成ツールへの振り分け)→ 分析 → 最適化 → ゲートの順に処理します。--json を指定すると、ルート、生成処理の判断、最適化レポート全体を 1 つのドキュメントとして出力します。
  • ✅ 上記すべてをラップする MCP サーバー(@glbforge/mcp、28 個のツール、公式 MCP レジストリの dev.glbforge/glbforge)
  • ✅ GLBForge Studio(glbforge ui)— ローカル Web UI:ドラッグ&ドロップによる分析、ビューポート内の比較スライダーを使ったワンクリック最適化、ロゴ生成、進行状況をリアルタイムで表示する Meshy 生成、STL エクスポート。ホスティング不要で、すべてお使いのマシン上で実行されます。
  • ✅ glbforge extrude — ロゴ/グラフィックを決定論的に 3D 化(AI 不使用、クレジット不要):輪郭をトレースし(マーチングスクエア → Douglas-Peucker → earcut)、水密に押し出して、元の画像をテクスチャとして投影します。ロゴやワードマークなどの 2D アートワークでは、画像から 3D を生成する方法を大きく上回ります。約 1.5k トリスで約 2M の場合より軽量で、輪郭も正確、色も元のままです。--bevel を指定すると、看板のような丸みのある縁を追加します(マイター制限、クランプを検証したインセット、および亀裂をつなぐ処理により、細いグラフィティの線でも水密性を維持します。実際のロゴのテストデータで境界エッジ 0 個/非多様体エッジ 0 個を確認済みです)。写真が入力された場合は検出して Meshy に振り分けます。または --matte auto を指定すると、先に背景から切り抜きます(以下を参照)。extrude_image MCP ツールとしても公開されています。
--matte auto — 被写体を切り抜き、ステッカーを生成

写真にはアルファチャンネルも白い背景もないため、forge は受け付けません。 マット処理(matte/border@2、core/src/extrude/matte.ts)は、その解決策となる第 3 の方法です。 フレームの端を背景として、その色のピクセルを内側へたどり、残った部分を被写体と見なします。スマートフォンの「被写体を切り抜き」と同じ発想ですが、単純な連結性を使うため、モデルのダウンロードは不要で、Node とブラウザーのどちらでも同じように動作し、バイト単位で決定論的です。 各ピクセルのクラスは色で決まり、その扱いは連結性で決まります。この仕組みによって、マグカップの取っ手の穴が保たれます。囲まれた背景色の領域は被写体ではなく、穴です。小さな囲まれた領域(ハイライト、JPEG のノイズ)は塗りつぶされ、小さく孤立した部分はゴミとして削除されます。色の近さは、色相を考慮して一方向に判定します。背景に近い色で、かつ背景よりも 暗い ピクセルはその影と見なされるため、落ち影が物体と一体化するのを防げます。一方、灰色の机の上にある白いマグカップは、色が明るく色相も同じでも、背景に吸収されません。輪郭をトレースする前に 3x3 の多数決フィルターでマスクを滑らかにするため、エッジに沿った JPEG のリンギングが何百もの輪郭になることもありません。

許容度は自動で調整されます。 tuneMatte は 8 段階のしきい値を試し、最もスコアの高いカットを採用します。つまみの両端では確度が下がるためです。厳しすぎると背景が残り、緩すぎると物体が削られます。Studio ではドロップ時に調整され(スライダーは調整後の値で開き、auto と表示されます)、CLI では --matte-tolerance auto で調整され、しきい値の一覧が出力されます。MCP の matte_preview ではデフォルトで調整されます。

生成する前に確認しましょう。 見えない許容度は選べないため、カットを利用できる場所ではどこでもプレビューできます。 glbforge extrude photo.jpg --matte auto --matte-preview cut.png はカット(被写体は不透明、削除された背景は薄く表示)を書き出し、ジオメトリを構築せずに数値を出力します。extrude_image に matte_preview: true を指定すると、その画像と、試すべき許容度を示す nextActions が返されます。また、Studio ではスライダーを動かすと、リフトボタンの下にカットがリアルタイムで再描画されます。

マスクは推定結果なので、それに応じた情報を報告します。カバレッジ、パーツ数、穴の数に加え、エッジの均一さ、カットを通過した部分のコントラスト、結果が妥当なサイズかどうかをもとに確度を算出します。確度が 0.4 未満の場合、forge は結果を返さず、代わりに数値を示して拒否します。MCP は受理されたケースを SUBJECT_LIFTED 診断として提示するため、エージェントはシルエットが読み取られたのではなく、推定されたものだとわかります。CLI の --matte auto、extrude_image の matte、そして Studio の ✂ 被写体を切り抜いて生成は、これまで行き止まりだった拒否箇所で利用できます。

使用方法

pnpm install && pnpm build
node packages/cli/dist/index.js analyze fixtures/veiled-guardian.glb --profile mobile-hero
node packages/cli/dist/index.js optimize fixtures/veiled-guardian-tex4k.glb -o out.web.glb --lods 40000,10000
node packages/cli/dist/index.js scaffold out.web.glb -o viewer && cd viewer && pnpm install --ignore-workspace && pnpm dev
node packages/cli/dist/index.js ui model.glb   # GLBForge Studio on localhost:5177

inspect <file>(glb/gltf/usdz/usda/usdc)は、メッシュを編集するエージェントが目視確認なしでは見落とす問題を検出します。15 万三角形のアセットで約 0.1 秒、未加工の 200 万三角形の生成データで約 0.8 秒です(溶接トポロジーの処理自体は 15 万三角形あたり約 70 ミリ秒です)。--profile authoring (デフォルト)では、トポロジーの問題を警告として扱います。直前の編集によって発生した可能性が最も高いためです。予算プロファイル(mobile-hero)では、情報として報告します。--packs core-geometry@1,core-scene@1 はルールパックを固定し、--no-topology は溶接処理をスキップします(ルールはスキップ済みとして表示され、黙って省略されることはありません)。--strict は警告がある場合に終了コード 1 で終了し、--json は完全なレポートを出力します。--expect "chair, Z-up, meters, single-shell, 0.4-1.2m tall, front -Y, watertight, origin base" を指定すると、実行は契約(intent@1)になります。シェル数、完全な水密性、サイズ範囲、原点を測定し、条件を満たさない場合はエラーとして失敗します(終了コード 1)。カテゴリだけを指定すると、明示された信頼度とともに、概算サイズ表に基づく妥当性警告が表示されます。front は宣言として記録され、測定されることはありません。GLB の Z-up は、glTF が定義上 Y-up であるため、情報として報告されます。パーサーが解釈できないトークンは破棄されず、報告されます。

glbforge usage は、GLBForge が使用フローに含まれているかを示す唯一の指標、アセットあたりの呼び出し回数を記録する、ローカルでオプトイン可能なカウンターです。デフォルトでは無効です。glbforge usage --enable または GLBFORGE_USAGE=1 で有効にできます。有効にすると、すべての inspect/diff/analyze(およびすべての MCP 呼び出し)で、~/.config/glbforge/usage.jsonl に JSON が 1 行ずつ追記されます(保存先は GLBFORGE_CONFIG_DIR で変更できます)。データが外部に送信されることはありません。--clear で削除できます。編集のたびにファイルのハッシュが変わるため、アセットは「系統」ごとにグループ化されます。同じセッション内の同じパス、2 時間以内の同じパス、diff のエッジ(変更前 → 変更後)、または明示的な --lineage <id> が基準です。レポートには、系統ごとの呼び出し回数の中央値と p90、少なくとも 5 回検査されたアセットの割合が表示されます。

analyze のフラグ:--profile mobile-hero|desktop-hero|product-configurator、 --json、--no-topology。アセットが予算を超過するとゼロ以外の終了コードで終了します。リンターと同様に CI に組み込んでください。optimize のフラグ:--target <tris>、--lods a,b、--no-textures、--no-compress、--no-verify。LOD ファイル(--lods 40000,10000)にはジオメトリのみが含まれます。マテリアルは除去され、頂点位置は溶接され、meshopt で簡略化されます。非多様体トポロジーによって簡略化処理が停滞する場合(積み重なったフォージレイヤー、二重シェル)は、グリッド頂点クラスタリングに切り替えて、必ず目標を達成します。その場合、CLI と Action のレポートには grid-clustered と表示されます。

同梱の Meshy 7 フィクスチャ(4K テクスチャ、199 万 tris)での測定結果: 89.4MB → 5.5MB(93.8% 縮小)、スコア 25 → 100、約 7 秒。 パイプライン: 重複除去 → 溶接 → 予算まで meshopt で簡略化(誤差ラダー)→ 欠落している法線を補完 → テクスチャのリサイズ+WebP(法線マップはほぼロスレス)→ プルーニング → EXT_meshopt_compression → 知覚的検証。

「見た目の劣化なし」は主張ではなく、測定結果です

すべての optimize/ship では、前後のアセットを 4 つの固定カメラからレンダリングし(決定論的なソフトウェアラスタライザー、2 倍のスーパーサンプリング、スムーズシェーディング、ベースカラーテクスチャ)、各ペアを SSIM でスコア化します。最も低いビューのスコアがプロファイルの minSsim のしきい値(mobile-hero は 0.94、product-configurator は 0.95、desktop-hero は 0.96)を下回ると、レポートカードに重大度がエラーの fidelity/perceptual 検出結果が追加され、予算超過の場合と同様に、コマンドはゼロ以外の終了コードで終了します。合格した実行では、数値が情報レベルの検出結果として記録されるため、CLI、--json、MCP、Studio のいずれでも、レポートとともにスコアが提供されます。

  visual fidelity ✓ SSIM 96.7%  weakest view 95.8% @ verify_135 · floor 94.0% · geometric deviation ≤ 0.1%

フィクスチャでは、予算内に収める処理(199 万 → 15 万 tris)のスコアは 0.958 です。40k tris に強制すると 0.896 に下がり、不合格になります(髪の毛がまとまってしまうため、妥当な結果です)。10k では 0.73 です。glbforge verify <candidate> <reference> は、任意の 2 つのファイルを同じ方法でスコア化します。カメラは参照アセットの境界に固定されるため、結果が移動したり縮小したりして、フレーミングを調整してスコアを上げることはできません。

パッケージ

パッケージ用途
@glbforge/core純粋な解析ライブラリ:統計、トポロジー、ルール、予算
glbforge (CLI)glbforge コマンドラインインターフェース
@glbforge/meshy型付き Meshy REST クライアント:タスク、バックオフ付きポーリング、ダウンロード
@glbforge/mcpMCP サーバー:安定したエラーコードとプリムパス、簡潔なレポートカードを備え、GLB と USD の検証/検査/レンダリング、ドライランと差分を使った最適化/出荷/生成/STL/USDZ、生成

MCP サーバー

.mcp.json は、Claude Code 用にサーバーを自動登録します(先にビルドしてください: pnpm build)。その他のクライアントの場合:

claude mcp add glbforge -- node /path/to/XUI/packages/mcp/dist/index.js

エージェント向けに構築されています。すべてのツールは、1 つのエンベロープ — { ok, summary, duration_ms, errors[], data } — を返します。errors[] には、 安定したコード(docs/error-codes.md)、重大度、参照先のプリムパスを含む すべての診断が格納され、すべてのレスポンスは schemas/<tool>.output.json に対して検証されます。validate、inspect_geometry、 inspect_animation、inspect_materials、analyze_performance、inspect_all は GLB、glTF、USDZ、USDA、USDC を読み取ります(純粋な TypeScript による USD リーダー、単一レイヤー)。render/render_animation_strip はそれらすべてを、 任意のアニメーション時刻のポーズで描画します。変更を加えるツールは dry_run を受け取り、diff と post_validation を返します。また、行った変更 (生成された法線、結合されたプリミティブ、トランスコードされたテクスチャなど)を、 コード付きのエントリーとしてすべて報告します。結果は簡潔なカード(判定、主要な数値、 すべてのエラーと主な所見、nextActions、drillDown ポインター)で表示され、 必要に応じて inspect_report で所見/テクスチャ/トポロジーの全情報を取得できます。 GLB に触れるすべてのツールは、レンダリング済みサムネイルまたは 2x2 のターンテーブルを 返します。また、最適化に失敗した場合は、参照 | 結果 | 変更ヒートマップのシートを返すため、 エージェントは損失箇所を確認できます(任意の 2 ファイルには compare_glb を使用)。 計画の作成前に、capabilities でキーが設定されているプロバイダーと KTX2 の利用可否を 確認できます。書き込まれたファイルはすべて sha256 を報告します。読み取り専用の ツールには readOnlyHint が付与され、クライアントは自動承認できます。生成ツールは 意図的に create/status/download に分割されています。タスクには数分かかるため、 ツール呼び出しを開いたままにせず、エージェントが自分のペースでポーリングできます。

アニメーションアセット

スキンメッシュとモーフターゲットは、ボーンを考慮したパスで処理されます。meshoptimizer の 属性対応簡略化処理は、スキンウェイト(およびターゲットごとのモーフ差分)を頂点属性として 扱い、主要なジョイント境界上の頂点はロックされ、各属性 — JOINTS_n、WEIGHTS_n、 各ターゲット — は同じリマップでコンパクト化されます。スキン、逆バインド行列、 アニメーションクリップは変更されずに維持されます。analyze は scene/animated-asset を報告します。回転クリップとモーフターゲットを備えたリグ付き円柱で テスト済みです(ブレンド範囲を維持し、ウェイトを正規化し、決定論的に動作します)。

iOS AR 向け USDZ

npx glbforge animate model.web.glb       # → model.idle.glb (looping idle clip, no rig; -p spin|bob|sway|breathe|hop)
npx glbforge companion model.idle.glb    # a talking desktop character (Electron via npx -y @glbforge/companion; --mcp registers its bridge, --hooks puts every Claude Code session on its face)
npx glbforge usdz model.web.glb          # → model.usdz (PNG textures; --jpeg for smaller)

UsdPreviewSurface マテリアル(ベースカラー、チャンネル出力によるメタリック/ラフネス、法線、オクルージョン、エミッシブ、アルファマスク/ブレンド)を含む バイナリ USD(usdc、crate 0.8.0)レイヤーを書き出し、WebP テクスチャを PNG/JPEG にトランスコードして、仕様で定められた 64 バイト境界にペイロードを配置したストア形式のみの zip にパックします。crate ライターは GLBForge 独自の純粋な TypeScript 実装です。バイトレイアウトは Pixar のライターが生成したファイルとセクションごとに照合済みです。また、test/usd-oracle.py は Pixar の USD で usdc と対応する usda の両方を開き、すべての prim、値、接続、リレーションシップが一致するか確認します(実行するには、usd-core をインストールした Python を GLBFORGE_PXR_PYTHON に設定してください)。Meshy のフィクスチャでは、レイヤーのサイズはバイナリ版が 5.4MB、ASCII 版が 13.4MB です。テキストレイヤーを書き出すには --usda を指定します。アニメーション付きアセットは UsdSkel として書き出されます。ジョイントは親が先になる順序で並べ、バインド変換とレスト変換を設定します。メッシュには SkelBindingAPI のジョイントインデックス/ウェイトを設定し、最初のアニメーションクリップを 30 fps でサンプリングして SkelAnimation に格納します(平行移動、クォータニオン回転、半精度スケール)。オラクルテストでは、Pixar の UsdSkel に結果からジョイント変換を再計算させます。モーフターゲットは UsdSkel の BlendShape prim になり、ウェイトトラックも合わせてサンプリングされます(モーフのみのメッシュには、UsdSkel が適用できるように 1 つのジョイントを持つスケルトンが設定されます)。マテリアルのないプリミティブにはニュートラルなデフォルトマテリアルが設定されます。これは、マテリアルが割り当てられていないメッシュが RealityKit ではマゼンタの「マテリアルなし」パターンで表示されるためです。KTX2 入力は案内メッセージとともに拒否されます。MCP サーバーの export_usdz と、Studio の Export USDZ ボタンからもエクスポートできます(ブラウザー内でも可能です。テクスチャは canvas 経由でトランスコードされます)。iOS の AR ボタンを表示するには、<model-viewer ios-src="model.usdz"> から参照します。iPhone の AR Quick Look で検証済みです。フラットマテリアル、完全なテクスチャ付き(カラーは JPEG、法線とメタリック/ラフネスは PNG)、スキニングとアニメーション、およびブレンドシェイプの各エクスポートは、すべて正常に開いて再生できます。

glbforge init — プロジェクトをエージェント対応にする

npx glbforge init            # in your project; idempotent

CLAUDE.md にマーカーで区切られたセクションを書き込みます(予算、使用するスクリプトと MCP ツール、forge と generate の振り分けルール、「目に見える劣化なし」の測定方法を記載します)。また、glb:check/glb:analyze/glb:optimize/glb:ship/glb:verify/glb:studio の npm スクリプトを追加し(devDependency として glbforge も追加)、.mcp.json に MCP サーバーを登録します(.cursor/mcp.json を使う場合は --client cursor|both を指定します)。既存の内容、他の MCP サーバー、独自のスクリプトは保持されます。2 回目の実行では、すべて変更なしと報告されます。フラグ:--profile、--assets <dir>、--local、--dry-run、--force、--no-claude-md、--no-scripts、--no-mcp。以降、そのプロジェクトでエージェントのセッションを開始すると、GLBForge が自動的に使用されます。

glb:check は glbforge audit <dir> を実行します。フォルダー内のすべての GLB を予算と照合し、いずれかが失敗すると 0 以外の終了コードを返します。これは pre-commit/CI のゲートです。

GitHub Action

# .github/workflows/assets.yml
on: pull_request
permissions: { contents: write, pull-requests: write }
jobs:
  assets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with: { fetch-depth: 0, lfs: true }
      - uses: glbforge/glbforge@main
        with:
          profile: mobile-hero
          optimize: true      # open a PR with the web-ready files

プルリクエストで変更された GLB/glTF ファイルのみを実行対象とします。実行ごとに固定のレポートカードコメントを投稿し、予算に基づいてチェックの合否を判定します。optimize: true を指定すると、不合格のアセットも最適化します(元のファイルの隣に <name>.web.glb を作成するか、replace: true で上書きします)。さらに、知覚的な検証を行い、結果(最適化前後の表、視覚的な SSIM、パイプラインの手順)を含むプルリクエストを、プルリクエストのブランチに対して作成または更新します。同じ入力、プロファイル、CLI バージョンでは常に同じバイト列が生成されるため、出力はコンテンツハッシュでキャッシュされ(cache: true)、再実行しても処理は行われません。フォークからのプルリクエストではボットのブランチを作成できないため、出力は代わりにワークフローアーティファクトとしてアップロードされます。プルリクエストを作成するには、リポジトリの設定(組織の場合は組織の設定も)で Allow GitHub Actions to create and approve pull requests を有効にする必要があります。無効の場合でも、実行時にレポートカードが投稿され、最適化されたファイルが glbforge-optimized アーティファクトとしてアップロードされます。最適化モードでは、最適化後の出力が合格すればゲートを通過するため、修正をマージするだけで完了します。target-triangles はプロファイルの三角形数の目標を上書きし、lods: 40000,10000 はジオメトリのみの LOD ファイル(<name>.web.lodN.glb)をプルリクエストに追加します。どちらもキャッシュキーに含まれます。入力項目:profile、fail-on-budget、optimize、optimize-all、replace、verify、target-triangles、lods、cache、open-pr、pr-branch、version、token。

Meshy API キー

.env.example を .env にコピーし、MESHY_API_KEY を設定してください(Git で無視され、自動的に読み込まれます。実際の環境変数を上書きすることはありません)。または、ファイルを一切使わずに macOS Keychain に保存できます。

security add-generic-password -a "$USER" -s meshy-api-key -w
# ~/.zshrc: export MESHY_API_KEY=$(security find-generic-password -s meshy-api-key -w)

一連の処理を 1 つのコマンドで実行できます。

node packages/cli/dist/index.js meshy image art.png --pbr --optimize -p mobile-hero -o hero.glb

オープンモデルによる生成(fal.ai)

GPU 推論でオープンウェイトを使用する、本格的な画像から 3D への変換です。商用の生成サービスより 5〜25 倍安価な場合があります。FAL_KEY を設定してください(https://fal.ai/dashboard/keys)。

node packages/cli/dist/index.js gen photo.png --model hunyuan --optimize   # Hunyuan3D-2
node packages/cli/dist/index.js gen photo.png --model trellis             # TRELLIS
node packages/cli/dist/index.js gen photo.png --model triposr             # fastest

スタジオの生成パネルは、設定済みのすべてのプロバイダーを自動的に取得します(ホストモードでは Meshy と 3 つのオープンモデルを並べて表示し、モデルごとのクレジット費用も表示します)。

ルール

perf/* の予算違反はビルドを失敗させます。geo/*、topo/*、mat/*、tex/*、scene/* は、AI 生成アセットに典型的な欠陥を示し、それぞれに具体的な修正方法があります。packages/core/src/rules.ts を参照してください。

設計上の決定

  • 純粋な Node/TS で、Blender への依存はありません。 分析と最適化は @gltf-transform、meshoptimizer、sharp を使って実行します。これらは glTF にネイティブで、品質を損なう DCC の往復処理がなく、npx からインストールでき、CI に適しています。処理はプラグイン可能なバックエンドとして設計されているため、CLI のインターフェイスを変更せずに、Blender 専用の機能(リトポロジー、UV 展開、ベイク処理)を後から追加できます。
  • トポロジーは頂点を結合した空間で処理します。 境界および非多様体の数は、位置が重複する頂点を統合した後に計算されるため、頂点が結合されていないエクスポートでも不正な数値が生成されません。
  • 予算はアドバイスではなくプロファイルです。 アセットは、名前付きのバージョン管理された目標に対して合格または不合格となります(mobile-hero@1 はそのバージョンに固定され、バージョンを指定しない mobile-hero は最新を使用します。上限がその場で変更されることはありません)。各上限の根拠とバージョン変更履歴は、docs/BUDGETS.md および glbforge.dev/budgets にあります。決定性があるため、自動化できます。

フィクスチャ

  • fixtures/veiled-guardian.glb — Meshy 7 の高詳細ジオメトリステージでエクスポートしたファイル(199 万トライアングル、POSITION のみ、34MB)。頂点を結合済みで、多様体です。誤検知が起きないことをテストで確認します。
  • fixtures/veiled-guardian-tex4k.glb — 同じアセットの 4K テクスチャステージ後のファイル(89MB)。位置が重複する 7.7 万個の頂点は UV シームの分割であり、無駄ではありません。topo/unwelded ルールがこれらを区別することを、回帰テストで確認します。

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。