iPanorama 360° - jQuery Virtual Tour

by AVIRTUM

Thank you for purchasing this plugin. If you have any questions that are beyond the scope of this help file, please feel free to email on avirtum@gmail.com. Thanks so much!

About the plugin

iPanorama 360° is a lightweight and rich-feature panorama viewer for the web. This plugin is built with modern libraries jQuery and Three.js to be used for part of backend solutions. Additionally, it has an awesome feature called virtual tour which allowed the user to navigate from one scene to another. Also, it supports hotspots for providing information about any part of the scene or for creating interactive tours. It uses their own tooltip system, you can enrich it with text, images, video and other online media. Use this plugin to create interactive tours, maps and presentations. The plugin can be deployed easily. It runs on all modern browsers and mobile devices like iOS, Android and Windows.

I'm using the Three.js library. It's a free and fast 3D engine for making WebGL worlds.

Files and Structure

The plugin's folder contains:

  • demo - folder with an example of use
    • assets - folder with additional files
    • index.html - html file with demo
  • src - folder with a javascript source file (full and min version)
    • less - LESS files
    • ipanorama.css - core and default theme for the panorama
    • ipanorama.theme.default.css - default theme for the panorama
    • ipanorama.theme.modern.css - modern theme for the panorama
    • ipanorama.theme.dark.css - dark theme for the panorama
    • jquery.ipanorama.js - main source file
    • jquery.ipanorama.min.js - compressed and obfuscated main source file

Installation

1. Load jQuery.js, Three.js and jquery.ipanorama.min.js in the head section for your html document

<script type="text/javascript" src="js/jquery.js"></script>
<script type="text/javascript" src="js/three.js"></script>
<script type="text/javascript" src="js/jquery.ipanorama.min.js"></script>

2. Load the CSS theme file that styles the plugin

<script type="text/css" src="css/ipanorama.css" rel="stylesheet" media="all"></script>
<script type="text/css" src="css/ipanorama.theme.default.css" rel="stylesheet" media="all"></script>

3. Create a DIV tag where to set the panorama:

<div id="panorama"></div>

4. Finally just call the plugin on the div ID or class

4.1 Simple example

$("#panorama").ipanorama();

4.2 Advanced example with two different type of scenes and virtual tour support

$("#panorama").ipanorama({
	sceneId: "main",
	scenes: {
		main: {
			type: "cube",
			image: {
				left: "assets/images/left.png",
				right: "assets/images/right.png",
				top: "assets/images/top.png",
				bottom: "assets/images/bottom.png",
				front: "assets/images/front.png",
				back: "assets/images/back.png",
			},
			hotSpots: [
				{
					pitch: 0,
					yaw: 0,
					sceneId: "second",
				},
			],
		},
		second: {
			type: "sphere",
			image: "assets/images/sphere.jpg",
			hotSpots: [
				{
					pitch: 0,
					yaw: 0,
					sceneId: "main",
				}
			],
		}
	},
});

How To Use Builder

iPanorama 360 Virtual Tour Builder is an editing web tool that allows you to quickly and easily make a config for the plugin. What you see is what you get! This builder is intuitive and a pleasure to use. It allows you to save custom configs and use it in the future. Please read below for information on how to use our builder.


Installation

Uploading the builder via FTP to your web server

  1. Download the zipped plugin pack to your local computer from CodeCanyon and extract the ZIP file contents to a folder on your local computer
  2. In the extracted folder you will find the folder 'builder'
  3. Use a FTP client to access your host web server
  4. Upload the builder folder 'builder' to your host web server (root directory or subdirectory)
  5. Type in the browser http://yousite.com/subdirectory/builder (depends on the last step)
  6. Check the working of the builder

HotSpot Setup

This is the description of a manual setup, but you can use the online builder for this task too.

1. Call the plugin on the div ID or class with the parameter "hotSpotSetup: true":

$("#panorama").ipanorama({hotSpotSetup: true});

2. Press a control key (marked "Ctrl") and click the left mouse button where you want.

3. Look into the browser's console. You should see an information line like below.

