News • Examples • Documentation • Download • Buy • Forum • Contact

krpano ThreeJS Plugin threejs_krpanoplugin.js Version 1.22
Select Version:

  • A plugin for using the ThreeJS 3D-graphics library inside krpano.
  • With this plugin it is possible to use 3D Models (glb, gltf, obj+mtl files) as krpano Hotspots. These hotspots can interact and intersect with the krpano content and automatically support all krpano hotspot controls and events.
  • Additionally this plugin supports many helper functions for using 3D-content:
  • The plugin has the ThreeJS library and some of its addons modules directly integrated and embedded. This integration allows much faster loading and provides better browser compatibility.
  • Beside the functions provided by this plugin, it is also possible to access the ThreeJS library directly via Javascript and perform custom tasks with it.
  • For even more customization and to help understanding how the integration works, there is an Open Source version of the plugin available.
Documentation topics:

Syntax

Including and core settings: 
<plugin api="threejs" keep="true"
        url="%VIEWER%/plugins/threejs_krpanoplugin.js"
        useembeddedthreejs="true"
        integratedrendering="true"
        es6modules="false"
        adjustlightfalloff="true"
        cache="true"
        onready=""
        />
Settings: 
<threejs shadowmap="pcf"
         textureanisotropy="true"
         tonemapping="no"
         exposure="1.0"
         ambientlight="1.0"
         ambientcolor="0xFFFFFF"
         ambientcolortemperature="0"
         shadowfloor="false"
         shadowfloorlevel="160.0"
         shadowflooralpha="0.5"
         envmapurl=""
         raycastcheck="hotspots"
         />
Global Events: 
<events threejs_onready=""
        threejs_onbeforerender=""
        threejs_onafterrender=""
        threejs_modelschanged=""
        threejs_lightschanged=""
        />
After loading, the plugin object will be also available as global threejs variable (the api name).

Additionally there are these ThreeJS objects and functions available:

Integrated ThreeJS Addons / Modules

The krpano ThreeJS plugin has these modules / add-ons already integrated:

Load additional ThreeJS Addons / Modules

Example: 
<plugin url="%VIEWER%/plugins/threejs_krpanoplugin.js" ...>
    <module name="TransformControls" url="TransformControls.js" />
    <module name="..." url="..." />
    ...
</plugin>
  • This syntax can be used to load additional ES6 modules (ThreeJS add-ons).
  • All modules listed there will be loaded before the plugin starts to runs.

Plugin Settings

Variable nameTypeDefault value
useembeddedthreejs Boolean true
  • Use the ThreeJS library that is embedded inside the krpano ThreeJS plugin.
  • When disabling this setting, the ThreeJS library and its add-ons need to be included manually in the html file. And an import map must exist to map the ThreeJS library files to their typical import names.
  • Example for a minimum importmap in the html file when useembeddedthreejs is disabled: 
    <script type="importmap">
{ "imports": {
  "three": "three.module.min.js",
  "BufferGeometryUtils": "BufferGeometryUtils.js",
  "GLTFLoader": "GLTFLoader.js"
}}
</script>
    The file paths would need to be adjusted accordingly of course. And when there are other modules they would need to be included there as well.
  • This could be used to use a different or custom version of the ThreeJS library than the one that is embedded inside the krpano ThreeJS plugin.
Variable nameTypeDefault value
integratedrendering Boolean true
  • Use 'integrated' rendering - that means rendering the krpano content and the ThreeJS content into the same WebGL context - same framebuffer, same depthbuffer, same WebGL states.
  • With this the 3D-contents of krpano and ThreeJS can intersect each other.
  • When disabled, ThreeJS will use its own separate WebGL context and render on top of the krpano WebGL content.
Variable nameTypeDefault value
es6modules Boolean false
  • Enable or disable the usage of Javascript ES6 modules.
  • By default the krpano ThreeJS plugin uses its own module loader. This one works also without importmap-support by the browser and additionally also should be faster.
  • When disabled, the plugin getmodule() function would need to be used instead of the Javascript import() function to get a module object.
