Skip to main content
Adapters are small pieces of code responsible for loading panorama texture(s) into the Three.js scene. Each adapter understands a specific image format and handles fetching, decoding, and mapping it onto the sphere or cube geometry. The core package ships with the equirectangular adapter built in. All other adapters are separate npm packages.

​
Available adapters

Equirectangular

The default adapter. Loads standard equirectangular JPEGs, including cropped or partial panoramas with XMP metadata support.

Equirectangular tiles

Reduces initial load time by slicing large equirectangular panoramas into smaller tiles loaded on demand.

Equirectangular video

Displays equirectangular video panoramas. Requires the VideoPlugin.

Cubemap

Loads cube mapping projections from six face images, a horizontal stripe, or a polyhedron net layout.

Cubemap tiles

Reduces initial load time by slicing large cubemap faces into tiles loaded on demand.

Cubemap video

Displays cubemap video panoramas in the format used by YouTube. Requires the VideoPlugin.

Dual fisheye

Displays raw dual-fisheye files produced by 360° cameras such as the Ricoh Theta Z1.

​
Choosing an adapter

Use caseAdapter
Standard 360° photo (JPEG, PNG)Equirectangular (default)
Very large equirectangular imageEquirectangular tiles
360° video in equirectangular formatEquirectangular video
Six-face cubemap imagesCubemap
Very large cubemap facesCubemap tiles
Cubemap video (YouTube-style)Cubemap video
Raw file from Ricoh Theta Z1Dual fisheye

​
How to use an adapter

Pass the adapter class to the adapter option when creating the Viewer. Some adapters also accept a configuration object, which you provide using the static withConfig method. 
<script type="importmap">
    {
        "imports": {
            "@photo-sphere-viewer/core": "https://cdn.jsdelivr.net/npm/@photo-sphere-viewer/core/index.module.js",
            "three": "https://cdn.jsdelivr.net/npm/three/build/three.module.js",
            "@photo-sphere-viewer/cubemap-adapter": "https://cdn.jsdelivr.net/npm/@photo-sphere-viewer/cubemap-adapter/index.module.js"
        }
    }
</script>

<script type="module">
    import { Viewer } from '@photo-sphere-viewer/core';
    import { CubemapAdapter } from '@photo-sphere-viewer/cubemap-adapter';

    new Viewer({
        adapter: CubemapAdapter,
        // or with config:
        // adapter: CubemapAdapter.withConfig({ /* options */ }),
        panorama: { /* adapter-specific */ },
    });
</script>
The equirectangular adapter is built into @photo-sphere-viewer/core and is the default. You only need to declare it explicitly if you want to pass configuration options.

Build docs developers (and LLMs) love

Get started for freeTalk to us