Skip to main content

Panorama viewer

Files Gallery includes a panorama viewer that creates an interactive 360° view from equirectangular source files. * Available for licensed Files Gallery installations.

Demo

Supported format: equirectangular​

The panorama viewer supports the popular equirectangular panorama format, which by definition always has a 2:1 aspect ratio.

Download equirectangular sample [6000 x 3000 px 2.46 MB]panorama-sample-preview

Equirectangular panorama detection​

Files Gallery will automatically detect panoramas from image sources that are exactly 2:1 aspect ratio and >= 2048 px. If this causes false positives or you would like to detect panoramas differently, you can edit the default detection function from advanced javascript config.

panorama: {
    is_pano: (item, tests) => {

        // panorama width
        var w = item.dimensions[0];

        // return panorama path if width >= 2048, width is supported and ratio (w/h) === 2
        return w >= 2048 && tests.max_texture_size >= w && w/item.dimensions[1] === 2 ? file_path(item) : false;
    }
}

Browser and device support​

Most desktop browsers support equirectangular dimensions up to 16384 px, but some older devices may only support 4096 or 8192 px. In some cases, if a device has insufficient memory, a large panorama may simply fail. If you want "best" quality for your panoramas, you can use up to 16384 px source files, but they they may fail in some browsers. If you want panoramas to work in almost all browsers, resize them to 8192 px. Also see multi-resolution section.

JPG compression​

Since equirectangular image source files are massive, file size will be proportionally high and they may load slow. It's a good idea to use sufficient JPG compression to improve the user experience. In our demo, we compressed files around 5x from 50MB->10MB and 10MB->2MB. File size will obviously depend on the source dimensions, but sufficient JPG compression will make a big difference. You could use an online tool like kraken.io to compress JPG files effectively.

Panorama preview images​

Because equirectangular source files are massive, Files Gallery may not automatically be able to create preview images because of server memory limitations. If your server is powerful enough, you can increase the following config values to allow resizing of large image source files:

// 512 MB should be sufficient for most equirectangular images, but you may have to go higher if using 16384 px
'image_resize_memory_limit' => 512,

// Disable image_resize_max_pixels to prevent Files Gallery from blocking resize based on pixel dimensions
'image_resize_max_pixels' => 0,

Multi-resolution​

Files Gallery has built-in support for multi-resolution panoramas if you store resized versions. This allows high-quality panoramas on large-screen desktops, while smaller versions will load on smaller screens. Files gallery will detect panorama size supported by browser, and also use screen size to determine the size to load. To achieve this, create multiple versions of your panorama source file:

// original file up to 16384 px (supported by modern desktop browsers)
// will be used on large screens that support 16384 px textures
panorama.jpg

// 8192 px version (hidden from layout _files*)
// will be used for browsers that only support 8192 textures and medium size screens
_files_8192_panorama.jpg

// 4096 px version (hidden from layout _files*)
// will be used for browsers that only support 4096 textures and small size screens
_files_4096_panorama.jpg

// 2048 px version (hidden from layout _files*)
// will be used for browsers that only support 2048 textures and smallest size screens
_files_2048_panorama.jpg

You only need to create resized versions specifically in sizes 8192, 4096 and 2048 px, because these are the specific values supported by browsers. Some browsers support 16384 px, but this would be your original so no need to create that resize variation. Also, you would only need to create resized versions smaller than your original. For example, if your original source is 7000 px, you would only create 4096 and 2048 px resized versions.