Variable nameTypeDefault value
adjustlightfalloff Boolean true
  • krpano and ThreeJS are using different units and generally this is no problem as the positions can be easily adjusted accordingly, but the physically-based lighting in ThreeJS has the light falloff decaying hard-coded in the Shader code and is based on the ThreeJS units.
  • Therefore without adjusting the lights would fall off much too quickly with distance.
  • When this setting is enabled (the default), the ThreeJS Shaders will be patched to use the krpano units for the light falloff.
  • This setting need to be set at startup and can't be changed at runtime.
Variable nameTypeDefault value
cache Boolean true
  • Enable or disable the ThreeJS Cache.
Variable nameTypeDefault value
shadowmap String "pcf"
  • The ThreeJS shadowMap settings.
  • Defines how shadows will be rendered, affects shadow quality and performance.
  • Available settings:
    • off - no shadows
    • basic (default) - hard shadows without anti-aliasing
    • pcf - Percentage-Closer Filtering (PCF) algorithm
    • pcfsoft - PCF with bilinear filtering
    • vsm - Variance Shadow Map (VSM) algorithm
Variable nameTypeDefault value
textureanisotropy Boolean true
  • Enable Anisotropic filtering for Textures.
  • This can improve the display quality of downscaled and mip-mapped images / textures.
  • But therefore increase the memory-need and reduce rendering-performance.
  • Note - this setting would need to be set or changed before loading textures! Any later setting change will only affect textures that will be loaded after the change.
Variable nameTypeDefault value
tonemapping
exposure 		String
Number		 "no"
1.0
Variable nameTypeDefault value
ambientlight
ambientcolor
ambientcolortemperature
 Number
Integer
Integer		 1.0
0xFFFFFF
0
  • The intensity and color of the Ambient light.
  • This light globally illuminates all objects in the scene equally.
  • The light color can be either set as RGB hexcolor value (0xRRGGBB) or using the color temperature in Kelvin (1000-40000, 0=off).
Variable nameTypeDefault value
shadowfloor
shadowfloorlevel
shadowflooralpha
 Boolean
Number
Number		 false
160.0
0.5
  • Enable a virtual / transparent floor plane that can receive shadows.
  • This can be used to give 3D Models, that are used on top of panoramic-background images, a floor where they can project their shadows.
  • shadowfloorlevel is distance from the camera-height to the floor in cm.
  • shadowflooralpha is blending between the shadows and the pano-background.
Variable nameTypeDefault value
envmapurl String null
  • The ThreeJS Scene environment texture.
  • Sets an environment map to illuminate the scene by a given image and to have a mirror image for reflecting materials.
  • Here either an url to a spherical pano image (360x180) could be set,
  • or the special value preview be used. In this case the current krpano pano <preview> image will be automatically used. Sphere and Cubestrip images are supported in this case.
Variable nameTypeDefault value
raycastcheck String "hotspots"
  • Define which 3D-objects should be used on raycasting / 3D-collision checking.
  • Possible settings:
    • hotspots (default) - use only krpano hotspots with hittest=true.
    • visible - use all 'visible' ThreeJS scene 3D geometry.
    • all - use all ThreeJS scene 3D geometry.
Variable nameTypeDefault value
onready
events.threejs_onready
 Event
Event
  • This event will be called when the krapno ThreeJS plugin is ready for usage.
Variable nameTypeDefault value
events.threejs_onbeforerender
events.threejs_onafterrender
 Event
Event
  • These events will be called before and after rendering the ThreeJS content.
Variable nameTypeDefault value
events.threejs_modelschanged
events.threejs_lightschanged
 Event
Event
  • These events will be called when 3D Models or Lights will be added or removed.
Function
getmodule(modulename)
  • A function to get the loaded Javascript ES6 modules.
  • When the es6modules setting is disabled (the default), then this function NEED to be used for get the module objects.
Function
p = krpano_to_threejs_position(p, h,v,d, x,y,z)
  • Convert a krpano 3D position to a ThreeJS 3D position.
  • Parameters:
    • p - a ThreeJS Vector Object (or any Object with x,y,z properties), where the result will be stored. Can be null, then a new object will be created.
    • h, v, d - spherical coordinates (ath, atv, depth), should be set to 0 when not used.
    • x, y, z - 3D coordinates, should be set to 0 when not used.
  • Return: the p Object (an object with x,y,z properties).
