Skip to content

Home

Jump to bottom
Michail Schwab edited this page Feb 8, 2018 · 13 revisions

Loading EasyPZ

To load EasyPZ, you can either use the npm package (npm i easypz -P), or you can use the online version:

<script src="https://code.easypz.io/easypz.latest.js"></script>

Enabling EasyPZ

To use EasyPZ, it needs to be bound to an element, usually a SVG element. This can be either done in HTML:

<svg width="600" height="400" easypz>

Or via JavaScript:

new EasyPZ(document.getElementsByClassName('svg')[0], function() {});

Then, EasyPZ will detect when a user wants to pan and zoom. The three ways this information can be used to update the visualization are discussed in the settings.

EasyPZ Settings

Updating the Visualization

There are three ways that panning and zooming can be applied to update your visualization:

  1. Automatically applying the transformation to the svg (easiest)
  2. Implementing an "onTransformed" Method (good for most advanced cases)
  3. Implementing "onPanned", "onZoomed", and "onResetAbsoluteScale" methods (advanced cases, rarely needed).

Automatic Transformation

This is the method used at http://demos.easypz.io/ and for examples such as this one. This method only works when EasyPZ is bound to an element via HTML. You can specify which elements the transformation applies to:

<svg easypz='{"applyTransformTo": "svg > *"}' width="400" height="400">

Here, the transformation is applied to all top level elements of the SVG. Nested elements do not need the transformation, since transformations on a SVG element are applied to its child elements. The selector can be easily changed however, for example to keep legends static.

Implementation using onTransformed

The zooming and panning can not always occur as SVG transformation, and may require changes in SVG paths, or could be used for other visualizations altogether, such as canvas and WebGL. For those cases, EasyPZ will still compute the total translate and scale required, and hand over the task of applying this knowledge to the developer. Examples are

This method can be used both with the HTML and the JS-based instantiation of EasyPZ. The two examples above use the JS based version:

new EasyPZ(document.getElementsByClassName('svg')[0], function(transform)
{
    // Use transform.scale, transform.translateX, transform.translateY to update your visualization
});

To use the HTML version, the simplest way is to create a function with name "applyTransformTo". EasyPZ will automatically call it. If you prefer a different function name, you can pass it to EasyPZ with a different instantiation:

<svg width="600" height="400" easypz='{"onTransformed": "nameOfYourTransformFunction"}'>

You can then implement your function as follows:

function nameOfYourTransformFunction(transform)
{
    // Use transform.scale, transform.translateX, transform.translateY to update your visualization
}

Manual Implementation (Very Rarely Needed)

Using the onPanned and onZoomed can be done the same way as the onTransformed method, since these two functions are passed the same transformation object. However, they also allow to manually track the total transformation if used together with onResetAbsoluteScale. They are passed each individual scale and position change. Implementation will vary from case to case and is extremely rarely needed. If you need help with this, please feel free to contact us.

Pan and Zoom Methods

Many ways of panning and zooming are available, including variations. Developers can use which of these modes to enable in their visualization.

When using the HTML-based instantiation of EasyPZ, the enabled modes, as shown below, can be passed as shown here:

<svg easypz='{"applyTransformTo": "svg > *", "modes": ["SIMPLE_PAN", "HOLD_ZOOM_IN", "CLICK_HOLD_ZOOM_OUT", "WHEEL_ZOOM", "PINCH_ZOOM", "DBLCLICK_ZOOM_IN", "DBLRIGHTCLICK_ZOOM_OUT"]}' width="400" height="400">

When using the JS-based instantiation of EasyPZ, the enabled modes, as shown below, can be used as fourth parameter of EasyPZ:

new EasyPZ(document.getElementsByClassName('svg')[0], function(transform)
{
    // Use transform.scale, transform.translateX, transform.translateY to update your visualization
}, null, ["SIMPLE_PAN", "HOLD_ZOOM_IN", "CLICK_HOLD_ZOOM_OUT", "WHEEL_ZOOM", "PINCH_ZOOM", "DBLCLICK_ZOOM_IN", "DBLRIGHTCLICK_ZOOM_OUT"]);

The list is:

