3D AR Studio

3D AR Studio

本格的な拡張現実スタジオを、どんなウェブページにも組み込めます。

カメラを通して、現実の部屋に好きなだけ3Dモデルを配置し、新しいモデルを説明して生成される様子を見ながら、すべてを手作業で配置できます。その後、シーン全体をリンクやQRコード、あるいは他の人と一緒に作り込めるライブのルームとして共有できます。

ライブデモ · npm · MCP サーバー

<script type="module" src="https://unpkg.com/3d-ar-studio/dist/ar-studio.min.js"></script>
<ar-studio></ar-studio>

これだけで、すぐに使えるARスタジオが完成します。ビルド手順も、APIキーも、アカウントも不要です。数百点のパブリックドメインモデルを揃えた無料ライブラリと、キー不要で無料のテキストから3Dモデルを生成する機能があらかじめ組み込まれています。準備ができたら、オプションを1つ指定するだけで独自のカタログに接続できます。

---

開発の背景

ウェブARの埋め込み機能は、モデルを1つだけ配置すると、すぐにネイティブビューアーに切り替わり、セッションが終了します。この機能では、シーン全体をページ内に保ちます。

• 1つの部屋に複数のモデル。 ライブカメラビュー内で、好きなだけモデルを配置し、ドラッグし、ピンチでサイズ変更し、ひねって回転させ、複製できます。
• カメラから離れずに生成。 ドックに「真鍮のデスクランプ」と入力します。ライブビューの背後で生成が進み、完成したモデルが部屋に配置されます。
• 対応環境では本物のWebXR。 常時有効なヒットテストのレティクル、配置したモデルごとのXRAnchor、現実の光源推定、家具の後ろにモデルが隠れる深度オクルージョンに対応しています。
• それ以外の環境では本物のARKitとARCore。 iPhoneはWebXRに対応していないため、空間に配置をタップすると、AppleのAR Quick Lookが実際に起動します。真の平面検出、実寸大表示、本物のオクルージョン、システム標準の「ARで表示」シートが利用できます。モデルはデバイス上でUSDZに変換されます（three.jsのUSDZExporterによる実際の変換で、サーバーは不要です）。シーン内にすでに配置したコピーからエクスポートするため、ピンチで変更したサイズと配置時の向きを保って表示されます。モデルを作成したときの高さのまま宙に浮くのではなく、床に立った状態で表示されます。WebXR非対応のAndroidではScene Viewerが起動します。デスクトップではグリッドプレビューと、スマートフォンに引き継ぐQRコードが表示されます。
• シーンをリンクで共有。 モデル、位置、回転、スケールはURLに保存され、再現できます。ノートPCで作成し、QRコードを読み取れば、スマートフォンで同じシーンが開きます。
• リアルタイムで一緒に作成。 ルームを開いて6文字のコードを共有すると、モデルの追加や移動が参加者全員に同期されます。
• キャラクターが実際に動きます。 あらかじめアニメーションが設定されていないヒューマノイドGLBには、各自のスケルトンに合わせたアイドルアニメーションが適用されます。リグの許可リストも、Tポーズもありません。
• エージェントで操作できます。 同梱のMCP サーバーを使うと、Claude、ChatGPT、または独自のエージェントでモデルを生成し、配置を組み立て、そのシーンを自分の部屋で開けるリンクをユーザーに渡せます。

レンダリングの段階的な処理、アンカーのライフサイクル、リターゲティングのパイプライン、シーン形式、共有ルームのプロトコルは、本番環境で稼働しているthree.wsのAR機能から抽出し、独自のモデルを使ってあらゆるサイトで動作するように一般化したものです。

---

インストール

npm i 3d-ar-studio three

three はピア依存関係なので、コピーを 1 つだけ保持し、バージョンを選択できます。CDN バンドル （dist/ar-studio.min.js）には three.js が含まれており、ほかに必要なものはありません。

import { createArStudio } from '3d-ar-studio'

const studio = createArStudio('#stage', {
  branding: { title: 'Acme AR', accent: '#00b894' },
})

studio.on('add', ({ placement }) => console.log('placed', placement.title))

