@igloo/krpano

Version 0.2.0.

A JavaScript module which can create a cubemap from a KRPano scene and provide a mechanism for synchronising views between different krpano instances.

Usage

Extend the HTML script tag which embeds your krpano tour.

It'll probably look something like this:

<body>
  <div id="pano"></div>
</body>

<script>
  embedpano({
    xml: 'tour.xml',
    target: 'pano',
    // your other options
  });
</script>

Adding igloo_krpano.js:

<body>
  <div id="pano"></div>
</body>

<!-- add type="module" to allow imports from igloo_krpano.js -->
<script type="module">
  import { iglooKrPano } from './igloo_krpano.js'; // import function

  embedpano({
    xml: 'tour.xml',
    target: 'pano',
    // ...
    onready: iglooKrPano(), // add onready to embedpano options, passing the result of calling iglooKrPano to it.
  });
</script>

Serve igloo_krpano.js alongside your tour html entrypoint. (The same place as krpano.js, tour.js, or whatever your krpano javascript file is called).

By default, this will do nothing. Adding url parameters or changing the configuration as outlined below will draw a cubemap, setup viewsync, or remove ui from the rendered cubemap.

Here's an tl;dr of the default behaviour, with the call to iglooKrPano included. See configuration and URL parameter sections below for more detailed info.

url	behaviour
`https://example.com/krpano/mytour/tour.html`	normal behaviour
`.../tour.html?igloo`	cubemap drawn
`.../tour.html?igloo&igloo_cubemap_showui`	cubemap drawn with ui
`.../tour.html?igloo_viewsync`	normal; viewsync set up to work inside `@igloo/krpano-wrapper`

Configuration

Behaviour can be modified by passing an options object to the iglooKrPano function.

type IglooKrPanoOptions = {
  drawCubemap?: (() => boolean) | boolean;
  doViewsync?: (() => boolean) | boolean;
  showUi?: (() => boolean) | boolean;
  handleViewsyncOut?: (msg: Viewsync.Message) => void;
  setupViewsyncIn?: (callback: (msg: Viewsync.Message) => void) => void;
};

Defaults are provided for every option, outlined below.

`drawCubemap`

Whether to draw a cubemap.

By default, this checks the URL parameters defined below. If any of them are present, a cubemap will be drawn.

To modify this behaviour, pass a boolean or a boolean-returning-function.

embedpano({
  // ...
  onready: iglooKrPano({ drawCubemap: true }),
});

// or

embedpano({
  // ...
  onready: iglooKrPano({ drawCubemap: () => true }),
});

`doViewsync`

Whether to enable viewsync functionality.

See the viewsync section below for an explanation of this.

By default, this checks for the igloo_viewsync url parameter. If this is present, viewsync functionality will be enabled.

To modify this behaviour, pass a boolean or a boolean-returning-function (as above).

`showUi`

Whether to show UI on cubemap faces.

By default, all non-WebGL-canvas elements are removed from the cubeface. Anything rendered with WebGL is present and interactable. This option allows non-WebGL-canvas elements to be retained.

This seems to be the default for non-text hotspots added using the krpano-provided tour builder. Text hotspots with renderer="webgl" added are also rendered correctly. Other UI which is "world-space" hasn't been tested, but any tour which is "VR-supported" according to krpano ought to be rendered correctly.

By default, this checks for the igloo_cubemap_showui url parameter. If this is present, UI will not be removed.

To modify this behaviour, pass a boolean or a boolean-returning-function (as above).

`handleViewsyncOut`

Pass a function which will be called with any outgoing viewsync messages from the KRPano instance.

`setupViewsyncIn`

Pass a function which will be called once when iglooKrPano initialises with a single argument.

This argument is a callback function which should be called with any incoming viewsync messages (which will be passed to handleViewsyncOut).

URL Parameters

These URL parameters are used when the default configuration is set. Overriding showUi, drawCubemap, or doViewsync will mean these parameters aren't used.

Parameter	Behaviour
`igloo`	Create cubemap
`igloomode`	Create cubemap
`igloo_cubemap`	Create cubemap
`igloo_cubemap_showui`	Do not remove UI from cubemap
`igloo_viewsync`	Send viewsync messages using `handleViewsyncOut` and `setupViewsyncIn`

Viewsync

In order to facilitate synchronisation of separate krpano instances (possibly in separate browsers or on separate machines), iglooKrPano() can set up viewsync.

iglooKrPano starts listening to events from krpano instances it's attached to. Whenever there's an event, it constructs a message and calls the handleViewsyncOut function with that message.

When this message is passed to the callback provided to setupViewsyncIn, iglooKrPano will ask the target krpano instance to do whatever action the message is describing.

The default behaviour of this feature is set up to work with the (separate) Igloo krpano wrapper.

@igloo/krpano-wrapper

The Igloo Core Service hosts a wrapper page for krpano content which has had iglooKrPano attached to it. It handles the passing of viewsync messages between different wrapper instances that are loaded.

Security

This package has no dependencies.

The default viewsync behaviour uses postMessage to pass messages to @igloo/krpano-wrapper, but won't post (or act on) any messages to (or from) urls other than those used by the wrapper.

Pre-requisites

This will only work in browsers that support ES modules, which is every major browser release since mid-2018.

As mentioned above, this is meant for augmenting existing, functional krpano sites. It assumes that krpano.js has been loaded (which is the case when krpano works prior to trying to use this script).

krpano version compatibility

Developed with krpano 1.21.2 (build 2023-12-11), but it should be comaptible with any non-ancient krpano release.

It's been tested with:

krpano 1.21.2 (build 2023-12-11)

Development

Put a KRPano project which is set up to import igloo_krpano.js inside the dist/ directory of this package.
Run pnpm watch to build igloo_krpano.js inside the dist/ directory. This script watches the source files and rebuilds igloo_krpano.js when they change, so it'll keep running.
Serve the dist/ directory however you like. The easiest way is probably python -m http.server 3000 inside the dist/ directory, which will serve that directory on port 3000. Open a browser and navigate to the tour's html entrypoint.
Make changes to source files and refresh the page.

Building

Run pnpm build. igloo_krpano.js will be spat out in the dist/ directory.

References

Changelog

v0.2.0

Changed: UI is removed from cubemaps by default, and can be opted into through creation options.

v0.1.0

Initial release