# Paver

## Configuration options

The following table is an alphabetical list of all accepted options for configuring your Paver instance. These options can either be declared in an object that is passed into the .paver() method, or as a HTML5 data- attribute.

cursorThrottle gyroscopeThrottle failureMessage failureMessageInsert gracefulFailure Option HTML5 data Type Default Description data-cursor-throttle Numeric 1000/60 This throttles to the listening of the mousemove events, to prevert jittery panning actions of Paver-enabled panoramas. Defaults to 60fps. data-gyroscope-throttle Numeric 1000/60 This throttles to the listening of the deviceorientation events, to prevert jittery panning actions of Paver-enabled panoramas. Defaults to 60fps. data-failure-message Text Scroll left/right to pan through panorama. The failure message to display when Paver is not initialized, such that users are not left in the dark in how to navigate/pan through the panorama. This message will appear in mobile devices with no gyroscopic data or no DeviceOrientationEvent support.Will only work when gracefulFailure is set to true. data-failure-message-insert Text after The DOM location where the failure message will be inserted. This follows the jQuery convention of inserting new DOM nodes—accepted values are before, after, append and prepend. If the value of this option is not one of the four specified, it will fallback to the default value of after.Will only work when gracefulFailure is set to true. data-graceful-failure Boolean true Allows the display of failure message (via failureMessage) at the desired DOM insertion location (via failureMessageInsert). data-grain Numeric (integer) 3 Determines to how many decimal places, via .toFixed(), the relative position of the cursor to the parent container of the panorama, or the ratio of device tilt, should be computed to. Higher values may lead to over-sensitivity, lower values may lead to jitter effect. The minimum value is 1, and will be coerced by the plugin if the user-supplied value is less than or equals to 0. data-meta Boolean false Determines whether a metadata overlay should be displayed. When enabled, the plugin will retrieve the value(s) of the title and/or alt, if declared (but by the way, the alt is always required), and injects them into the Paver container:
Title Description
 data-minimum-overflow Numeric (integer) 200 The excess width the panorama must have, in pixels, before Paver kicks in. In other words, this option allows the panorama's computed width to exceed that of its parent container by n amount of pixels before we allow for panning. Nobody wants a panorama that can barely be panned, which could almost fit in the whole screen, right?This value should be determined on a case-by-case basis, depending on how wide your panorama container is, but with repeated testing I find 200 to be a good in-between value. data-mouse-smoothing-function String or Function linear Determines how tilting movement can be translated and smoothed into a panning action. Default option is linear, but you may choose between gaussian, cosine and tangent. For details of each smoothing function, refer to smoothing functions.If you are declaring a function, refer to custom smoothing functions for instructions on how to create one yourself. data-panning-throttle Numeric (ms) 125 This parameter is deprecated in favour of separate throttling values for mouse-based and gyroscope-based events. See: cursorThrottle and gyroscopeThrottle respectively.This throttles to the listening of the deviceorientation and/or mousemove events, to prevert jittery panning actions of Paver-enabled panoramas. This is partially due to the high sampling rate of gyroscoping data. However, increasing this number (longer durations) will lead to jerky panning movements due to low resolution of device tilt available to Paver. When updating this value, remember to update the transition-duration property in paver.scss (and recompile it) or paver.css, such that it is equivalent to the panningThrottle value. data-resize-throttle Numeric (ms) 500 Governs how often the window resize event should be fired. Due to intensive computation requirements of each Paver instance, the window resize event has been highly throttled. Afterall, it is the final dimensions of the viewport that matters, not that of during transitional resizing events. data-responsive Boolean true Toggles the responsiveness of the panorama image, in the event that the viewport is too wide such that panning is not required. If enable, Paver will attempt to resize the image to fill the dimensions of the image's parent. data-start-position Numeric (ratio) 0.5 Determines the start position of the panorama when Paver is enabled. By default, this will horizontally center the panorama. The ratio extends from 0 through 1, from the left to the right of the panorama. For example, if you want the panorama to be at the leftmost position upon initialization, use 0.Since this value must be a ratio, Paver will coerce the value to fall within this range, i.e. numeric values that fall beyond the range will be forced to 0 or 1. This option will be nullified when gyroscopic data is in use. data-tilt Boolean true Experimental feature that depends on device support.When enabled, this option allows Paver to tap to the gyroscopic data available from the device. It translates tilting (front-back and left-right) into panning actions. data-tilt-sensitivity Numeric (degrees) 0.2 Experimental feature that depends on device support.The number of degrees that has to be tilted in between measurements for the scroller to be display on a gyroscope-equipped device. The larger the value, the more rapid tilting action has to be initiated before the scoller appears on a gyroscope-equipped device. data-tilt-scroller-persistence Numeric (ms) 500 Experimental feature that depends on device support.Determines the duration, in milliseconds, of which the scroller overlay will appear when the device is being tilted beyond the tiltThreshold (which is device orientation-sensitive). This rule is enforced using the window.setTimeout() function.When this value is set to 0, the scroller will always appear over the panorama on devices that provide gyroscopic data. data-tilt-smoothing-function String or Function gaussian Experimental feature that depends on device support.Determines how tilting movement can be translated and smoothed into a panning action. Default option is gaussian, but you may choose between linear, cosine and tangent. For details of each smoothing function, refer to smoothing functions.If you are declaring a function, refer to custom smoothing functions for instructions on how to create one yourself. data-tilt-threshold-landscape Numeric (degrees) 24 Experimental feature that depends on device support.The number of degrees from the resting start position where the panning will end, when the device orientation is in landscape mode. For example, with the default value of 24, the user simply has to tilt left/right by 24 degrees to reach the left/rightmost edges of the panorama in landscape mode.This value will be coerced within the range of 0 to 180 degrees. data-tilt-threshold-portrait Numeric (degrees) 12 Experimental feature that depends on device support.The number of degrees from the resting start position where the panning will end, when the device orientation is in portrait mode. For example, with the default value of 12, the user simply has to tilt left/right by 12 degrees to reach the left/rightmost edges of the panorama in portrait mode.This value will be coerced within the range of 0 to 180 degrees.

