News Examples Documentation Download Buy Forum Contact

Documentation

Plugins

Tools


Third Party Software
for krpano

zFlare Plugin zflare.js HTML5 only
by indexofrefraction - (send forum message)

Description

zFlare is a lensflare plugin to enhance the visual effect of your panorama images.

  • zFlare is a pure javascript plugin for a minimal performance impact !
  • supports mobile webvr and true webvr !
  • supports 3D tours: distant and positioned lights, fading out in dollhouse mode!
  • supports multiple flares at the same time !
  • is simple to use ! two lines to add the plugin and a flare.
  • you can design your own lensflares !
  • can get extended by the zFilter plugin for extra filter effects !

Just check out the examples below!

zFlare 2.5.8 / 2022-11-29 - indexofrefraction

Concept

zFlare.js adds three custom xml elements to krpano:

<flare name="myname" preset="mypreset" ... />
  • a flare is a composition / preset of flarespot elements
  • it is possible to have multiple flares active
    in this case each flare needs an unique name
  • the flare attributes describe the preset / composition to use
    and the position of the light source

<flarespot name="mypreset|myname" ... />
<flarefilter name="mypreset|filtername" ... />
  • flarespots and flarefilters are elements of your own flare compositions / presets
  • flarespots are an image hospots / visible flares
    flarefilters are zFilter plugin filter effects, ie. exposure when looking into the light source
    note: flarefilters need an active zFilter plugin
  • the flarespot attributes describe the position, scale, rotate and alpha behaviour
    the flarefilter alpha attribute describes the filter strength / value behaviour

Usage Example

  • Add zflare.js and its assets folder to your project
  • In your main xml (tour.xml) add
    <plugin name="zflare" url="zflare.js"
    	preload="true" keep="true" />
  • Finally add a flare to a scene simply like
    <scene name="myscene" ... >
    	<flare name="sun" preset="summer01" ath="35" atv="-15" />
    </scene>

To define your own flare composition / preset you would

  • Define arrays using flarespots and flarefilters using the same preset name
    <flarespot name="sunbeam|sun"
    	   asset="flares/flare006_512.jpg"
    	   pos="0.0" scale="0.5" alpha="0.5" />
    <flarespot name="sunbeam|hexa1"
    	   asset="polys/hexa007_128.jpg"
    	   pos="0.2" scale="0.6" alpha="0.4" />
    <flarespot name="sunbeam|hexa2"
    	   asset="polys/hexa007_128.jpg"
    	   pos="0.5" scale="0.8" alpha="0.6" />
    <flarespot name="sunbeam|flare3"
    	   asset="rings/ring004_128.jpg"
    	   pos="0.8" scale="1" alpha="0.75" />
    <flarefilter name="sunbeam|exposure"
    	   alpha="0.1" alphamap="0|0.2|1|0" reset="0" />
    
  • And access it by its preset name in any scene
    <scene name="myscene" ... >
    	<flare name="sun" preset="sunbeam" ath="35" atv="-15" />
    </scene>

Plugin Attributes

<plugin name="zflare"
	url="zflare.js"
	preload="true"
	keep="true"
	alpha="1.0"
	scale="1.0"
	assets="zflares"
	mark="false"
	forcegrid="false"
	zfiltername="zfilter"
	skipfilter=""
	edgewidth="0.1"
	offsetfade="500"
	webvr="3"
	webvrfov="50"
	fovbase="60"
	mode3d="1"
	rafloop="true"
	imageready="onblendcomplete"
        />
Attribute nameTypeValue
ready (read only)Booleantrue | false
version (read only)Stringthe plugin version
urlStringzflare.js
preloadBooleantrue
keepBooleantrue
  • ready is true if the plugin is loaded and ready
  • version holds the plugins version number
  • url must point to the plugin (documentation)
  • preload should be set to true (documentation)
  • keep should be true for most cases (documentation)
Attribute nameTypeDefault valueMinMax
alphaNumber1.00.01.0
scaleNumber1.00.010.0
  • alpha and scale are global multipliers affecting all flares
