Krpano WebVR插件使用指南

• krpano WebVR / WebXR / MobileVR 支持::
  • WebVR 支持意味着在可用时使用浏览器的 WebVR API 或 WebXR API 在这里，浏览器和系统将执行头部和位置跟踪以及镜头失真。这是最好的质量和性能的情况下，但需要一个系统和浏览器与WebVR/WebXR的支持。
  • WebXR注意:  WebXR API 的使用可以通过 webxr 嵌入设置来控制。目前WebVR API更受欢迎，因为它更成熟，得到更好的支持，提供了更多的功能和稳定性。
  • MobileVR支持意味着对移动设备的“手动”VR支持。当浏览器不支持WebVR或WebXR API时，这将用作回退。这里将使用移动设备的加速度计和陀螺仪传感器进行头部跟踪，并手动完成镜头畸变。为了获得正确的vr视图，可能需要手动调整特定耳机或设备的设置。
• 体验任何全景图像或视频(正常和立体)在3D虚拟现实模式直接在浏览器内。当使用 depthmap-panos 时，还可以使用位置跟踪。

主题

• 语法
• 插件属性
• 插件状态变量
• 插件的事件
• 插件操作
• iFrame的支持

语法

动态或只读layer / hotspot 变量:

• isavailable
• isenabled
• iswebvr / iswebxr / ismobilevr / isfake
• isvrbrowser
• vrcontrollers
• havepostracking
• floorlevel
• havesettings
• devicename / devicesize
• renderwidth / renderheight

Actions / Functions:

• enterVR()
• exitVR()
• toggleVR
• lookat(hlookat)
• loadSettings()
• saveSettings()
• resetSettings()

krpano API 集成

• 加载后，插件对象也将作为全局webvr变量可用。

krpano 事件

除了插件事件之外，插件还调度这些krpano事件:

插件属性