Name Description
SIMPLE_PAN Standard Panning with a 1:1 mapping between pointer movement and pan.
FLICK_PAN Standard Panning, except when the pointer is released while moving, the panning will continue for a while until it comes to a stop.
HOLD_ZOOM_IN Hold the pointer still to zoom in.
HOLD_ZOOM_OUT Hold the pointer still to zoom out.
CLICK_HOLD_ZOOM_IN Click (Mouse Down, Mouse Up), and then hold the pointer still to zoom in.
CLICK_HOLD_ZOOM_OUT Click (Mouse Down, Mouse Up), and then hold the pointer still to zoom out.
DBLCLICK_ZOOM_IN Double Click to zoom in.
DBLCLICK_ZOOM_OUT Double Click to zoom out.
DBLRIGHTCLICK_ZOOM_IN Double Right Click to zoom in.
DBLRIGHTCLICK_ZOOM_OUT Double Right Click to zoom out.
WHEEL_ZOOM Scroll Wheel to zoom in and out. Linear Mapping.
WHEEL_ZOOM_MOMENTUM Scroll Wheel to zoom in and out, but like Flick Pan, the zooming is continued for a while after stopping the scrolling before coming to a stop.
PINCH_ZOOM Two finger zoom. Linear Mapping.
PINCH_ZOOM_QUADRATIC Two finger zoom. Quadratic Mapping: Small changes are similar to linear pinch zoom, but larger changes lead to much bigger changes in the visualization.
PINCH_ZOOM_POWER_FOUR Two finger zoom. Power of Four Mapping: Small changes are similar to linear pinch zoom, but larger changes lead to much much bigger changes in the visualization.
PINCH_ZOOM_MOMENTUM Two finger zoom, but with momentum, similar to flick pan.
PINCH_PAN Like Pinch Zoom, except it can only be used to pan the visualization, not to zoom.
WHEEL_PAN_X Using the Scroll Wheel to pan horizontally.
WHEEL_PAN_Y Using the Scroll Wheel to pan vertically, similar to normal page scroll.
BRUSH_ZOOM 2D Brush to zoom in.
BRUSH_ZOOM_X 1D Horizontal Brush to zoom in.
BRUSH_ZOOM_Y 1D Vertical Brush to zoom in.
DYNAMIC_ZOOM_X_STATIC
DYNAMIC_ZOOM_X_ORIGINAL_PAN
DYNAMIC_ZOOM_X_NORMAL_PAN
DYNAMIC_ZOOM_X_ADJUSTABLE
DYNAMIC_ZOOM_Y_STATIC
DYNAMIC_ZOOM_Y_ORIGINAL_PAN
DYNAMIC_ZOOM_Y_NORMAL_PAN
DYNAMIC_ZOOM_Y_ADJUSTABLE
RUB_ZOOM_IN_X
RUB_ZOOM_IN_Y
RUB_ZOOM_OUT_X
RUB_ZOOM_OUT_Y

Scale and Translate Bounds

Nobody wants to be lost. Zooming in or out way too far, or panning of the screen, should be avoided, which is why EasyPZ uses sensible defaults for limits on scale and translate. If you want different settings, or you want to disable these limits, here's what you have to do!

When using the HTML-based instantiation of EasyPZ, the boundary options can be passed as shown here:

<svg easypz='{"applyTransformTo": "svg > *", "options": { "minScale": 0.8, "maxScale": 10, "bounds": { "top": -50, "right": 50, "bottom": 50, "left": -50 }} }' width="400" height="400">

When using the JS-based instantiation of EasyPZ, the boundary options can be used as third parameter of EasyPZ:

new EasyPZ(document.getElementsByClassName('svg')[0], function(transform)
{
    // Use transform.scale, transform.translateX, transform.translateY to update your visualization
}, { minScale: 0.8, maxScale: 10, bounds: { top: -150, right: 150, bottom: 150, left: -150 } });

Above, we show the default boundaries for scale and translate. Feel free to replace them with other values. To disable any of the bounds, you can just set them to NaN, and EasyPZ will zoom in and out, and pan, infinitely:

<svg easypz='{"applyTransformTo": "svg > *", "options": { "minScale": "NaN", "maxScale": "NaN", "bounds": { "top": "NaN", "right": "NaN", "bottom": "NaN", "left": "NaN" }} }' width="400" height="400">

When using the JS-based instantiation of EasyPZ, the boundary options can be used as third parameter of EasyPZ:

new EasyPZ(document.getElementsByClassName('svg')[0], function(transform)
{
    // Use transform.scale, transform.translateX, transform.translateY to update your visualization
}, { minScale: NaN, maxScale: NaN, bounds: { top: NaN, right: NaN, bottom: NaN, left: NaN } });

Extending EasyPZ

Clone this wiki locally