Attribute nameTypeDefault value
assetsStringzflares
  • this is the root path if flarespot images are defined by the asset property.
Attribute nameTypeDefault value
markBooleanfalse
  • mark globally adds a cross mark on each flarespot
Attribute nameTypeDefault value
forcegridBooleanfalse
  • forcegrid forces a dark grid as scene background
    note: this is a private functionality only working in a specific private setup
Attribute nameTypeDefault value
zfilternameStringzfilter
skipfilterString
  • zfiltername defines the name the zFilter plugin was loaded with.
    only needs to be defined if zFilter was loaded with a different name than "zfilter".
  • skipfilter is a global filter ignore list for zFilter attributes
    allowing to ignore specific or all filters defined in flarespots.
  • skipfilter can be used to prevent filter changes by zFlare
    if specific filters are already used otherwise in the project.
  • Examples:
    • skipfilter="blur|saturation"
    • skipfilter="all"
Attribute nameTypeDefault value
webvrNumber303
  • enable zFlare in webvr modes
    0 = no webvr, 1 = fake webvr, 2 = mobile webvr, 3 = true webvr
Attribute nameTypeDefault valueMinMax
edgewidthNumber0.10.00.5
offsetfadeNumber5000.0
  • edgewidth defines the border width where the flare begins to edgewidth out
    (with 0.1 the fading happens within a border zone of 10% of the stage width/height) note: the flare attribute overrides the plugin attribute!
  • offsetfade defines the view offset distance at which the flare fades out
    (this is visible when view.ox / oy / oz is used for a dollhouse effect)
    note: the flare attribute overrides the plugin attribute!
  • distfade defines the distance at which a 3D positioned flare fades out
    distfade="5000" fades the flare out at a distance of 0 to 5000
    distfade="2500|5000" fades the flare out at a distance of 2500 to 5000
    note: the flare attribute overrides the plugin attribute!
Attribute nameTypeDefault valueMinMax
fovbaseNumber601179
webvrfovNumber501179
mode3dInteger102
rafloopBooleantrue
imagereadyStringonxmlcomplete
  • fovbase defines the vertical fov as a scale base for each flarespot
    note: this is an internal setting and should not be changed.
  • webvrfov defines the vertical fov for real webvr
    note: this is an internal setting and should not be changed.
  • mode3d enables/disables a 3d effect in real webvr.
    the effect is only visible on webvr devices (gear vr, vive, oculus rift and go, etc)
    mode3d=0 disables the effect
    mode3d=1 enables the effect for true webvr (default)
    mode3d=2 enables the 3d effect all modes
    note: this is an internal setting and should not be changed.
  • with rafloop=true (default) zFlare uses a request animation loop,
    which allows to tween the plugin alpha or flare alpha, ath and atv attributes.
    with rafloop=false the onviewchanged event is used and tweens are not supported
    note: this is an internal setting and should not be changed.
  • imageready defines when the flares are shown and is either
    onxmlcomplete, onloadcomplete or onblendcomplete
    note: onxmlcomplete (default) is a safe setting but if your project
    loads panos with blending onblendcomplete would be the best choice.

flare Attributes

<flare name="myname"
       keep="false"
       preset="summer01"
       ath="0" atv="0" depth="1000"
       tx="0" ty="0" tz="0"
       torigin="world"
       alpha="1.0"
       spotalpha="1.0"
       filteralpha="1.0"
       scale="1.0"
       mark="false"
       skipfilter=""
       edgewidth=""
       offsetfade=""
       distfade=""
       />
Attribute nameTypeValue
nameStringmyzflare
keepBooleanfalse
  • name of the flare
    note: if a scene holds multiple flares, unique name must be used!
  • flares without keep="true" get unload on scene change.
    if a flare is defined globally, outside of all scenes keep is normally true.
    in this case it would stay active for the complete tour, independent of scene changes.
    if a flare is defined in a scene, keep is false for most cases.
    in this case the flare would be active for this scene only.