Attribute name	Type	Default value
postracking	String	"auto"
启用VR位置跟踪。 需要带有位置跟踪支持的VR头显，否则没有效果。 当前位置将被添加到视图中 view.tx/ty/tz 设置. 当位置跟踪可用时， onhavepostracking 事件将被调用。 可用的设置: auto - 使用 depthmap-panos 时自动启用位置跟踪。 true - 始终启用位置跟踪(当VR硬件可用时)。 但请注意，正常的全景图像会失真，当不从他们的正常图像中心观看! false - 始终禁用位置跟踪。
Attribute name	Type	Default value
absolute	Boolean	false
使用绝对/真实世界导向的方向跟踪。 MobileVR目前这只能在移动设备上实现! 使用WebVR或WebXR api的真实VR头显(例如Oculus Quest头显)目前不提供任何api或现实世界方向跟踪的可能性，甚至无法以某种方式获得现实世界的方向。 默认情况下，pano-image-center (hlookat=0.0)将指向北方，但也可以设置自定义的北方位置/偏移量。 当禁用(默认)时，陀螺仪跟踪将相对于当前观看方向。 这个设备必须有一个磁传感器才能可靠地工作。iOS设备通常运行得很好，但在Android设备上，情况有所不同，这取决于设备。 注意-当使用绝对跟踪，所有panos应该设置/对齐到相同的北方。否则，北方的设置将需要为每个全景动态调整。
Attribute name	Type	Default value
north	Number	0.0
定义北在全景图像中的位置(从-180到+180)。 默认值是0.0，它指的是全景图像的中心。 注意-这只适用于使用 absolute 方向跟踪。 坐标系:
Attribute name	Type	Default value
hlookatoffset	Number	0.0
水平位置 (view.hlookat) 的自定义偏移量，以度为单位。 可用于独立旋转视图，也可用于用户查看。
Attribute name	Type	Default value
oversampling	Number	1.0
渲染分辨率的过采样比例因子。 更高的值将提高图像质量，但需要更多的GPU处理能力。 较低的值将降低图像质量，并需要更少的GPU处理能力。 注意:WebXR API不允许高于1.0的值，并且设置不能在以后更改，因此只有初始值重要。
Attribute name	Type	Default value
auto_oversampling	Boolean	true
当启用时，根据实际的VR耳机应用一个自动额外的过采样因子。 这样做是因为设备提供的默认分辨率低于设备出于性能原因所能提供的分辨率。 增加的过采样因子以牺牲一点性能为代价提高了图像质量。 当更高和更稳定的帧率比图像质量更重要时，请考虑禁用该设置或使用较低的过采样设置。 支持耳机: 对于Oculus Go和Oculus Quest，将自动添加~1.4的因子。 将遵循自定义过采样设置，并自动避免过高的过采样因子。
Attribute name	Type	Default value
zoom	Number	1.0
将自定义缩放比例应用于VR视图。 应该非常小心地使用，只有在特殊情况下才使用!
Attribute name	Type	Default value
friction	Number	0.0
介于0.0和0.999之间的值 增加摩擦以降低陀螺的响应速度。 应该只用于高变焦值，以减少震动，但绝不用于正常观看!
Attribute name	Type	Default value
headtracking	Boolean	true
通过将头部跟踪设置为false，可以禁用头戴式移动跟踪，并通过更改视图设置自行控制观看方向。 警告-不建议禁用此设置! 在VR中改变观看方向与用户头部运动不同是一种糟糕的体验。在带有“重新投影”功能的系统(如HTC Vice和Oculus Rift)上，这可能会导致图像错误，因为这些系统不会假设视图会随着头部运动而改变。
Attribute name	Type	Default value
fullscreen_mirroring	Boolean	false
当使用WebVR时，也可以自动切换到全屏模式。
Attribute name	Type	Default value
mouse_pointerlock	Boolean	true
在VR模式下锁定鼠标控制(不可见鼠标光标)，通过鼠标移动直接控制观看方向。
Attribute name	Type	Default value
webvr_highrefreshrate	String
Oculus浏览器在Oculus Go上的渲染默认为60Hz，而Oculus Quest的渲染默认为72Hz。72Hz的渲染模式也适用于Go，这增加了舒适性，但性能和能量的权衡。 设置为true可启用72Hz模式。 设置为false明确禁用Go和Quest上的72Hz模式。 如果没有设置，将使用系统默认值。 支持WebVR API和WebXR API。
Attribute name	Type	Default value
webvr_foveationlevel	int	1
固定注视点渲染是一种提高渲染性能的方法。启用后，屏幕边缘以低于中心的分辨率呈现，从而需要计算的总像素更少。 webvr_foveationlevel设置指定固定注视点的级别。取值范围为0 ~ 3，各参数取值说明如下:0 - none、1 - low、2 - medium、3 - high。缺省值为1。 支持WebVR API和WebXR API。 More information.
Attribute name	Type	Default value
webvr_ca_correction	Boolean
设置为true将显式请求CA-Lens-Correction。 这可以纠正由镜头引起的边缘色差，但也需要额外的GPU处理能力。 如果没有设置，将使用系统默认值。 仅由WebXR API支持。 More information.
Attribute name	Type	Default value
mobilevr_support	Boolean	true
启用或禁用MobileVR支持。 当浏览器中没有WebVR API支持时，这是一个后备解决方案。 它允许在任何带有陀螺仪和加速度计传感器的移动设备上使用VR。
Attribute name	Type	Default value
mobilevr_desktop_support	Boolean	false
在桌面设备上也提供MobileVR支持。 默认情况下，支持仅限于移动和平板设备。
Attribute name	Type	Default value
mobilevr_fake_support	Boolean	false
为平板电脑和非vr桌面设备启用“假”MobileVR支持。 在这些设备上使用VR通常是不可能的，但是启用了这个设置后，krpano将提供一个假的解决方案/模拟，让用户仍然有VR模式的印象。 要检查是否启用了假模式，可以使用isfake属性。
Attribute name	Type	Default value
mobilevr_touch_support	Boolean	false
启用触摸支持旋转/调整水平偏移。 默认情况下，这个设置是禁用的，因为一些VR头显用外壳触摸屏幕，有时会触发错误的输入。
Attribute name	Type	Default value
mobilevr_profile	String
MobileVR模式下的 VR-headset配置文件参数。 使用Cardboard lens distortion model 模型。 参数: "fov|lensdistance|screendistance|traydistance|k1|k2" fov - 以度表示的视野。 lensdistance - 镜头间距离，以毫米为单位。 screendistance - 屏幕到镜头的距离以毫米为单位。 traydistance - 从耳机托盘底部到镜头中心的距离，以毫米为单位。当设置为0时，将使用设备的中心。 k1 and k2 - 透镜畸变系数。 默认值(用于Cardboard V1耳机): "80|60|42|35|0.441|0.156"
Attribute name	Type	Default value
mobilevr_screensize	String	"auto"
设置自定义对角线设备屏幕尺寸(以英寸为单位)。 了解物理屏幕尺寸对于计算正确的VR视场和镜头畸变是非常重要的。 当设置为auto(默认)时: 在这种情况下，插件试图检测设备本身以获得其屏幕尺寸。 因此，插件使用一个内部设备列表。另外，可以在xml中定义一个可定制的设备列表。 当设备未知时，可以使用外部数据库(参见mobilevr_database_url)来查找设备的大小。 当检测到大小不可能时，插件发送onunknowndevice事件。
Attribute name	Type	Default value
mobilevr_database_support	String	"xml|internal|external"
设置应该使用哪些数据库来查找设备的物理屏幕大小。 设置可以是以下值的组合: xml - 使用xml中定义的 mobilevr_device_database 命名数据库。 internal - 使用内部数据库。 external - 使用外部数据库 (mobilevr_database_url). xml数据库的语法: mobilevr_device_database : ... mobilevr_database_url元素可以在xml文件的任何地方定义。 多个声明将被自动合并。 一个device元素可以有以下设置来定义一个设备: name - 设备名称，需要是唯一的。 size - 物理屏幕尺寸对角线英寸(检测结果)。 对于iOS设备，可以定义两种大小。第一个值是全屏时的大小，第二个值是仅使用安全区域时的大小。 bevel - 屏幕周围的物理斜度，单位为毫米(默认为4毫米)。 ua - 一个字符串，应该是user-agent字符串的一部分，用于检测设备，不区分大小写(用于检测Android设备)。 screen -屏幕大小(纵向模式下)的逻辑CSS像素和可选的像素比(用于检测iOS设备)。 语法:WIDTHxHEIGHTxPIXELRATIO。
Attribute name	Type	Default value
mobilevr_database_url	String
使用 Cardboard Device Parameter Database (DPDB) 作为获取未知设备的屏幕大小的备用方法。 默认情况下，这个在线数据库将被使用: https://dpdb.webvr.rocks/dpdb.json 当将数据库url设置为空字符串值或null时，将不会为未知设备发出在线数据库请求。
Attribute name	Type	Default value
mobilevr_wakelock	Boolean	true
Wakelock - 尽量保持移动设备处于唤醒状态，并防止显示器切换到睡眠/待机模式。这是必要的，因为在VR观看过程中，通常不会发生用户触摸显示器(这会阻止睡眠)的情况。 浏览器屏幕 Screen Wake Lock API 在可用时使用 (在Android Chrome和iOS 16.4版本后)。 如果没有Wake Lock API支持，则使用播放和循环小隐藏视频的解决方案。但这可能会干扰其他视频。这意味着在播放视频时，唤醒器可能会被打断。
Attribute name	Type	Default value
mobilevr_sensor	int	1
定义哪个浏览器事件应该用于设备移动跟踪: 0 =  deviceorientation 事件 在这里，传感器融合将由浏览器自己完成。 不幸的是，这个事件的数据在许多Android设备和Android浏览器中都有bug或者是坏的(慢的、不准确的、错误的)。 1 = devicemotion 事件(默认的) 在这里，传感器融合将由krpano完成。 浏览器提供来自加速度和陀螺仪传感器的原始数据，krpano将它们结合起来以获得最终的设备旋转: 陀螺仪的数据非常快速和准确，但陀螺仪传感器只能测量相对旋转，因此随着时间的推移，它会偏离真实的物理方向。 为了补偿这种漂移，使用了加速度传感器。这个传感器测量地球的重力加速度，可以作为绝对参考。 但是加速度数据非常嘈杂，它只能用于检测“倾斜”旋转(向左，向右，向上或向下倾斜)-围绕设备本身的旋转不能通过加速度检测，为此需要陀螺仪数据。 因此，来自两个传感器的数据将被合并/融合。加速度数据将进行低通滤波，并用作慢速“稳定”和陀螺仪数据，以便在所有方向上快速准确地运动。 使用devicemotion事件(设置mobilevr_sensor=1)是默认的，通常不需要或没有好处使用deviceorientation事件，除非可能有一些极端的浏览器错误… 注意-在iOS 13.4 / Safari 13.1中，devicemotion事件被破坏。因此，在这些系统上，mobilevr_sensor的默认值被设置为0，以使用deviceorientation事件(它正在工作)。
Attribute name	Type	Default value
mobilevr_sensor_mode	int	3
帧渲染和“传感器数据事件”以不同的时间间隔/速率发生(取决于系统和浏览器)，因此有必要评估和插值/外推传感器数据，以获得平滑、快速和响应性的移动。 通过此设置，可以为该过程选择不同的模式。 可用的模式: 0 = 直接使用最新可用的传感器数据。没有内插或外推。根据浏览器的传感器时间间隔，移动可以是不稳定的，也可以是平稳的。 1 = 平滑插值之间的最新可用的传感器数据。这将给一个非常平稳但延迟的动作。 2 = 预测设备旋转，然后在传感器数据之间进行插值。 3 = 将最新可用的传感器数据外推到当前帧时间。这将提供快速响应和平滑的移动，但当推断/预测数据与实际移动不匹配时，可能会出现抖动。 4 = 预测设备旋转到当前帧时间。这将提供快速响应和平滑的移动，但当推断/预测数据与实际移动不匹配时，可能会出现抖动。 5 = 预测设备旋转，并从最新事件推断传感器数据到当前帧时间。 6 = 提前一帧预测设备旋转。 7 = 提前两帧预测设备旋转。 注意-这些设置需要在VR-HMD(头戴式显示器)内进行评级!例如，mode=1在屏幕上看起来很好而且超级平滑，但在HMD中延迟的移动可能会令人不愉快。其他模式可能在屏幕上看起来不太好，但在头戴式显示器中效果不错。 此外，这取决于浏览器的传感器速率，以及每种模式看起来有多好。对于不同的设备，模式3和模式4是一个很好的折衷方案。
Attribute name	Type	Default value
flatpanohfov	Number	120.0
启用在VR中观看平面全景的特殊模式。 由  定义的平面全景将在进入VR模式时自动升级到该水平视野。 hotspot的 ath, atv and scale 设置也将自动升级。 当设置为0.0时，该模式将被禁用。
Attribute name	Type	Default value
vr_cursor	String
使用热点作为虚拟现实光标。 该光标热点将自动显示在屏幕中央所有其他热点的上方，并充当光标/指针。热点本身的样式可以通过普通的热点属性来控制。 鼠标悬停时，光标的立体3D深度会自动调整，以匹配其他热点的3D深度。这使得聚焦不同深度的热点变得更加容易。 当光标在其他热点上时，该热点本身的onover和onout事件以及vr_cursor_onover、vr_cursor_onout事件将被调用。这可以用来实现一个自动点击，当一个热点悬停一段时间。 语法: vr_cursor="hotspot[name]" name - 热点的名称。 热点本身在启动时应该是不可见的 (visible=false) 。
Attribute name	Type	Default value
vr_cursor_enabled	Boolean	true
启用或禁用vr-cursor。 当禁用时，游标将不会触发 onover / vr_cursor_onover 事件。
Attribute name	Type	Default value
vr_cursor_onover vr_cursor_onout	Action Event Action Event
当 vr_cursor 移动到其他热点之外时，将调用这些事件。 这些事件的 'scope' 将是悬停的热点之一。这意味着这些事件的行为就像热点本身的 onover, onout 事件。
Attribute name	Type	Default value
vr_controller_support	Boolean	true
开启或关闭对vr-controller的支持。
Attribute name	Type	Default value
vr_controller	String
定义一个逗号分隔的热点列表，这些热点应该用作vr控制器。 一个或两个热点可以用于左手和右手。当不应该使用某手牌的热点时，可以使用值null代替。 例子: vr_controller="vrcontroller_l,vrcontroller_r" 其中'vrcontroller_l'和'vrcontroller_r'为  元素的名称。 当使用vr控制器时，链接的热点将自动更新: 它们的 tx,ty,tz 位置将被设置为控制器位置。 rx,ry,rz 转设置以匹配控制器旋转。 表示控制器所指向的方向单位矢量的其他dx、dy、dz属性将被添加到controller-hotspot中。 控制器热点元素可以有一个可选的handrotate="rx|ry|rz|rotationorder"设置，用于自定义热点控制器图像的旋转: 默认值为handrotate="0|180|0|XYZ" handrotate="0|0|0|XYZ"表示右手。 控制器热点元素也可以有一个可选的瞄准角="0"设置，用于自定义控制器瞄准/命中射线的方向。 瞄准角以度表示瞄准方向的角度。 默认瞄准角度取决于VR控制器模型。较新的型号通常使用0.0度，但一些较旧的控制器也会使用45度甚至60度的设置。 当控制器指向其他热点时: 带有对该热点对象引用的target属性将被添加到controller-hotspot中。 目标热点和控制器热点的 onover, onout 事件将被调用。 目标热点和控制器热点的 hovering 属性将被设置为true。 为了检查控制器在该热点上指向的确切位置，可以使用目标热点的 hitx,hity,hitd属性。 当按下或释放控制器按钮时，控制器热点的onvrcontrollerbutton事件将被调用。此外，控制器热点将获得: vrbuttonindex - 当前按钮的索引(0-n)。 vrbuttonstate - 按钮“上”或“下”的当前状态。 变量，用于获取关于按下或释放哪个按钮的信息。 当按下控制器按钮并同时悬停在另一个热点时，并且按下的按钮是 vr_controller_clickbuttons之一： 那么目标热点的 pressed 属性和控制器热点的pressed属性将被设为true， 目标热点的 ondown, onup, onclick 事件会被调用。 对于触觉反馈，热点得到一个脉冲(值，持续时间)功能。这可以在悬停物体时调用 onover 事件。 value - 脉冲的强度(控制器振动)。 duration - 脉冲的持续时间，单位为秒。 当控制器被更新时， onvrcontrollers 事件将被调用。 关于vr控制器本身的信息也可以通过 vrcontrollers Array获得。
Attribute name	Type	Default value
vr_controller_clickbuttons	String	"0,1"
应该使用vr控制器的哪些按钮来触发点击事件。 可用的按钮:Gamepad

