dash-pannellum — 360° panoramas for Dash

Interactive 360° panoramas, virtual tours, multi-resolution tiles and 360° video for Plotly Dash 4.

Built on Pannellum — the plug-in-free WebGL panorama viewer — wrapped as a single Dash component with a real-time imperative API.

Documentation · PyPI · Changelog · Discord

This repository is two things at once: the component package (dash_pannellum, published to PyPI) and its documentation site — a markdown-driven Dash app where every example is live, deployed at pannellum.2plot.dev as a 2plot network satellite. The site doubles as the component's test bed.

Install

pip install dash-pannellum

Python 3.9+ and Dash 4.2+. The component's own bundle ships inside the package; the Pannellum 2.5 viewer (and video.js, for 360° video) load from their CDNs at runtime, with one shared load no matter how many viewers are on the page.

Quick start

import dash
from dash import html
from dash_pannellum import DashPannellum

app = dash.Dash(__name__)

app.layout = html.Div(
    DashPannellum(
        id="panorama",
        tour={
            "default": {"firstScene": "alma"},
            "scenes": {
                "alma": {
                    "type": "equirectangular",
                    "panorama": "https://pannellum.org/images/alma.jpg",
                }
            },
        },
        autoLoad=True,
        width="100%",
        height="500px",
    )
)

if __name__ == "__main__":
    app.run(debug=True)

Viewer modes

Pass exactly one of:

Reading the viewer

pitch, yaw, hfov, currentScene, loaded and lastClickedHotspot update from the viewer — use them as Inputs. View-state updates are throttled to 4/s and change-detected, so idle viewers don't fire callbacks.

Driving the viewer in real time

The camera and the scene are imperative — no teardown, no rebuild, no flash:

Changing the configuration props (tour, multiRes, video, compass, northOffset, …) re-initializes the viewer cleanly, so panoramas can be swapped from a callback.

Documentation

Every page at pannellum.2plot.dev runs its examples live:

Each page also serves an LLM-ready version at /<page>/llms.txt (its prose plus complete example source), and the site exposes /llms.txt, /sitemap.xml and /robots.txt. SKILLS.md is a skills guide to the package — modes, callback patterns, prop reference and gotchas — written for AI coding assistants (and humans in a hurry).

Development

git clone https://github.com/pip-install-python/dash_pannellum
cd dash_pannellum

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt      # the docs site's dependencies

# markdown2dash pins gunicorn<22, against the CVE-driven gunicorn>=23 floor in
# requirements.txt. pip cannot resolve both, so it installs without its
# dependency set — everything it actually needs is already in the line above.
pip install --no-deps markdown2dash==0.1.2

pip install -e .                     # the component itself, editable

npm install
npm run build                        # webpack bundle + generated Python classes

python run.py                        # the docs site at http://127.0.0.1:8561

npm run build writes into dash_pannellum/ — both the bundle and the generated DashPannellum.py. Both are committed: that is what lets pip install work without Node. After a build, restart run.py — the docs site imports the package you just built, so it is the integration test.

The docs app's backend is pluggable (Dash 4.4+). Select it in .env or the environment:

DASH_BACKEND=fastapi python run.py   # ASGI — what production runs
DASH_BACKEND=flask   python run.py   # WSGI default

Or with Docker: docker compose up (serves on port 8561).

Before opening a PR, run the test suite — it boots the real run.py with zero secrets and checks every registered page, exactly as CI's container job does:

pytest

Repository layout

├── src/lib/                  # React component source
│   ├── components/DashPannellum.react.js
│   └── assets/videojs-pannellum-plugin.js
├── dash_pannellum/           # generated Python package (committed)
├── pyproject.toml            # package metadata (dash>=4.2.0)
├── package.json              # JS build toolchain (webpack 5, babel, react 18)
│
├── run.py                    # documentation app entry point
├── docs/                     # markdown docs + live examples (one folder per page)
├── pages/                    # home + markdown loader
├── components/               # appshell, header, navbar (dash-mantine-components)
├── lib/                      # backend resolver, network wiring, analytics
├── assets/ templates/        # css/js, index.html with SEO/LLM meta
├── scripts/                  # social-card generator, link audit, smoke tests
├── tests/                    # secretless pytest suite (flask/fastapi/quart)
└── vendor/                   # dash-clerk-auth tarball (docs-site auth, not on PyPI)

Adding a docs page means adding a folder under docs/ — a markdown file plus the example.py files it references — with no Python wiring anywhere else.

Publish

npm run build
python -m build              # sdist + wheel from pyproject.toml
twine upload dist/*

Upgrading from 0.0.6

dash-pannellum 0.1.0+ is the modernized revival of the original 0.0.6 component: Dash 4.2+ / React 18, coherent customControls semantics, throttled + change-detected view-state updates, callback hotspots wired through real Pannellum click handlers, deduplicated CDN script loading, pyproject.toml packaging. See CHANGELOG.md for the full history, including everything the real-time releases (0.2.0–0.4.0) added.

Credits

• Pannellum by Matthew Petroff — the underlying viewer (MIT)
• video.js — 360° video playback
• Documentation shell from the dash-documentation-boilerplate

License

MIT — see LICENSE. Built by Pip Install Python.