Function
p = threejs_to_krpano_position(...)
  • Convert a ThreeJS 3D position to a krpano 3D position.
  • Parameters:
    • Either an Object with x,y,z properties (e.g. a ThreeJS Vector object).
    • Or an Array with the x,y,z values.
    • Or x,y,z as individual parameters.
  • Return: a new Object with x,y,z properties.

3D Model Hotspots

  • By adding type="threejs" to a <hotspot> it is possible to load and use 3D Models.
  • The supported 3D Model formats are:
  • The hotspots use the same positioning system as normal krpano hotspots.
    • This means that the resulting position in 3D space is a combination of the spherical position given by ath/atv/depth and the translation given by tx/ty/tz.
    • For using only the 3D XYZ position, set depth to 0.0.
    • The unit for the 3D positions is: 1.0 ^= 1.0 cm.
The XML syntax with all supported settings and their default values: 
<hotspot name="spot1"
         type="threejs"
         ☞ 3D model
         url="3dmodel.glb"
         mtlurl=""
         convertmaterials=""
         ☞ spherical position
         ath="0.0"
         atv="0.0"
         depth="1000.0"
         ☞ 3D position
         tx="0.0"
         ty="0.0"
         tz="0.0"
         ☞ 3D rotation
         rx="0.0"
         ry="0.0"
         rz="0.0"
         rotationorder="yxz"
         ☞ scaling
         scale="1.0"
         scalex="1.0"
         scaley="1.0"
         scalez="1.0"
         ☞ settings
         visible="true"
         enabled="true"
         capture="true"
         capturewheel="false"
         cursor="pointer"
         hittest="false"
         ☞ shadows
         castshadow="true"
         receiveshadow="true"
         ☞ events
         onover=""
         onhover=""
         onout=""
         ondown=""
         onup=""
         onclick=""
         onwheel=""
         onloaded=""
         onloadprogress=""
         onloaderror=""
         />
Dynamic or read-only hotspot variables: Hotspot functions:
Variable name Type Default value
url String
Variable name Type Default value
mtlurl String
  • When using .obj and .mtl files, ThreeJS doesn't automatically take the .mtl file specified in the .obj file.
  • That means the path and filename of the .mtl file would need to be set manually.
  • The krpano ThreeJS plugin adds a little helper here - when mtlurl is not set, it automatically uses the same path and filename as the .obj file and tries loading that one. For many cases this automatic help should work, but if the filenames are different, it would be necessary to set the mtlurl filename manually.
Variable name Type Default value
convertmaterials String
  • A helper setting for automatically converting Materials.
  • Syntax: 
    convertmaterials="oldmaterial-to-newmaterial|..."
    • oldmaterial - the material type that should be converted, can be all to convert all material types.
    • newmaterial - the new material type.
    • It's possible to convert multiple material types by adding another conversion separated by a | character.
    • Available material types:
      • basic - most simple, no lights and shadows, best performance.
      • lambert - supports lights and shadows, but no specular highlights.
      • phong - similar to lambert, but with specular highlights.
      • standard - standard physically based material using metallic-roughness, more accurate and realistic, but more computationally expensive.
      • physical - more advanced physically-based rendering, but with a higher performance cost.
      • toon - a material implementing toon shading.
  • Examples: 
    convertmaterials="basic-to-lambert"
    • Some .gltf/.glb files were saved with only a basic material, which does not allow lighting and shadows.
    • Using this example will allow to use lighting and shadows on the 3D model. 
    convertmaterials="all-to-basic"
    • When using photometric 3D scans, lighting and shadows can be unnecessary or even unwanted.
    • This examples fixes this, while also improving the rendering performance.
Variable nameTypeDefault value
scale
scalex
scaley
scalez
 Number
Number
Number
Number		 1.0
1.0
1.0
1.0
  • Set the scale of the 3D Model.
  • Changing scale will change the other scalex/y/z variables to the same value.
Variable nameTypeDefault value
castshadow
receiveshadow
 Boolean
Boolean		 true
true
  • Should the 3D Model cast- and/or receive shadows?
  • Warning - using shadows can be very performance intensive!
Variable nameTypeDefault value
onloadprogress
onloaderror
 Event
Event
  • Loading events.
  • When the onloaderror event is not set, the default error reporting will be done on errors.
Variable nameTypeDefault value
threejsobject
 Object
