News Examples Documentation Download Buy Forum Contact

zFilter Plugin zfilter.js WebGL + HTML5 only
by indexofrefraction - (send forum message)

Description

zFilter is a postpocessing WebGL shader plugin for dynamic effects on your panorama image,
layers and hotspots. It allows you to add visual effects for startup intros, scene changes,
information popups, etc. Setting or tweening simple attributes adjusts the brightness,
saturation or blurs your panorama, layers or hotpots!

Just check out the examples below!

zFilter 2 Release :
more features and lower price :) !
release discount until 2020-02-15 !

zFilter 2.2.7 / 2020-02-01 - indexofrefraction

Syntax / XML Usage Example

<plugin name="zfilter"
	url="zfilter.js"
	preload="true"
	keep="true"
	enabled="true"
	phase="2"
	order=""
	webvr="2"
	gamma="2.2"
	brightness="0"
	contrast="0"
	exposure="0"
	hue="0"
	saturation="0"
	vibrance="0"
	sepia="0"
	swirl="0"
	pixelate="0"
	ripple="0"
	sobel="0"
	split="0"
	fquality.mobile="3"
	fquality.tablet="6"
	fquality.desktop="9"
	fblur="0"
	blur="0"
	blendcolor="0" blendmode="add"
	vignettecolor="0"
	mixcolor="0"
        />

  • Add zfilter.js to your project folder
  • In your html (index/tour.html) ensure that you embedd krpano with html5:"only+webgl"
    embedpano({ html5:"only+webgl", ... });
  • In your main xml (tour.xml) add
    <plugin name="zfilter" url="zfilter.js"
    	preload="true" keep="true" />
    or just use the full block above with all attibutes on their default values.
  • A simple intro for example, can be done by setting initial attribute values
    in combination with an onstart action tweening the attributes back to the defaults.
    <plugin name="zfilter" url="zfilter.js"
    	preload="true" keep="true"
    	mixcolor="0xff000000" />
    <action name="intro" autorun="onstart">
    	tween(plugin[zfilter].mixcolor, 0x00000000, 2.0);
    </action>
  • Note: zFilter is optimized to minimize the performance load on your devices.
    If all attributes are set to their default values, the plugin stays idle and does
    not affect the performance at all.

Plugin Attributes

Attribute nameTypeValue
ready (read only)Booleantrue | false
version (read only)Stringthe plugin version
shaders (read only)Numbernumber of active shaders
shadernames (read only)Stringactive shader names
urlStringzfilter.js
preloadBooleantrue
keepBooleantrue
  • ready is true if the plugin is loaded and ready
  • version holds the plugins version number
  • shaders contains the number of active WebGL shaders
  • shadernames contains the names of active WebGL shaders (in the active order)
  • url must point to the plugin (documentation)
  • preload should be set to true (documentation)
  • also keep should be true for most cases (documentation)
Attribute nameTypeDefault valueMinMax
enabledBooleantrue
webvrNumber212
orderString
iorder (read only)Stringadjust|swirl|pixelate|ripple|sobel|split|fblur|
blur|blendcolor|vignettecolor|mixcolor
webvrNumber203
  • enabled globally enables/disables all plugin effects
  • phase:
    • please read the definition for the postprocessing phase
    • phase is used to set a default or specific phases for zfilter attributes
    • phase is never undefined. If omitted, it will fall back to the last defined default
    • Examples:
      • phase="2" sets phase 2 for all zfilter attributes
      • phase="2|blur=1|mixcolor=1" sets separate phases for blur and mixcolor
    • Note: phase is only supported with krpano 1.20 or newer!
  • order:
    • please read the definition for the postprocessing order
    • order is used to set a default order or specific orders for zfilter attributes
    • order is never undefined. If omitted, it will be set to the highest order on stack
    • Next to the global plugin order, order also allows to set the zfilter internal order
    • The internal order can be changed using attribute names without assignment
    • global order assignments (numbers) precede the zfilter internal order (names)
    • Examples:
      • order="5" sets the order for all zfilter attributes
      • order="5|blur=7|adjust=3" sets separate orders for blur and adjust
      • order="5|blur|sobel" sets the internal order to execute blur before sobel
        while the order is 5 for all zfilter attributes, the internal order is now
        iorder=""adjust|blur|swirl|pixelate|ripple|split|fblur|sobel|blendcolor|vignettecolor|mixcolor""
      • order="5|blendcolor=4|blur|sobel" set the internal order to execute blur
        before sobel under a default order of 5 with a special order for blendcolor
    • Notes:
      • adjust filters (brightness, contrast, saturation, etc) are implemented as
        a combined postprocessing filter and therefore can't get ordered individually
      • If multiple postprocessing plugins are used, you should give each of them an
        individual order, otherwise you may experience unwanted filter interference
      • order is only supported with krpano 1.20 or newer!
  • iorder is used to get the zfilter internal order
    • iorder is read only, to change values order must be used!
    • it considers separate global orders for zfilter attributes
    • Example:
      • order="2|blur=3|fblur=1" will result in:
        iorder=""fblur|adjust|swirl|pixelate|ripple|sobel|split|blendcolor|vignettecolor|mixcolor|blur""
  • webvr is used suppress zfilter for certain webvr levels
    • zFilter is highly optimized and performs great on deskops, tablets and mobiles.
      Sadly this is not the case for true webVR (ie. Oculus Go, Quest, Rift, etc),
      where most devices have a poor WebGL performance.
    • Therefore the default is webvr="2" which suppresses zfilter for true webVR
    • possible values/levels for the webvr attribute are:
      0=normal / no VR, 1=fake VR, 2=mobile VR, 3=true WebVR
