<aside> 📙 目次

</aside>

概要

既存のWebサイトに簡単に3Dモデル閲覧機能およびARプレビュー機能を追加できます

サンプル

<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8" />
		<script defer src="<https://unpkg.com/@cynack/figni-viewer/dist/figni-viewer.min.js>"></script>
		<title>Figni Viewer Sample</title>
		<style>
			figni-viewer:not(:defined) {
				display: none;
			}
		</style>
	</head>
	<body>
		<h1>Hello, Figni Viewer!</h1>
		<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4" />
	</body>
</html>

ヒント

figni-viewerが表示される前にHTML要素がちらつく場合があります
以下に示すスタイルをheadまたはbodyに書くことでその問題を解消することができます
```
figni-viewer:not(:defined) {
	display: none;
}
```

変更履歴

対応バージョン	変更詳細	編集日時
1.5.0	・スタイルにいくつかのカスタムプロパティを追加
・`openHelpPanel()`, `backHelpPanel()`, `closeHelpPanel()`, `openTipsPanel()`, `closeTipsPanel()`, `updateColorSettings()`の説明を追加	2022/05/30
1.4.1	・スタイルに関する記述を変更	2022/04/21
1.3.0	・`toggle-caption`についての説明を追加	2022/03/25
1.2.1	・`addHostpot()`および`editHotspot()`の説明を修正	2022/03/03
1.2.0	・`visible-state`の複数指定に関する説明を追加
・`reverse`についての説明を追加
・`playAnimation()`の引数の説明を変更	2022/02/10
1.1.0	・`anime`および`closeup`を非推奨に変更
・`resetCameraTargetAndOrbit()`についての説明を追加
・サポートに関して注意事項を追記	2022/02/02
1.0.1	・`addHostpot()`および`editHotspot()`の説明を修正	2022/01/21
1.0.0	・`loop`を削除し、`loopCount`を追加
・`playAnimation()`の説明を修正	2022/01/14
0.0.33	・`loop`についての説明を追加
・`playAnimation()`の説明を修正	2021/12/28
0.0.32	・ヒント項目を追加	2021/12/17
0.0.26	・`place`についての説明を追加
・`orbit`の説明文を修正	2021/12/07
0.0.23	・`visible`の名称を`visible-state`に変更	2021/12/01
0.0.20	・メソッド`playAnimation()`, `stopAnimation()`の説明を追加	2021/11/30
0.0.19	・スタイル`.figni-viewer-toggle-visible-hotspot-button`の説明を追加
・メソッド`toggleVisibleHotspot()`の説明を追加	2021/11/29
0.0.18	・メソッドの情報を追加	2021/11/25
0.0.16	・スタイルの情報を追加	2021/11/22
0.0.13	・`to-state`, `visible`の説明を追加	2021/11/18
~0.0.12	・実装済み事項に関する全ドキュメントを追加	2021/11/17

サポート

<aside> ⚠️ 機能に関する注意

推奨ブラウザはChrome、Safari、Edgeです。それ以外のブラウザでの動作は保証していません。
AR機能はPC, Macでは利用できません。
AR機能に関して、iPhoneおよびiPadではiOS11以降、AndroidではAndroid 7 Nougat以降のOSが対応しています。また、端末によってはOSのバージョンに寄らずAR機能が動作しない可能性があります。以下のリンクをご参照ください。
- iOS/iPad端末対応情報(iPhone DevicesおよびiPad Devicesの表にあるarkitの欄をご覧ください)
- Android端末対応情報 </aside>

属性

基本設定

item-id

string
必須
3D表示したい商品を指定します
Cynackから提供された値を使用してください

token

string
必須
3Dモデルへのアクセストークンを設定します
Cynackから提供された値を使用してください

model-tag

string
省略可
商品に紐づく3Dモデルの中から使用する3Dモデルを指定します
省略した場合デフォルトのモデルが選択されます

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4" model-tag="open" />

追加設定

target

string
カメラが注視する点の初期位置を指定します
target="X座標 Y座標 Z座標"のような形で指定し、m、cm、mmの単位を利用できます
指定がない場合3Dモデルの中心を示すauto auto autoに設定されます

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4" target="0.1m 0.5m 0m"/>

orbit

string
カメラが注視している点を基準としたカメラの初期極座標を指定します
orbit="方位角極角カメラまでの距離"のような形で指定します
方位角と極角(1)はdeg(度)、rad(ラジアン)の単位を利用でき、カメラまでの距離(2)はm*、cm、mm、%(100%でモデルがちょうど画面内に収まる)の単位を利用できます
指定がない場合"0deg 75deg 105%"に設定されます

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4" orbit="45deg 50deg 120%"/>

state

figni-viewer内で利用されるstate(状態)の初期値を指定します

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4" state="state1"/>

パーツ

hotspot

slot="hotspot-〇〇〇〇"のような形でユニークな名前をつける必要があります
この値を持つパーツは3D空間にアンカーされて描画されます

position

