News Examples Documentation Download Buy Forum Contact



XML Extensions


Third Party Software
for krpano

Gyro 2 Plugin gyro2.js Version 1.21

This plugin uses the gyroscope and acceleration sensors of a mobile or tablet device to control the viewing / looking direction in krpano.

Note - in many newer browser versions the usage of HTTPS is a core requirement to get gyro-support from the browser.


Gyro Testing
Sensor Comparison
A default Virtual Tour

krpano API Integration

  • After loading, the plugin object will be also available as global gyro variable.

Plugin Attributes

Attribute nameTypeDefault value
  • Enable or disable the gyro plugin.
  • Can by changed anytime - e.g. by using the set() or switch() actions.
Attribute nameTypeDefault value
  • Roll / level the viewer camera according to the device roll.
Attribute nameTypeDefault value
  • Use an absolute / real-world-oriented gyroscope tracking.
  • By default the pano-image-center (hlookat=0.0) will point to North, but it is also possible to set a custom north position/offset.
  • When disabled (the default), the gyroscope tracking will be relative to the current viewing direction.
  • The device must have a magnetic sensor for this to work reliably. iOS devices are typically working very well, on Android it varies and depends on the device.
  • Note - when using absolute tracking, all panos should be set/aligned to the same North. Otherwise the north setting would need to be adjusted dynamically for each pano.
Attribute nameTypeDefault value
  • Define where North is located in the pano-image (from -180 to +180).
  • The default is 0.0, which refers to the center of the pano-image.
  • Note - this is only relevant when using using absolute gyroscope tracking.
  • The coordinate system:
Attribute nameTypeDefault value
frictionString / Number0.0
  • Friction / vibration dampening of the gyro movement.
  • Values: 0.0 - 0.99 or "auto"
    • 0.0 = no friction / dampening, 0.99 = very strong dampening
      The higher the value the more dampening, but therefore also the movement will be delayed more.
    • auto - use dynamically an automatic zoom friction value based on the current zoom/fov and the current frame-rate based friction - e.g. more shake dampening when zooming in.
Attribute nameTypeDefault value
  • Available modes:
    • off - No touch control / panning.
    • horizontaloffset - By touch dragging only the horizontal offset will change.
    • full - Full touch control - pan horizontally and vertically. The vertical offset will return slowly to the real device orientation when moving the device.
    • disablegyro - When the user touches the screen, the gyro control gets automatically disabled and the normal controls are taking over. To get the gyro control back, the gyro would need to get enabled again.
Attribute nameTypeDefault value
  • Define which browser event should be used for the device movement tracking:
    • 0 - the deviceorientation event
      • Here the sensor fusion will be done by the browser itself.
      • The data from this event is unfortunately buggy or just bad (slow, inaccurate, wrong) in many Android devices and Android browsers.
    • 1 - the devicemotion event (default)
      • Here the sensor fusion will be done by krpano.
      • The browser provides the raw data from the acceleration and the gyroscope sensors and krpano combines them for getting the final device rotation:
        • The gyroscope data is very quick and accurate but the gyroscope sensor measures only relative rotations and therefore it drifts away from the real physical orientation over time.
        • To compensate that drift, the acceleration sensor is used. That sensor measures the gravity acceleration of the earth and that can be used as absolute reference.
        • But the acceleration data is very noisy and it can be only used for detection 'tilt' rotations (tilt left, right, up or down) - rotations around the device itself can't detected by acceleration, for this the gyroscope data is required.
        • So the data from both sensors will be combined / fused. The acceleration data will be low-pass filtered and used as slow 'stabilization' and the gyroscope data for quick and accurate movements in all directions.
  • Using the devicemotion event (setting sensor=1) is the default and there should be normally no need or benefit to use the deviceorientation event, except maybe for some extreme browser bugs...
  • Note - In iOS 13.4 / Safari 13.1 the devicemotion event is broken. Therefore on these systems the default value of sensor is set to 0 to use the deviceorientation event (which is working) instead.