插件状态变量(只读)

Attribute name	Type	Default value
isavailable	Boolean	false
是否提供VR支持? 注意-正确的状态只有在 onavailable or onunavailable 事件之后才可用!
Attribute name	Type	Default value
isenabled	Boolean	false
当前是否开启VR模式?
Attribute name	Type	Default value
iswebvr	Boolean	false
浏览器是否支持WebVR API或WebXR API ? 注意-正确的状态只有在 onavailable 事件之后才可用!
Attribute name	Type	Default value
iswebxr	Boolean	false
浏览器是否支持WebXR API ? 注意-正确的状态只有在 onavailable 事件之后才可用!
Attribute name	Type	Default value
ismobilevr	Boolean	false
当没有WebVR API支持可用，但设备本身是一个具有工作陀螺仪传感器支持的移动设备时?⇒ MobileVR 支持。 注意-正确的状态只有在 onavailable 事件之后才可用!
Attribute name	Type	Default value
isfake	Boolean	false
是在MobileVR fake 模式。 注意-正确的状态只有在 onavailable 事件之后才可用!
Attribute name	Type	Default value
isvrbrowser	Boolean	false
浏览器本身也是一个VR应用程序吗? 这可以用于显示一个特殊的用户界面，例如，代替普通的桌面/移动皮肤，直接使用一个大的“进入VR”按钮。 注意-正确的状态只有在 onavailable 事件之后才可用!
Attribute name	Type	Default value
vrcontrollers	JS-Array
一个包含当前可用vr控制器信息的Javascript-Array。 每个Array-item包含以下信息: id - 虚拟机控制器的id/name。 hand - 字符串: "left" 或 "right". axes - 一个4计数的浮点数组，其值范围为-1.0到+1.0，表示控制杆轴(或触控板)位置 (更多信息). buttons - 一组手柄按钮 (更多信息). pressed - 一个布尔值，指示其中一个触发按钮 (根据 vr_controller_clickbuttons) 被按下。 rx,ry,rz - 以度为单位的旋转角。 dx,dy,dz - 一个方向单位矢量。 tx,ty,tz - 虚拟机控制器的位置。 hs - 对分配给该vr控制器的krpano热点的对象引用。
Attribute name	Type	Default value
havepostracking	Boolean	false
有 positional-tracking? 注意-这个状态是在进入VR模式和 onhavepostracking 事件后第一次更新!
Attribute name	Type	Default value
floorlevel	Number
实际眼/楼面高度(厘米) 仅在使用WebXR API以及设备和浏览器支持位置跟踪时可用。 当不可用时，该值将为0.0。
Attribute name	Type	Default value
havesettings	Boolean	false
是否有 loadsettings() 动作加载的设置?
Attribute name	Type	Default value
devicename	String
获取WebVR设备名称或检测到的移动设备名称。 注意-正确的状态只有在 onavailable 事件之后才可用!
Attribute name	Type	Default value
devicesize	Number	0.0
获取设备的物理对角线屏幕尺寸(以英寸为单位)。 当大小未知时，该值将为0.0。 注意-正确的状态只有在 onavailable or onunknowndevice 事件之后才可用!
Attribute name	Type	Default value
renderwidth renderheight	int int	0 0
当前渲染缓冲区的像素大小。