Attribute nameTypeDefault valueMinMax
gammaNumber2.20.04.4
brightnessNumber0.0-1.01.0
contrastNumber0.0-1.01.0
exposureNumber0.0-1.01.0
hueNumber0.0-1.01.0
saturationNumber0.0-1.01.0
vibranceNumber0.0-1.01.0
sepiaNumber0.00.01.0
  • Basic image filters
  • Examples:
    • set(plugin[zfilter].brightness, 0.25);
    • tween(plugin[zfilter].saturation, -1.0, 1.0);
Attribute nameTypeDefault valueMinMax
swirlNumber0.00.01.0
pixelateNumber0.00.01.0
rippleNumber0.00.01.0
sobelNumber0.00.01.0
splitNumber0.0-1.01.0
  • Swirl effect
  • Pixelate effect
  • Ripple effect
  • Sobel edge detection
  • RGB split effect
  • Examples:
    • set(plugin[zfilter].split, 0.5);
    • tween(plugin[zfilter].sobel, 1.0, 1.0);
Attribute nameTypeDefault valueMinMax
fblurNumber0050
fqualityNumber6032
blurNumber0050
  • fblur (fastblur) is a very fast gaussian blur
  • fquality defines the quality for fblur
    • With low fquality settings fblur shows some visual noise,
      but even with maxed out fquality it is still faster than the standard blur filter.
    • It is recomended to set per device values, as done above under Syntax.
      The chosen values are low on purpose to get the best device support.
  • blur is a quality blur without any visual artefacts
    • Note: blur uses an intelligent, performance optimized algorithm,
      but the higher the blur value, the more WebGL shader passes are needed.
      On low performance devices you should avoid high blur values or use fblur.
  • Examples:
    • set(plugin[zfilter].fblur, 9);
    • tween(plugin[zfilter].fblur, 25, 1.0);
Attribute nameTypeDefault valueMinMax
blendcolorString000xffffffff
blendmodeStringadd
  • blendcolor blends the image with a color by a blendmode (alpha 100% = blended image)
  • 32bit ARGB value layout:
    • 1st byte: alpha (0x00 disables the shader)
    • 2nd byte: red
    • 3rd byte: green
    • 4th byte: blue
    • please read section about 32bit ARGB values
  • supported blendmodes:
    • add, subtract, multiply, darken, colorburn, linearburn, lighten, screen
    • colordodge, lineardodge, overlay, softlight, hardlight, vividlight, linearlight,
    • pinlight, difference, exclusion, hue, saturation, color, luminosity, mix
  • Examples:
    • set(plugin[zfilter].blendmode, 'overlay');
    • set(plugin[zfilter].blendcolor, 0xffff0000);
    • tween(plugin[zfilter].blendcolor, 0x8000ff00, 1.0);
Attribute nameTypeDefault valueMinMax
vignettecolorString000xffffffff
  • vignettecolor blends a black vignette over the image
  • 32bit ARGB value layout:
    • 1st byte: alpha (0x00 disables the shader)
    • 2nd byte: aspect ratio (0x00 stage aspect ratio, 0xff circle 1:1 ratio)
    • 3rd byte: softness (0x00 soft, 0xff hard)
    • 4th byte: radius (0x00 zero, 0x80 fit screen, 0xff max)
    • please read section about 32bit ARGB values
  • Examples:
    • set(plugin[zfilter].vignettecolor, 0xffc01090);
    • tween(plugin[zfilter].vignettecolor, 0xff5060b0, 1.0);
Attribute nameTypeDefault valueMinMax
mixcolorString000xffffffff
  • mixcolor mixes the image with a color (alpha 100% = given color)
  • 32bit ARGB value layout:
    • 1st byte: alpha (0x00 disables the shader)
    • 2nd byte: red
    • 3rd byte: green
    • 4th byte: blue
    • please read section about 32bit ARGB values
  • Examples:
    • set(plugin[zfilter].mixcolor, 0xffff0000);
    • tween(plugin[zfilter].mixcolor, 0x8000ff00, 1.0);

32bit ARGB values