Attribute nameTypeDefault value
presetString
  • the preset used for the flare
    (a flare preset is an array of flarespot elements)
  • preinstalled flare presets:
    • preset="summer01"
  • custom flare presets can be defined using flarespot elements
Attribute nameTypeDefault valueMinMax
athNumber0.00.0360.0
atvNumber0.0-90.090.0
depthNumber1000.0
txNumber0.0
tyNumber0.0
tzNumber0.0
toriginStringworld
  • ath / atv / depth are spherical coordinates to define the flares position
  • tx / ty / tz are 3D coordinates to define the flares position
  • torigin is the translation origin - to what point the tx/ty/tz translation is relative to.
    it is either world, image or view (documentation)
  • note: the 3D coordinates are added to the spherical coordinates!
    so when you position flares in 3D using tx/ty/tz, best set depth=0.
  • note: for regular tours with matching view and world origin it doesn't matter,
    but for tours with 3D movement, distant lights (eg. sun) should have torigin=view.
Attribute nameTypeDefault valueMinMax
alphaNumber1.00.01.0
spotalphaNumber1.00.01.0
filteralphaNumber1.00.01.0
scaleNumber1.00.010.0
  • alpha and scale multipliers
    note: the flare scale/alpha attributes are multiplied with plugin scale/alpha attributes
Attribute nameTypeDefault value
markBooleanfalse
  • mark adds a cross mark on each individual flarespot
Attribute nameTypeDefault value
skipfilterString
  • skipfilter is a filter ignore list for zFilter attributes
    allowing to ignore specific or all filters defined in individual flarespots.
  • skipfilter can be used to prevent filter changes by zFlare
    if specific filters are already used otherwise in the project.
  • Examples:
    • skipfilter="blur|saturation"
    • skipfilter="all"
Attribute nameTypeDefault valueMinMax
edgewidthNumber0.00.5
offsetfadeNumber0.0
distfadeString
  • edgewidth defines the border width where the flare begins to fade out
    (with 0.1 the fading happens within a border zone of 10% of the stage width/height)
    note: the flare attribute overrides the plugin attribute!
  • offsetfade defines the view offset distance at which the flare fades out
    (this is visible when view.ox / oy / oz is used for a dollhouse effect)
    note: the flare attribute overrides the plugin attribute!
  • distfade defines the distance at which a 3D positioned flare fades out
    distfade="5000" fades the flare out at a distance of 0 to 5000
    distfade="2500|5000" fades the flare out at a distance of 2500 to 5000
    note: the flare attribute overrides the plugin attribute!

flarespot Attributes

Prerequisites:
  • a flarespot is an image hotspot as part of a flare preset
  • flarespots and flarefilters are read onxmlcomplete, dynamic changes are not supported!
    ie. you can set or change attributes by xml, but you can't tween them in an action.
  • flarespots and flarefilters are normally defined globally, outside of all scenes!
    like this they are accessible from all scenes.
  • flarespots and flarefilter do not use memory if there is no active flare using them.

<flarespot name="mypreset|myname"
	   blendmode="add"
	   url=""
	   asset=""
	   pos="0" posmap="" posclamp=""
	   scale="0" scalemap="" scaleclamp=""
	   alpha="0" alphamap="" alphaclamp="0|1" alpha90="0"
	   rot="0"  rlock="false" rcomp="false"
	   xoff="0" yoff="0"
	   edgefade="-1.0"
	   />
Attribute nameTypeValue
nameStringmypreset|myname
  • the flarespot name consists of two parts separated by by a | character.
    the first part defines the preset the flarespot belongs to
    the second part is a name/identifier for the flarespot.