Variable nameTypeDefault value
animations
 Array null
  • When loading a GLTF 3D Model that contains animations, these will be available in the animations Array.
  • This is a krpano-Array, where each Array-item has a name and an index.
  • The name will be name of the animation.
  • Each animation Array-item has these settings (mapped to the related ThreeJS settings):
    • enabled - a Boolean, true by default.
    • paused - a Boolean, false by default.
    • loop - a String, can be "repeat" (default), "pingpong" or "once".
    • blendmode - a String, can be "normal" (default) or "additive".
    • repetitions - a Number, Infinity by default.
    • time - a Number, 0 by default.
    • timescale - a Number, 1.0 by default.
    • weight - a Number, 1.0 by default.
    • duration - duration of this animation in seconds.
    Actions: Events:
    • onloop
    • onfinished
Variable nameTypeDefault value
activeanimation
 String null
  • Name of the current active animation.
Variable nameTypeDefault value
bytesloaded
bytestotal
 Number
Number		 0
0
  • The loading progress in bytes.
  • These values will be updated in the onloadprogress event.
Variable nameTypeDefault value
centerx
centery
centerz
 Number
Number
Number
  • The center point of the 3D Model.
  • Can be read or set to change.
  • Will be first available after the onloaded event.
  • When the 3D Model gets modified, then hotspot[name].updateboundingbox() need to be called to update these information.
Variable nameTypeDefault value
bboxx
bboxy
bboxz
 Number
Number
Number
  • The bounding-box (without hotspot position, rotation or scale) of the 3D Model.
  • Will be first available after the onloaded event.
  • When the 3D Model gets modified, then hotspot[name].updateboundingbox() need to be called to update these information.
Function
set_threejs_pose()
  • Instantly update the ThreeJS position, rotation, scale settings.
Function
get_threejs_pose()
  • Get the current ThreeJS position, rotation, scale settings and convert them to the related krpano hotspot settings (tx,ty,tz, rx,ry,rz, scalex,scaley,scalez).
Function
updateboundingbox()
  • Update the bounding-box and center information.
  • Should be called when the 3D Model gets manually modified.
Function
centermodel()
  • Center the 3D Model.

Light Hotspots

  • By adding type="threejslight" to a <hotspot> it is possible to use it as light source.
  • The supported Lightmodes are:
    • Hemisphere Light - mode="hemisphere"
      • An Ambient Light from two direction.
      • Like a sky and ground light (no shadows).
    • Directional Light - mode="directional"
      • An kind of infinitely far away light.
      • Light-rays from it are all parallel.
      • Could be used to simulate a sun-light.
      • Even 'infinitely' away, the shadows produced by this light can work only within a certain, defined range/area.
    • Sun Light - mode="sun"
      • A automatic special mode of Directional Light.
      • Here the light source position is defined by a spherical ath/atv position and the light target and so also the shadow-map is always automatically at the camera / view position.
    • Point Light - mode="point"
      • A light from a single point into all directions, with a certain range with a decreasing intenstiy.
      • Note - shadows from this light require the most processing power! That's because here a cubemap (six sides/images) needs to be rendered to have shadows into all directions.
    • Spot Light - mode="spot"
      • A light from a single point into a specific direction, in the shape of a cone.
  • Notes about Performance and Implementation
    • Lights and shadows can be very performance intensive, each light and shadow counts. For best performance try to use a few lights and shadows as possible!
    • Try to avoid dynamically adding and removing lights (this requires an internal recompilation of the WebGL shader). Instead toggle the hotspot visible setting.
    • The light-positioning, ranges and some settings and helpers are not directly mapped to their ThreeJS equivalents and use an own implementation for a better krpano integration.

Hemisphere Light Hotspot
ThreeJS Reference: HemisphereLight

<hotspot name="hemilight"
         type="threejslight"
         mode="hemisphere"
         ☞ spherical light position
         ath="0.0"
         atv="0.0"
         ☞ lighting
         intensity="1.0"
         color="0xFFFFFF"
         color2="0x000000"
         ☞ helper
         helper="false"
         ☞ events
         onloaded=""
         />
  • The Hemisphere Light is a direction based ambient light, it can shade 3D Models from two directions - e.g. to use colors from the sky and the ground.
  • The orientate the light, the spherical ath / atv position can be used.
  • Technically this light is the most simple one with the best performance. It doesn't produce shadows or specular highlights.