yaw: 27.4483248729099, pitch: 0.36013708227241986, camera yaw: 0, camera pitch: 0, camera zoom: 75

Setup a Virtual Tour

This is the description of a manual setup, but you can use the online builder for this task too.

  1. Prepare panoramic photos for your scenes. For example, I make two scenes with photos below.

  2. Load jQuery.js, Three.js and jquery.ipanorama.min.js in the head section for your html document
    <script type="text/javascript" src="js/jquery.js"></script>
    <script type="text/javascript" src="js/three.js"></script>
    <script type="text/javascript" src="js/jquery.ipanorama.min.js"></script>
    
  3. Load the CSS theme file that styles the plugin
    <script type="text/css" src="css/ipanorama.css" rel="stylesheet" media="all"></script>
    <script type="text/css" src="css/ipanorama.theme.default.css" rel="stylesheet" media="all"></script>
    
  4. Create a DIV tag where to set the panorama:
    <div id="myvirtualtour"></div>
    
  5. Call the plugin to setup your scenes with hotSpotSetup = true
    $("#myvirtualtour").ipanorama({
    	theme: "ipnrm-theme-modern",
    	hotSpotSetup: true,
    	sceneId: "entrance",
    	scenes: {
    		entrance: {
    			type: "sphere", // specifies the scene type ("box", "sphere", "cylinder")
    			image: "assets/images/entrance.jpg",
    			title: "The entrance to the house"
    		},
    		livingroom: {
    			type: "sphere", // specifies the scene type ("box", "sphere", "cylinder")
    			image: "assets/images/livingroom.jpg",
    			title: "The Living Room"
    		}
    	}
    });
    
  6. Let's setup hotspots. Press ctrl and click anythere your want in the first scene.

    If you check your browser console, you will see coordinates for your hotspot (yaw and pitch)

  7. Let's rewrite our panorama config with hotspots support
    $("#myvirtualtour").ipanorama({
    	theme: "ipnrm-theme-modern",
    	hotSpotSetup: true,
    	sceneId: "entrance",
    	scenes: {
    		entrance: {
    			type: "sphere", // specifies the scene type ("box", "sphere", "cylinder")
    			image: "assets/images/entrance.jpg",
    			title: "The entrance to the house",
    			hotSpots: [{
    				yaw: 190.86405695726037, 
    				pitch: 4.8227115073584,
    				sceneId: "livingroom",
    				popoverContent: "The Living Room"
    			}]
    		},
    		livingroom: {
    			type: "sphere", // specifies the scene type ("box", "sphere", "cylinder")
    			image: "assets/images/livingroom.jpg",
    			title: "The Living Room",
    			hotSpots: [{
    				yaw: 120.81267038066335,
    				pitch: 4.153851619425508,
    				sceneId: "entrance",
    				popoverContent: "The entrance to the house"
    			}]
    		}
    	}
    });
    
  8. Repeat steps above, you can build your own virtual tour

Options

All of the options below are available to customize iPanorama 360°.