Attribute nameTypeDefault value
blendmodeStringadd
urlString
assetString
  • available blendmodes are "add" (default) or "normal"
    (detailed descripion is available here)
  • either url or asset can be used to set path to the flarespot image
    asset will use a root path defined in plugin[zflare].assets
  • flare image notes:
    depending on the blendmode a flarespot image is either
    a png with transparency (blendmode normal) or
    a jpg with a black background (blendmode add)
    best use a resolution close to the target size
    and avoid extreme up/down scaling.
Attribute nameTypeDefault valueMinMax
posNumber0.0-10.010.0
posmapString
posclampString
  • pos is the position on the lensbeam
    note: in most cases a value between 0 and 1
  • posmap allows to alter (map) the position depending on the viewing angle
    posclamp allows to clamp the position range in defined boundaries
    see flarespot mapping and clamping.
Attribute nameTypeDefault valueMinMax
scaleNumber0.0-10.010.0
scalemapString
scaleclampString
  • scale allows to alter the flarespot size
    note: it is better to avoid extreme up/down scaling and
    to use image resolutions close to the target size instead
  • scalemap allows to alter (map) the scale depending on the viewing angle
    scaleclamp allows to clamp the scale range in defined boundaries
    see flarespot mapping and clamping.
Attribute nameTypeDefault valueMinMax
alphaNumber0.00.01.0
alpha90Numberalpha0.01.0
alphamapString
alphaclampString0|1
  • alpha defines the flarespot opacity / visibility
  • if alpha90 is unset, it uses the same value as alpha
    otherwise alpha90 defines the flares opacity / visibility for a horizontal beam and alpha defines the flarespot opacity / visibility for a vertical beam
  • alphamap allows to alter (map) the alpha depending on the viewing angle
    alphaclamp allows to clamp the alpha range in defined boundaries
    see flarespot mapping and clamping.
Attribute nameTypeDefault valueMinMax
rotNumber0.0-180.0180.0
rlockBooleanfalse
rcompBooleanfalse
  • rot is a rotation offset for the flarespot
  • rlock="true" locks the flarespot rotation to the given value
    (prevents the default rotation depending on the view angle)
  • rcomp="true" enables an enhanced rotation handling and
    should be enabled for directional flarespot images, only.
Attribute nameTypeDefault valueMinMax
xoffNumber0.0-180.0180.0
yoffNumber0.0-180.0180.0
  • Offset / parallel-shift from the flarespot center.
    (detailed descripion is available here)
Attribute nameTypeDefault valueMinMax
edgefadeNumber-1.0
  • defines the fading behaviour when the flare origin gets close to the stage border
    the default of -1.0 fades the flare out,
    a value of -0.5 would not completely fade out the flarespot,
    a positive value reverses the behaviour resulting in an invisible flarespot
    fading in when the flare origin gets close to the stage border
    a value of 0 disables th edge fading behaviour.

flarefilter Attributes

Prerequisites:
  • flarefilters are zFilter plugin filter effects as part of flare presets
    ie. a raising exposure when looking into the light source
    note: flarefilters need an active zFilter plugin
  • flarespots and flarefilters are read onxmlcomplete, dynamic changes are not supported!
    ie. you can set or change attributes by xml, but you can't tween them in an action.
  • flarespots and flarefilters are normally defined globally, outside of all scenes!
    like this they are accessible from all scenes.
  • flarespots and flarefilter do not use memory if there is no active flare using them.

<flarefilter name="mypreset|filtername"
	     reset=""
	     blendmode="add"
	     color="0x000000"
	     alpha="0" alphamap="" alphaclamp="0|1"
	     />
Attribute nameTypeValue
nameStringmypreset|filtername
  • the flarefilter name consists of two parts separated by a | character.
    the first part defines the preset the flarefilter belongs to
    the second part is a name/identifier for the zFilter attribute.