Attribute nameTypeDefault value
  • The frame-rendering and the 'sensor-data-events' are happening in different time intervals / rates (depending on the system and browser), so it is necessary to evaluate and interpolate/extrapolate the sensor data somehow to get a smooth and also fast and responsive movement.
  • With this setting, different modes for this process can be selected.
  • Available modes:
    • 0 = Directly use the latest available sensor data. No interpolation or extrapolation. Depending on the sensor-time-intervals of the browser the movement can be either jerky or smooth.
    • 1 = Smoothly interpolate between the latest available sensor data. This will give a very smooth but slightly delayed movement.
    • 2 = Forecast the device rotations and then interpolate between the sensor data.
    • 3 = Extrapolate the latest available sensor data to the current frame time. This will give a fast responsive and smooth movement, but there can be a jerking when the extrapolated/predicted data and the real movement don't match.
    • 4 = Forecast the device rotation to the current frame time. This will give a fast responsive and smooth movement, but there can be a jerking when the extrapolated/predicted data and the real movement don't match.
    • 5 = Forecast the device rotation and extrapolate the sensor data from the latest event to the current frame time.
Attribute nameTypeDefault value
  • When enabling the gyro tracking fade slowy from the current viewing direction to the gyro-tracked viewing direction.
  • The softstart setting defines the number of seconds for this 'fade-in' process.
  • Set this setting to 0 to disable it to instantly use the gyro-tracked values.
Attribute nameTypeDefault value
  • Enable an automatic gyroscope calibration.
  • Some devices have uncalibrated sensors and there this automatic calibration can help to avoid an unintended gyroscope movement / drifting.
  • The automatic self-calibration will be done every time when the device will be hold very still, e.g. either by holding the device very steady or by laying the device on a stable table.
Attribute nameTypeDefault value
  • Enable the gyroscope support also for desktop devices (e.g. Windows Tablet-PCs).
  • By default the gyroscope support is only available for mobile and tablet devices.
  • This settings should be not enabled by default! Desktop browsers might wrongly report that they have gyroscope support even when there is no gryoscope sensor available!

Plugin State Attributes (read only)

Attribute nameTypeDefault value
  • Is gyroscope support available?
  • This variable will be first set to its correct value after the onavailable or onunavailable event.
Attribute nameTypeDefault value
  • Is the gyroscope currently actually enabled?

Plugin Events

Attribute nameTypeDefault value
onavailableAction Event
  • This event will be called when gyroscope support is available.
  • Could be used to show a 'Gyro' button.
Attribute nameTypeDefault value
onunavailableAction Event
  • This event will be called when no gyroscope support is available on the current device / browser.
Attribute nameTypeDefault value
onenableAction Event
  • This event will be called when gyroscope gets enabled.
Attribute nameTypeDefault value
ondisableAction Event
  • This event will be called when gyroscope gets disabled.
Attribute nameTypeDefault value
ondeniedAction Event
  • This event will be called when using the gyroscope failed. The reason for failing could be that the user didn't allow the usage.

Additionally to the direct plugin events, the plugin also dispatches these krpano events:
<events gyro_onavailable=""

Plugin Actions

resetsensor(hlookat, vlookat*)
  • Reset the sensor tracking to look to the given hlookat (horizontal looking) direction.
  • When using touch_mode=full, it's optionally also possible to set the vlookat (vertical looking) direction.

iFrame Notes

When using the gyro inside an 'cross-origin' iframe (that means the outer page and inner iframe page are on different origins/domains) then the gyro-usage might be blocked by the browser.

To work-around that limitation, it is possible to 'capture' the devicemotion event in the outer page and send it via the postMessage API to the inner iframe.
Here example Javascript code for the outer (the iframe-containing) webpage:
var pano_iframe_name = "enter_here_the_id_of_your_iframe_element";
window.addEventListener("devicemotion", function(e){ var iframe = document.getElementById(pano_iframe_name); if (iframe) iframe.contentWindow.postMessage({ type:"devicemotion", deviceMotionEvent:{ acceleration:{ x:e.acceleration.x, y:e.acceleration.y, z:e.acceleration.z }, accelerationIncludingGravity:{ x:e.accelerationIncludingGravity.x, y:e.accelerationIncludingGravity.y, z:e.accelerationIncludingGravity.z }, rotationRate:{ alpha:e.rotationRate.alpha, beta:e.rotationRate.beta, gamma:e.rotationRate.gamma }, interval:e.interval, timeStamp:e.timeStamp } }, "*"); });