スタジオはホスト要素いっぱいに絶対配置されるため、ホストに高さを指定してください（実際の高さがある位置指定済みのボックスなら何でも使えます。高さを指定していない <div> には、まったく表示されなくなる代わりに、適切なデフォルト値として 70vh が設定されます）。

デプロイ可能なページを作成する

npx 3d-ar-studio create my-ar-site     # a folder you can publish as-is
cd my-ar-site
npx 3d-ar-studio dev                   # look at it locally
npx 3d-ar-studio deploy                # push it and turn on GitHub Pages

deploy は実行前にすべての git および gh コマンドを表示します。git と GitHub CLI が必要です。これらがない場合は、黙って失敗するのではなく、手動で行う 3 つの手順を案内します。

テンプレート：static（HTML ファイル 1 つ、ビルド不要）、vite、react。

3d-ar-studio と ar-studio のどちらでも CLI を実行できます。MCP サーバーは独自のパッケージに含まれる別のバイナリなので、npx 3d-ar-studio-mcp で問題なく解決できます。詳しくはMCP サーバーをご覧ください。

---

独自のモデル

デフォルトでは、トレイには three.ws から取得した、商用利用が可能でオープン CORS で配信される、パブリックドメイン（CC0）の小道具が数百点ほど表示されます。assets オプションを使えば、独自のものに差し替えられます。

場所を問わない JSON ファイル。 よくある 5 種類の形式を、形を変えずに読み込めます。

createArStudio(el, { assets: 'https://cdn.acme.com/models.json' })

// Any of these work:
[ { "url": "https://cdn.acme.com/chair.glb", "name": "Aero chair" } ]
{ "items":     [ … ] }
{ "objects":   [ … ] }   // three.ws object library
{ "creations": [ … ] }   // three.ws forge gallery
{ "models":    [ … ] }

各エントリーでは、モデル URL は src、url、glb、glb_url、glbUrl、file、model のうち最初に存在するものから、ラベルは title、label、name、prompt のいずれかから、サムネイルは poster、thumb、thumbnail、image、preview_image_url のいずれかから読み込まれます。https URL（またはサイト相対 URL）以外のものは、ローダーに渡されずに除外されます。

コード内で管理するリスト：

import { staticSource } from '3d-ar-studio/sources'

createArStudio(el, {
  assets: staticSource({
    label: 'Our furniture',
    items: [{ src: 'https://cdn.acme.com/chair.glb', title: 'Aero chair', poster: '…' }],
  }),
})

複数のタブを一度に、好きな順序で表示する：

createArStudio(el, { assets: ['recent', myCatalogue, 'objects', 'link'] })

組み込みキー：'three.ws'（デフォルトのセット）、'recent'、'objects'、'community'、'link'。

それ以外の場合。 ソースは list() を持つオブジェクトです。

createArStudio(el, {
  assets: {
    id: 'search',
    label: 'Search',
    searchable: true,
    async list() {
      const rows = await fetch('/api/models').then((r) => r.json())
      return rows.map((m) => ({ src: m.glb, title: m.name, poster: m.thumb }))
    },
  },
})

list() が例外をスローしても問題ありません。トレイには、再試行ボタン付きのエラー状態が適切に表示されます。

ユーザーはコードに触れることなく、ソースを切り替えることもできます。 ページ URL に ?assets=https://…/manifest.json を指定してください。受け付けるのは https URL のみです。また、すべてのモデルソースはローダーに渡される前に再検証されるため、悪意のあるリンクでカタログを追加することはできても、javascript: や data: のモデルをシーンに紛れ込ませることはできません。これを無効にするには、allowUrlOverride: false を設定してください。

CORS

モデルはブラウザーで読み込まれるため、.glb ファイルを配信するホストでクロスオリジンリクエスト（access-control-allow-origin）を許可する必要があります。モデルの読み込みに失敗する原因は、ほとんどの場合これです。スタジオは黙って失敗するのではなく、ステータス行でその旨を表示します。

---

オプション