Attribute nameTypeDefault valueMinMax
alphaNumber0.00.01.0
alpha90Numberalpha0.01.0
alphamapString
alphaclampString0|1
  • alpha defines the filter strengh or value
  • if alpha90 is unset, it uses the same value as alpha
    otherwise alpha90 defines the flares opacity / visibility for a horizontal beam and alpha defines the flarefilter opacity / visibility for a vertical beam
  • alphamap allows to alter (map) the alpha depending on the viewing angle
    alphaclamp allows to clamp the alpha range in defined boundaries
    see flarefilter mapping and clamping.
    note:
    zFilter attributes have misc value ranges and alphaclamp defaults to "0|1",
    therefore sometimes alphaclamp must be adjusted to the zFilter attribute
  • Examples:
    • name="mypreset|gamma" alphaclamp="-1|1"
    • filter="mypreset|blur" alphaclamp="0|50"
Attribute nameTypeDefault valueMinMax
resetString / Number0
colorNumber0x0000000x0000000xffffff
blendmodeStringadd
  • reset is the reset / default value for the filter strength
    note:
    zFilter attributes have different default values and alpha defaults to 0,
    therefore the reset attribute depends on the zFilter attribute
  • color is the color value needed for some zFilter plugin attributes
  • blendmode is the zFilter plugin blendmode
    note: this is a special case where the alpha attribute is not used
    note: this is not the image mode / hotspot blendmode
  • Examples:
    • name="mypreset|gamma" reset="2.2"
    • name="mypreset|blur" reset="0"
    • name="mypreset|mixcolor" color="0xffffff" reset="0"
    • name="mypreset|blendcolor" color="0xffffff" reset="0"
    • name="mypreset|blendmode" blendmode="lineardodge" reset="add"

flarespot and flarefilter
Attribute Mapping and Clamping

Attribute Mapping
The posmap, scalemap and alphamap attributes allow to alter (map)
the attribute values depending on the viewing angle.
ie. a flarespot can scale up or get more visible when looking directly into the sun.

Mapping attributes take 4 numerical values in a format like "a|b|c|d"

a and b are two values of the internal nl factor which is 0 when looking directly
into the flare origin and scale up to ~2.5 when the flare origin gets out of view.
c and d are the new remapped values for a and b.

Examples:
  • scalemap="0|0.3|2|0" results in a scale of 2 when looking directly into the flare origin
    and quite fast a value of 0 (invisible) when looking away from the flare.
    such a setup allows flares only shown when looking at the flare origin.
  • alphamap="0.5|1|0|1" results in an alpha of 0 when looking directly into the flare origin
    and a value of 1 when looking away from the flare origin.
    such a setup allows flares only shown when looking away from the flare origin.
Attribute Clamping
The posclamp, scaleclamp and alphaclamp attributes allow to clamp values
in the given boundaries. clamping can be used in conjunction with mapping
to keep the attribute value in a desired range.

Clamping attributes take 2 numerical values in a format like "min|max"

Examples:
  • alphaclamp="0|1" clamps alpha to a minimum of 0 and a maximum of 1.
  • scaleclamp="0.5|1" clamps scale to a minimum of 0.5 and a maximum of 1.

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)
    support for all features requires krpano 1.20.11 or higher
  • zFlare is tied to your krpano license (needs a registered version of krpano)
  • zFilter is a separate plugin (not included in this purchase)
License
  • All copyrights to zFlare 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


Example <flare> using the built in "summer01" preset
xml: tour-simple.xml
xml: tour-simple-zfilter.xml (combined with zFilter)

Example <flare> with <flarespot> and <flarefilter> definitions
xml: tour-complex.xml
xml: tour-complex-zfilter.xml (combined with zFilter)


zFlare Example
use right-click to enable fullscreen
CLICK TO VIEW EXAMPLE


WebVR / vtourskin Example
use right-click to enable fullscreen
CLICK TO VIEW EXAMPLE


3D Example
Click on the floor to move and look around to explore the distant and positioned lights.
also notice the fading on dollhouse enter/ exit.
use right-click to enable fullscreen
CLICK TO VIEW EXAMPLE


zFlare with / without zFilter Comparison
To see the extra effect of zFilter, zoom out and look directly into the sun.
use right-click to enable fullscreen
CLICK TO VIEW EXAMPLE
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