Panorama Plugin

How to use the X3 panorama plugin, and how to prepare your panorama sources.

X3 Panorama Plugin

Available since X3.26.0, the X3 panorama plugin allows you to display spherical and flat panoramas directly in X3. To enable the panorama plugin for any gallery, navigate to Page settings › Plugins › Panorama and check ✓ Enabled.

Demo

Spherical Panorama

Spherical format is a full 360/180 degree panorama, either taken with a special 360/180 camera, or stitched from multiple images using a 3rd party tool. X3 supports both single-file equirectangular source and multi-resolution cube source exported from Marzipano tools.

Flat Panorama

Flat panorama format is a very large "gigapixel" image, allowing extreme zoom levels, exported into multi-resolution tiles from tools like Pano2VR and Krpano.

The panorama plugin is reserved for the X3 PRO license. You can upgrade here.

1 Equirectangular Spherical

Equirectangular spherical format is the easiest panorama to include into X3, since it consists of a single source file in 2:1 aspect ratio. Simply resize your equirectangular image to 4096 px width and upload into your X3 gallery.

Demo Source Wiki

Equirectangular upload dimensions

The reason we recommend 4096 px width is because 4096 is the max_texture_size supported by all devices, and offers a balance between file size and visual quality. Most modern desktops also support 8192 px textures, so you can upload your sources at 8192 px if you want higher quality. If you upload sources at 8192 px, you will need to make sure your server is powerful enough to downsize 8192 px images, or you will have to create downsized versions manually.

2 Cube Spherical

Cube format is a spherical panorama exported into tiles and folders with the Marzipano Tool. Cube multi-resolution format is more tedious to use than the equirectangular format, but advantages include progressive loading and support for higher resolutions.

Demo Wiki

Create and export your cube panorama from the Marzipano Tool.
Unzip and upload the folder to your X3 gallery via FTP.
Upload a preview image that will represent the panorama in your gallery.
Name the folder the same as the preview "mycube.jpg" => "_mycube".

Multiple scene export

The Marzipano Tool allows you to create multiple panorama scenes in a single export, which you can then upload directly to your X3 gallery. You will then need to upload a preview image for each scene, with file names matching each scene ID.

3 Flat Panorama

Flat gigapixel panorama format is an extremely large and detailed image, exported into multi-resolution tiles by tools like Pano2VR and Krpano.

Demo

Upload the flat panorama folder into your X3 gallery via FTP.
Upload a preview image that will represent the panorama in your gallery.
Name the folder the same as the preview "myflat.jpg" => "_myflat".

Export tools

X3 currently supports flat panoramas exported from 3rd party tools Pano2VR and Krpano, which include a pano.xml config file used by X3 to render the panorama. Unfortunately, none of these 3rd-party tools are free, but I hope in the future there will be a low-price version available.

Manual configuration

If your exported project doesn't contain a pano.xml file, or if you are loading tiles from a remote source or CDN, you will need to apply flat parameters manually.

url_format=l1/%0v/l1_%0v_%0h.jpg&tilesize=2048&width=1024,3072,6144,12288,23552&height=404,1208,2416,4832,9260

Panorama Settings

Navigate to Settings › Plugins › Panorama for advanced panorama plugin settings. Most options here are for tweaking the interface and editing view defaults, and you are not required to changed anything screenshot

Panorama Parameters

Sometimes you may want to include custom parameters for each of your panoramas, to override global settings or include special instructions. Find the parameters input field in your page gallery tab after clicking [list view] until you are in [edit mode].

Custom parameters are added in query-string format:

option1=2&option2=hello&option3=false

Parameters

The following panorama parameters are available.