Option Type Default Description
themeStringipnrm-default CSS styles for controls, change it to match your own theme
containerSizeSelectorStringnull specify the selector for select a single element what define panorama size if the plugin can't detect it
imagePreviewStringnull specifies a URL for a preview image to display before the panorama is loaded
autoLoadBoolfalse when set to true, the panorama will automatically load, when false, the user needs to click on the load button to load the panorama
autoRotateBoolfalse setting this parameter causes the panorama to automatically rotate when loaded, the value specifies the rotation speed in degrees per second, positive is counter-clockwise, and negative is clockwise
autoRotateSpeedFloat0.001 the value specifies the rotation speed in degrees per second, positive is counter-clockwise, and negative is clockwise
autoRotateInactivityDelayInt3000 sets the delay, in milliseconds, to start automatically rotating the panorama after user activity ceases, this parameter only has an effect if the autoRotate parameter is set
mouseWheelPreventDefaultBooltrue enable or disable default behaviour on mouse wheel event
mouseWheelRotateBoolfalse enable or disable rotating on mouse wheel
mouseWheelRotateCoefFloat0.2 the coefficient by which the panorama is rotated on each mousewheel unit
mouseWheelZoomBooltrue enable or disable zooming on mouse wheel
mouseWheelZoomCoefFloat0.05 the coefficient by which the panorama is zoomed on each mousewheel unit, this parameter only has an effect if the mouseWheelRotate parameter is set to false
hoverGrabBoolfalse enable or disable grabbing on mouse hover
hoverGrabYawCoefFloat20 the coefficient by which the yaw angle is changed on each mouse move unit
hoverGrabPitchCoefFloat20 the coefficient by which the pitch angle is changed on each mouse move unit
grabBooltrue enable or disable grabbing on mouse click
grabCoefFloat0.1 the coefficient by which the panorama is moved on each mouse grab unit
showControlsOnHoverBoolfalse determines whether the controls should be shown when hovering on the panorama
showSceneThumbsCtrlBoolfalse show or hide the scene thumbs control
showSceneMenuCtrlBoolfalse show or hide the scene menu control
showSceneNextPrevCtrlBooltrue show or hide the scene next and prev controls
showShareCtrlBooltrue show or hide the stereo view toggle control
showZoomCtrlBooltrue show or hide the zoom controls
showFullscreenCtrlBooltrue show or hide the fullscreen toggle control
showAutoRotateCtrlBoolfalse show or hide the autorotate toggle control
sceneThumbsVerticalBooltrue change scene thumbs's direction from horizontal to vertical
sceneThumbsStaticBoolfalse thumbs are static
keyboardNavBooltrue set or disable navigation with keyboard (arrows keys)
keyboardZoomBooltrue set or disable zoom with keyboard (plus and minus keys)
pinchZoomBooltrue enable or disable multitouchzoom (2 fingers touch on the screen at the same time)
pinchZoomCoefFloat0.1 the coefficient by which the panorama is zoomed
titleBooltrue show or hide the title control
compassBooltrue enable or disable the compass
sceneNextPrevLoopBoolfalse set or disable loop for the scene navigation with next & prev controls
popoverBooltrue enable or disable the build-in popover system
popoverTemplateString base HTML to use when creating the popover
<div class='ipnrm-popover'>
	<div class='ipnrm-close'></div>
	<div class='ipnrm-arrow'></div>
	<div class='ipnrm-content'></div>
</div>
popoverPlacementStringtop set the position of the popover on top, bottom, left or the right side of the hotspot
popoverShowTriggerStringhover specify how popover is triggered (click, hover)
popoverHideTriggerStringleave specify how popover is hidden (click, leave, grab, manual)
hotSpotBelowPopoverBooltrue specify the z-order of the hotSpot against the popover
popoverShowClassStringnull

specify the css3 animation class for the popover show

Note

You can use my open-source library Effect.less with over 100 animation classes
popoverHideClassStringnull

specify the css3 animation class for the popover hide

Note

You can use my open-source library Effect.less with over 100 animation classes
sceneIdStringnull id of the scene to load first
sceneFadeDurationInt3000 specify the fade duration, in milliseconds, when transitioning between scenes
sceneBackgroundLoadBoolfalse load all scene in the background
pitchLimitsBooltrue enable or disable the pitch limits
hotSpotSetupBoolfalse set or disable manual setup of hotspots in the current scene
mobileBoolfalse enable or disable the animation in the mobile browsers
onHotSpotSetupCallbacknull callback funtion, if set, it will fire after click in the panorama
function(yaw, pitch, cameraYaw, cameraPitch, cameraZoom, event) {}
onCameraUpdateCallbacknull callback funtion, if set, it will fire after the camera updated
function(cameraYaw, cameraPitch, cameraZoom) {}
onShareCallbacknull callback funtion, if set, it will fire after the user click on the share control
function(event) {} 
onLoadCallbacknull callback funtion, if set, it will fire after the plugin loaded
function() {} 

Options for the scene definition

