X3 Panorama Demo :star:
https://demo.photo.gallery/examples/plugins/panorama/
Documentation :star:
https://www.photo.gallery/docs/plugins/panorama/
Update to X3.26.0
Simply go to your Panel > Tools > X3 Updates. If you want to try X3.26.0 first, you can install in a temporary location. The X3 "full" installation includes a sample page /examples/plugins/panorama/ which contains a few examples.
Panorama Formats
X3 panorama plugin supports three panorama formats:
- Equirectangular / Spherical panorama loaded from a single-file source [wiki].
- Cube / Spherical panorama loaded from multi-file cube source [wiki].
- Flat / Flat (non-spherical) multi-resolution gigapixel images.
In addition to buttons and control methods drag, swipe, autorotate, gyroscope deviceOrientation (mobile only) and "lookto" (tap/click on stage), the following keyboard controls are supported:
- [space] Toggle interface
- [escape] Close viewer
- [shift-arrow-right] Next scene
- [shift-arrow-left] Previous scene
- [arrow keys] View up, down, left and right
- [+ / -] Zoom in / out
- [wasdqe] Up, left, down, right, roll left, roll right
Below is a screenshot of Settings > Plugins > Panorama, including "advanced" tab expanded. Most settings here you will not need to change, but it shows how extensive the panorama settings are.
Panorama Parameters
There is a new parameters field in your panel gallery, where you can include specific options for each panorama. You can normally leave this field blank, but in some cases you may need to include panorama-specific options. Without getting into detail, the following options are supported for panoramas: id, title, open, width, height, type, source, source_4096, preview, levels, path, url_format, zero_padding, index_start, tilesize, yaw, pitch, fov, maxVFov, maxHFov, pitch_min, pitch_max, maxResolution, pinFirstLevel, pin_levels, zoom, scene_id, scene_index, geo. Parameters are added in a query-string format:
Code
option1=2&option2=hello&option3=false
INSTRUCTIONS
=============
You will need to ENABLE page Settings > Plugins > Panorama plugin for any gallery where you intend to include panoramas. X3 will then attempt to detect panorama formats.
* You do not need to enable the panorama plugin for panoramas added to custom content.
Equirectangular Instructions
--------------------------------------
Equirectanular [source][demo][wiki] is a single-file spherical 360/180 panorama format. It is easy to include equirect panoramas in X3, since they are single files.
- Resize your image to 4096 px wide.
- Upload to your X3 panorama page.
- Done! X3 will do the rest.
The reason we recommend 4096 px wide, is because this is the MAX_TEXTURE_SIZE supported by all devices, and many devices (most notably mobile) will not load WEBGL textures larger than 4096 px. 4096 px provides acceptable quality for most screens, but for optimal quality on larger high-res screens, you may want to upload width 8192 px. Most new/modern desktops support 8192 px (or even 16384 px), and X3 will attempt to serve a resized 4096 px image for unsupported devices.
Equirectangular Notes
- If your server is not capable of resizing large 4096 px (or higher) images to preview-size in the X3 gallery layout, you can 1. Upload a downsized placeholder image (for example 1280 px) panorama.jpg, and then upload your panorama source file panorama_large.jpg (for example 4096 px or 8192 px). Make sure to HIDE the _large image from the gallery layout.
- If you upload a 8192 px image and your server is not capable of resizing it down to 4096 px (for devices that don't support 8192 px textures), you can upload an image panorama_4096.jpg, and HIDE it from the gallery layout.
- X3 will attempt to create a preview image from your equirect image source, to display in the viewer while the original large size is loading. If your server is not capable of resizing to preview image, you can disable equirect previews from panorama settings > advanced [screen] or set "preview=false" in parameters.
- You can use parameters source and source_4096 to target a specific source file for your equirect panorama. You can also use source parameter to load a remote file (CDN), but you will then need to set the width parameter since X3 cannot automatically detect the width of the image.
Cube Instructions
------------------------
Cube [demo][wiki] panoramas are multi-file and often multi-resolution representations of a spherical panorama. Because cube panoramas are "exported" and contained in a folder, they require a few more steps to include into X3. Advantages of cube panoramas are that they support higher resolutions, don't have texture size limitations and tiles are loaded progressively into view.
- Create your cube panorama from the Marzipano Tool. Export and download.
- Unzip and upload the folder into your X3 gallery via FTP.
- Upload a placeholder image that represents the panorama.
- Make sure the placeholder image has the same _name as the uploaded folder, for example folder image "mycube.jpg" and folder "_mycube".
- Done! X3 will do the rest, and will even support your Marzipano export configuration (data.js).
The Marzipano Tool allows you to create multiple cube panoramas in a single export. To support an exported project with multiple scenes, simply follow the same procedure as above, and then:
- Upload a placeholder image for EACH of the scenes in your panorama export.
- Add "path=FOLDERNAME" [screen] to parameters for each of the placeholder images, effectively pointing to the export folder name.
- If the names of your placeholder images match the names of your panoramas, no further action is required. Optionally, you can target specific scenes with parameters "scene_id=SCENEID" [screen] or "scene_index=3" [screen].
If your cube folder path does not match the placeholder file name (_mycube => mycube.jpg), you can instead use the path parameter to point to the folder that contains the exported panorama. You can also add remote paths here (CDN), but you will then need to point the path directly to the folder that contains the tiles (*/export/tiles/0-scene-name) and also assign the levels parameter to let X3 know how many levels the cube has [screen].
Flat Instructions
----------------------
Flat [demo] (non-spherical) multi-resolution gigapixel images exported from tools like Pano2VR and Krpano. Since these tools export their own configuration for their own native viewer, it can be tedious to configure for X3.
- Upload a placeholder image that represents the flat panorama.
- Upload your flat project folder into the same gallery folder by FTP.
- Make sure the placeholder image and project folder have the same _name, for example image flat_pano.jpg and folder _flat_pano.
- Done! If your pano folder contains a pano.xml config file (Krpano or Pano2VR), X3 will auto-detect configuration.
If your exported project doesn't have a pano.xml file or the exporter tool is unknown, you will need manually apply flat parameters url_format, tilesize, width and height. Example:
Code
url_format=l1/%0v/l1_%0v_%0h.jpg&tilesize=2048&width=1024,3072,6144,12288,23552&height=404,1208,2416,4832,9260
CUSTOM CONTENT panorama links
You can also use the X3 panorama plugin directly in your custom CONTENT section. Simply add a link with the data-panorama attribute, and include any of the panorama parameters. * Since X3 cannot detect panorama sources added to custom HTML links, you will need to provide sufficient info in parameters. A couple of examples:
Open an equirectangular panorama, making sure to declare the width:
Code
<a href="{{path}}source.jpg" data-panorama="width=8192">Click here</a>
Code
<a href="{{path}}placeholder.jpg" data-panorama="path=mycube&levels=3">Click here</a>
---
The End
Not really :sunglasses: I have a few improvements to include before non-beta release. Suggestions, questions and comments are more than welcome. X3.26.0 will also include other features, but panorama plugin will be the main feature.