Directional Light Hotspot
ThreeJS Reference: DirectionalLight

<hotspot name="dirlight"
         type="threejslight"
         mode="directional"
         ☞ 3D position light source
         tx="0.0"
         ty="0.0"
         tz="0.0"
         ☞ 3D position light target
         targetx="0.0"
         targety="0.0"
         targetz="0.0"
         ☞ lighting
         color="0xFFFFFF"
         colortemperature="0"
         intensity="1.0"
         ☞ shadows
         castshadow="false"
         shadowmaprange="500"
         shadowmapnear="50"
         shadowmapfar="50000"
         shadowmapbias="0.001"
         shadowmapnormalbias="0.01"
         shadowmapres="512"
         ☞ helper
         helper="false"
         ☞ events
         onloaded=""
         />
  • The Directional Light that gets emitted in a specific direction.
  • This light will behave as though it is infinitely far away and the rays produced from it are all parallel.
  • The common use case for this is to simulate daylight. The sun is far enough away that its position can be considered to be infinite, and all light rays coming from it are parallel.
  • The light direction is calculated as pointing from the light's position to the target's position.

Sun Light Hotspot
ThreeJS Reference: DirectionalLight

<hotspot name="sunlight"
         type="threejslight"
         mode="sun"
         ☞ spherical light position
         ath="0.0"
         atv="0.0"
         ☞ shadowmap position
         atview="true"
         tx="0.0"
         ty="0.0"
         tz="0.0"
         ☞ lighting
         color="0xFFFFFF"
         colortemperature="0"
         intensity="1.0"
         ☞ shadows
         castshadow="false"
         shadowmaprange="500"
         shadowmapnear="50"
         shadowmapfar="50000"
         shadowmapbias="0.001"
         shadowmapnormalbias="0.01"
         shadowmapres="512"
         ☞ helper
         helper="false"
         shadowmaphelper="false"
         ☞ events
         onloaded=""
         />
  • The Sun Light is a special variant of a Directional Light.
  • Different to a normal directional light, which has a source and target position, the sun light is always automatically positioned around the current camera/view position.
  • The shadowmap therefore also is automatically always around the current camera/view position.

Point Light Hotspot
ThreeJS Reference: PointLight

<hotspot name="pointlight"
         type="threejslight"
         mode="point"
         ☞ 3D position light source
         tx="0.0"
         ty="0.0"
         tz="0.0"
         ☞ lighting
         color="0xFFFFFF"
         colortemperature="0"
         intensity="1.0"
         decay="2.0"
         distance="0.0"
         ☞ shadows
         castshadow="false"
         shadowmapnear="50"
         shadowmapfar="50000"
         shadowmapbias="0.001"
         shadowmapnormalbias="0.01"
         shadowmapres="256"
         ☞ helper
         helper="false"
         ☞ events
         onloaded=""
         />
  • The Point Light light gets emitted from the tx, ty, tz position and shines in all directions.
  • Note - shadows from this light require the most processing power! That's because here a cubemap (six sides/images) needs to be rendered to have shadows into all directions.

Spot Light Hotspot
ThreeJS Reference: SpotLight

<hotspot name="spotlight"
         type="threejslight"
         mode="spot"
         ☞ 3D position light source
         tx="0.0"
         ty="0.0"
         tz="0.0"
         ☞ 3D position light target
         targetx="0.0"
         targety="0.0"
         targetz="0.0"
         ☞ lighting
         color="0xFFFFFF"
         colortemperature="0"
         intensity="1.0"
         decay="2.0"
         angle="60.0"
         penumbra="0.5"
         distance="0.0"
         mapurl=""
         ☞ shadows
         castshadow="false"
         shadowmapnear="50"
         shadowmapfar="50000"
         shadowmapbias="0.001"
         shadowmapnormalbias="0.01"
         shadowmapres="512"
         ☞ helper
         helper="false"
         ☞ events
         onloaded=""
         />
