rxpan v0.1.34

RxPan

A 360 panorama viewer and editor that works in modern browsers including mobile.

Viewer:

Editor:

Viewer

Structure:

The RxPan editor allows you to create tours which are saved as .json files or can be embedded in your markup.

A tour consists of one or more locations. A location can be rotated and zoomed and may contain portals and hotspots. A portal allows the user to go from one location to another. A hotspot dispatches events that you can listen to and use to show popups or take other actions.

Usage:

const rxpan = new RxPan(element, config, options);

import RxPan from 'rxpan';                     // import the module  
import config from 'config.json';              // import the config file

const element = document.createElement('div'); // create a container
document.body.appendChild(element);            // add it to the DOM

const viewer = new RxPan(element, config);      // create a viewer inside the container

<script src='node_modules/rxpan/viewer.js'></script>        <!-- import the module -->

<script>
  const element = document.createElement('div');            // create a container
  document.body.appendChild(element);                       // add it to the DOM

  fetch('config.json').then(e => e.json()).then(config => { // fetch the config file
    const viewer = new RxPan(element, config);         // create the viewer inside the container
  });
</script>

<!-- tour config as markup -->
<rxpan id='example1' imagesDirectory='/editor/client/example-images' initialLocation='home'>
  <location id='home' image='center.png' rotation='0' />
    <portal id='back-left' angle='224.691' distance='7.086' />
  </location>
  <location id='back-left' image='back-left.png' rotation='0' />
    <hotspot id='popup' angle='66.550' height='-13.114' />
    <portal id='home' angle='45.447' distance='7.070' />
  </location>
</rxpan>

<script src='node_modules/rxpan/viewer.js'></script>   <!-- import the module -->

<script>
  const element = document.getElementById('example1'); // select the container
  const viewer = new RxPan(element, config);      // create the viewer inside the container
</script>

Config

tour  
├─ imagesDirectory <string> where the panorama images are located
├─ initialLocation <string> the location to display on load
└─ location <object>
   ├─ id <string> the name of the location (referenced by portals)
   ├─ image <string> the image file relative to imagesDirectory
   ├─ rotation <number> an initial rotaion offset for this location
   ├─ portal  
   |  ├─ id <string> the name of the location the portal should link to
   |  ├─ angle <number> the longitudinal angle of the portal 0-360 degrees. 0 = directly in front of camera
   │  └─ distance <number> the distance from the camera (0 - 50) 0 = directly under the camera, 50 = at the horizon
   └─ hotspot
      ├─ id <string> the name of the hotspot
      ├─ angle <number> the longitudinal angle of the hotspot 0-360 degrees. 0 = directly in front of camera
      └─ height <number> the latitudinal angle of the hotspot (-90 = directly above camera, 90 = directly below)

Options

autoResize - viewer resizes as it's containing DOM element's dimensions change. If false, call viewer.resize() to manually update its dimensions. Default is true.
hideRxPanLogo - hide the default RxPan background while panorama images load. Default is false.
preload - viewer will load the panorama images for each location in the tour before showing the initialLocation. Default is false.
debug - log all viewer events to the console. Default is false.
hideProgress - hide the progress bar while images are loading. Default is false.

Methods

viewer.goto(locationName) - goes to a new location in the tour.
viewer.lookat({ x, y, z }) - points the camera at a position in 3d space.
viewer.resize() - resizes the webgl canvas to fit it's container.
viewer.destroy() - removes the viewer's DOM element and all listeners attached to it.

Events

viewer.addEventListener('portal', portalClicked) - get notified when user moves to a new location.
viewer.addEventListener('hotspot', hotspotClicked) - get notified when a user clicks a hotspot.

Editor

RxPan comes pre-packaged with an example tour to help get you started.

In a terminal, run:

npm install rxpan  
cd node_modules/rxpan  
npm start

In a browser, visit:
http://localhost:9000/example.html - the example tour embedded within a page.
http://localhost:9000 - the editor

There are instructions within the editor that will guide you through the process of creating a tour from scratch, modifying or deleting an existing tour.

Development

If you'd like to work on the viewer or editor, this is the preferred method:

Clone the rxpan repo
Within that folder run npm link to create a global symlink.
Within the folder of a project that uses RxPan run npm link rxpan
This will then use your local RxPan folder as the module so you can update and see the effects without having to publish to npm and reinstall.

From within the rxpan folder run the editor's server: npm start
From within the rxpan folder build and watch the viewer: npm run viewer-dev
From within the rxpan folder build and watch the editor: npm run editor-dev

You can now edit the files within rxpan/editor/ and rxpan/viewer/

To publish, run npm publish or better: npm run build-and-publish which will first bundle the viewer and editor before publishing.

Make sure to increment the version number in the package.json when publishing as well. Follow semver standards.