panolens

library0.12.1jsnpmunverified

Panolens.js is a lightweight, event-driven, and WebGL-based JavaScript library designed for creating interactive 360-degree panorama viewers in web applications. Built on top of Three.JS, it provides robust capabilities for displaying spherical images and videos, including features like infospots, linking between panoramas, and various control mechanisms. The current stable version is 0.12.1, with releases occurring on an irregular basis, often bundling multiple fixes and new features within minor versions, and occasionally introducing significant breaking changes (e.g., the v0.10.0 ES Module refactor). Its key differentiators include its tight integration with Three.JS, emphasis on performance through WebGL, and an event-driven architecture that allows for highly customizable interactions.

web-framework http-networking

npm install panolens

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PANOLENS

panolens

web-frameworkjavascriptv0.12.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Viewer

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

✗ const Viewer = require('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

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

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

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

VideoPanorama

✓ import { VideoPanorama } from 'panolens';

✗ const panorama = new PANOLENS.VideoPanorama();

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

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);

Debug

Known issues

breakingVersion 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.

affects: >=0.10.0

breakingIn 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`.

affects: >=0.8.0

deprecatedVersion 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.

affects: >=0.11.0

gotchaPanolens.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.

affects: All versions

Errors

Common errors & fixes

Uncaught ReferenceError: PANOLENS is not defined

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')

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

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

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.

Upgrade

Version history

0.12.1latest on npm

Audit

Dependencies

threerequiredCore rendering engine for WebGL-based panorama display. Required at runtime.

tween.jsrequiredIncluded by default for animations and transitions within panoramas. Available as a global TWEEN object.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/pchen66/panolens.js ↗

packagehttps://www.npmjs.com/package/panolens ↗

homepagehttps://pchen66.github.io/panolens.js/ ↗