【model-viewer】AR(Augmented Reality) APIの解説

こんにちは、もしくはこんばんは。シロです！

model-viewerは、Web上で簡単に3Dモデルを表示できるJavaScriptライブラリです。

しかし、残念ながら具体的な使いかたのドキュメントが少なく、調べるのに苦労したので自分でまとめることにしました！

この記事では、3Dコンテンツ最大の魅力であるAR(Augmented Reality)の項目から検証した結果も含めて解説していきます。

Attributes：属性

ar

AR機能を有効にします。ARが有効なOSは以下の通りです。

• iOS 11以降のiPhoneおよびiPad
• Android 7.0以降のAndroidスマートフォンおよびタブレット

<model-viewr>のタグにarを付与すると、下の画像のようにAR起動ボタンが表示されます。

<model-viewer src="path/to/mode.gltf" ar></model-viewer>

ar-modes

ar-scale

ar-scale属性は、AR表示を行う際に、3Dモデルのスケールを調整するために使用します。

設定値はautoかfixedを指定でき、デフォルトはautoが設定されています。

autoを設定すると、ARモードでのスケーリングが有効になり、ピンチイン・ピンチアウト操作で3Dモデルの大きさを調整できます。

fixedを指定すると、ARモードでのスケーリングを無効にし、3Dモデルを常に100%の大きさで表示します。

<model-viewer src="path/to/mode.gltf" ar ar-scale="fixed"></model-viewer>

iPadOS16.3.1およびiOS16.3.1ではfixedを指定してもスケーリングができてしまいました。AndroidOSでは未検証です。

ar-placement

ar-placement属性は、AR表示を行う際に、3Dモデルを配置する位置を指定するために使用します。

AR表示では、デバイスのカメラを使用して現実世界を背景として3Dモデルを表示するため、3Dモデルを正確に配置することが重要です。ar-placement属性は、3Dモデルをどのように配置するかを指定することができます。

ar-placement属性には、以下の値を指定することができ、デフォルトはfloorが設定されています。

• floor: 3Dモデルを地面に配置します。この場合、3Dモデルの底面が地面に接するように配置されます。
• wall: 3Dモデルを壁に配置します。この場合、3Dモデルの底面が壁に接するように配置されます。

ar-placement属性は、ar属性が指定された場合にのみ有効であり、通常の表示時には無視されます。また、ar属性が指定されていない場合には、ar-placement属性も無視されます。

例えば、以下のようにar-placement="floor"と指定することで、3Dモデルを地面に配置することができます。

<model-viewer src="path/to/mode.gltf" ar ar-placement="floor"></model-viewer>

ios-src

準備中

xr-environment

準備中

CSS：スタイルシート

ar-status

CSSのar-statusは、<model-viewer>要素がARモードに入ったときに表示されるステータスメッセージに対して、スタイルを適用するためのセレクターです。

ar-tracking

CSSのar-trackingは、<model-viewer>要素がARモードで動作しているときに、現在のARトラッキング状態を示すスタイルを定義するために使用されます。このスタイルは、ARトラッキングが開始されたかどうか、ARセッションがアクティブかどうか、ARトラッキングが失われたかどうかなど、さまざまな状況でカスタムスタイルを設定するために使用できます。

具体的には、ar-trackingスタイルを使用することで、ARセッションがアクティブな場合に要素に特定のスタイルを適用したり、ARトラッキングが失われた場合に要素に別のスタイルを適用したりすることができます。

以下は、ar-trackingスタイルを使用して、ARセッションがアクティブである場合に背景色を緑色に、ARトラッキングが失われた場合に背景色を赤色に変更する例です。

model-viewer[ar-status="tracking"] {
  background-color: green;
}

model-viewer[ar-status="not-tracking"] {
  background-color: red;
}

Properties：プロパティ

canActivateAR

canActivateARプロパティは、AR機能を有効化するためにユーザーが使用できるかどうかを示す真偽値を返すプロパティです。

このプロパティは、AR機能をサポートしているデバイスの場合にtrueを返します。

この例では、AR機能が有効なデバイスの場合のみにEnable ARボタンを有効にしています。

<model-viewer src="path/to/model.gltf" ar>
  <button id="ar-button" disabled>Enable AR</button>
</model-viewer>

