Dear panorama folks! We have created a panorama demo that simulates how the panorama plugin may work in X3 once implemented. The demo includes examples of a few different panorama source types. Check it out:
panorama.photo.gallery
Forewords
First of all, I need to emphasize that attempting to "automate" panorama integration in a web gallery (like X3) is not flawless science. There are reasons why not many web apps automatically support this out-of-the-box, and also a reason why most panorama projects are pre-created from publisher-tools like
krpano,
ptgui,
marzipano and
pano2vr (something X3 is not).
Panorama Achievements Unlocked :star:
As you will find in the demo, we have achieved the following X3 panorama integrations:
- Gallery support for automatic panoramas from single-file equirectangular sources.
- Gallery support for panoramas from multi-resolution / multi-file cube panorama sources.
- Gallery support for multi-resolution / multi-file flat (gigapixel) images.
- Support to add any of the above to X3 custom content with some basic html tags.
- Support for loading panorama source tiles from remote CDN (when specified by configuration).
X3 Panorama Viewer
We have created our own pano viewer interface, functionality and controls, although internally we use
marzipano as panorama render engine. As you can see in the demo, you can navigate between panoramas directly from the viewer. Buttons, options and controls will be configurable of course, but in the demo, we have included all options. I would also like to me it clear that the panorama "popup" viewer is entirely separate from the standard X3 popup, because they are entirely incompatible. For example, the panorama viewer requires key-controls to control the view (not prev/next), touch "swipe" gestures are reserved for navigating the view, "arrow" buttons must not be confused with prev/next buttons and "zoom" works entirely differently. Although you can mix panorama images in an X3 gallery with non-panorama images, I would say that is a
bad idea because it will mix popup methods
Viewer UI Controls
We have included an unprecedented amount of viewer controls:
- Drag/swipe gestures to navigate the panorama. Obviously.
- Click or tap (touch) to "look to" any area of the panorama. This is currently set to single-click/tap, although it might be better as double-tap. Thoughts?
- Deviceorientation "gyroscope" view *only available for mobile devices. This feature is really cool, although at the same time, it's quite useless ... To be able to benefit from "gyroscope" mode, I would literally have to stand up on two feet and rotate myself 360 degrees just to view a panorama, when I can easily achieve the same by swiping with a finger. Personally, I would prefer to keep this option unavailable by default.
- Arrow keyboard keys left, right, up down.
- WASD keyboards keys w=up, a=left, s=down, d=left (often used in games)
- QE keyboard keys to control "roll". PS! Try holding Q+A buttons simultaneously for a rollercoaster ride.
- -+ keyboard keys to zoom in and out.
- Buttons zoom in, zoom out, up, down, left and right.
- Previous/Next scene buttons to navigate between multiple panoramas.
- Fullscreen button
- Autorotate / play button
- View SRC button (opens the src image of the panorama in the standard X3 popup).
Ok, let's get started with the Panorama types ...
---
EQUIRECTANGULAR FORMAT
https://panorama.photo.gallery/#equirect
As referenced earlier in this thread, single-file equirectangular images is the simplest way to display panoramas in X3. There are
PROS and
CONS with the equirectangular format, but the one huge benefit is that it's a
single file that requires no preparation ... You simply upload the equirectangular JPG image source into an X3 gallery, and it will open and render in the panorama viewer.
4096 px width
One of the limitations of equirectangular image sources, is that browsers have a MAX_TEXTURE_SIZE that limits how many px wide the src can be. For modern browsers on modern desktops, this value is a generous 16384 px. However, for the majority of devices, including mobile, the limit is set to
4096 px. This therefore means that logically, you will need to limit your equirectangular image sources to 4096 px. In stats, you will see that 99.99% browsers support 4096 px, while only 22.6% support 16384 px:
http://webglstats.com/webgl/parameter/MAX_TEXTURE_SIZE
This is not really a bad thing, because you will need to limit your image to a reasonable file size for loading into browser anyway. Width 4096 px provides sufficient quality for good-looking panoramas on almost all screens, although you cannot expect much from "zoom". I would almost go as far as to say that zoom is kinda useless or un-interesting for spherical panoramas anyway. Furthermore, if your server has reasonable memory resources, it is likely X3 is able to create resized preview images from your 4096 px images. If you however upload LARGER images (for instance 8192 px), it is unlikely your server has the capacity to resize the images, and there will therefore be errors. On a side-note, if your server does have sufficient memory resources, it would be possible for you to upload 8192 px panoramas, and then have X3 create 4096 px versions for devices that only support 4096. However, if you really need ultra high-res panoramas, you should consider using multi-file "cube" format instead.
For the sake of comparison, we have one equirectangular source uploaded at
8196 px for testing. As you will see, file size is almost quadruple that of the 4096 px images. Furthermore, only devices that support textures >= 8196 px will be able to load this file, while other devices will load the 4096 px "fallback" version. Although offering a higher level of zoom, unless are on some ultra-high-res screen (eg 3000 px +), this size provides little benefit.
https://panorama.photo.gallery/#pano=4.sunset
Even smaller images (down to 2048 px) provide "acceptable" quality levels on most screens for basic 360/180 spherical view. Example from a
3200 x 1600 px image at
890kb:
https://panorama.photo.gallery/#pano=3.dubrovnik
JPG Compression
With low or no compression, your 4096 px JPG's may weigh in at 5-15 MB, which is a bit much since they need to entirely load into browser before they can display. Because panoramas are "rendered" and do not display on a per-pixel basis in the visitors browser and because a 4096 px is normally zoomed out, I would recommend using relatively high jpg compression for your 4096 px equirectangular image sources. In our demo, our sources are mostly around ~1MB. I optimized our test images with
imageoptim at 79%.
Recommendation :star:
Resize your rectangular JPG sources to
4096 px with slightly
more compression that you are used to.
How will it work in X3?
Simply upload your equirectangular images into any X3 gallery and they will be detected by the panorama plugin.
+ PROS
- Single-file panorama source. Simply upload into X3 gallery.
- CONS
* To fully understand the "cons" of equirectangular, please refer to advantages of "cube" format in next section.
- Texture width limitation (4096 px).
- Does not load progressively like multi-file cube format.
- Does not support multi-levels, eg. loading source data based on screen resolution and current zoom level.
- Not really a format for "zoom".
---
MULTI-RES CUBE FORMAT
https://panorama.photo.gallery/#cube
Over to multi-file cube panoramas, this format has a few advantages not available to the equirectangular format. The main
disadvantage of the cube format, is that you will have to manually upload a directory of tiles exported from a tool (eg.
Marzipano tool), so it requires more work and preparation on your side. As you will see in the demo, CUBE panoramas look very similar to the equirectangular panoramas. However, there are several advantages /
PROS:
+ Progressive Loading
Since a cube panorama consists of multiple files, tiles will load progressively into the pano viewer on-demand as they are required by the current screen/view/zoom. This means the initial view will often display faster than equirectangular, and files will load progressively as the panorama is navigated.
+ Multiple Levels / Multi-resolution
Cube panoramas support multiple
levels of resolution. The advantage of this is not primarily the extended level of zoom, but the ability to load a specific cube level depending on the resolution of the display. For example, a high-resolution screen (eg. macbook 15" retina 2880 px) may skip level 1 and 2, immediately loading level 3 into view, as the screen is capable of taking advantage of the higher resolution at default zoom/FOV. Smaller screens may initially load level 1. Multiple levels does not necessarily mean there is more zoom, although, depending on the amount of levels, there is often more zoom than with equirectangular. The amount of zoom available is
inversely proportional with the screen display resolution ... For example, an ultra-high-res 5000 px will likely have very little or no zoom at all, because the pano is already displaying at it's maxResolution value (to prevent pixelation). Meanwhile, a non-retina low-resolution 640 px mobile device will have a large amount of zoom, in which case cube-levels will load progressively as visitor zooms in.
+ Optimal Loading
Considering the above, different devices will be able to load cube level depending on their screen resolution.
+ No Size Limits
Since cube panoramas are cut into multiple files, there are no size limitations to worry about.
- CONS
As mentioned, implementing cube format panoramas requires more effort and preparation:
How will it work in X3?
To enable cube format panoramas in an X3 gallery:
- Upload a placeholder preview image for the panorama. Usually an equirectangular image representation.
- By FTP, upload the folder with the cube tiles, and give it the same name as the image. For example "pano.jpg" should have a directory "pano".
- Enable the panorama plugin for the page.
X3 will detect that the image has a folder with the same name and interpret it as a multi-file cube panorama. It will then count the amount of folders within the tiles directory, so that it can automatically create the configuration for the cube format. Done!
PS! Although X3 may support cube formats exported from other tools, for now you should use the
Marzipano tool to prepare your multi-resolution cube format panoramas for X3.
Equirectangular vs Cube
For comparison, I have added examples of the same panorama in both equirectangular and cube format:
https://panorama.photo.gallery/#pano=10.walls
https://panorama.photo.gallery/#pano=11.walls
* Apart from the subtle advantages of the cube format, you will likely find they look almost identical.
---
MULTI-RES FLAT
https://panorama.photo.gallery/#flat :clap: Thanks @GeoPal for many of the examples.
Flat (non-spherical) multi-resolution images are not really "panoramas", but they use the same "viewer" interface. The main objective of multi-res flat images, is to be able to serve extremely large images (often referred to as "gigapixel") with extreme zoom levels. This is achieved by progressively serving the tiles for the image on-demand based on screen and zoom-level.
Adding multi-res flat images to X3 is similar in preparation as the panorama cube format, but with one additional step: Since X3 does not know the tile size, levels or folder name structure, this needs to be provided as a configuration.
How will it work in X3?
To enable multi-resolution flat images in an X3 gallery:
- Upload a placeholder preview image.
- By FTP, upload the folder with the tiles, and give it the same name as the image. For example "flat.jpg" should have a directory "flat".
- Enable the panorama plugin for the page.
- Go to page Gallery > Edit mode and add pano configuration parameters for the image.
The flat pano configuration will at it's minimum look something like below:
tilesize=2048&width=1024,3072,6144,12288,23552&height=404,1208,2416,4832,9260
The values are derived from the XML file created by the tool used to create the tiles. For example KRpano:
https://panorama.photo.gallery/images/1 ... s/pano.xml
Panorama tiles loaded from remote CDN
https://panorama.photo.gallery/#pano=18.lakatnik
Thanks to @GeoPal, it has been made clear that many gigapixel panoramas have their images hosted on a CDN or remote storage like Amazon. We have therefore included an option to load tiles from a remote source path. Config for the panorama example above with tiles loaded from Amazon storage:
tilesize=2048&url_format=l{z}/{y}/l{z}_{y}_{x}.jpg&zero_padding=2&index_start=1&width=1024,2560,5120,10240,20480,39936,80384&height=450,1126,2252,4502,9004,17558,35340&path=https://s3.eu-west-2.amazonaws.com/gigapanos/Lakatnik/Lakatnik.tiles
Single-image FLAT panorama :thumbsdown:
https://panorama.photo.gallery/#pano=19.canal
For the sake of testing, I have also implemented a single-file flat (non-spherical) panorama. The advantage, as with the equirectangular format, is that a single file can simply be uploaded into X3, without any configuration. However, I have concluded that this feature is
USELESS because of the following reasons:
- Considering it is a single massive file, it is often too large to load as a single file.
- As with the equirectangular format, only a fraction of browsers ~30% [ref] currently support textures larger than 4096 px. Thus, if you have to limit your image to 4096 px, it is really nothing more than a large image.
- It is unlikely your server has the memory capacity to resize images at 8192 px anyway.
- Ultimately, there is really not much advantage to viewing this image in a "panorama viewer".
---
Panoramas in custom html content
The above covers panoramas in the X3
gallery, but you will also be able to open your panoramas from your X3 page's
content section by using some basic html tags:
Open an equirectangular panorama:
<a href="{{path}}equirect.jpg" data-pano>Click here</a>
Opening a multi-res cube or flat panorama will require some options.
<a href="{{path}}cube.jpg" data-pano data-pano-options="option1=X&option2=X">Click here</a>
You may of course use an image for the link. For example
<a href="{{path}}equirect.jpg" data-pano><img src="{{path}}equirect.jpg" alt=""></a>
* It is unlikely we will support embedding panoramas directly into a page instead of opening in the full viewer. I can't see how this is useful in any way, as it is clumsy to navigate a panorama embedded at specific width/height, especially on mobile, and clearly desirable to open the panoramas at full window size.
---
Panorama Global Options
There will be a range of global settings that can be applied from the panorama-plugin settings, some perhaps also on a per-page basis. These options will mostly include options for the interface, like buttons, controls and speed.
Per-Panorama Options
You will not be required to add configuration for equirectangular or cube panoramas added to an X3 gallery. However, there will be several
optional OPTIONS available for you to apply on a per-panorama basis. Options for panoramas added to the gallery will be available from a page's
Gallery > Edit mode (alongside image titles and descriptions). Options for panoramas added to a page's "content", will be available to set from attribute
data-pano-options="{OPTIONS}". The format of options will be parameter style:
There may be dozens of per-panorama options, some that only apply to spherical panoramas (equirectangular and cube), and some that only apply to flat gigapixel panoramas.
---
How does X3 detect a panorama and panorama type in the gallery?
When the panorama plugin is enabled for a gallery, X3 will check for panoramas in the following order:
- If the uploaded image has config parameters, X3 will check the config, which may refer to a flat panorama.
- If the image has a sibling folder with identical name, it will be considered a multi-file spherical cube panorama.
- If the image is exactly 2:1 aspect (360/180), it will be considered a single-file equirectangular panorama.
- If none of the above apply, it will be considered a NORMAL image, that opens in the standard X3 popup.
---
A few additional observations:
Multi-file equirectangular:thumbsdown:
Technically, it would be possible to serve multiple size levels for the equirectangular format. For example, you could upload an 8192 px image and X3 could create intermediate sizes 4096 and 2048, which would benefit smaller screens and/or devices that don't support high-res textures.
HOWEVER (emphasis), this seems like an unproductive approach: 1. Your server will struggle to resize images that big, 2. Zooming in/out would start loading and replacing large single-file textures and 3. It's simply inferior to the progressive "cube" format.
Panorama Intro Plugin :sunglasses:
I was thinking, wouldn't it be cool to create a panorama-intro plugin, similar to the
video-intro plugin, but using a panorama? There are some pitfalls with this, as in limited controls (because it has to go "under" the menu), CPU usage (since it will autorotate also after visitor scrolls past it), and it may not work in all browsers.
MaxResolution, maxVFov, maxHFov and startFov :thinking:
As mentioned initially in this post, spherical panoramas are not an exact science. Technically, it's just a flat distorted image stretched into a spherical view. There are defaults for
maxResolution (how far one can zoom into the image), and
FOV (field of view), but these are just "smart" defaults. Essentially, on initial load, you want as much FOV as possible, but without having the panorama seem "warped" at the far left and right. Zoom and FOV will also depend on the size and aspect of the screen that the panorama is being viewed from, and to some degree the nature of the image itself. You will be able to set these
optional parameters globally and on a per-panorama basis.
Will hotspots be supported?
No, not for now. Hotspots are added from various panorama publisher tools, explicitly for their own panorama viewer. It is a bit much to expect X3 to read configurations created for 3rd party panorama viewers.
That's it for now folks!
Happy to get any feedback. I will start implementing into X3 shortly ...