Build Virtual Tours of Houses and Parks with Open Source Software

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!

Overview

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. 

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.

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. 

Upload the files you want to use in your tour.

The files will load into the online tool.

Marzipano has an easy to use GUI to set up the links between the 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.

Hosting on GitHub Pages

Click on New to start a new repo.

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

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

I'm putting my files in the master branch.

Under "Settings," select 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.

<!DOCTYPE html>

<html lang="en">

<head>

    <meta charset="UTF-8">

    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <title>Virtual Tour Demo</title>

    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css" integrity="sha384-9aIt2nRpC12Uk9gS9baDl411NQApFmC26EwAOH8WgZl5MYYxFfc+NcPb1dKGj7Sk" crossorigin="anonymous">

    <link rel="stylesheet" href="main.css">

</head>

<body>

    <div class="p-3">

        <div class="jumbotron bg">

            <h1 class="display-4">Family</h1>

            <p class-"lead">Beautiful 4 bedroom house near great parks</p>

            <hr class="my-4">

            <a class="btn btn-primary btn-lg" role="button" href="#">Learn more</a>

        </div>

        <h2>See Neighborhood Parks</h2>

        <a href="https://codetricity.github.io/theta-miku/">Cherry Blossom Park</a>

        <div class="d-flex justify-content-center">

            <iframe src="https://codetricity.github.io/picture-tour-california/" 

            frameborder="0"

            width="800" height="400" allowfullscreen></iframe>

        </div>

    </div>

    <script src="https://code.jquery.com/jquery-3.5.1.slim.min.js" integrity="sha384-DfXdz2htPH0lsSSs5nCTpuj/zy4C+OGpamoFVy38MVBnE+IbbVYUew+OrCXaRkfj" crossorigin="anonymous"></script>

    <script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script>

    <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js" integrity="sha384-OgVRvuATP1z7JjHLkuOU7Xw704+h835Lr+6QL9UvYjZE3Ipu6Tp75j7Bh/kR0JKI" crossorigin="anonymous"></script>    

</body>

</html>

This is the css file.

xxxxxxxxxx

.bg {

    background: url('house.jpg');

    background-repeat: no-repeat;

}

.jumbotron {

    min-height: 650px;

}

Metadata

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.

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.  

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.

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

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.

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.

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.

Summary

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.