### Smoothing Functions

As of v1.2.0, you can now declare your own smoothing functions. Please refer to advanced usage for an example.

Paver comes with four smoothing functions that converts cursor coordinates and/or device tilt into CSS transforms that will pan your panoramas. Note that these functions accept variables mapped to the range of $[-1,1]$, where 0 represents the center of the panorama, and will transform outputs mapped to the range of $[0,1]$, where 0.5 represents the center of the panorama. The reasoning behind this is that device tilt can take on negative and positive values—cursor coordinates are simply mapped to $[-1,1]$ prior to passing them into smoothing functions.

Note: in mathematical terms, square brackets is the representation of the concept "inclusive of", i.e. $[-1,1]$ is inclusive of $-1$ and $1$, or $-1 \le n \le 1$.

• #### Linear

\begin{align} y &= f(x) \\ &= \frac{\left(x+1\right)}{2} \end{align} $$\textrm{where } x = [-1,1] \textrm{ and } f(x) = [0,1]$$
var linear = function(delta, threshold) {
if (delta >= threshold) return 1;
if (delta <= -threshold) return 0;
return 0.5 * (delta/threshold + 1);
};

The simplest of all, this function simply transforms $x$ linearly, from its original range of $[-1,1]$, to $f(x)$ with a range of $[0,1]$. This is the default smoothing function (a misnomer, actually, since it is not smoothing anything) for cursor position.

• #### Tangent

\begin{align} y &= f(x) \\ &= \frac{1}{2} \left[\frac{\tan \left(0.351 \pi x \right)}{2} + 1 \right] \end{align} $$\textrm{where } x = [-1,1] \textrm{ and } f(x) = [0,1]$$
var tangent = function(delta, threshold) {
if (delta >= threshold) return 1;
if (delta <= -threshold) return 0;
return 0.5 * (0.5 * Math.tan((delta/threshold) * (Math.PI * 0.351)) + 1);
};

This function transforms $x$ in the range of $[-1,1]$ via a tangent function. Since the transformation of the tangent curve is imprecise and only down to three decimal places, the range of $f(x)$ lies approximately between $[0,1]$.

• #### Cosine

\begin{align} y &= f(x) \\ &= \frac{1}{2} \left[ \sin\left(\frac{x}{2}\right) + 1 \right] \end{align} $$\textrm{where } x = [-1,1] \textrm{ and } f(x) = [0,1]$$
var cosine = function(delta, threshold) {
if (delta >= threshold) return 1;
if (delta <= -threshold) return 0;
return 0.5 * (Math.sin((delta/threshold) * (Math.PI/2)) + 1);
};

This function transforms $x$ in the range of $[-1,1]$ via a cosine function. The output, $f(x)$, again lies in the range of $[0,1]$.

• #### Gaussian

\begin{align} y &= f(x) \\ &= \frac{1}{\sigma \sqrt{2\pi}} \int_{-\infty}^x \! e^{-(x - \mu)^2/2\sigma^2} \textrm{d}x \\ &= \frac{1}{2} \left[ \textrm{erf} \left( \frac{x - \mu}{\sigma \sqrt{2}} \right) + 1 \right] \end{align} \begin{align} \textrm{where } & x = [-1,1] \textrm{ and } f(x) = [0,1] \\ & \mu = 1 \textrm{ and } \sigma = 0.375 \end{align}
var normalcdf = function(mean, sigma, to) {
var z = (to-mean)/Math.sqrt(2*sigma*sigma),
t = 1/(1+0.3275911*Math.abs(z)),
a1 =  0.254829592,
a2 = -0.284496736,
a3 =  1.421413741,
a4 = -1.453152027,
a5 =  1.061405429,
erf = 1-(((((a5*t + a4)*t) + a3)*t + a2)*t + a1)*t*Math.exp(-z*z),
sign = 1;
if(z < 0) sign = -1;
return (1/2)*(1+sign*erf);
};

var gaussian = function(delta, threshold) {
if (delta >= threshold) return 1;
if (delta <= -threshold) return 0;
return normalcdf(0, 0.375, delta/threshold);
}

This function is a simplified equation of the cumulative distribution function of a normal distribution. This is the default smoothing function for device tilt angles, provided by the gyroscope (if present). Note that since the error function $\textrm{erf}()$ is simply an approximation (code adapted from a StackOverflow answer), the range of $f(x)$ will only be accurate to at most 9 decimal points (which is more than sufficient, anyway).