string
hotspotの位置を指定します
position="X座標 Y座標 Z座標"のような形で指定し、m、cm、mmの単位を利用できます。
省略した場合、position="0m 0m 0m"を指定した時と同じ位置に設定されます。

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4">
	<button slot="hotspot-sample1" position="-0.2m 1.1m 0.35m"></button>
	<button slot="hotspot-sample2" position="0.5m 101cm 3520mm"></button>
</figni-viewer>

normal

string
hotspotの法線を指定します(hotspotが有効になる方向)
normal="X座標 Y座標 Z座標"のような形で指定し、m、cm、mmの単位を利用できます
省略した場合、normal="0m 1m 0m"を指定した時と同じ方向に設定されます

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4">
	<button slot="hotspot-sample1" normal="0m 0m 1m"></button>
	<button slot="hotspot-sample2" normal="-0.8m 0m 0.5m"></button>
</figni-viewer>

clip

string
再生するアニメーション名を指定します
3Dモデルに含まれるアニメーションに指定したアニメーション名が存在しない場合、アニメーションは再生されません

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4">
	<button
		slot="hotspot-sample1"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
		clip="Push_in"
	></button>
</figni-viewer>

loopCount

アニメーションを再生する回数を指定します
この属性を指定しなかった場合、アニメーションは一度だけ再生されます
"Infinity"を指定することでループ再生できます

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4">
	<button
		slot="hotspot-sample1"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
		clip="Push_in"
		loopCount="5" 
	></button>
</figni-viewer>

reverse

アニメーションを逆再生にします
この属性を指定しなかった場合、アニメーションは通常再生されます

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4">
	<button
		slot="hotspot-sample1"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
		clip="Push_in"
		reverse
	></button>
</figni-viewer>

onstart

アニメーションの再生が始まったタイミングで呼び出されるイベントです

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4">
	<button
		slot="hotspot-sample1"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
		clip="Push_in"
		onstart="console.log('animation start!')"
	></button>
</figni-viewer>

onend

アニメーションの再生が終わったタイミングで呼び出されるイベントです
アニメーションがループ再生している場合呼び出されません

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4">
	<button
		slot="hotspot-sample1"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
		clip="Push_in"
		onend="console.log('animation end!')"
	></button>
</figni-viewer>

target

string
カメラが注視する点を指定します
target="X座標 Y座標 Z座標"のような形で指定し、m、cm、mmの単位を利用できます
省略した場合、positionと同じ値が使用されます

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4">
	<button
		slot="hotspot-sample1"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
		target="0.1m 0.5m 0.2m"
	></button>
</figni-viewer>

orbit

string
カメラが注視している点からみたカメラの極座標を指定します
orbit="方位角極角カメラまでの距離"のような形で指定します
方位角と極角(1)はdeg(度)、rad(ラジアン)の単位を利用でき、カメラまでの距離(2)はm、cm、mm、%(100%でモデルがちょうど画面内に収まる)の単位を利用できます
省略した場合、初期値("0deg 75deg 105%")が使用されます

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4">
	<button
		slot="hotspot-sample1"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
		orbit="30deg 75deg 110%"
	></button>
</figni-viewer>

visible-state

string
hotspotが表示されるstate(状態)を指定します
複数の値を設定する場合は" "で区切ってください
stateの初期値は""です

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4" state="normal">
	<button
		slot="hotspot-sample1"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
		visible-state="open normal"
	></button>
	<button
		slot="hotspot-sample2"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
		visible-state="close"
	></button>
</figni-viewer>

to-state

string
このパーツがクリックされたとき、stateを指定した値に変更します
このパーツにアニメーションの再生が適用されている場合、アニメーションが再生されて終了するまで一時的なstate(乱数)に変更され、終了すると指定したstateに移行します。ループアニメーションの場合は即座に指定したstateに移行します。

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4">
	<button
		slot="hotspot-sample1"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
		visible-state="open"
		to-state="close"
	></button>
	<button
		slot="hotspot-sample2"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
		visible-state="close"
		to-state="open"
	></button>
</figni-viewer>

panel

slot="panel-〇〇〇〇"のような形でユニークな名前をつける必要があります
この値をもつパーツはslot="hotspot-○○○○"の値をもつパーツの子供である必要があります
slot="hotspot-○○○○"の値をもつ親のいずれかがクリックされたときこのパーツの表示非表示が切り替わります(初期値は非表示です)

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4">
	<button
		slot="hotspot-sample1"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
	>
		<div slot="panel-sample1">
			<span>これはサンプルです</span>
		</div>
	</button>
</figni-viewer>

place

panelが表示される位置を指定します
水平方向の位置を指定するleft, center, rightから一つと、垂直方向の位置を特定するtop, middle, bottomから一つをスペース区切りで指定します
place="center bottom"という形で指定し、二つの値は順不同です
省略した場合、"left middle"が使用されます

<figni-viewer item-id="wQbRquQ9" token="0zVlvrjLEKS3Ggz4">
	<button
		slot="hotspot-sample1"
		position="-0.2m 1.1m 0.35m"
		normal="0m 0m 1m"
	>
		<div slot="panel-sample1" place="right top">
			<span>これはサンプルです</span>
		</div>
	</button>
</figni-viewer>