Usage Notes · Paver, a jQuery plugin for easy panorama viewing

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.

Option	HTML5 data	Type	Default	Description
cursorThrottle	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.
gyroscopeThrottle	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.
failureMessage	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`.
failureMessageInsert	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`.
gracefulFailure	data-graceful-failure	Boolean	true	Allows the display of failure message (via `failureMessage`) at the desired DOM insertion location (via `failureMessageInsert`).
grain	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.
meta	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: `<div class="paver__meta"> <span class="paver__title">Title</span> <span class="paver__desc">Description</span> </div>`
minimumOverflow	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.
mouseSmoothingFunction	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.
panningThrottle	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.
resizeThrottle	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.
responsive	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.
startPosition	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.
tilt	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.
tiltSensitivity	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.
tiltScrollerPersistence	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.
tiltSmoothingFunction	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.
tiltThresholdLandscape	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.
tiltThresholdPortrait	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).

Configuration options

Smoothing Functions

Linear

Tangent

Cosine

Gaussian