こんにちは、もしくはこんばんは。シロです！
model-viewerは、Web上で簡単に3Dモデルを表示できるJavaScriptライブラリです。
しかし、残念ながら具体的な使いかたのドキュメントが少なく、調べるのに苦労したので自分でまとめることにしました！
この記事では、model-viewer上の3Dモデルに注釈をつけるアノテーション機能について、公式ドキュメントのAnnotationsの項目から検証した結果も含めて解説していきます。
アノテーション機能とは
3Dモデルに対して注釈をつける機能です。
アノテーションを使用すると、3Dモデルに対して追加の情報を提供できるため、説明的でわかりやすいビューアーを作成することができます。
また、ホットスポットと呼ばれる目印を3次元の3Dモデル上に表示することもできます。
この例では、２つのアノテーションと、３つのホットスポット(鼻、右手、左足)をビューアー上に表示しています。
<style>
.hotspot{
display: block;
width: 20px;
height: 20px;
border-radius: 10px;
border: none;
background-color: blue;
box-sizing: border-box;
pointer-events: none;
}
.hotspot[slot="hotspot-hand"]{
--min-hotspot-opacity: 0;
background-color: red;
}
.hotspot[slot="hotspot-foot"]:not([data-visible]) {
background-color: transparent;
border: 3px solid blue;
}
.annotation{
background-color: #888888;
position: absolute;
transform: translate(10px, 10px);
border-radius: 10px;
padding: 10px;
width:200px;
}
/* This keeps child nodes hidden while the element loads */
:not(:defined) > * {
display: none;
}
</style>
<model-viewer src="path/to/model.gltf" camera-controls="">
<button class="hotspot" slot="hotspot-visor" data-position="0 1.8 0.75" data-normal="0 0 1"></button>
<button class="hotspot" slot="hotspot-hand" data-position="-0.57 0.75 0" data-normal="-0.73 0.05 0.69">
<div class="annotation">このアノテーションはモデルに隠れます</div>
</button>
<button class="hotspot" slot="hotspot-foot" data-position="0.25 0.1 0.18" data-normal="-0.07 0.97 0.23" data-visibility-attribute="visible"></button>
<div class="annotation">このアノテーションは画面に固定されています</div>
</model-viewer>CSS：スタイルシート
–min-hotspot-opacity
--min-hotspot-opacity属性は、非表示状態となったホットスポットの不透明度を設定することができます。
設定値は0から1までの任意の実数値で、デフォルト値は0.25です。
モデルを回転させると、ホットスポットはモデルの裏に隠れる場合があります。この時、非表示状態となります。
–max-hotspot-opacity
--max-hotspot-opacity属性は、表示状態のホットスポットの不透明度を設定することができます。
設定値は0から1までの任意の実数値で、デフォルト値は1です。
この例では、非表示中の不透明度を0.5、表示中の不透明度を0.8に設定しています。
<style>
.hotspot{
display: block;
width: 20px;
height: 20px;
border-radius: 10px;
border: none;
background-color: blue;
box-sizing: border-box;
pointer-events: none;
--min-hotspot-opacity: 0.5;
--max-hotspot-opacity: 0.8;
}
</style>
<model-viewer src="path/to/model.gltf" camera-controls="">
<button class="hotspot" slot="hotspot-visor" data-position="0 1.8 0.75" data-normal="0 0 1"></button>
</model-viewer>Methods：メソッド
updateHotspot({name, position, normal})
queryHotspot(name)
positionAndNormalFromPoint(clientX, clientY)
surfaceFromPoint(clientX, clientY)
Slots：スロット
hotspot-*
ホットスポット機能は、3Dモデル上に画像やテキストなどのコンテンツを重ねて表示することができる機能です。ホットスポットは、3Dモデルの特定のポイントに配置できます。
ホットスポットは、model-viewerで<model-viewer>要素の子要素にslot="hotspot-XXX"という属性を設定することで定義できます。
ホットスポットの位置は、data-position属性とdata-normal属性、もしくはdata-surface属性を使用して3D座標上に設置します。
3D座標軸については以下の記事を参考にしてみてください。
data-position
data-position属性は、3Dモデルの座標系でホットスポットの位置を指定します。
この属性の値は、3つの数字からなるスペース区切りの文字列で表され、それぞれX、Y、Z座標を表します。たとえば、以下のようにdata-position属性を使用して、ホットスポットの位置を指定することができます。
<model-viewer src="path/to/model.gltf" camera-controls="">
<button class="hotspot" slot="hotspot-hoge" data-position="0 0.5 0"></button>
</model-viewer>data-normal
data-normal属性は、ホットスポットの法線ベクトルを指定します。
ホットスポットの法線は、ホットスポットを配置する面の法線ベクトルと一致する方向を向いている必要があります。この属性の値は、3つの数字からなるスペース区切りの文字列で表され、それぞれX、Y、Z方向の法線ベクトルを表します。たとえば、以下のようにdata-normal属性を使用して、ホットスポットの法線を指定することができます。
<model-viewer src="path/to/model.gltf" camera-controls="">
<button class="hotspot" slot="hotspot-hoge" data-normal="0 1 0"></button>
</model-viewer>法線ベクトルとはつまり、ホットスポットの正面がどちらを向いているかを定義しています。
モデルを回転させて、法線ベクトルの裏側に向くと、非表示状態となり上述した--min-hotspot-opacityが有効になります。
これらの属性を使用することで、ホットスポットの位置や法線を細かく調整することができます。ただし、これらの属性を使用する場合は、3Dモデル上で正しい位置や法線を指定する必要があります。適切な位置や法線が指定されていない場合、ホットスポットが意図した通りに表示されないことがあります。
data-surface
data-surface属性は、3Dモデルの重心座標を指定します。
重心座標を指定できれば、アニメーションを含む3Dモデルの重心が変わった場合に、アニメーションに追従してアノテーションを表示させることができます。
例については準備中です。
まとめ
この記事では、<model-viewer>のAnnotations APIについて解説しました。
アノテーション機能を使えば、よりユーザフレンドリーな3D Webコンテンツを作成できます。
3次元のビューアーへの配置は難しいですが、ぜひAnnotation APIを使いこなして、魅力的な3D Webコンテンツを作成してください！
以上、「【model-viewer】Annotations APIの解説」でした。
コメント