オプション	デフォルト	機能
assets	'three.ws'	モデルの取得元です。プリセットキー、マニフェスト URL、ソースオブジェクト、またはそれらの配列を指定します。
generate	有効	{ enabled, endpoint, kind, tier, timeoutMs, pollMs }。endpoint には、互換性のある生成ツールを公開している任意の MCP サーバーを指定します。
rooms	有効	{ enabled, server }。server に独自の Colyseus デプロイを指定すると、共有ルームを自分でホストできます。
animations	three.ws のアイドルクリップ	{ enabled, manifestUrl, clip }。アニメーションが付属しないヒューマノイドモデルにリターゲットするクリップです。
lighting	'studio' HDRI	{ preset, urls }。preset: null の場合はプロシージャルライティングのみを使用し、HDRI はダウンロードしません。
branding	:	{ title, accent, backHref, backLabel }。
shareBaseUrl	このページ	共有リンクと QR コードのリンク先です。
origin	https://three.ws	ホストされた「空間に表示」ランチャーとビューアーリンクのオリジンです。
persistKey	'ar-studio:scene:v1'	保存したシーンの localStorage キーです。変更すると、同じオリジン上で 2 つのスタジオを実行できます。
persist	true	読み込み時に前回のシーンを復元します。
maxPlacements	20	同時に配置できるモデルの上限です。低価格帯のスマートフォンでも操作性を保てます。
fullscreen	自動	固定の全画面レイヤーとして描画します。document.body にマウントした場合のみ、デフォルトで true になります。
allowUrlOverride	true	ホストページの URL にある ?assets=、?src=、?room=、?forge= を反映します。
onEvent	null	注目すべきアクションごとに (event, detail) を受け取って呼び出されます。分析ツールに接続できます。

URL パラメーター

パラメーター	効果
?assets=<https url>	カタログを切り替えます。
?src=<glb>&title=<name>	シーンにモデルを読み込みます。複数指定できます。
#s=<payload>	変換情報も含めた配置全体を再び開きます。shareUrl() によって生成されます。
?room=<code>	共有ルームに参加します。
?forge=<prompt>	読み込み時に生成を開始します。

メソッド

await studio.addModel({ src, title })        // place a model
studio.clear()                               // remove everything; returns what was there
studio.getScene()                            // [{ src, title, x, z, yaw, scale }]
await studio.setScene(items)                 // replace the arrangement
studio.shareUrl()                            // a link that reopens it exactly
await studio.generate('a brass desk lamp')   // text to 3D, into the room
studio.viewInYourSpace(src, title)           // open the hosted launch page for one model
await studio.startCamera()                   // needs a user gesture on iOS
await studio.enterAR()                       // best AR path for this device
studio.openArSheet()                         // the "Place in your space" hand-off sheet
studio.closeArSheet()
await studio.placeInYourSpace()              // straight to the native viewer, no sheet
await studio.toggleImmersive()               // enter or leave WebXR specifically
await studio.openRoom()                      // returns the room code
studio.destroy()                             // releases camera, socket and GPU context

イベント

studio.on(name, fn) は、登録解除関数を返します。同じイベントは、マウントされた要素上で ar-studio:<name> DOM イベントとしても発火します。

イベント	詳細
add	{ placement, remote }
remove	{ src, title }
select	{ placement }（選択解除時は null）
clear	{ items }
generate	{ model }
generate-error	{ error, prompt }
camera	{ active }
xr	{ active }
native-ar	{ src, title, viewer }。viewer は quicklook、sceneviewer、none のいずれかです。
native-ar-error	{ error, src }
ar-sheet	ハンドオフシートが開閉したときの { open }
room	{ status, code }
share	{ url }

---

Web コンポーネント

<ar-studio
  assets="https://cdn.acme.com/models.json"
  title="Acme AR"
  accent="#00b894"
  generate="true"
  rooms="true"
></ar-studio>

element.studio は稼働中のインスタンスです。3d-ar-studio/auto（CDN バンドルが使用するもの）をインポートすると、要素が自動で登録されます。

---

キーボード操作とアクセシビリティ

すべてのコントロールはアクセシブルな名前を持つ実際のボタンです。ソースタブは ARIA タブリストの仕様を完全に実装しており、各ダイアログはフォーカスを受け取り、元に戻します。