Option Type Default Description
typeString"cube" specifies the scene type ("cube", "sphere", "cylinder")
cubeTextureCountString"six" specify the cube texture count (single or six)
sphereWidthSegmentsInt100 number of horizontal segments for a sphere type scene
sphereHeightSegmentsInt40 number of vertical segments for a sphere type scene
imageString/Objectnull full file name specify the background of the scene, for the 'cube' type scene you have to define six textures
thumbBoolfalse enable or disable the scene thumb
thumbImageStringnull full file name specify the thumbnail of the scene
yawInt0 sets the panorama’s starting yaw position in degrees
pitchInt0 sets the panorama’s starting pitch position in degrees
zoomInt75 sets the panorama’s starting zoom from 40 to 100
titleHtmlBoolfalse specify the type of the scene title
titleSelectorStringnull specify the selector for select a single element with a content for the title
titleStringnull if set, the value is displayed as the panorama’s scene title, it can be text or HTML content
compassNorthOffsetIntnull set the offset, in degrees, of the center of the panorama from North, as this affects the compass, it only has an effect if compass is set to true
hotSpotsArray[] specifies an array of hot spots that can be links to other scenes or information

Options for the hotspot definition

Option Type Default Description
yawInt0 specify the yaw portion of the hot spot’s location
pitchInt0 specify the pitch portion of the hot spot’s location
sceneIdStringnull specify the id of the scene to link to
imageUrlStringnull url for the hotspot image
imageWidthIntnull hotspot image width
imageHeightIntnull hotspot image height
linkStringnull if set, the hotspot is a link
linkNewWindowBoolfalse if set, open link in new window
classNameStringnull specify additional css classes
contentStringnull if set, the value is displayed as the hotspot's content
popoverLazyloadBooltrue enable or disable lazy load for the popover content
popoverShowBoolfalse show the popover content when the scene's loaded
popoverHtmlBooltrue specify the type of the popover content
popoverContentStringnull if set, the value is displayed as the popover's content, it can be text or HTML content, or a method - function myfunc()
popoverSelectorStringnull specify the selector for select a single element with a content for the popover
popoverPlacementStringtop set the position of the popover on top, bottom, left or the right side of the hotspot
popoverWidthIntnull specify the width of the popover
userDataObjectnull specify the user data that is associated with the hotspot, useful when the popoverContent is a method

Methods

Method Parameters Description
destroydestroy the plugin, this reverts all plugin elements back to their original state (before calling the plugin)
loadscenesceneIdload the specific scene
loadhotspotssceneId, hotSpotsload hotspots into the specific scene
lookatyaw, pitchchange the LookAt vector of the camera
grabon/off grab functionality
instanceget instance
fullscreenswitch to fullscreen mode and back
resizeyou should call this after the layout is changed

Example:

$("#panorama").ipanorama("loadscene", {sceneId: "main"});
$("#panorama").ipanorama("loadhotspots", {sceneId: "main", hotSpots: []})
$("#panorama").ipanorama("lookat", {yaw: 0, pitch: 0})
$("#panorama").ipanorama("fullscreen");
$("#panorama").ipanorama("grab")
$("#panorama").ipanorama("instance")
$("#panorama").ipanorama("resize");
$("#panorama").ipanorama("destroy");

Preview demo via Brackets editor

  1. Download the Brackets editor and install it on your local computer.
  2. Download the zipped plugin pack to your local computer from CodeCanyon and extract the ZIP file contents to a folder on your local computer.
  3. Run Brackets editor.
  4. Click on the "File" > "Open Folder...". In the extracted folder you will find the folder 'ipanorama'. Select it.
  5. Find and select the file 'index.html' in the folder 'demo'.
  6. Click on the "File" > "Live Preview".
  7. Check plugin working.

Sources and Credits

I've used the following libraries:


Once again, Thank you so much for purchasing this product. As I said at the beginning, I'd be glad to help you if you have any questions relating to this script. No guarantees, but I'll do my best to assist. Feel free to rate my plugin as 5 out of 5 stars. If it's not a 5 of out 5, e-mail me and let me know what I can do to improve your experience.


Max Lawrence, avirtum@gmail.com