32bit ARGB values consist of 4 bytes, each with a range of hexadecimal 0x00 to 0xff.
Normally 32bit ARGB values are used for colors and are mapped to alpha, red, green and blue,
but zFilter can also map them to other parameters as in the vignettecolor attibute.
The byte to shader parameter mapping is described above for each attribute.

  • You can set 32bit ARGB values by Numbers or Strings in decimal or hex format
  • Reading a 32bit ARGB value returns a String in hexadecimal format
  • Examples:
    • an ARGB value of 0x801eff64 means:
      0x8000ff00 --> A = 0x80/128, R = 0x1e/30, G = 0xFF/255, B = 0x64/100
    • set(plugin[zfilter].blendcolor, 0x8000ff00);
    • tween(plugin[zfilter].blendcolor, 0xffff0000, 2.0);
    • copy(col, plugin[zfilter].blendcolor);

Layers and Hotspots

zFilter can add filter effect attributes to layers and hotspots,
with the following limitations / conditions:
  • Hotspots and layers must be initialized first ! (may change in the future)
  • Supported attributes are: brightness, contrast, saturation, hue, sepia and blur
  • Hotspots need to be rendered by css3d (renderer=css3d)
  • Browser support may vary (should work on most current browsers)

After the layer/hotspot has been initialized, the added zfilter attributes
can be used like any other krpano layer attribute:
  • set(hotspot[myhotspot].saturation, -1);
  • tween(layer[mylayer].blur, 15, 1);
  • tween(layer[mylayer].blur|layer[mylayer].alpha, 15|0, 1);


addzfilter(layer or hotspot)
The addzfilter action initializes zfilter for the given layer or hotspot.
the added zfilter attributes then can be used as any other krpano attribute.

Parameters:
  • layer or hotspot
    • either an object or a string like "layer[mylayer]" or "hotspot[myhotspot]".
      if the layer/hotspot does not exist, it will be created
Examples:
  • addzfilter(layer[mylayer]); // string
  • addzfilter(get(hotspot[myhotspot])); // object
removezfilter(layer or hotspot)
The removezfilter action removes zfilter from the given layer or hotspot.

Parameters:
  • layer or hotspot
    • either an object or a string like "layer[mylayer]" or "hotspot[myhotspot]"
zfiltersupport(variable)
The zfiltersupport action checks if layer/hotspot filtering is supported by the browser.

Parameters:
  • variable
    • The destination variable for the return value (true or false)

Buy / Order the plugin

This is a commercial plugin - to use it, it must be purchased.
Before you buy, please check the Compatibility / Requirements / Limitations!

zFilter is split up in modules which can be purchased separately.
If additional modules are ordered at a later time,
you will receive a combined build containing all (new and older) purchases.

Compatibility / Requirements / Limitations
  • krpano 1.19-pr15 or newer, html5 + webgl only! (Flash is not supported)
  • krpano 1.20 or newer to use the postprocessing phase and order attributes
  • zFilter works on the panorama image and on hotspots with renderer=webgl
  • Layer and hotspot filters support a limited set of effects and require renderer=css3d
  • Browser support for layer and hotpot filters my vary and is not guaranteed
  • support for true webVR is experimental only
  • zFilter is tied to your krpano license (needs a registered version of krpano)
License
  • All copyrights to zFilter are exclusively owned by indexofrefraction.
  • This plugin is offered as a commercial plugin. It is provided "As Is" without warranty of any kind, either express or implied, including any warranty of quality, merchantability, or fitness for a particular purpose. In no event will the author of the plugin be liable for loss of data, costs of procurement of substitute goods or services or any special, consequential or incidental damages, under any cause of action and regardless of whether or not the plugin author have been advised of the possibility of such damage. This limitation will apply notwithstanding any failure of essential purpose of any limited remedy provided herein. In any event the plugin author will have no liability arising out of this agreement.

Buy zFilter modules


Release discount until 2020-02-15 !
49€ - 20% = 39€ (for all modules)

In the purchase form, please register using the exact
name and email you are using for your krpano license
You can check your registration information with the "krpano Tools" application.

* VAT: Depending on your country or company status VAT may be added to the price.
In the Share‑It order form select your country and enter your VAT/UID number to remove the VAT.
The correct price will be shown on the next page in the order form.

Examples

Intro example
xml: tour.xml
Use right-click to enable Fullscreen
CLICK TO VIEW EXAMPLE

Editor example
xml: tour.xml
Use right-click to enable Fullscreen
CLICK TO VIEW EXAMPLE

Layer example
xml: tour.xml
Use right-click to enable Fullscreen
CLICK TO VIEW EXAMPLE

Popup example
xml: tour.xml
Use right-click to enable Fullscreen
CLICK TO VIEW EXAMPLE

QuickFx example
Use right-click to enable Fullscreen
CLICK TO VIEW EXAMPLE

Blend example (Kudos to Tuur!)
xml: tour.xml
Use right-click to enable Fullscreen
CLICK TO VIEW EXAMPLE

Panorama images (licensed under CC BY-SA 3.0)
© The Ocean Agency / XL Catlin Seaview Survey / Aaron Spence and Christophe Bailhache