When I use map apps such as Google Maps, I often use Street View to display more detailed views of a street or inside of a building.  Although Google Street View is fantastic, there are many use cases where I want to control the development pipeline and assets without having to upload images to Street View. 

To control and optimize your business workflow, you can use open-source Marzipano to build virtual tours yourself and host the tours on your own web site.  This tutorial explains how to build the tour with open source software and host it for free on GitHub Pages. The technology and techniques can scale to large cloud businesses and are in production at commercial sites.   This tutorial focuses on a minimal simplified site to get you started with the basic concepts in minutes.

If you prefer to understand concepts by looking at examples first, this list by community member Sam Rohn provides results from a poll on free and commercial 360 tour software and hosting sites.  Another list of free and commercial virtual tour software is available here.  

Instead of jumping straight to a completed solution, let’s first build our own virtual tour site with open source software so that we understand the concepts and can modify the system to our exact needs!


A virtual tour consists of a set of 360° images that are linked together.  To navigate between the images, you either click on an arrow embedded in the image or click on the image inside a menu.  This simplified example shows both navigational techniques.  A third way to handle navigation is to provide a top-down overview map with pins or flags for the individual images. 

Navigate between images with menu or arrows

Live demo of the tour.

Getting 360 Images and Code Examples for Your Tour

Most mobile phones can take full 360° images.  The image quality is excellent, but the pictures take time to produce.  You will need to take multiple shots with your mobile phone for a single 360° image.  The mobile device will stitch the images together.

Sample 360 media for developers is also available here. Another site with sample images and additional developer tools and information is available here (requires email registration).

You can also search online for equirectangular images or 360° images.

The simple HTML code for this tutorial is available on GitHub

Building the Tour

Organize the 360° image files you’ll use in your tour.

organize 360 images

Go to marzipano.net.  We’ll use the online tool in this example.  However, you can also download the project from GitHub and run it locally. If you’re building your own service, you’ll want to eventually download and run Marzipano on your own servers. To get started quickly, I suggest using the online tool. 

getting startd with the marzipano tool

Upload the files you want to use in your tour.

add some panoramos

The files will load into the online tool.

loading the online tool

Marzipano has an easy to use GUI to set up the links between the images.

easy to use GUI to set up links between images

Link to each image in the tour.  You can also set up information hotspots to allow people to get more information on objects in your tour.  Once you’re done with the tour, click “Export” to get the tour onto your local computer.

export button

Hosting on GitHub Pages

Click on New to start a new repo.

new button to start new repo

Create a public repo.  In this example, my repo is called, “picture-tour-california”.

creating public repo

Extract the project-title.zip file you downloaded from Marzipano and push it up to the new repo.

extract project-tile.zip file

I’m putting my files in the master branch.

master branch

Under “Settings,” select master branch and /root.

master branch and /root

The live tour on GitHub Pages is here.

Embed Tour Into a Real Estate Web Page

The Marzipano tour site can be embedded into another site using an iframe.  The typical strategy is to use high-quality DSLR photos for the exterior of a house or to highlight key exhibits at a museum.  You then use the 360° image tour as supplemental information.  The virtual tour is usually not used as the primary interface for the exhibits as people are more familiar with a web page.   However, it is technically possible to use the tour as the main interface if your audience is comfortable with virtual tours.

Here’s the full code for a simplified web site with the virtual tour embedded into the site as supplemental information.

This is the css file.


To take your project to the next step of automatically placing the images on a map with the proper orientation, you will need to parse the image metadata and extract the GPS location, internal compass, and gyroscopic data.  A popular tool to extract metadata  is ExifTool by Phil Harvey.  There are a number of GUI front-ends to ExifTool, including jExifToolGUI.


Here’s an example of extracting GPS data from a 360 image taken with a Google Pixel at close to 10,000 foot elevation.

example of extracting GPS data

In addition to the GPS location, you also need to grab the Pose Heading Degrees.

Once you set the location and orientation, the person viewing your image, will see a view that they can navigate with a mouse, mobile phone movement or headset.  

example of nature picture

Adapting Tour with 3D Character or Object Assets

If you are building a type of game such as a scavenger hunt or a tour where the user sees additional “fun” assets, you can either place the 3D asset into the scene with something like A-Frame or a simpler technique is to convert the 3D asset into an image and paste the image into the scene. The example below shows a tour built with images using software from a large camera vendor.

adding characters to scene

You can create different poses with the animated character and embed the character into a scene in the virtual tour.

different poses for virtual character

A sample tour with animated characters is available here.

This shot from the tool for character placement illustrates the concept of placing a 3D asset and then converting it into a standard image embedded into a JPG.

character shots

To create front and back perspectives, you can either use an AI to detect objects in the front such as leaves, or manually select the leaf and push it to the front.

masking tool with character

Point Clouds and Automatic 3D Model Creation

It’s possible to use 360° images to create full 3D models of a space. The technology is still at an early stage.  In the example below, software vendor Cupix used a RICOH THETA V to build the 3D model on the right of the picture.  Other companies such as Matterport offer similar capabilities.

creating 3D models of a space


The simplest and most popular way to add virtual tours to a website is by using 360° images linked together with HTML and JavaScript. These types of tours are great for real estate, parks, museums, aquariums, and other places that may be difficult for the public to see due to restrictions. The tours are best as an extra element on an existing web site.  

The image used in the tour are standard JPG, webp, or PNG images and are easy for web developers to use quickly.  To make the linking easy, free tools such as the open source Marzipano offer hosted or local tools. After a virtual tour is built on one site, developers can easily embed it into their primary web templates with an iframe. 

With the public facing restrictions on access to locations, web developers can help people to experience some of the locations and exhibits through virtual tours.

Source link

Write A Comment