キー	操作
矢印キー	選択中のモデルをカメラ基準で少し移動します。Shift キーを押しながら操作すると、移動幅が小さくなります。
R	45° 回転します。
D	複製します。
Delete / Backspace	削除します。ステータス行から元に戻せます。
Escape	開いているパネルを閉じるか、選択を解除します。

prefers-reduced-motion が有効な場合、出現アニメーションとすべてのトランジションが無効になります。

---

MCP サーバー

npx 3d-ar-studio-mcp

{
  "mcpServers": {
    "3d-ar-studio": {
      "command": "npx",
      "args": ["-y", "3d-ar-studio-mcp"]
    }
  }
}

API キーは不要です。すべてのツールを無料で、キーなしで利用できます。

ツール	機能
generate_3d_model	テキストプロンプトからテクスチャ付きの GLB を生成します。モデルに加え、AR で開くリンクも返します。
check_generation	最初の呼び出しが返された時点でレンダリング中だった生成結果を取得します。
search_models	名前、カテゴリ、タグを使って、無料の CC0 ライブラリ（または設定したカタログ）を検索します。
compose_ar_scene	複数のモデルをひとつのシーンに配置し、まったく同じ状態で再び開ける単一のリンクを返します。
export_ar	任意の GLB URL を、デバイスに対応した「空間に表示」リンクに変換します。
create_ar_page	スタジオを埋め込んだ完全な自己完結型 HTML ページを出力します。コミットすればすぐに使えます。

環境変数	デフォルト	変更される内容
AR_STUDIO_PAGE_URL	ホストされたデモ	compose_ar_scene がリンクするページです。独自のデプロイ先に設定してください。
AR_STUDIO_ASSETS	無料の CC0 ライブラリ	search_models が検索するカタログです。
AR_STUDIO_MCP_ENDPOINT	three.ws 3D Studio	生成に使用する MCP エンドポイントです。
AR_STUDIO_ORIGIN	https://three.ws	ホストされた AR 起動リンクおよびビューアーリンクのオリジンです。

セッションは次のようになります。

> Put a mid-century lamp and a potted fern in my living room.

  generate_3d_model  { prompt: "a brass mid-century desk lamp" }   → lamp.glb
  search_models      { query: "potted plant" }                     → fern.glb
  compose_ar_scene   { models: [{ src: lamp.glb, x: 0,   z: -1.4 },
                                { src: fern.glb, x: 0.9, z: -1.2 }] }

  → one link; open it on a phone and both objects stand in the room.

---

デバイスのサポート

デバイス	パス	利用できる機能
Android Chrome	WebXR immersive-ar	部屋全体にシーンを配置します。ヒットテストによる配置、モデルごとのアンカー、光源推定、深度オクルージョンに対応しています。
iOS Safari	AR Quick Look	Apple 独自のビューアーで一度にひとつのモデルを表示し、実際の ARKit トラッキング、スケール、オクルージョンを利用できます。モデルはデバイス上で USDZ に変換されます。ジャイロによるワールドロックを使ったカメラのパススルーで、複数モデルのシーンをページ内で並べて合成します。
WebXR 非対応の Android	Scene Viewer	ARCore を通じて一度にひとつのモデルを表示します。ARCore がない場合はブラウザーにフォールバックします。
デスクトップ	プレビュー	グリッド床、ドラッグによる視点操作、スマートフォンへの QR 引き継ぎに対応しています。
ヘッドセット	WebXR	Android Chrome と同じ機能を利用できます。

トップバーの AR ボタンは、デバイスで利用できる最適な方法を常に選択します。誤解を招く表示にならないよう方式を明示し、選択したモデル（または最後に配置したモデル）を対象にします。

カメラと WebXR の利用には、https:// または localhost のセキュアコンテキストが必要です。

実際の部屋にモデルを配置する

WebXR 対応デバイスでは、AR ボタンを押すとすぐに没入型セッションが始まります。それ以外のデバイスでは、引き継ぎシートが開きます。シートには、配置するモデル、シーンに複数のモデルがある場合の選択メニュー、そしてデバイス標準の AR ビューアーを開くメインボタンが表示されます。