<script>
  const viewer = document.querySelector('model-viewer');
  const arButton = document.querySelector('#ar-button');

  if (viewer.canActivateAR) {
    arButton.disabled = false;
    arButton.addEventListener('click', () => {
      viewer.activateAR();
    });
  }
</script>

Methods：メソッド

activateAR()

activateARメソッドは、ARモードに移行するためのメソッドです。

この例では、ボタンクリック時にcanActiveARプロパティでAR機能が有効かチェックし、有効な場合にactiveAR()メソッドでARモードに移行しています。

const viewer = document.querySelector('model-viewer');

// ARを有効にするボタンのクリック時に実行する
document.querySelector('#activate-ar-button').addEventListener('click', () => {
  // ARがサポートされている場合にARモードに移行する
  if (viewer.canActivateAR) {
    viewer.activateAR();
  }
});

Events：イベント

ar-status

ar-statusイベントは、ARモードの状態に変更があったときに発生するイベントです。<model-viewer>要素のcanActivateARプロパティがtrueに設定されている場合、ARサポートを持つデバイスでこの要素がクリックされたときに、ar-statusイベントがトリガーされます。また、ARモードに移行した場合、ARモードから戻った場合にもイベントが発生します。

ar-statusイベントには、detailプロパティが含まれており、detailプロパティにはARモードの状態を示すstatusプロパティが含まれています。statusプロパティは、次のいずれかの値を持ちます。

• not-present: デバイスがARをサポートしていない場合
• unsupported: ブラウザがARをサポートしていない場合
• presenting: ARモードに移行中の場合
• not-presenting: ARモードから戻った場合

以下は、ar-statusイベントをリッスンして、ARモードが有効化されたかどうかを検出する方法の例です。

<model-viewer id="modelViewer" src="model.glb" ar ar-modes="webxr scene-viewer quick-look"></model-viewer>

<script>
  const modelViewer = document.querySelector('#modelViewer');

  modelViewer.addEventListener('ar-status', (event) => {
    if (event.detail.status === 'presenting') {
      console.log('AR mode enabled');
    } else if (event.detail.status === 'not-presenting') {
      console.log('AR mode disabled');
    }
  });
</script>

ar-tracking

ar-trackingイベントは、ARモードで表示されている3Dモデルがトラッキングされているかどうかを示すために発生するイベントです。

このイベントは、ARモードで3Dモデルがトラッキングされている場合に発生します。トラッキングが失われた場合は、イベントは自動的に解除されます。イベントの詳細は、イベントオブジェクトによって提供されます。

以下は、ar-trackingイベントの例です。

const modelViewer = document.querySelector('model-viewer');

modelViewer.addEventListener('ar-tracking', (event) => {
  if (event.detail.state === 'tracking') {
    console.log('3D model is being tracked.');
  } else if (event.detail.state === 'not-tracking') {
    console.log('3D model is not being tracked.');
  }
});

この例では、ar-trackingイベントが発生したときに、3Dモデルがトラッキングされているかどうかに基づいてログメッセージが表示されます。stateプロパティには、現在のトラッキング状態が含まれます。stateプロパティの値は、’tracking’または’not-tracking’のいずれかです。

quick-look-button-tapped

quick-look-button-tappedイベントは、Quick Lookボタンがタップされたときに発生するmodel-viewerのカスタムイベントです。Quick Lookボタンは、iOSデバイスのSafariブラウザでmodel-viewerが表示されている場合に表示され、ユーザーがAR体験を開始することができます。

quick-look-button-tappedイベントは、以下のようにして使用できます。

const viewer = document.querySelector('model-viewer');

viewer.addEventListener('quick-look-button-tapped', () => {
  // Quick Lookボタンがタップされた時の処理
});

Quick Lookボタンを使用するには、model-viewerにar属性を設定する必要があります。また、Quick Lookボタンをタップすることで、iOSデバイスのQuick Lookアプリが起動し、AR体験を開始することができます。

Parts：パーツ

default-ar-button

準備中

default-exit-webxr-ar-button

準備中

Slots：スロット

ar-button

準備中

exit-webxr-ar-button

準備中

まとめ

この記事では、<model-viewer>のAR(Augmented Reality) APIについて解説しました。

model-viewerのAR機能を使えば、あなたが作った3Dモデルを簡単に現実世界に投影できるようになります。

ぜひ、AR APIを使いこなして、魅力的な3D ARコンテンツを作成してください！

以上、「【model-viewer】AR(Augmented Reality) APIの解説」でした。