Variable nameTypeDefault value
tx, ty, tz
Number0.0
Variable nameTypeDefault value
targetx, targety, targetz
Number0.0
Variable nameTypeDefault value
atviewBooleantrue
  • Only for Sun lights: the sun itself is basically infinity far away and has only a direction (ath/atv) and no position, but the shadowmap (an area where shadows can be rendered) can only at/around a certain position.
  • If true (default): the center of the shadowmap will be always at the view position.
  • If false: the center of the shadowmap will be at the tx, ty, tz position.
Variable nameTypeDefault value
color int0xFFFFFF
  • The color of the light.
Variable nameTypeDefault value
colortemperature Number0
  • An alternative method for setting the color of the light.
  • Define the color by setting the color temperature in Kelvin (1000-40000).
  • When this will be set to a non-0 value, the color setting will be automatically set to a corresponding value.
Variable nameTypeDefault value
color2 int0x000000
Variable nameTypeDefault value
intensityNumber1.0
  • The intensity of the light.
Variable nameTypeDefault value
decayNumber2.0
  • The amount the light dims along the distance of the light.
  • When set to 0.0, the light wil not decay.
  • When set to 1.0, the light will decay linearly with the distance.
  • When set to 2.0 (the default), the light will decay 'physically correct' according to the Inverse Square Law.
  • Only for Point and Spot lights.
Variable nameTypeDefault value
distanceNumber0.0
  • When distance is set to 0.0, the decay setting will be used to calculate the light intensity falloff.
  • When distance is set to a value greater than 0.0, then the light intensity will falloff according to Inverse Square Law until near the distance cutoff, where it will then attenuate quickly and smoothly to 0. Inherently, cutoffs are not physically correct.
  • Only for Point and Spot lights.
Variable nameTypeDefault value
angleNumber60.0
  • The opening angle of the spotlight cone in degrees.
  • Only for Spot lights.
Variable nameTypeDefault value
penumbraNumber0.5
  • Percent of the spotlight cone that is attenuated due to penumbra (0.0 to 1.0).
  • Only for Spot lights.
Variable nameTypeDefault value
mapurlStringnull
  • An image used to modulate the color of the light.
  • The Spot Light color is mixed with the RGB values of the image, with a ratio corresponding to its alpha value.
  • Note - castshadow need to be enabled for this effect.
  • Only for Spot lights.
Variable nameTypeDefault value
castshadowBooleanfalse
  • Should the light cast shadows?
Variable nameTypeDefault value
shadowmaprangeNumber500
  • The range of the from the light-ray into all directions around, that should be included into the shadowmap rendering.
  • The unit is cm.
  • Only for Directional and Sun lights.
Variable nameTypeDefault value
shadowmapnear
shadowmapfar
 Number
Number		50
50000
  • These settings control the distance range when rendering the shadowmap.
  • The units are cm.
Variable nameTypeDefault value
shadowmapbias
shadowmapnormalbias
 Number
Number		0.001
0.01
  • The Shadowmaps bias settings are for fine-tuning the shadow rendering.
  • It controls kind of how an elements affects its self-shadowing.
Variable nameTypeDefault value
shadowmapresint256 or 512
  • The resolution of the internal shadowmap.
  • This affects the quality of the shadows, but also the memory need and the rendering performance!
  • The default is 256 for point lights (because point-lights use a cubemap where six maps with that size are used) and 512 for all other lights (there only one map).
Variable nameTypeDefault value
shadowmaphelperBooleanfalse
  • When enabled a helper object to visualize the range of the shadowmap will be displayed (Sun Light only).
Variable nameTypeDefault value
helperBooleanfalse
  • When enabled a helper object for the Light will be displayed.



Examples

Dancing Cat
Environment Maps
Third Person Controls
Tuscany
Tesla
Open Source



krpano ThreeJS Plugin - Open Source Version

The Open Source version is a simplified and stripped down version of the krpano ThreeJS Plugin. It shows how the renderer and hittest integration works and how to use 3D Models as hotspots.

Plugin Source code:
threejs_krpanoplugin_opensource.js

Differences to the normal plugin:
  • No embedded ThreeJS library
  • No module loader
  • No krpano-compatible OBJ/MTL loader
  • No Light Hotspots
  • No Shadow Floor
  • No Environment Mapping
  • No Animations
  • No Material conversions
  • No pano/scene management
  • Fewer settings and APIs

Example:
ThreeJS: Open Source Plugin