Panolens.js Panorama Viewer

Common errors

• Uncaught ReferenceError: PANOLENS is not defined

  cause Attempting to use `PANOLENS` global object without loading `panolens.min.js` via a script tag or incorrectly importing it in an ES module environment.
  fix If using script tags, ensure `<script src="panolens.min.js"></script>` is included after `three.min.js`. If using ES modules and a bundler, ensure `import * as PANOLENS from 'panolens';` (or named imports) is used and 'panolens' is installed.

• TypeError: Cannot read properties of undefined (reading 'Viewer')

  cause Attempting to access `PANOLENS.Viewer` after v0.10.0 ES module refactor when not using a global script or when `PANOLENS` is not correctly imported as a namespace.
  fix For modern module-based projects, use `import { Viewer } from 'panolens';`. If you strictly require a namespace, ensure `import * as PANOLENS from 'panolens';` is used. For script tag usage, verify the `panolens.min.js` script is loaded.

• THREE is not defined

  cause Panolens.js depends on Three.JS, but the `THREE` global object is not available, or the `three` module is not correctly imported.
  fix Ensure `three.min.js` is loaded before `panolens.min.js` in script tag setups. If using modules, explicitly `import * as THREE from 'three';` in your file.

• Uncaught TypeError: panorama.link is not a function

  cause The `panorama` object is not an instance of a Panolens panorama class, or the method name is incorrect.
  fix Verify that `panorama` is correctly instantiated as `new PANOLENS.ImagePanorama()` or `new PANOLENS.VideoPanorama()`. Check method names against current documentation, especially after major updates.

Warnings

• breaking Version 0.10.0 introduced a major refactor to ES6 modules, deprecating CommonJS `require` usage. It also removed several classes (SpriteText, Tile, TileGroup, BendModifier, Bmfont) and changed constant variable naming conventions (e.g., `PANOLENS.Controls` became `PANOLENS.CONTROLS`). Gulp was replaced by Rollup for builds.
  Fix: Migrate import statements to ES module syntax (`import { ... } from 'panolens'`). Update usage of deprecated classes and constants according to the migration guide. Re-evaluate build processes if relying on internal tooling that used Gulp.
• breaking In version 0.8.0, the library reduced its size by replacing data URI images with remote links. This change removed `PANOLENS.DataImage` and requires users who need locally hosted assets to either provide their own image sources or use the `panolens-offline.min.js` version.
  Fix: If using local assets, ensure you're either providing direct image URLs for panoramas or utilizing the `panolens-offline.min.js` build. Remove any references to `PANOLENS.DataImage`.
• deprecated Version 0.11.0 deprecated the use of `video` elements with a `src` attribute in favor of `source` elements within the `video` tag for better multimedia handling and flexibility.
  Fix: When creating `VideoPanorama` instances or working with video elements, use `<source>` child elements within the `<video>` tag to specify video sources instead of the `src` attribute directly on the `video` tag.
• gotcha Panolens.js relies on Three.JS. While Panolens.js exposes `PANOLENS.THREE_VERSION` to check compatibility, developers must ensure they are including a compatible version of `three.min.js` before `panolens.min.js` when using script tags, or correctly installing `three` as a peer dependency in module environments.
  Fix: Always check the `package.json` dependencies for the recommended `three.js` version. If using script tags, include `three.min.js` before `panolens.min.js`. If using a bundler, ensure `three` is correctly installed and resolvable.

Install

• npm install panolens npm
• yarn add panolens yarn
• pnpm add panolens pnpm

Imports

• Viewer
  wrong:

  const Viewer = require('panolens').Viewer;

  correct:

  import { Viewer } from 'panolens';
  // Or if using global script tags:
  // const viewer = new PANOLENS.Viewer();

  Panolens.js transitioned to ES modules in v0.10.0. For module bundlers, use named imports. For traditional script tags, the library exposes a global `PANOLENS` object.
• ImagePanorama
  wrong:

  import Panolens from 'panolens';
  const panorama = new Panolens.ImagePanorama('...');

  correct:

  import { ImagePanorama } from 'panolens';
  // Or if using global script tags:
  // const panorama = new PANOLENS.ImagePanorama('path/to/image.jpg');

  Individual components like ImagePanorama are named exports. The global `PANOLENS` object acts as a namespace for all components when loaded via script tags.
• VideoPanorama
  wrong:

  const panorama = new PANOLENS.VideoPanorama();

  correct:

  import { VideoPanorama } from 'panolens';

  Since v0.10.0, it supports ES module imports. Earlier versions or script tag usage would access via the global `PANOLENS` object.

Quickstart

This quickstart demonstrates how to initialize a Panolens.js viewer, load an equirectangular image panorama, and add it to the viewer. It also shows how to conceptually link two panoramas, and ensures the viewer is attached to a pre-existing DOM element.

import { Viewer, ImagePanorama } from 'panolens';
import * as THREE from 'three';

// Ensure a DOM element exists for the viewer
const appContainer = document.createElement('div');
appContainer.id = 'panorama-container';
appContainer.style.width = '100vw';
appContainer.style.height = '100vh';
document.body.appendChild(appContainer);

// Create a new panorama from an image
const panorama = new ImagePanorama('https://pchen66.github.io/Panolens/examples/asset/textures/equirectangular/cabin.jpg');

// Create the viewer instance, attaching it to the container
const viewer = new Viewer({
    container: appContainer,
    autoRotate: true,
    autoRotateSpeed: 0.5
});

// Add the panorama to the viewer
viewer.add(panorama);

// Example of linking another panorama (dummy link for demonstration)
const otherPanorama = new ImagePanorama('https://pchen66.github.io/Panolens/examples/asset/textures/equirectangular/field.jpg');
viewer.add(otherPanorama);

// Link the first panorama to the second one at a specific 3D coordinate
panorama.link(otherPanorama, new THREE.Vector3(0, 0, -500), 100);