{"id":11521,"library":"panolens","title":"Panolens.js Panorama Viewer","description":"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.","status":"active","version":"0.12.1","language":"javascript","source_language":"en","source_url":"https://github.com/pchen66/panolens.js","tags":["javascript","panorama","viewer","html5","3d"],"install":[{"cmd":"npm install panolens","lang":"bash","label":"npm"},{"cmd":"yarn add panolens","lang":"bash","label":"yarn"},{"cmd":"pnpm add panolens","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core rendering engine for WebGL-based panorama display. Required at runtime.","package":"three","optional":false},{"reason":"Included by default for animations and transitions within panoramas. Available as a global TWEEN object.","package":"tween.js","optional":false}],"imports":[{"note":"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.","wrong":"const Viewer = require('panolens').Viewer;","symbol":"Viewer","correct":"import { Viewer } from 'panolens';\n// Or if using global script tags:\n// const viewer = new PANOLENS.Viewer();"},{"note":"Individual components like ImagePanorama are named exports. The global `PANOLENS` object acts as a namespace for all components when loaded via script tags.","wrong":"import Panolens from 'panolens';\nconst panorama = new Panolens.ImagePanorama('...');","symbol":"ImagePanorama","correct":"import { ImagePanorama } from 'panolens';\n// Or if using global script tags:\n// const panorama = new PANOLENS.ImagePanorama('path/to/image.jpg');"},{"note":"Since v0.10.0, it supports ES module imports. Earlier versions or script tag usage would access via the global `PANOLENS` object.","wrong":"const panorama = new PANOLENS.VideoPanorama();","symbol":"VideoPanorama","correct":"import { VideoPanorama } from 'panolens';"}],"quickstart":{"code":"import { Viewer, ImagePanorama } from 'panolens';\nimport * as THREE from 'three';\n\n// Ensure a DOM element exists for the viewer\nconst appContainer = document.createElement('div');\nappContainer.id = 'panorama-container';\nappContainer.style.width = '100vw';\nappContainer.style.height = '100vh';\ndocument.body.appendChild(appContainer);\n\n// Create a new panorama from an image\nconst panorama = new ImagePanorama('https://pchen66.github.io/Panolens/examples/asset/textures/equirectangular/cabin.jpg');\n\n// Create the viewer instance, attaching it to the container\nconst viewer = new Viewer({\n    container: appContainer,\n    autoRotate: true,\n    autoRotateSpeed: 0.5\n});\n\n// Add the panorama to the viewer\nviewer.add(panorama);\n\n// Example of linking another panorama (dummy link for demonstration)\nconst otherPanorama = new ImagePanorama('https://pchen66.github.io/Panolens/examples/asset/textures/equirectangular/field.jpg');\nviewer.add(otherPanorama);\n\n// Link the first panorama to the second one at a specific 3D coordinate\npanorama.link(otherPanorama, new THREE.Vector3(0, 0, -500), 100);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.10.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=0.8.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=0.11.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Uncaught ReferenceError: PANOLENS is not defined"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'Viewer')"},{"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.","cause":"Panolens.js depends on Three.JS, but the `THREE` global object is not available, or the `three` module is not correctly imported.","error":"THREE is not defined"},{"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.","cause":"The `panorama` object is not an instance of a Panolens panorama class, or the method name is incorrect.","error":"Uncaught TypeError: panorama.link is not a function"}],"ecosystem":"npm"}