こんにちは、もしくはこんばんは。シロです！
model-viewerは、Web上で簡単に3Dモデルを表示できるJavaScriptライブラリです。
しかし、残念ながら具体的な使いかたのドキュメントが少なく、調べるのに苦労したので自分でまとめることにしました！
この記事では、3DデータをWebページ上でぐるぐる動かすためのStaging & Camerasの項目から検証した結果も含めて解説していきます。
Attributes：属性
camera-controls
camera-controls属性は、3Dモデルを操作するためのカメラコントロールを有効にするための属性です。
この属性が有効にすると、Webページに表示した3Dモデルをマウスやタッチを使って自由に操作することができます。
<model-viewer src="path/to/model.gltf" camera-controls></model-viewer>camera-controls属性を有効にすると以下の操作が行えます。
モデルを回転させる…(マウス)マウス左クリックを押したままドラッグ / (タッチ)シングルタッチ
モデルをパン(水平移動)させる…(マウス)マウス右クリックを押したままドラッグ / (タッチ)ダブルタッチ
モデルを拡大縮小させる…(マウス)ホイールをスクロール / (タッチ)ピンチイン/アウト
disable-pan
disable-pan属性は、3Dモデルを水平方向にパン（スライド）できるようにするかどうかを制御するためにの属性です。
この属性を有効にすると、3Dモデルにマウスでドラッグすると、水平方向にスライドする代わりに、マウスポインターが移動する方向に応じて、3Dモデルが回転します。
<model-viewer src="path/to/model.gltf" camera-controls disable-pan></model-viewer>disable-pan属性を有効にすると、モデルのパン(水平移動)を無効化します。マウス右クリックの操作は左クリックと同等になります。
disable-tap
disable-tap属性は、タップ操作を使用してコントロールを操作できるようにするかどうかを制御するための属性です。
この属性を有効にすると、タップ操作を使用してコントロールを操作できなくなります。
例えば、タッチデバイスでユーザーがモデルを意図しない方法で操作してしまうのを防止できます。
<model-viewer src="path/to/model.gltf" camera-controls disable-tap></model-viewer>disanle-tap属性を有効にすると、タップ操作を無効化します。スマホやタブレットなどで試してみてください。
touch-action
touch-action属性は、モバイル端末で3Dモデルをタッチ操作する場合のブラウザのデフォルトのタッチアクションを変更するために使用します。
ブラウザのデフォルトのタッチ操作との競合を回避することができます。
公式ドキュメントによると、一部のiOSではバグが発生するそうで、この影響かわかりませんが、実際に試してみても違いがよくわかりませんでした…(iPadOS 16.3.1)
<model-viewer src="path/to/model.gltf" camera-controls touch-action="pan-x"></model-viewer>disable-zoom
disable-zoom属性は、3Dモデルのズーム機能を無効化します。
この属性が設定されている場合、ユーザーは3Dモデルをズームインまたはズームアウトすることができなくなります。つまり、ユーザーは、カメラコントロールによって指定された距離と視野角の間でのみ3Dモデルを表示できます。
<model-viewer src="path/to/model.gltf" camera-controls disable-zoom></model-viewer>orbit-sensitivity
orbit-sensitivity属性は、3Dモデルのカメラコントロールにおいて、マウスのドラッグ操作に対する感度を調整できます。
この属性に指定する値は、マウスのドラッグ操作に対する感度を表す数値で、値が大きいほど感度が高くなり、小さいほど感度が低くなります。
デフォルト値は1で、1より小さい値を設定すると感度が下り、カメラの回転が遅くなります。大きい値を設定すると感度が上がり、カメラの回転が速くなります。
また、逆に負の値を設定することができます。負の値を設定すると、カメラの回転が逆になります。
<model-viewer src="path/to/model.gltf" camera-controls orbit-sensitivity="0"></model-viewer>auto-rotate
auto-rotate属性は、3Dモデルの自動回転を有効にします。
この属性が設定されていると、モデルを表示してからauto-rotate-delay属性で指定した時間後にモデルの自動回転が始まります。
<model-viewer src="path/to/model.gltf" auto-rotate></model-viewer>auto-rotate-delay
auto-rotate-delay属性は、3Dモデルの自動回転が始まるまでの遅延時間を設定できます。
設定する値はミリ秒単位の0以上の正数値で、デフォルト値は3000ミリ秒です。
<model-viewer src="path/to/model.gltf" auto-rotate auto-rotate-delay="1500"></model-viewer>rotation-per-second
rotation-per-second属性は、3Dモデルの自動回転速度を設定できます。
設定する値は度またはラジアンの値と、デフォルト値(pi/32ラジアン)に対するパーセントを指定できます。
例えば、rotation-per-second="30deg"を設定すると、1秒間に30度自動回転します。rotation-per-second="200%"を設定すると、デフォルトよりも2倍速く自動回転します。
また、負の値を設定することもでき、負の値を設定すると自動回転の方向が逆(時計回り)になります。
<model-viewer src="path/to/model.gltf" auto-rotate rotation-per-second="200%"></model-viewer>interaction-prompt
interaction-prompt属性は、ユーザーに対して3Dモデルの操作方法を対話するかのように示すプロンプトを表示するために使用します。
設定値にはautoとnoneを指定でき、デフォルトにはautoが設定されています。
interation-prompt="none"を指定すると、プロンプトを無効化します。
<model-viewer src="path/to/model.gltf" camera-controls interaction-prompt="none"></model-viewer>interaction-prompt-style
interaction-prompt-style属性は、interaction-prompt属性によって表示されるプロンプトのスタイルをカスタマイズするために使用します。
設定値にはwiggleとbasicを指定でき、デフォルトにはwiggleが設定されています。
wiggleはプロンプトを水平方向にアニメーション化し、モデルはユーザと対話しているかのように回転することで、ユーザにモデルを操作可能であることを提示できます。
basicはプロンプトやモデルをアニメーション化しませんが、ユーザの操作によって閉じられるまでプロンプトを表示し続けます。
<model-viewer src="path/to/model.gltf" camera-controls interaction-prompt-style="basic"></model-viewer>
interaction-prompt-threshold
interaction-prompt-threshold属性は、interaction-prompt属性によって表示されるプロンプトを表示するまでの時間を設定できます。
設定値はミリ秒単位で0以上の正の数値を指定できます。デフォルト値は3000ミリ秒です。
この例では、モデルを表示してから5000ミリ秒(5秒)後にプロンプトを表示します。
<model-viewer src="path/to/model.gltf" camera-controls interaction-prompt-threshold="5000"></model-viewer>camera-orbit
camera-orbit属性は、3Dモデルのカメラの軌道を定義するために使用します。この属性を使用すると、カメラの位置と向きを制御し、3Dモデルを異なる角度から見ることができます。
設定値は左から順に、方位角θ、極角φ、カメラ距離radiusを指定します。
方位角θは垂直軸に対しての角度、極角φは水平軸に対しての角度、カメラ距離はモデル中心からの半径を表します。
方位角θおよび極角φの単位は度数法degと弧度法radが使用できます。
カメラ距離の単位はcmとmmおよび、カメラとの距離に対する%が使用できます。
camera-orbit属性の値は、3つのスペース区切りの数値で表され、それぞれの数値は、カメラが注視する点（ターゲット）からの距離、垂直軸まわりの角度、水平軸まわりの角度を表します。
例えば、以下のようにcamera-orbit属性を使用して、カメラの軌道を定義することができます。
<model-viewer src="path/to/model.gltf" camera-controls camera-orbit="10deg 45deg 0"></model-viewer>上記の例では、カメラはターゲットから10単位の距離にあり、垂直軸まわりに45度回転し、水平軸まわりに0度回転しています。
camera-orbit属性を使用すると、3Dモデルの異なる視点からの表示を簡単に変更できるため、3Dモデルの詳細な観察やデモンストレーションに便利です。
camera-target
camera-target属性は、3Dモデルのカメラの注視点（ターゲット）を定義するために使用します。この属性を使用すると、カメラの視点は固定され、3Dモデルの特定の位置を中心に見ることができます。
camera-target属性の値は、3つのスペース区切りの数値で表され、それぞれの数値は、カメラが注視する点のX、Y、Z座標を表します。例えば、以下のようにcamera-target属性を使用して、カメラの注視点を定義することができます。
<model-viewer src="path/to/model.gltf" camera-controls camera-target="0 0 0"></model-viewer>上記の例では、カメラの注視点は、3Dモデルの原点（X、Y、Z座標がすべて0）に設定されています。
camera-target属性を使用すると、カメラの位置を固定しながら、3Dモデルの特定の位置を中心に見ることができます。これは、3Dモデルの特定の部分に焦点を合わせる必要がある場合などに便利です。
field-of-view
準備中
max-camera-orbit
準備中
min-camera-orbit
準備中
max-field-of-view
準備中
min-field-of-view
準備中
interpolation-decay
準備中
Properties：プロパティ
turntableRotation
準備中
inputSensitivity
準備中
Methods：メソッド
resetTurntableRotation(theta)
準備中
resetInteractionPrompt()
準備中
getCameraOrbit()
準備中
getCameraTarget()
準備中
getFieldOfView()
準備中
jumpCameraToGoal()
準備中
updateFraming()
準備中
getMinimumFieldOfView()
準備中
getMaximumFieldOfView()
準備中
getIdealAspect()
準備中
zoom(keyPresses)
準備中
interact(duration, finger0, finger1)
準備中
Events：イベント
camera-change
準備中
interact-stopped
準備中
Slots：スロット（準備中）
interaction-prompt
準備中
finger0/finger1
準備中
pan-target
準備中
まとめ
この記事では、<model-viewer>のStaging & Cameras APIについて解説しました。
カメラコントロールはユーザの操作性に直結する重要な要素です。
デフォルトでも十分に使えますが、作成するコンテンツによってはよりユーザビリティにこだわりたい場合もあるでしょう。
ぜひ、Staging & Cameras APIを使いこなして、魅力的な3D Webコンテンツを作成してください！
以上、「【model-viewer】Staging & Cameras APIの解説」でした。