model-viewerのAPI Reference説明ページの翻訳
何ができるのか、とりあえずGoogle翻訳にかけたものです
https://modelviewer.dev/docs/index.html
〜〜〜
属性（Attributes）
属性（Attributes）
src
3DモデルのURL。glTF/GLBモデルのみサポートされます。
alt
スクリーンリーダーを使用するユーザーや、表示内容を理解するために追加のセマンティックコンテキストを必要とするユーザー向けに、モデルを説明するカスタムテキストを設定します。
poster
モデルの代わりに画像を表示します。モデルが読み込まれてレンダリング準備ができる前に、ユーザーに何かを見せるのに便利です。
loading
モデルをプリロードする条件を指定する列挙可能な属性です。サポートされる値は「auto」、「lazy」、「eager」です。autoはlazyと同等で、reveal="auto"の場合はモデルがビューポートに近づいたときに、reveal="interaction"の場合は操作があったときにモデルをロードします。 Eager はモデルを即座に読み込みます。
デフォルト値：auto
オプション値：auto,lazy, eager
reveal
この属性は、モデルを表示するタイミングを制御します。reveal が "auto" に設定されている場合、モデルは読み込みとレンダリングが完了次第表示されます。reveal が "manual" に設定されている場合、モデルは dismissPoster() が呼び出されるまで非表示のままです。
デフォルト値：auto
オプション値：auto, manual
with-credentials
この属性は、ブラウザが 3D モデルを取得するリクエストに認証情報（Cookie、認証ヘッダー、または TLS クライアント証明書）を含めるように指定します。これは、3D モデルファイルが認証を必要とする別のサーバーに保存されている場合に便利です。デフォルトでは、ファイルは認証情報なしで取得されます。ただし、ローカルまたは同じドメインからファイルを読み込む場合は、このオプションは効果がありません。
デフォルト値：false
オプション値：true, false
a11y
wcag 準拠モデルに固有の翻訳を追加します。この属性を使用する場合は、以下のキーを持つJSONオブジェクトを指定する必要があります：front、back、left、right、upper-front、upper-back、upper-left、upper-right、lower-front、lower-back、lower-left、lower-right、interaction-prompt。これらのキーの値は、モデルの向きを表す翻訳値である必要があります。この属性は、スクリーンリーダーやその他の支援技術で役立ちます。
デフォルト値：null
オプション値：{"front": "Front of 3D model","back": "Back of 3D model","left": "Left of 3D model","right": "Right of 3D model","upper-front": "Upper front of 3D model","upper-back": "Upper back of 3D model","upper-left": "Upper left of 3D model","upper-right": "Upper right of 3D model","lower-front": "Lower front of 3D model","lower-back": "Lower back of 3D model","lower-left": "Lower left of 3D model","lower-right": "Lower right of 3D model","interaction-prompt": "'Use mouse, touch or arrow keys to move"}
プロパティ(Properties）
loaded
このプロパティは読み取り専用です。src が最後に変更されてから以下の load イベントが発生した場合、true を返します。
デフォルト値：N/A
オプション値：true, false
modelIsVisible
このプロパティ（model-is-visible と発音）は読み取り専用です。要素がページ上に表示されており（IntersectionObserver が存在する場合）、投稿者が閉じられている場合、true を返します。このプロパティは model-visibility イベントに関連しています。
デフォルト値：N/A
オプション値：true, false
静的プロパティ(Static Properties)
dracoDecoderLocation
この静的で書き込み可能なプロパティは、<model-viewer> の DRACO デコーダーのロケーション URL を設定します。デフォルトでは、DRACO デコーダーは Google CDN から読み込まれます。
ktx2TranscoderLocation
この静的で書き込み可能なプロパティは、<model-viewer> の KTX2 トランスコーダのロケーション URL を設定します。デフォルトでは、KTX2 トランスコーダは Google CDN から読み込まれます。
meshoptDecoderLocation
この静的かつ書き込み可能なプロパティは、<model-viewer> の Meshopt デコーダーのロケーション URL を設定します。デフォルトでは、Meshopt デコーダーは無効です。
lottieLoaderLocation
この静的かつ書き込み可能なプロパティは、<model-viewer> の LottieLoader のロケーション URL を設定します。デフォルトの URL は https://cdn.jsdelivr.net/npm/three@0.174.0/examples/jsm/loaders/LottieLoader.js です。また、サーバー側で lottie キャンバスモジュール (../libs/lottie_canvas.module.js) を提供する必要があります。
minimumRenderScale
この静的かつ書き込み可能なプロパティは、<model-viewer> がフレームレートを維持するために解像度を動的に変更する際の最小レンダリングスケール係数を設定します。render-scale イベントで動作を監視してください。この効果を無効にするには、1 に設定します。
デフォルト値：0.5
オプション値：0.25 ～ 1 の間の数値
modelCacheSize
この静的かつ書き込み可能なプロパティは、<model-viewer> の内部 glTF モデルキャッシュサイズを設定し、キャッシュする個々のモデルの数を制御します。同時に任意の数のモデルをキャッシュできることに注意してください。この数値は、ドキュメント内の <model-viewer> 要素で使用されていない場合でも、キャッシュできるモデルの最大数を設定します。また、キャッシュサイズはバイト数ではなく glTF モデルの数で測定されることに注意してください。2 つのモデルのバイトサイズが大きく異なる可能性があるため、この点に注意してください。
デフォルト値：5
オプション値：0以上の任意の整数
powerPreference
この静的かつ書き込み可能なプロパティは、<model-viewer> の電力設定値を設定します。値が指定されていない場合、model-viewer はこのプロパティを高パフォーマンスに設定します。
デフォルト値：high-performance
オプション値：high-performance, low-power, default
メソッド(Methods)
dismissPoster()
ポスターを閉じ、必要に応じてモデルの読み込みとレンダリングを行います。これは現在、ユーザー入力によるポスターの操作と実質的に同じです。
showPoster()
ポスターを表示し、モデルを非表示にします。3Dモデルが表示された後でこのメソッドが呼び出された場合、reveal='interaction' が指定されたかのように動作し、ユーザーのクリックまたはdismissPoster()の呼び出しによってモデルが閉じられます。
getDimensions()
ターンテーブルの回転とは無関係に、モデルの境界ボックスの寸法をメートル単位で返します。返されるオブジェクトは、x、y、zプロパティとtoString()メソッドを持ちます。
getBoundingBoxCenter()
ターンテーブルの回転とは無関係に、モデルの境界ボックスの中心点をメートル単位で返します。返されるオブジェクトは、x、y、zプロパティとtoString()メソッドを持ちます。
toBlob(options: {mimeType, qualityArgument, idealAspect})
mimeType で指定された形式（デフォルトは image/png）の Blob オブジェクトに解決される Promise を返します。Blob オブジェクトは、不変の生データを持つファイルのようなオブジェクトを表します。qualityArgument には 0 から 1 の間の値を指定することもできます（現在 Chrome デスクトップと Firefox でのみ使用可能）。image/png の場合はデフォルトで 0.92、image/webp の場合は 0.8 です。idealAspect を true に設定すると、Blob はキャンバスのアスペクト比ではなく、理想的なポスターのアスペクト比でキャプチャされます。これにより、単一のポスターがどのキャンバスのアスペクト比でもレンダリングとシームレスに一致する、ポスターを簡単に作成できます。
toDataURL(type, encoderOptions)
現在のモデルレンダリングのスクリーンショットを、type で指定された形式（デフォルトは image/png）で返します。スクリーンショットはデータ URL 文字列としてエンコードされます。品質のスライドスケールをサポートするフォーマット（image/jpeg や image/webp など）では、encoderOptions に 0 から 1 の値を指定することもできます（それ以外の場合、encoderOptions のデフォルトは 0.92 です）。
registerEffectComposer(effectComposer)
このメソッドを使用すると、この要素のデフォルトのレンダリングを EffectComposer レンダラースタックに置き換えることができます。externalRenderer とは異なり、glTF およびレンダリング関連の API 部分はすべて引き続き正常に機能します。
提供された EffectComposer は、以下の関数で構成される EffectComposerInterface を実装する必要があります。
- render(deltaTime?: number): void
- setRenderer(renderer: WebGLRenderer): void
- setMainScene(scene: Scene): void
- setMainCamera(camera: Camera): void
- setSize(width: number, height: number): void
このメソッドを使用して EffectComposer を登録すると、setRenderer、setMainScene、setMainCamera が呼び出されます。通常の render メソッドと同様に、deltaTime をミリ秒単位で指定して render メソッドが呼び出されます。要素のサイズが変更されると、setSize メソッドが呼び出されるため、エフェクトは常に適切なサイズになります。
unregisterEffectComposer()
デフォルトのレンダリングに切り替え、EffectComposer の呼び出しを停止します。
registerRenderer(externalRenderer)
このメソッドを使用すると、この要素のレンダリングスタック全体を独自のものに置き換えることができます。 API の glTF 関連部分（AR、ライティング、ステージング、アニメーション、シーングラフ）は機能しなくなります。ただし、読み込み、カメラ、アノテーションは引き続き通常通り機能します。データはユーザーが管理するため、任意の種類のファイルをロードしたり、スクリプトからシーンを生成したりすることも可能です。
提供された externalRenderer は、以下の 3 つの関数で構成される RendererInterface を実装する必要があります。
- load(progressCallback: (progress: number) => void): Promise<FramingInfo>
- render(camera: Camera): void
- resize(width: number, height: number): void
要素は通常 glTF をロードするときに、load メソッドを呼び出します。デフォルトでは遅延ロードされます。src には、空の要素ではないことを示す値（任意の文字列）を設定してください。progressCallback を定期的に呼び出してプログレスバーを更新し、ピクセルの表示準備が完了したら、進捗状況を 1.0 に設定してください。カメラがデフォルト設定を行えるように、framedRadius と fieldOfViewAspect という 2 つの数値を含む FramingInfo オブジェクトを返す必要があります。framedRadius は境界球のサイズ、fieldOfViewAspect はモデルをフレームするための理想的な要素アスペクト比です (1.0 が適切なデフォルトです)。
カメラが変更されると render メソッドが呼び出され、viewMatrix: Array<number> と projectionMatrix: Array<number> を 4x4 行列として含む Camera オブジェクトが渡されます。これを使用して、キャンバス スロット要素内のレンダリングされたピクセルを更新します。要素のサイズが変更されると resize メソッドが呼び出されるため、スロット化されたキャンバス要素に対して調整されたアクションを実行できます。
unregisterRenderer()
glTF/GLB ソースのレンダリングをデフォルトに戻し、外部レンダラーの呼び出しを停止します。同時に、独自のスロット化されたキャンバス要素を手動で削除する必要があることに注意してください。
静的メソッド（Static Methods）
mapURLs(callback)
指定されている場合、コールバックにはリクエストの送信前に各リソースURLが渡されます。コールバックは元のURLを返す場合もあれば、読み込み動作をオーバーライドする新しいURLを返す場合もあります。この動作は、.ZIPファイル、ドラッグアンドドロップAPI、データURIからアセットを読み込む際に使用できます。
イベント（Events）
error
このイベントは、モデルの読み込みまたは解析に失敗した、またはWebGLコンテキストが失われたという2つの理由で発生します。モデルの読み込みに失敗した場合、event.detail.typeは「loadfailure」になります。WebGLコンテキストが失われた場合、event.detail.typeは「webglcontextlost」になります。どちらの場合も、回復対策はユーザーの判断に委ねられます。要素は、読み込みに失敗したモデルの再読み込みを自動的に試行することはありません。また、WebGLコンテキストが失われた後に復元を試行することもありません。errorイベントは、発生したエラーイベント（存在する場合）への参照をevent.detail.sourceEventとして保持します。
before-render
モデルが読み込まれたとき、最初のレンダリングフレームの前に発生します。src属性が変更されている場合は、<model-viewer>ごとに複数回発生する可能性があります。
load
モデルが読み込まれたとき、最初のレンダリングフレームの後に発生します。src属性が変更されている場合は、<model-viewer>ごとに複数回発生する可能性があります。
poster-dismissed
ポスターが完全に消えたときに発生します。レンダラーがシェーダーをコンパイルすることで、「load」イベントからの遅延が発生する可能性があります。
model-visibility
このイベントは、モデルの可視性が変更されたときに発生します。モデルがロードされ、要素がビューポート内にある場合（IntersectionObserver が存在すると仮定）、このイベントが発生し、event.detail.visible は「true」になります。
progress
このイベントは、モデル、環境、スカイボックス、バリアント、または usdz 変換のロード中（ダウンロードと処理の両方）に発生します。これらの同時実行タスクの進行状況は、0 から 1 の間の値（event.detail.totalProgress）で示されます。また、イベントが発生した理由（「model-load」、「environment-update」、「variant-update」、「usdz-conversion」）（event.detail.reason）も示されます。
render-scale
このイベントは、要素がDOMにアタッチされたとき、およびレンダリングされたDPR（デバイスピクセル比）が変化するたびに発生します。これは通常、レンダラーがフレームレートを維持するために解像度をスケーリングすることによって発生します。event.detailには、reportedDpr（window.devicePixelRatio）、renderedDpr（<= reportingDpr）、minimumDpr（minimumRenderScaleに基づく）、reason（「GPUスロットリング」または「meta viewportタグがありません」）、およびpixelWidth/pixelHeight（要素のレンダリング解像度）が含まれます。レンダラーは共有されているため、サイズ以外の要素はすべてページ上のすべての要素で同一です。
パーツ（Parts）
default-progress-bar
デフォルトのプログレスバーのスタイルを、スロットに完全に置き換えることなく変更するには、CSSのスコープをmodel-viewer::part(default-progress-bar)に設定します。最も一般的な変更は、背景色、高さ、幅、およびマージンの変更です（プログレスバーの更新にはtransformプロパティを使用するため、transformプロパティは使用しないでください）。
スロット（Slots）
poster
<model-viewer> の下に slot="poster" を指定した子要素を配置すると、この要素はデフォルトの白いポスターを置き換えます。このポスターは、モデルが読み込まれて表示されるまで表示されます。
progress-bar
<model-viewer> の下に slot="progress-bar" を指定した子要素を配置すると、この要素はデフォルトのプログレスバー（要素上部の細いバー）を置き換えます。プログレスバーのスタイルを更新するには、progress イベントを使用します。
canvas
<model-viewer> の下に slot="canvas" を指定した子要素を配置すると、この要素はデフォルトのレンダリングキャンバスを置き換えます。このスロットは、registerRenderer で提供される外部レンダラーでのみ使用できます。WebGL キャンバス、2D キャンバス、ストリーミングビデオなど、レンダラーが描画するあらゆる種類の要素を指定できます。
拡張現実（Augmented Reality）
属性（Attributes）
ar
対応デバイスでARエクスペリエンスを起動する機能を有効にします。
ar-modes
有効にするARエクスペリエンスの種類の優先順位リスト。指定できる値は、ブラウザでARエクスペリエンスを起動する「webxr」、Scene Viewerアプリを起動する「scene-viewer」、iOS Quick Lookアプリを起動する「quick-look」です。任意の数のモードを空白で区切って指定できます。ios-src（デフォルト）を指定せずにquick-lookを指定すると、別途ios-srcファイルをダウンロードするのではなく、USDZファイルが即座に生成されます。
デフォルト値：webxr scene-viewer quick-look
可能なARモードの優先順位リスト：webxr, scene-viewer, quick-look
ar-scale
ARモードでのスケーリング動作を制御します。「fixed」に設定するとモデルのスケーリングが無効になり、常に100%のスケールで表示されます。デフォルトは「auto」で、ピンチ操作でモデルのサイズを変更できます。
デフォルト値：auto
オプション値：auto, fixed
ar-placement
ARでオブジェクトを床（水平面）に配置するか、壁（垂直面）に配置するかを選択します。オブジェクトのバウンディングボックスの背面（負のZ軸）は壁に配置され、影もこの面に投影されます。ARモードによって配置UXの処理方法が異なることに注意してください。
デフォルト値：floor
オプション値：floor, wall
ios-src
iOS 12以降の対応デバイスでSafariのAR Quick Look経由で使用されるUSDZモデルのURL。この属性を指定するとクイックルックARモードが自動的に有効になりますが、これは必須ではありません。クイックルックARモードを指定し、ios-srcを指定しない場合（デフォルト）、ARボタンが押された際にUSDZが即座に生成されます。これにより、シーングラフ API 経由の変更が Quick Look に反映されるようになりました。ただし、USDZ 生成は完璧ではありません。例えば、アニメーションはまだサポートされていないため、ios-src を指定すると、より良い結果が得られる場合があります。
ar-usdz-max-texture-size
Quick Look で自動生成される USDZ モデルのテクスチャの最大解像度を設定します。
デフォルト値：auto (最大テクスチャ解像度に制限なし)
オプション値：16 以上の数値
xr-environment
WebXR モードで AR ライティング推定を有効にします。パフォーマンスが低下し、AR セッション中に環境画像で選択されたライティングが置き換えられます。既知の問題：暗すぎる場合、突然の更新、光沢のあるマテリアルがマットに見える場合があります。
CSS
ar-status
この読み取り専用属性を使用すると、WebXR AR プレゼンテーションの状態に基づいて DOM コンテンツのスタイルを設定できます。たとえば、CSS ルールのスコープを model-viewer[ar-status="session-started"] に設定することで、オブジェクトがユーザーのスペースに配置されるまでスマートフォンを動かすように求めるプロンプトを表示できます。この属性を設定しても効果はありません。
デフォルト値：N/A
オプション値：not-presenting, session-started, object-placed, failed
ar-tracking
この読み取り専用属性を使用すると、WebXR AR トラッキングの状態に基づいて DOM コンテンツのスタイルを設定できます。たとえば、CSS ルールのスコープを model-viewer[ar-tracking="not-tracking"] に設定することで、失敗メッセージを表示できます。この属性を設定しても効果はありません。AR トラッキングの失敗の多くは、カメラが覆われているか、認識できるテクスチャがほとんどないことが原因です。
デフォルト値：N/A
オプション値：tracking, not-tracking
プロパティ（Properties）
canActivateAR
このプロパティは、現在のプラットフォームが AR をサポートしている場合は true を返し、そうでない場合は false を返します。
メソッド（Methods）
activateAR()
AR をアクティブ化します。このメソッドは、ユーザーインタラクションハンドラーから同期的に呼び出す必要がある場合が多いため、そうでない場合は無視される可能性があります。
イベント（Events）
ar-status
上記の ar-status 属性が変更されたときに発生します。event.detail.status プロパティは、ar-status 属性と同じ値（「not-presenting」、「session-started」、「object-placed」、「failed」のいずれか）に設定されます。このイベントは、WebXR AR セッションでのみ有効です。ただし、「failed」イベントは例外で、AR が開始されたものの、指定されたすべてのモードで開始できなかった場合に発生します。
ar-tracking
上記の ar-tracking 属性が変更されたときに発生します。 event.detail.status プロパティは、ar-tracking 属性と同じ値（「tracking」または「not-tracking」）に設定されます。このイベントは WebXR AR セッションでのみ有効です。
quick-look-button-tapped
ユーザーが iOS でクイックルック AR セッションを開始した場合、アクションボタンがタップされるとこのイベントが発生します。アクションボタンは、ios-src の URL パラメータを使用して定義できます。Apple のドキュメントを参照してください。
パーツ（Parts）
default-ar-button
デフォルトの「AR 開始」ボタンのスタイルを、スロットに完全に置き換えることなく変更するには、CSS のスコープを model-viewer::part(default-ar-button) に設定します。最も一般的な変更方法は、transform と margins を使用して位置やサイズを変更することです。
default-exit-webxr-ar-button
WebXR モードのデフォルトの「AR 終了」ボタンのスタイルを変更するには、CSS のスコープを model-viewer::part(default-exit-webxr-ar-button) に設定します。ボタン全体をスロットに置き換える必要はありません。最も一般的な変更は、おそらく transform と margin を使用して位置やサイズを変更することでしょう。
スロット（Slots）
ar-button
<model-viewer> の下に slot="ar-button" を指定した子要素を配置すると、この要素はデフォルトの「AR 開始」ボタン（右下にある <model-viewer> アイコン）を置き換えます。このボタンは、AR が利用可能な場合に表示されます（ユーザーが実際に試すまでは誤検知が発生する場合があります）。
exit-webxr-ar-button
<model-viewer> の下に slot="exit-webxr-ar-button" を指定した子要素を配置すると、この要素は WebXR モードのみのデフォルトの「AR 終了」ボタン（左上にある「X」アイコン）を置き換えます。
ステージングとカメラ（Staging & Cameras）
属性（Attributes）
camera-controls
マウス/タッチによる操作を有効にします。すべてのモデルの動きが JavaScript 関数によって制御されている場合を除き、この属性はほぼ常に指定する必要があります。
disable-pan
2 本指タッチ、または右クリックもしくは修飾キーによるドラッグでデフォルトで有効になっているパン操作を無効にします。
disable-tap
タップして中央に戻す動作（タップした点を中央に戻す動作と、タップした点の外側をタップしたときにビューをリセットする動作の両方）を無効にします。この属性は 'disable-pan' と組み合わせても効果がありません。タップして中央に戻す動作はパン操作の一部だからです。パン操作と回転操作を行った後、ユーザーが元のビューに正確に戻ることは事実上不可能であるため、 'disable-tap' を使用する場合は、カスタムの中央に戻す動作を作成することをお勧めします。
touch-action
CSS の touch-action プロパティ（iOS のバグにより動作しません）と同様に、デフォルトの 'pan-y' では、タッチユーザーは <model-viewer> 要素を垂直方向にスクロールできますが、ジェスチャーが水平方向に開始した場合は操作できます。従来の動作は 'none' で実現でき、スクロールはすべて禁止されます。一方、'pan-x' は 'pan-y' の逆の動作です。通常の CSS のデフォルトの 'auto' は、camera-controls 属性を含めないことで実現できるため、ここでは使用できません。
デフォルト値：pan-y
オプション値：pan-y, pan-x, none
disable-zoom
camera-controls が有効な場合、ユーザーによるズームを無効にします（それ以外の場合は効果がありません）。副次的な効果として、マウスホイールイベントとピンチジェスチャーを無効にし、それぞれページのスクロールとズームを行います。
orbit-sensitivity
theta および phi 軌道操作の速度を調整します。負の値を設定すると反転します。これは、半径をゼロにして洞窟のようなモデルの内部を見回すときに便利です。
デフォルト値：1
オプション値：（任意の数値）
zoom-sensitivity
ズーム操作の速度を調整します。
デフォルト値：1
オプション値：（任意の数値）
pan-sensitivity
パン操作の速度を調整します。
デフォルト値：1
オプション値：（任意の数値）
auto-rotate
モデルの自動回転を有効にします。
auto-rotate-delay
自動回転を開始するまでの遅延時間を設定します。値の形式はミリ秒単位の数値です。
デフォルト値：3000
オプション値：数値 >= 0
rotation-per-second
自動回転が有効になっている場合の速度を設定します。度またはラジアン単位（例："30deg" または "0.5rad"）、およびデフォルト値（π/32ラジアン）に対するパーセント（例："-100%"）で値を指定できます。
デフォルト値：pi/32ラジアン
オプション値：角度及び単位
interaction-prompt
視覚的および聴覚的なインタラクションプロンプトを無効にできます。「auto」に設定すると、モデルが表示されてから、interaction-prompt-threshold（下記参照）の時間が経過するとすぐにインタラクションプロンプトが表示されます。インタラクションプロンプトは、カメラコントロールが有効になっている場合にのみ表示されます。
デフォルト値：auto
オプション値：auto, none
interaction-prompt-style
インタラクションプロンプトを表示した際の表示スタイルを設定します。「wiggle」に設定すると、プロンプトが水平方向にアニメーション表示され、モデルがプロンプトとインタラクションしているかのように回転します。 「basic」に設定すると、プロンプトはアニメーション表示されず、ユーザー操作によって閉じられるまで表示されます。
デフォルト値：wiggle
オプション値：wiggle, basic
interaction-prompt-threshold
camera-controls が有効な場合、<model-viewer> は、ユーザーがカメラにフォーカスを当てたものの、しばらく操作が行われないと、視覚的に（スクリーンリーダーの場合は音声で）操作を促すプロンプトを表示します。この属性を使用すると、<model-viewer> が操作を促すまでの待機時間（ミリ秒単位）を設定できます。デフォルトは 3000 です。
デフォルト値：3000
オプション値：数値 >= 0
camera-orbit
カメラの開始位置および/または後続の軌道位置を設定します。方位角、シータ角、極角、ファイ角（ファイ角は上面から下方向に測定されます）、そしてモデルの中心からの半径を制御できます。「$theta $phi $radius」形式の値（例：「10deg 75deg 1.5m」）を受け付けます。角度の単位はラジアン（「rad」）、カメラ距離の単位はセンチメートル（「cm」）またはミリメートル（「mm」）もサポートしています。カメラ距離はパーセンテージ（「%」）で設定することもできます。100%を指定すると、シータとファイ角のあらゆる値に基づいて、任意のウィンドウ内でモデルがぴったりとフレーミングされます。この値が初期設定値から変更されるたびに、カメラは現在の位置から新しい値まで補間します。「auto」に設定された値はデフォルトに戻ります。camera-orbit、camera-target、field-of-view の各プロパティ値の一部は、CSSのような関数で設定できます。これらの値には、CSS calc() 関数と、env() 関数の特殊な形式がサポートされています。式の任意の場所で env(window-scroll-y) を使用することで、現在のフレームの最上位スクロール位置に対応する 0～1 の数値を取得できます。例えば、「calc(30deg - env(window-scroll-y) * 60deg) 75deg 1.5m」のような値を指定すると、ユーザーがページをスクロールダウンすると、カメラがモデルの周囲を水平に周回します。
デフォルト値：0deg 75deg 105%
オプション値：$theta $phi $radius
camera-target
カメラが周回する開始点および／または後続点を設定します。「$X $Y $Z」形式の値（例：「0m 1.5m -0.5m」）を指定できます。センチメートル（「cm」）またはミリメートル（「mm」）の単位もサポートしています。特別な値「auto」を使用すると、その方向におけるモデルの境界ボックスの中心がターゲットに設定されます。この値が初期設定値から変更されるたびに、カメラは現在の位置から新しい値まで補間します。
デフォルト値：auto auto auto
オプション値：$X $Y $Z
field-of-view
カメラの垂直視野角を設定します。度とラジアンの両方の値（例：「30deg」または「0.5rad」）を指定できます。設定された最小視野角と最大視野角の間の任意の値を指定できます。この値が初期設定値から変更されるたびに、カメラは現在の位置から新しい値まで補間します。デフォルトは「auto」で、モデルの寸法とキャンバスのアスペクト比に応じて、垂直または水平の視野角が45度に設定されます。
デフォルト値：auto
オプション値：0～180度
max-camera-orbit
カメラの軌道角の最大値を設定します。camera-orbitと同じ形式で値を取りますが、env()はサポートしていません。「Infinity」は有効なキーワードではありませんが、「auto」を渡すことでデフォルト値を取得できます。「auto」の半径値は、camera-orbitの半径「auto」の値と同じです。
デフォルト値：Infinity 180deg auto
オプション値：$theta $phi $radius
min-camera-orbit
カメラの軌道角の最小値を設定します。「Infinity」は有効なキーワードではありませんが、「auto」を渡すことでデフォルト値を取得できます。「auto」の半径値は、カメラがモデルに入らないようにするための控えめな値であるため、他の値を設定する場合は注意してください。
デフォルト値：-Infinity 0deg auto
オプション値：$theta $phi $radius
max-field-of-view
カメラの最大視野角（最大ズームアウトに対応）を設定します。field-of-view と同じ形式で値を取りますが、env() はサポートしていません。デフォルトの "auto" はデフォルトの field-of-view と同じです。
デフォルト値：auto
オプション値：0～180度
min-field-of-view
カメラの最小視野角（最大ズームインに対応）を設定します。field-of-view と同じ形式で値を取りますが、env() はサポートしていません。カメラがモデルに干渉することなくズームインするには、この値を小さく設定します。
デフォルト値：25deg
オプション値：0～180度
interpolation-decay
ユーザー操作または属性の変更によってカメラまたはモデルが移動した場合の補間率を制御します。減衰は漸近的で、値はミリ秒単位で、動きの大部分はこの値の時間内に発生します。この値を2倍にすると、速度は半分になります。
デフォルト値：50
オプション値：0より大きい値
プロパティ（Properties）
turntableRotation
モデルのターンテーブルの向き（自動回転設定によって回転）を、上から見下ろした際に反時計回りのラジアン単位で返します。
inputSensitivity
マウス、タッチ、キーボードなど、すべてのユーザー入力に対する乗数です。選択的に微調整したり、カスタムインタラクションプロンプトで指の動きに比べてモデルの動きを少なくしたりできます。
メソッド（Methods）
resetTurntableRotation(theta)
自動回転が有効な場合、モデルを回転させるターンテーブルをリセットします。このメソッドが呼び出されると、ターンテーブルの回転角度の新しい値は theta ラジアンになりますが、モデルは次のレンダリングフレームまで更新されない場合があります。引数が指定されていない場合、theta はデフォルトで 0 になります。
resetInteractionPrompt()
通常、インタラクションプロンプトは一度だけ表示され、ユーザーが 3D モデルを初めて操作した後は表示されなくなります。このメソッドを呼び出すことで、インタラクションプロンプトが既に表示されている後にリセットすることができます。これにより、インタラクションプロンプトの表示条件が満たされたときに、インタラクションプロンプトが再び表示されます。
getCameraOrbit()
カメラのリアルタイムの軌道位置を返します。返されるオブジェクトには、theta、phi、radius の各プロパティと、カメラの軌道属性を設定するのに適した toString() メソッドがあります。方位角（シータ）と極角（ファイ）はラジアンで表され、距離（半径）はメートルで表されます。この値は、ユーザー操作やカメラ補間の影響により、camera-orbit 属性で設定された値と異なる場合があります。
getCameraTarget()
カメラのリアルタイムの目標位置をメートル単位で返します。返されるオブジェクトは、x、y、z の各プロパティと、camera-target 属性に代入するのに適した toString() メソッドを持ちます。この値は、ユーザー操作やカメラ補間の影響により、camera-target 属性で設定された値と異なる場合があります。
getFieldOfView()
カメラのリアルタイムの垂直視野角を度単位で返します。この値は、ユーザー操作やカメラ補間の影響により、field-of-view 属性で設定された値と異なる場合があります。
jumpCameraToGoal()
時間経過に伴う動きの補間ではなく、次回の更新時にカメラを最後に設定された目標状態に即座に変更します。
updateFraming()
モデルが変更された場合（例えば、方向やスケール属性など）に、カメラのデフォルトを再計算します。
getMinimumFieldOfView()
カメラの最小垂直視野角（度）を返します。
getMaximumFieldOfView()
カメラの最大垂直視野角（度）を返します。
getIdealAspect()
このモデルが現在フレーム化されている際の、ポスター画像の理想的なアスペクト比を返します。
zoom(keyPresses)
キーボードまたはマウスホイール入力を模倣し、デフォルトのズーム動作（半径と視野角の変化の組み合わせ）を適用します。keyPresses が 1.0 の場合、1 回のキーストロークと同じだけズームインし、負の値の場合はズームアウトします。
interact(duration, finger0, finger1)
カスタムインタラクションプロンプトの作成に最適な、合成タッチインタラクションを作成します。duration（ミリ秒）と finger0 は必須です。finger1 はオプションで、指定された場合は回転ではなくズーム/パンインタラクションを作成します。その他のカメラ変更は自動的にこのモーションをキャンセルし、現在の合成インタラクションの再生中は interact() を呼び出すことはできません。各指入力は x と y メンバーを持つオブジェクトで、各メンバーには initialValue と keyframes メンバーがあります。keyframes は、frames メンバーと value メンバーを持つオブジェクトの配列です。値は 0 から 1 の間で、要素の幅と高さにわたります。frames は相対的な時間単位で、その合計は継続時間に対して正規化されます。各フレームは値の間でイーズインとイーズアウトします。タッチポイントは、finger0/finger1 スロットを使用して視覚化します。
イベント（Events）
camera-change
カメラの位置や視野が変化したときに発生します。ユーザーインタラクションによって変化した場合、event.detail.source プロパティは "user-interaction" に設定されます。interaction-prompt または interact() メソッドの場合は "automatic" に設定されます。その他の API によるカメラ変更の場合は "none" に設定されます。
interact-stopped
interact() の動作が停止したときに発生します。event.detail.source が "automatic" に設定されていることで動作が完了したことがわかります。source が "user-interaction" または "none"（JS によるカメラ変更の場合）の場合は、動作が途中でキャンセルされたことになります。
スロット（Slots）
interaction-prompt
<model-viewer> の下に slot="interaction-prompt" を指定した子要素を配置すると、この要素がデフォルトの手のアイコンに置き換えられます。このアイコンは、ユーザーがインタラクションするまでモデルに合わせて前後に揺れます。
finger0/finger1
interact() と組み合わせて使用し、各タッチポイントを表す HTML 要素を指定します。 <model-viewer> の下に slot="finger0" の子要素を配置すると、この要素が表示され、interact() メソッドの finger0 入力で指定されたパスに沿って移動します。finger1 についても同様です。デフォルトでは空です。
pan-target
<model-viewer> の下に slot="pan-target" の子要素を配置すると、この要素は、ユーザーがパン操作を行ったときにカメラのターゲットを示すためにデフォルトで表示される小さな円を置き換えます。
アノテーション（Annotations）
CSS
--min-hotspot-opacity
非表示のホットスポットの不透明度を設定します。
デフォルト値：0.25
オプション値：0～1 の任意の値
--max-hotspot-opacity
表示されているホットスポットの不透明度を設定します。
デフォルト値：1
オプション値：0～1 の任意の値
メソッド（Methods）
updateHotspot({name, position?, normal?, surface?})
slot="name" に関連付けられたホットスポットの位置、法線、および/または表面を更新します。位置、法線、および表面は、スロット定義のホットスポット属性 data-position、data-normal、および data-surface と同じ文字列形式で指定します。
queryHotspot(name)
ホットスポット名に対応するホットスポットの現在の状態に関する情報（位置、法線、canvasPosition、およびfacingCamera）をスナップショットとして返します。キャンバスの位置は、OpenGL の深度情報として z を持つ Vector3D で表されます。ホットスポットが見つからない場合、この関数は null を返します。
positionAndNormalFromPoint(clientX, clientY)
画面を基準とした入力ピクセル座標に対応するメッシュ上の点のワールド座標、法線、テクスチャ座標を返します。位置と法線は Vector3D として返され、Vector3D にはホットスポットの data-position 属性と data-normal 属性に格納するのに適した形式を出力する toString() メソッドがあります。テクスチャ座標は Vector2D として返され、Vector2D にも独自の toString() メソッドがあります。オブジェクトにヒットしていない場合、この関数は null を返します。
surfaceFromPoint(clientX, clientY)
このメソッドは、モデルビューア要素を基準とした入力ピクセル座標に対応するメッシュ上の点の動的なホットスポット ID 文字列を返します。この ID 文字列をホットスポットの data-surface 属性で使用することで、モデルがアニメーションしているときでも、ホットスポットがサーフェス上のこの点に追従するようにすることができます。メッシュにヒットしなかった場合、結果は null になります。
スロット（Slots）
hotspot-*
<model-viewer> 配下の子要素で、スロット名が「hotspot」で始まる要素は、data-position 属性と data-normal 属性を使用して、camera-target と同じ形式でモデル座標系で 3D モデルに位置合わせされます。また、data-surface 属性を使用して、glTF メッシュ、プリミティブ、3 つの頂点インデックス、および 3 つの重心座標を指定し、メッシュに沿ってアニメーションするサーフェスポイントを指定することもできます。この文字列を対話的に生成するには、surfaceFromPoint メソッドを使用することをお勧めします。詳細については、アノテーションの例を参照してください。
ライティングとスカイボックス（Lighting & Skybox）
属性（Attributes）
skybox-image
シーンの背景画像を設定します。スカイボックスに使用される正距円筒投影画像へのURLを指定します。この画像はモデルの環境マップとしても適用されます。png、hdr、jpg（UltraHDRを含む）画像をサポートしています。ライティングを適切に表現するにはHDR画像を強く推奨します。特に、HDRデータの高圧縮率を誇るUltraHDR JPEG形式をお勧めします。こちらの無料オンラインコンバーターを使って、ご自身で試してみてください。
skybox-height
スカイボックスを地面に投影します。heightはカメラの地面からの距離を示し、地面レベルで画像を適切なサイズにスケーリングします。単位はメートル（m）、センチメートル（cm）、ミリメートル（mm）です。デフォルト値の0mは地面投影を無効にします。
デフォルト値：0m
オプション値：任意の正の値
environment-image
モデルの環境反射を制御します。通常、スカイボックス画像が設定されている場合は、その画像が環境画像にも使用されます。背景に影響を与えずに反射のみを設定するには、環境画像を使用してください。どちらも指定されていない場合は、デフォルトのニュートラルライティングが適用されます。スカイボックスを指定せずに「legacy」を指定した場合は、代わりに以前のデフォルトの環境が適用されます。
デフォルト値：null
オプション値：'neutral', 'legacy', hdr または .jpg ファイルへの URL
exposure
主に HDR 環境で使用するために、モデルとスカイボックスの両方の露出を制御します。
デフォルト値：1
オプション値：任意の正の値
tone-mapping
HDR レンダリングを画面上の SDR 画像に圧縮する関数を選択します。ACES は映画業界の標準規格として広く使用されていますが、色精度に深刻な問題があります。AgX は、映画やゲームで広く採用されている、新しく改良されたトーンマッパーです。 Khronos PBR Neutral（「neutral」）は、eコマースにおける正確な色再現のために特別に設計された標準関数です。現在のデフォルトはneutralですが、v4.0より前のデフォルトはACESでした。廃止されたcommerceという名称はneutralの別名です。その他のオプションには、トーンマッピングを完全に無効にするNoToneMapping、輝度値を単純に線形にスケーリングするLinearToneMapping、自然なHDR画像のためのバランスの取れたアプローチであるReinhardToneMapping、従来のフィルムの外観をエミュレートするCineonToneMappingなどがあります。各トーンマッパーは、望ましい視覚効果とアプリケーションの要件に応じて、それぞれ独自の用途があります。
デフォルト値：neutral
オプション値：neutral, aces, agx, reinhard, cineon, linear, none
shadow-intensity
影の不透明度を制御します。影を完全にオフにするには0に設定します。
デフォルト値：0
オプション値：0～1 の任意の値
shadow-softness
影のぼかし具合を制御します。0 に設定するとハードシャドウになります。パフォーマンスが低下するため、ソフトネスを毎フレーム変更しないでください。ソフトシャドウはレンダリング速度が速くなります。
デフォルト値：1
オプション値：0～1 の任意の値
メソッド（Methods）
hasBakedShadow()
ベイクされたシャドウプレーンがこのモデルの一部であるように見える場合、true を返します。これらのプレーンはフレーミング計算から除外され、複数のシャドウが相互作用するのを防ぐため、shadow-intensity が 0 の場合にのみレンダリングされます。
イベント（Events）
environment-change
環境が変化したときに発生します。環境が skybox-image または environment-image から派生している場合、このイベントが発生するまでに画像は読み込まれています。
アニメーション（Animation）
属性（Attributes）
animation-name
再生するアニメーションを名前で選択します。このアニメーションは、.play() メソッドが呼び出されたとき、または <model-viewer> が自動再生に設定されている場合、再生されます。animation-name が指定されていない場合、<model-viewer> は常にモデル内で最初に見つかったアニメーションを選択します。
animation-crossfade-duration
再生するアニメーションを名前で選択します。このアニメーションは、.play() メソッドが呼び出されたとき、または <model-viewer> が自動再生に設定されている場合、再生されます。animation-name が指定されていない場合、<model-viewer> は常にモデル内で最初に見つかったアニメーションを選択します。
デフォルト値：300
オプション値：任意の数値 >= 0
autoplay
この属性が true で、モデルにアニメーションが含まれている場合、この属性が設定されたとき（またはプロパティが true に設定されている場合）、アニメーションが自動的に再生されます。animation-name が指定されていない場合は、最初のアニメーションが再生されます。
デフォルト値：false
オプション値：true, false
プロパティ（Properties）
availableAnimations
このプロパティは、読み込まれたモデル内のアニメーションに対応する文字列の配列を返します。これらのアニメーションは、animation-name で選択できます。
currentTime
このプロパティは、現在選択されているアニメーションの現在のトラック時間を秒単位で返します。利用可能なアニメーションがない場合、値は常に 0 になります。このプロパティを設定すると、現在再生中のアニメーションのタイムラインに沿ってシークすることができます。たとえば、0 に設定すると、アニメーションは先頭にリセットされます。
timeScale
このプロパティは、アニメーション時間のスケーリング係数を返します。これを使用して、アニメーションを遅くしたり、速くしたり、逆方向に再生したりできます。たとえば、0.5 に設定すると、アニメーションは半分の速度で再生されます。デフォルト値は 1 です。
duration
このプロパティは読み取り専用です。現在選択されているアニメーションの継続時間を秒単位で返します。利用可能なアニメーションがない場合、値は常に 0 になります。
paused
このプロパティは読み取り専用です。アニメーションが一時停止中の場合は true を返します。アニメーションが再生中の場合は false を返します。アニメーションは常に一時停止状態で開始され、autoplay 属性が設定されるか、.play() メソッドが呼び出されるまで一時停止状態が維持されます。
appendedAnimations
このプロパティは読み取り専用です。現在の状態に追加されたアニメーションの名前の配列を返し、animation-name を使用してメインアニメーションが変更されるとクリアされます。
メソッド（Methods）
play(options: {repetitions, pingpong})
アニメーションを再生します。アニメーションの繰り返し回数を指定するには、繰り返し回数を 0 より大きい値（デフォルトは無限大）に設定します。また、pingpong を true に設定すると、順方向と逆方向を交互に再生します（デフォルトは false）。アニメーションを自動的に再生したい場合は、autoplay 属性を使用します。アニメーションがない場合、何も起こりません。このメソッドを呼び出す前に、モデルが読み込まれていることを確認してください。
pause()
アニメーションを一時停止します。現在のアニメーションを最初にリセットしたい場合は、currentTime プロパティも 0 に設定する必要があります。
appendAnimation(animationName, options: {repetitions, pingpong, weight, timeScale, time, fade, warp, relativeWarp})
現在のアニメーションと同時にアニメーションを実行し、ブレンドします。追加したアニメーションを取得するには、appendAnimations プロパティを使用します。アニメーションの繰り返し回数を指定するには、繰り返し回数を 0 より大きい値（デフォルトは無限大）に設定します。また、pingpong を true に設定すると、順方向と逆方向が交互に再生されます（デフォルトは false）。weight は、このアニメーションの影響度（範囲 [0, 1]）です。0（影響なし）から 1（最大影響）までの値は、複数のアクションをブレンドするために使用できます（デフォルトは 1）。 timeScale オプションを使用すると、アニメーションの速度を落としたり、上げたり、逆方向に再生したりできます。たとえば、0.5 に設定すると、アニメーションは半分の速度で再生されます (デフォルトは 1)。time オプションは、指定された値からアニメーションを開始します。このオプションの値は、0 より大きい浮動小数点数 (秒単位) にすることができ、0 とアニメーションの継続時間の間でクランプされます。設定されていない場合、アニメーションは最後に停止した時間から開始されます (つまり、前の状態が継続します)。fade オプションは、このアニメーションの重みを 0 から 1 まで徐々に増加させます。このオプションの値は、0 より大きいブール値または浮動小数点数 (秒単位) にすることができ、値が true の場合、デフォルトの継続時間 (1.25 秒) が適用されます (デフォルトは false)。 warp オプションは、指定された時間間隔内で、timeScale を 0 から現在の timeScale 値まで徐々に変更することで再生速度を変更します。このオプションの値は、0 より大きいブール値または浮動小数点数（秒単位）にすることができます。値が true の場合、デフォルトの再生時間（1.25 秒）が適用されます（デフォルトは false）。このオプションは、現在の timeScale から新しい値へのワープを変更します。このオプションの値はブール値です。false に設定すると、timeScale は 0 から開始し、入力された値まで再生されます（デフォルトは true）。
detachAnimation(animationName, options: {fade})
追加されたアニメーションを切り離します。フェードオプションは、アニメーションのウェイトを徐々に0に変化させます。このオプションの値は、0より大きいブール値または浮動小数点数（秒単位）で指定できます。値がtrueの場合、デフォルトの持続時間（1.25秒）が適用されます（デフォルトはtrueです）。
イベント（Events）
play
アニメーションの再生が開始されたときにディスパッチされます。
pause
アニメーションが一時停止されたときにディスパッチされます。モデルは常に一時停止状態から開始されるため、アニメーションの再生が開始された後に .pause() メソッドが呼び出されるまで、このイベントはディスパッチされないことに注意してください。
loop
現在のアニメーションがループしたときにディスパッチされます。ループ回数は e.detail.count で取得できます。
finished
現在のアニメーションの再生が終了したときにディスパッチされます。
append-animation
現在のアニメーションにアニメーションが追加されたときにディスパッチされます。
detach-animation
追加されたアニメーションが切り離されたときにディスパッチされます。
マテリアルとシーン（Materials & Scene）
属性（Attributes）
variant-name
モデルバリアントを名前で選択します。
orientation
ロール、ピッチ、ヨーのオイラー角で指定された方向にモデルを回転させます。最初にY軸を中心にヨー角が適用され、次に新しいローカルX軸を中心にピッチ角が適用され（正は正面下）、最後に新しいローカルZ軸を中心にロール角が適用されます。モデルの読み込み前に指定した場合、自動カメラフレーミングでこの変更が考慮されます。そうでない場合は、updateFraming() メソッドを手動で呼び出す必要があります。
デフォルト値：0deg 0deg 0deg
オプション値：$roll $pitch $yaw
scale
指定されたX、Y、Z方向のスケールに従ってモデルを拡大縮小します。スケールは方向の前に適用されます。モデルの読み込み前に指定した場合、自動カメラフレーミングでこの変更が考慮されます。そうでない場合は、updateFraming() メソッドを手動で呼び出す必要があります。
デフォルト値：1 1 1
オプション値：$x $y $z
プロパティ（Properties）
availableVariants
このプロパティは、ロードされたモデル内のvariant-nameで選択可能なバリアントに対応する文字列の配列を返します。
model
このオブジェクトには、マテリアルAPIのすべてのメソッドが含まれています。使用方法については例を参照してください。
originalGltfJson
ロードされたGLTF JSONオブジェクトの読み取り専用コピーを返します。このオブジェクトを変更してもシーンには影響がなく、マテリアルAPIによる変更もここには反映されません。このオブジェクトは、マテリアルAPIによる個々の変更を元に戻すのに役立ちます。
メソッド（Methods）
exportScene(options)
モデルをglTFまたはGLB形式でエクスポートします。エクスポート形式に応じて、"application/octet-stream"または"application/json"型のBlobで解決されるPromiseを返します。パラメータの一覧については、GLTFエクスポーターのドキュメントを参照してください。ただし、すべてのアニメーションは自動的にエクスポートされ、truncateDrawRangeはデフォルトでtrueになります。
materialFromPoint(clientX, clientY)
入力ピクセル座標から画面を基準として作成されたレイとメッシュプリミティブが交差するマテリアルを返します。カメラに最も近いメッシュを持つマテリアルを返します。
createTexture(uri, type?)
Materials API の TextureInfo オブジェクトの setTexture メソッドで使用するテクスチャオブジェクトを返す非同期メソッドです。uri は必須ですが、type はデフォルトで 'image/png' に設定され、GLB を保存するためのエクスポート形式のみを指定します。MIME タイプ 'image/jpeg' と 'image/webp' もサポートされています。
createVideoTexture(uri)
Materials API の TextureInfo オブジェクトの setTexture メソッドで使用するテクスチャオブジェクトを返します。作成されたビデオ要素は、texture.source.element を通じて再生を制御するために使用できます。
createCanvasTexture()
Materials API の TextureInfo オブジェクトの setTexture メソッドで使用するテクスチャオブジェクトを返します。作成された 2D キャンバス要素は texture.source.element から取得できます。2D コンテキストを取得して必要な描画を行い、texture.source.update() を呼び出すだけです。
createLottieTexture(uri, quality?)
Materials API の TextureInfo オブジェクトの setTexture メソッドで使用するテクスチャオブジェクトを返す非同期メソッドです。lottie JSON ファイルの uri は必須で、quality はデフォルトで 1（ファイルで指定された解像度）になります。作成された Lottie アニメーションは、texture.source.animation から再生を制御するために使用できます。Lottie キャンバスモジュールは DRACO デコーダーと同様に遅延ロードされます。デフォルトの CDN が気に入らない場合は、lottieLoaderLocation を使用して独自の場所を指定できます。 Lottie を読み込むには、モデルビューアのライブラリファイルに「3」をマッピングしたインポートマップが必要です。例については、以下のリンクをご覧ください。