id
Optional ID used in URL #fragment, normally extracted from file name.
```
id=my-panorama-id
```
title
Optional panorama title to display in top left corner.
```
title=My Panorama Title
```
open
Designates the specified panorama to automatically open when the page loads.
```
open=true
```
width equirectangular4096
Specify source width for single-file equirectangular panoramas if the source is located on a remote server or when adding to custom content. If width is specified, height it calculated automatically.
```
width=8192
```
width flat
Specify flat width array if no pano.xml or source is located on a remove server.
```
width=1024,3072,6144,12288,23552
```
height flat
Specify flat height array if no pano.xml or source is located on a remove server.
```
height=404,1208,2416,4832,9260
```
type
Force panorama type: equirect, cube or flat.
```
type=equirect
```
source equirectangular
Point the panorama to a different source than the file uploaded to the gallery.
```
source=equirect_source.jpg
```
source_4096 equirectangular
Specify path to a 4096 px equirectangular source. Use only if your original source is 8192 px and your server is not capable or resizing down to 4096 px or if your source is located on a remote server.
```
source_4096=equirect_source_4096.jpg
```
preview equirectangulartrue
X3 will by default attempt to create a small preview image that displays in the panorama viewer while the large source is loading. Disable if our server is incapable of resizing large source images.
```
preview=false
```
levels cube3
Use to define cube levels amount if your source is located on a remote server.
```
levels=4
```
path cubeflat
Optional path to cube or flat project dir if your source is located on a remote server.
```
path=pano_folder
```
url_format flat
Define url format if no pano.xml or you are loading from a remote server.
```
url_format=l1/%0v/l1_%0v_%0h.jpg
```
zero_padding flat0
Define url zero-padding if no pano.xml and your project is from Krpano.
```
zero_padding=2
```
index_start flat0
Define index start if no pano.xml and your project is from Krpano.
```
index_start=1
```
tilesize flat512
Define tile size if no pano.xml or loading source from a remote server.
```
tilesize=1024
```
yaw spherical0
Horizontal rotation start position for spherical panorama in radians [-π, π].
```
yaw=-1.15
```
pitch spherical0
Vertical rotation start position for spherical panorama in radians [-π, π].
```
pitch=0.5
```
fov spherical1.2
FOV (field of view) for spherial panoramas in radians [0 - π].
```
fov=1.5
```
maxVFov spherical1.75
Maximum vertical FOV in radians [0 - π].
```
maxVFov=1.5
```
maxHFov spherical
Maximum horizontal FOV in radians [0 - π], by default inherited from maxVFov.
```
maxVFov=2.1
```
pitch_min spherical-90
Constrain the upwards (negative) vertical viewing angle (pitch) in degrees [0 - -90].
```
pitch_min=-45
```
pitch_max spherical90
Constrain the downwards vertical viewing angle (pitch) in degrees [0 - 90].
```
pitch_max=70
```
maxResolution spherical
Set the maximum zoom level, normally calculated from the source pixel width.
```
maxResolution=5000
```
pinFirstLevel
Disable panorama preview from preloading and pinning to memory.
```
pinFirstLevel=false
```
pin_levels flat
Designate the amount of levels to preload and pin to memory for flat panoramas.
```
pin_levels=2
```
zoom true
Disable the zoom button (even if the scene is zoomable).
```
zoom=false
```
scene_id cubemulti
Assign a specific panorama ID from a Marzipano multi-scene export.
```
scene_id=scene-name
```
scene_index cubemulti
Assign a specific panorama scene index from a Marzipano multi-scene export.
```
scene_index=3
```
geo
Assign latitude and longtitude for Google maps if source does not contain EXIF geo.
```
geo=39.721563,21.632105
```

Panorama Links in Content

You can also use the X3 panorama plugin directly in your custom content. Simply add a link with the data-panorama attribute and include panorama parameters. Since X3 does not know the panorama source configuration up front, you will need to manually include required parameters. A few examples:

Open an equirectangular panorama, making sure to declare the width:

equirectangular

Open a cube panorama, making sure to declare the folder path and levels amount:

cube

Open a flat panorama, making sure to declare several required parameters that you can acquire from the project's pano.xml file:

flat

FAQ

How can I include Google Maps like the demo? screenshot

X3 will automatically read GPS meta data from your panoramas and create Google maps in the info popup. If your panoramas don't contain GPS meta data, you can set latitude and longtitude from the geo parameter.

geo=39.721563,21.632105

Can I load panoramas from remote server or CDN?

Yes, as long as the server does not have a policy to block requests from other origins. You will need to upload a preview image, and then apply custom parameters source (equirectangular) or path (cube and flat), pointing to the absolute panorama path on the remote server. Since X3 cannot automatically detect panorama configurations on remote servers, you may also need to include additional parameters.

Does X3 support cylindrical panoramas?

No, X3 does not currently support partial or cylindrical panoramas. Spherical panoramas must exist in full 360/180 format. Some tools allow you to create 360/180 panoramas from cylindrical panoramas, by filling the empty spots with repeating image data. You can also use pitch_min and pitch_max parameters to limit the up/down view og a spherical panorama.

Does X3 support hotspots?

No, X3 does not currently support hotspots created from other tools. We have plans to include support for hotspots created from Marzipano tools, Pano2VR and Krpano.

How can I export my FLAT gigapixel panoramas for free?

As of writing, there does not seem to be any quality free tools for exporting flat gigapixel panoramas. Both Pano2VR and Krpano are quite expensive, but I am hoping in the future they will offer budget versions of their tools for amateurs, perhaps limited to gigapixel amount.

Fotomoto Files gallery