このシートがあるのには、明確な理由がひとつあります。このパッケージを使って独自の UI を構築する場合は、知っておく価値があります。

iOS では、ページが AR Quick Look を開くユーザージェスチャーを保持している間しか、AR Quick Look を起動できません。 GLB を USDZ に変換するには 1、2 秒かかります。タップハンドラー内で変換を始めると、<a rel="ar"> をクリックする時点でジェスチャーの有効期限が切れています。Safari は何も表示せずに起動を拒否し、ボタンが壊れているように見えます。iPhone で「AR で表示」ボタンを押しても何も起きない原因として、これが最もよくあります。

すぐ後ろには、成功したように見えるため、さらに厄介な別の落とし穴があります。

Safari は URL のファイル拡張子から、それが AR アセットかどうかを判断します。 blob: URL にはパスがないため、拡張子もありません。ファイル名を指定せずに <a rel="ar"> に渡すと、Safari は Quick Look を開きますが、一般的な 3D プレビューとして開きます。ビューアーは Object モードになり、AR は利用できません。アンカーに download="something.usdz" を設定すると、Safari が判別に使う名前が渡され、Quick Look が AR モードで開きます。openQuickLook() がこの処理を行います。

そのため、このパッケージでは準備と起動を分けており、1 回のタップで両方を行うことはありません。

import { prepareNativeAr, isQuickLookReady } from '3d-ar-studio';

// Ahead of the tap: convert, cache, and keep the result.
const handoff = await prepareNativeAr({
  src: 'https://example.com/chair.glb',
  title: 'Chair',
  key: '[email protected]',            // cache identity; include the scale if you bake one in
});

// Inside the tap, synchronously. No await between the click and open().
button.addEventListener('click', () => handoff?.open());

prepareNativeAr は、ネイティブ AR ビューアーのないデバイスでは null を返し、開く準備ができた blob: USDZ がある iOS では { viewer: 'quicklook' } を返します。Android では変換が不要なため、{ viewer: 'sceneviewer' } を返します。変換結果はキャッシュされます（同時に 4 件まで、最長未使用のものから削除し、削除時にオブジェクト URL を解放します）。isQuickLookReady(key)、releaseQuickLook(key)、clearQuickLookCache() を使えば、キャッシュを自分で操作できます。

スタジオでは、ボタンで配置するモデルのキャッシュをバックグラウンドで事前に準備します。そのため、その日の 2 回目のタップは即座に反応します。placeInYourSpace() も引き続き利用でき、1 回の呼び出しで両方を行います。USDZ がすでにキャッシュされている場合や、自分で用意したボタンから呼び出す場合に使用してください。

ライブシーンからエクスポートし、GLB を再取得しないのも意図的な設計です。2 回目のダウンロードや CORS の再通信が不要になり、ユーザーが見ているポーズやサイズのまま配置できます。独自の three.js シーンで使いたい場合は、objectToUsdzBlob(object3D) もエクスポートされています。

モデルが床に置かれず、宙に浮いてしまう理由

3つ目の落とし穴は、ほかの2つを回避しても残るものです。

AR Quick Look は、検出した平面にシーンの原点を固定し、ジオメトリは確認しません。 バウンディングボックスの中心を基準に作成された GLB は半分埋まった状態で表示され、離れたシーン原点を基準に作成されたモデルは、モデリング時の高さのまま部屋の中に浮かびます。どちらもトラッキングの不具合のように見えますが、アンカリングのプロパティでは解決できません。コンテンツ自体を移動する必要があります。

そのため、このパッケージからエクスポートするものはすべて、書き出す前に y = 0 の位置に立たせ、フットプリントを原点の上で中央に配置します。独自のシーンに適用したい場合は、groundOnFloor() をエクスポートして使用できます。

これに関連して、もう少し小さな落とし穴が2つあります。

USDZExporter は scene.children をたどり、各ノードのローカル行列を書き込みます。 そのため、渡したオブジェクトのトランスフォームは一切書き込まれません。ルートにスケールを設定しても、警告なしで元のサイズのファイルが出力されます。usdzExportRoot() は、アイデンティティルートと Model ステージノードでコンテンツをラップします。このパッケージが適用する配置はすべて、書き込まれるステージ上に設定されます。

