News Examples Documentation Download Buy Forum Contact

Documentation

Plugins

XML Extensions

Tools


Third Party Software
for krpano

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 3 change log


zFilter 3 is a paid update. The upgrade discount for existing users is 40% (29€)
for users which purchased zFilter after 2022.04.15 it is free of charge !

zFilter 3.1.2 / 2023-04-24 - indexofrefraction

Syntax / XML Usage Example

<plugin name="zfilter"
	url="zfilter.js"
	preload="true"
	keep="true"
	regkey=""
	enabled="true"
	phase="2"
	order=""
	webvr="2"
	addzfilter="false"
	csslegacy="false"
	gamma="2.2"
	brightness="0"
	contrast="0"
	exposure="0"
	hue="0"
	saturate="0"
	vibrance="0"
	sepia="0"
	invert="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" regkey="abcdef" />
    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" regkey="abcdef"
    	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
regkeyString
  • 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)
  • regkey is used to register the plugin with your personal registration key
Attribute nameTypeDefault valueMinMax
enabledBooleantrue
phaseNumber212
orderString
iorder (read only)Stringadjust|swirl|pixelate|ripple|sobel|split|fblur|
blur|blendcolor|vignettecolor|mixcolor
webvrNumber203
csslegacyBooleanfalse
addzfilterBooleanfalse
  • enabled globally enables/disables all postprocessing effects
  • phase:
    • phase="1" after rendering the pano image, but BEFORE rendering the hotspots
      phase="2" after rendering the pano image and AFTER rendering the hotspots
    • 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:
    • order is used to set the global plugin order if several postprocessing plugins are used
      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, saturate, 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
  • csslegacy="true" enables legacy value ranges for layer and hotspot attributes
    the value ranges were changed with zFilter 3 to be compatible with krpano 1.21+
    important: csslegacy="true" works for krpano below 1.21, only!
  • addzfilter="true" makes it unnecessary to call addzfilter() for layers and hotspots
    the default is false because filters are normally used for specific elements, only
    important: addzfilter="true" requires kprano 1.21+ to work!

Plugin Attributes (Postprocessing Filters)

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
saturateNumber0.0-1.01.0
vibranceNumber0.0-1.01.0
sepiaNumber0.00.01.0
invertNumber0.00.01.0
  • Basic image filters
  • Examples:
    • set(plugin[zfilter].brightness, 0.25);
    • tween(plugin[zfilter].saturate, -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, saturate, 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);

Layer and Hotspot Attributes

zFilter allows to use CSS filter attributes on layers and hotspots,
with the following limitations / conditions:
  • hotspots and layers must get manually initialized by calling addzfilter()
    and released using removezfilter() before removing the layer/hotspot
  • krpano 1.21 and above:
    addzfilter() is handled automatically if addzfilter="true"
    removezfilter() is handled automatically in any case
  • Supported attributes are:
    brightness, contrast, saturate, hue, sepia, invert, blur, dropshadow and
    bgbrightness, bgcontrast, bgsaturate, bghue, bgsepia, bginvert, bgblur
  • Hotspots need to be rendered with renderer=css3d
  • Browser support:
    The normal filters should work on most current main browsers,
    but support may vary, specially if multiple filters are active.
  • Technical note: krpano 1.21 has a limited support for CSS filters
    (background, layers, type=container or text)
    zFilter provides full support for CSS filters
    (foreground & background, hotspots & layers, type=container, text and image)

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

Layer and Hotspot Attributes (CSS Filters)

Attribute nameTypeDefault valueMinMax
brightness / bgbrightnessNumber1.00.0
contrast / bgcontrastNumber1.00.0
saturate / bgsaturateNumber1.00.0
hue / bghueNumber0.0
sepia / bgsepiaNumber0.00.01.0
invert / bginvertNumber0.00.01.0
blur / bgblurNumber0.00.0
dropshadowString    see krpano layer.bgshadow

new value ranges with krpano 1.21+ or old krpano versions with csslegacy="false"
note: these ranges correspond to the regular CSS filter value ranges

Attribute nameTypeDefault valueMinMax
brightness / bgbrightnessNumber0.0-1.01.0
contrast / bgcontrastNumber0.0-1.01.0
saturate / bgsaturateNumber0.0-1.01.0
hue / bghueNumber0.0-1.01.0
sepia / bgsepiaNumber0.00.01.0
invert / bginvertNumber0.00.01.0
blur / bgblurNumber0.00.050.0
dropshadowString    see krpano layer.bgshadow

Old / legacy value ranges for old krpano versions with csslegacy="true"
note: these ranges correspond to the panorama postprocessing filters provided by zFilter

note: csslegacy="true" is supported for old krpano versions below 1.21, only!
         on kprano 1.21 it is mandatory to use the new value ranges!


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]"
haszfilter(variable, layer or hotspot)
The haszfilter action checks if zFilter is added the given layer or hotspot.

Parameters:
  • variable
    The destination variable for the return value (true or false)
  • 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!

Compatibility / Requirements / Limitations
  • krpano 1.20 or newer, html5 + webgl only! (Flash is not supported)
  • Postprocessing filters work on the panorama and on hotspots with renderer=webgl
  • Layer and hotpot filters support a limited set of effects and require renderer=css3d
  • Support for layer and hotpot filters are depending on browser support
  • Support for true webVR is experimental
  • 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.
  • Third parties are not allowed not use your licensed plugin to create new projects, including modified versions of your projects.
  • You are not allowed to rent, lease, lend or sublicense your plugin.
  • Offering your licensed plugin to third parties on a hosting platform is not allowed without a separate hosting license. In such cases (e.g. integration in content management services) please contact: support@refraction.ch
Withdrawal period
  • For any digital content purchased online, you agree upon checkout that the withdrawal period will expire 14 days after you purchase such digital content or when you start downloading the content for the first time, whichever is sooner.

Examples

Intro example
xml: tour.xml
use right-click to enable fullscreen
CLICK TO VIEW EXAMPLE

Postprocessing example
xml: tour.xml
use right-click to enable fullscreen
open console and press Q to log all zFilter values

CLICK TO VIEW EXAMPLE

CSS filter example (Layers and Hotspots)
xml: tour.xml
use right-click to enable fullscreen
open console and press Q to log all zFilter values

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