Plugin Events

Attribute name	Type	Default value
onavailable	Action Event
当WebVR或MobileVR支持可用时，将调用此事件。 可以用来显示“进入VR模式”按钮。这个按钮可以调用enterVR()动作来输入它。
Attribute name	Type	Default value
onunavailable	Action Event
此事件将在没有VR支持时调用。
Attribute name	Type	Default value
onunknowndevice	Action Event
当无法检测到移动设备及其屏幕大小时，将调用此事件。 在这种情况下，可能会显示菜单或设置屏幕，并询问用户其设备的屏幕尺寸。
Attribute name	Type	Default value
onvrcontrollers	Action Event
此事件将在更新vr-控制器时被调用。 关于vr-控制器本身的信息可以通过vrcontrollers变量获得。 注意-当虚拟现实控制器可用时，虚拟现实光标将自动隐藏。
Attribute name	Type	Default value
onvrcontrollerbutton	Action Event
当vr控制器上的按钮状态发生改变时，将调用此事件。 事件的调用范围将是vr-controller热点元素。 这些信息将在该范围内可用/存储在热点中: vrbuttonindex -当前按钮的索引(0-n)。 vrbuttonstate -按钮“down”或“up”的当前状态。 vrcontroller -当前虚拟控制器信息。 当为事件使用Javascript回调函数时，vr-controller热点将作为参数传递。
Attribute name	Type	Default value
onhavepostracking	Action Event
当 positional-tracking.的可用性时，将调用此事件一次。 这只有在进入VR模式后才能发生。
Attribute name	Type	Default value
onentervr	Action Event
此事件将在切换到VR模式时被调用。 可用于设置自定义VR布局-例如，显示“退出VR”按钮，隐藏不必要或干扰VR模式的UI元素。
Attribute name	Type	Default value
onexitvr	Action Event
此事件将在退出VR模式时被调用。
Attribute name	Type	Default value
ondenied	Action Event
当进入VR模式失败时，将调用此事件。失败的原因可能是用户不允许使用VR或陀螺仪。

插件操作

enterVR()

• 切换到VR全屏模式。

exitVR()

• 退出VR模式。

toggleVR()

• 切换当前的VR模式状态——根据当前状态，切换到VR模式或退出VR模式。

lookat(hlookat)

• 设置水平方向 (hlookat).

loadSettings()
saveSettings()
resetSettings()

• 加载或保存MobileVR设置(屏幕大小，配置文件，陀螺仪校准)。
• 设置将只存储在本地浏览器的localStorage中。
• 当调用resetSettings()时，设置存储将被清除。
• 存储仅适用于当前域，由于浏览器限制，跨域存储共享不再可能。

iFrame的支持

​
        当试图使用MobileVR支持在一个“跨起源”iframe(这意味着外部页面和内部iframe页面是在不同的起源/域)，然后陀螺的使用(与此同时，VR支持)可能会被浏览器阻止。

        为了解决这个限制，可以在外部页面中“捕获”devicemotion事件，并通过postMessage API将其发送到内部iframe。

下面是外部(包含iframe的)网页的Javascript代码示例: