News • Examples • Documentation • Download • Buy • Forum • Contact
NOTE: This page is from an older version, see the latest version here.

Gyro 2 Plugin gyro2.js Version 1.20

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

Topics

Syntax

<plugin name="gyro" devices="html5" keep="true"
        url="gyro2.js" 
        enabled="false"
        camroll="true"
        friction="0.0"
        touch_mode="full"
        sensor="1"
        sensor_mode="1"
        softstart="0.5"
        autocalibration="false"
        desktopsupport="false"
        onavailable=""
        onunavailable=""
        onenable=""
        ondisable=""
        />

Plugin Attributes

Attribute nameTypeDefault value
enabledBooleanfalse
  • Enable or disable the gyro plugin.
  • Can by changed anytime - e.g. by using the set() or switch() actions.
Attribute nameTypeDefault value
camrollBooleantrue
  • Roll / level the viewer camera according to the device roll.
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
touch_modeString"full"
  • 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
sensorint1
  • 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 sensor 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...
Attribute nameTypeDefault value
sensor_modeint1
  • 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
softstartNumber0.5
  • 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
autocalibrationBooleanfalse
  • 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
desktopsupportBooleanfalse
  • 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 gryoscope sensor available!

Plugin State Attributes (read only)

Attribute nameTypeDefault value
isavailableBooleanfalse
  • Is gyroscope support available?
  • This variable will be first set to its correctly value after the onavailable or onunavailable events.

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.


Additionally to the direct plugin events, the plugin also dispatches these krpano events: 
<events gyro_onavailable=""
        gyro_onunavailable=""
        gyro_onenable=""
        gyro_ondisable=""
        />

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: 
<script>

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 } }, "*"); });

</script>