USDZ の単位はメートルです（metersPerUnit = 1）。センチメートル単位で作成した高さ 75 cm の小道具は、高さ 75 m で読み込まれます。大きすぎて屋内で ARKit が検出したどの平面にも収まらず、ビューアーの周囲を漂います。ネットワークから取得したモデルを直接正規化するには、sceneToUsdzBlob() に { fit: true } を渡してください（glbUrlToUsdzBlob() ではすでに適用されています）。現実世界で妥当なサイズの2倍以内に収まるものは、作成時のサイズのまま変更されません。

そして、最もトラッキングの不具合に見える落とし穴がもう1つあります。

Quick Look は、ARKit がモデルを載せられる大きさの平面を検出するまで、モデルを配置しません。 それまではカメラに向けて浮かび、スマートフォンと一緒に移動します。一定の大きさを超えると、一般的な部屋にはそのような平面がないため、モデルはまったく着地しません。clampToPlaceableSize() によって、エクスポートするすべてのモデルは MAX_AR_FOOTPRINT_M（2.5 m）と MAX_AR_HEIGHT_M（2.5 m）を上限とします。これは正規化ではなく上限設定です。家具、人、道具は変更されません。

カメラを使えるクライアントは一度に1つだけです

スタジオはデバイスの AR ビューアーを開く際に getUserMedia のパススルーを解放し、戻ってきたときに再起動します。ページのストリームを動かしたままにすると、別のプロセスがすでに使用しているカメラを使って ARKit が起動します。モデルは表示されますが、ワールドトラッキングと平面検出が収束せず、モデルは安定せずにスマートフォンと一緒に移動します。独自のカメラ UI からこの切り替えを行う場合は、open() を呼び出す前にトラックを停止してください。

パススルーは、ビデオフィードにジャイロスコープを組み合わせたものにすぎません。ユーザーと一緒に向きを変える、それだけです。平面検出も位置トラッキングもないため、実際の床の位置にモデルを固定することはできません。iOS ではそのために Quick Look を使用します。スタジオのステータス行にもその旨が表示されます。

---

開発

npm install
npm test                 # 75 unit tests, no browser needed
npm run build            # dist/ bundles
npm run build:site       # docs/ (the GitHub Pages site)
npm run test:browser     # 35 end-to-end checks in a real browser (needs Playwright)
npm run inspect          # MCP Inspector against the local server

公開サイトは docs/ にコミットされ、main ブランチから GitHub Pages で配信されます。CI ワークフローはありません。npm run build && npm run build:site を実行して、コミットし、プッシュしてください。

---

ライセンスとクレジット

Apache-2.0。

バンドルには three.js（MIT）と colyseus.js（MIT）が含まれています。デフォルトのモデルライブラリには Poly Haven の CC0 コンテンツを使用し、デフォルトの生成およびアニメーションのレーンは three.ws がホストしています。どれも必須ではありません。いずれも変更可能な URL です。

Star History

プロジェクトをサポートする

3D-AR-Studio が時間の節約に役立ったら、GitHub でスターを付けてください。スターがあると、他の開発者や AI エージェントが信頼できるリポジトリを見つけやすくなります。クリックは 1 回だけです。

使ってくれそうな方をご存じですか？ X に投稿する · Bluesky でシェアする · LinkedIn でシェアする · Hacker News に投稿する · Reddit でシェアする

AI エージェントにも対応

コーディングエージェントや LLM ツールは、このリポジトリを直接読み取れます：AGENTS.md、llms.txt、llms-full.txt。エージェントに https://github.com/nirholas/3D-AR-Studio を指定すれば、必要なコンテキストを取得できます。

同じ作者によるその他のプロジェクト

• nirholas のすべてのリポジトリ：トピック別にまとめた全カタログ
• three.ws：Solana ウォレット、スキルマーケットプレイス、x402 決済を備えた 3D AI エージェント向けプラットフォーム
• 質問やアイデア：issue を作成するか、ディスカッションを始める

コントリビューター