Search…

X3 Photo Gallery Support Forums

Search…
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 11412
Joined: 30 Sep 2006, 07:37

X3 Panorama Plugin [X3.26.0 Beta]

10 Dec 2018, 06:53

We have now released new X3.26.0 BETA, which includes the new X3 Panorama Plugin [X3 Pro] The panorama plugin will require extensive documentation, but I will have to keep instructions short and sweet for now. Please help test from various platforms, and please feel free to make suggestions, comments and questions about anything.

X3 Panorama Demo  :thumbsup:
https://demo.photo.gallery/examples/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:
  1. Equirectangular / Spherical panorama loaded from a single-file source [wiki].
  2. Cube / Spherical panorama loaded from multi-file cube source [wiki].
  3. Flat / Flat (non-spherical) multi-resolution gigapixel images.
Panorama Controls
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
Panorama Settings
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, zoom, scene_id, scene_index, geo. Parameters are added in a query-string format:
Code
option1=2&option2=hello&option3=false
Image


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.
Image


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.
  1. Resize your image to 4096 px wide.
  2. Upload to your X3 panorama page.
  3. Done! X3 will do the rest.
Equirectangular larger than 4096 px?
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.
  1. Create your cube panorama from the Marzipano Tool. Export and download.
  2. Unzip and upload the folder into your X3 gallery via FTP.
  3. From the X3 panel, hide the folder.
  4. Upload a placeholder image that represents the panorama.
  5. Make sure the placeholder image has the same name as the uploaded folder, for example folder "mycube" and image "mycube.jpg".
  6. Done! X3 will do the rest, and will even support your Marzipano export configuration (data.js).
Multiple cube export
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:
  1. Upload a placeholder image for EACH of the scenes in your panorama export.
  2. Add "path=FOLDERNAME" [screen] to parameters for each of the placeholder images, effectively pointing to the export folder name.
  3. 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].
Cube path parameter
You can 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.
  1. Upload a placeholder image that will represent the flat panorama.
  2. Upload your flat project folder into the same gallery folder by FTP.
  3. Make sure the placeholder image and project folder have the same name, for example image my_flat_pano.jpg and folder my_flat_pano.
  4. Configure flat parameters tilesizezero_padding, index_start and url_format to match the exported folder structure of your flat export. You will normally be able to figure out these values from the XML file included in your export. * You only need to add parameters that are non-default (see Settings > Panorama > Advanced> Flat).
---

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>
Open a cube panorama, making sure to declare the folder path and levels:
Code
<a href="{{path}}placeholder.jpg" data-panorama="path=mycube&levels=3">Click here</a>
Parameters: 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, zoom, scene_id, scene_index, geo

---

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.
 
User avatar
Martin
Experienced
Posts: 628
Joined: 31 Jan 2011, 04:24

Re: X3 Panorama Plugin [X3.26.0 Beta]

10 Dec 2018, 08:52

Hi Karl,

(I deleted my post in the 'Firefox vs Chrome' thread)

Yes, the panorama plug-in works great!

The interface looks great, with lot of options ... I'm going to study it...
Thnx a lot!

My folder:
http://martinbroeze.nl/more/fortasperen/

Update: it works like a charm on my iPad too... 
ImageImage
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 11412
Joined: 30 Sep 2006, 07:37

Re: X3 Panorama Plugin [X3.26.0 Beta]

10 Dec 2018, 09:31

Martin wrote: Yes, the panorama plug-in works great!
The resolution of my images is far too small and the pano's are very coarse... so I have to upload bigger files...
But the interface looks great, with lot of options ... I'm going to study it...
Thnx a lot!

My example folder with the rough looking pano's:
http://martinbroeze.nl/more/fortasperen/

Update: it works like a charm on my iPad too... 
Thanks Martin. I put a lot of effort into this plugin. Regarding equirectangular images, although any size will "work", you should definitely consider larger image dimensions for higher quality. Since FOV (field of view) might be 120 degrees (depending on several factors), the screen may only show 1/3 of the image width. Thus, a 3000 px wide image, would fully satisfy a 1000px wide screen. To fully satisfy 1920 px wide screen, image should be > 5760 px. As you can see in my post, we recommend 4096 px, because it's acceptable quality vs file size, and also because majority of devices only support 4096 px [ref]. Next step up is 8192 px, and if I was you, I would either resize images DOWN to 4096 px or use 8192 px ...
 
User avatar
Martin
Experienced
Posts: 628
Joined: 31 Jan 2011, 04:24

Re: X3 Panorama Plugin [X3.26.0 Beta]

10 Dec 2018, 09:59

mjau-mjau wrote: Thanks Martin. I put a lot of effort into this plugin.
Yes, I can see that you put an enormous amount of effort in this plug-in.
But then again, it covers a lot of functionality, like being able to choose the default view paramaters...

mjau-mjau wrote: Regarding equirectangular images, although any size will "work", you should definitely consider larger image dimensions for higher quality. Since FOV (field of view) might be 120 degrees (depending on several factors), the screen may only show 1/3 of the image width. Thus, a 3000 px wide image, would fully satisfy a 1000px wide screen. To fully satisfy 1920 px wide screen, image should be > 5760 px. As you can see in my post, we recommend 4096 px, because it's acceptable quality vs file size, and also because majority of devices only support 4096 px [ref]. Next step up is 8192 px, and if I was you, I would either resize images DOWN to 4096 px or use 8192 px ...
My originals are 5400px, but indeed I downsized them to 4096 and that looks good on my iPad.
Though on my 27inch screen (2560px) the panos look still a bit grainy. This is partly due to the images themselves because they were taken under dark circumstances with a cheap 180degree fisheye.

The step to use images of 8192 will make them twice as big... about 5Mb... and this will have an impact on loading them.

There comes a new feature to my mind :-)
In order to assess the default view parameters it would come in handy to be able to see them on screen while viewing a pano.

So, all I have to do now is ordering a new fisheye lens and have some fun with it :-)
ImageImage
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 11412
Joined: 30 Sep 2006, 07:37

Re: X3 Panorama Plugin [X3.26.0 Beta]

10 Dec 2018, 10:17

Martin wrote:My originals are 5400px, but indeed I downsized them to 4096 and that looks good on my iPad.
Though on my 27inch screen (2560px) the panos look still a bit grainy. This is partly due to the images themselves because they were taken under dark circumstances with a cheap 180degree fisheye.
Yep, I noticed they were a bit grainy by default. You can try 8192 px images, which will look slightly better on your 2560 px screen, although file size will be larger.
Martin wrote:The step to use images of 8192 will make them twice as big... about 5Mb... and this will have an impact on loading them.
It might actually make them 3-4 times as big, as 8192 px image contains 4x times as many pixels as 4096 px image ... but depends on compression. It's not a huge problem with larger file sizes ... I think a user can wait a few seconds extra as they can clearly see a high-quality panorama is loading. For me, the issue is more about logistics ... as soon as you want to upload 8192 px images, you will need to make sure your server is capable of resizing down to 4096 px and preview-size width.

You would get to a point where you may instead want to export to CUBE format, which automatically solves these issues: 1. No texture limit, 2. Cube would load level depending on screen resolution, 3. Progressive loading of tiles.
Martin wrote:There comes a new feature to my mind :-)
In order to assess the default view parameters it would come in handy to be able to see them on screen while viewing a pano.
This is not essentially a feature we will be building into X3. If you export for CUBE with the Marzipano Tool, you can already set default view parameters in real-time.

I must say up front, FOV (field of view) is an incredibly complex feature, which depends on the panorama, screen aspect, screen resolution, maxResolution, maxVFov and maxHFov settings
 
User avatar
Martin
Experienced
Posts: 628
Joined: 31 Jan 2011, 04:24

Re: X3 Panorama Plugin [X3.26.0 Beta]

10 Dec 2018, 13:58

Works great on my Android too!
(Samsung A5 / Chrome & Samsung browsers)
ImageImage
 
User avatar
GeoPal
Experienced
Posts: 180
Joined: 20 Dec 2007, 17:56

Re: X3 Panorama Plugin [X3.26.0 Beta]

11 Dec 2018, 13:22

Hi Karl,
I want to personally thank you for the effort for the pano plugin! Everything looks just great, tried the examples from Martin, works on windows desktop and on android 8. Can't wait to load the panos shot for 10 years and test the limits :)
Thanks again, will show some pano usage soon (I hope).
Best wishes, G
 
User avatar
EHRETic
Experienced
Posts: 107
Joined: 02 Feb 2011, 21:26

Re: X3 Panorama Plugin [X3.26.0 Beta]

12 Dec 2018, 13:57

Hi,

I've assembled panoramas that can up to 20000 px width (1/3 format). Those are already assembled in one picture in Lightroom (orginal are TIFF or DNG and exported JPG of course)

Would "Flat" work with one single JPG image ? 
Yes or no, what would be your recommendations for the picture(s) to upload (size, quality, amount) ?

Thanks in advance and best regards
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 11412
Joined: 30 Sep 2006, 07:37

Re: X3 Panorama Plugin [X3.26.0 Beta]

12 Dec 2018, 14:23

EHRETic wrote:I've assembled panoramas that can up to 20000 px width (1/3 format). Those are already assembled in one picture in Lightroom (orginal are TIFF or DNG and exported JPG of course)

Would "Flat" work with one single JPG image ? 
Yes or no, what would be your recommendations for the picture(s) to upload (size, quality, amount) ?
It is not entirely clear to me if your images are 360/180 degrees SPHERICAL, or if they are ultra-high resolution non-spherical FLAT "gigapixel" images. I assume the latter. Can you please clarify?
 
User avatar
GeoPal
Experienced
Posts: 180
Joined: 20 Dec 2007, 17:56

Re: X3 Panorama Plugin [X3.26.0 Beta]

14 Dec 2018, 08:28

This is my first try :) Hope you like it

Ayvalik, Turkey

I used multilevel Marzipano export.
Thanks, Karl!
Best, G
 
User avatar
Martin
Experienced
Posts: 628
Joined: 31 Jan 2011, 04:24

Re: X3 Panorama Plugin [X3.26.0 Beta]

14 Dec 2018, 08:51

I like it...
A world with two sun's :)
ImageImage
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 11412
Joined: 30 Sep 2006, 07:37

Re: X3 Panorama Plugin [X3.26.0 Beta]

14 Dec 2018, 08:54

GeoPal wrote:This is my first try :) Hope you like it
Ayvalik, Turkey
Nice to see a working version!

On a side note, from X3.26.1 (coming soon), I will be recommending to rename your exported folders (cube or flat) starting with _underscore: /_foldername/. Panorama export folders often contain HUNDREDS of subfolders, and are slowing down the control panel folder menu processing. With X3.26.1, I will include a function to ignore children of folders that start with _underscore. X3 will still auto-detect panorama folders /_name/ or /name/ from placeholder image "name.jpg".
 
User avatar
GeoPal
Experienced
Posts: 180
Joined: 20 Dec 2007, 17:56

Re: X3 Panorama Plugin [X3.26.0 Beta]

14 Dec 2018, 09:10

I see, Marzipano really makes a lot of files. That is the reason I will probably not use multiresolution output from it, but third party like krpano- single level. Will test it and write back.
p.s. from marzipano output from many panos- it puts 0-, 1-, 2-...etc in front of the names of the pano files. Do we need to put this indexes on the file names also, to have exact match?
 
User avatar
mjau-mjau
X3 Wizard
Topic Author
Posts: 11412
Joined: 30 Sep 2006, 07:37

Re: X3 Panorama Plugin [X3.26.0 Beta]

14 Dec 2018, 14:50

GeoPal wrote:I see, Marzipano really makes a lot of files. That is the reason I will probably not use multiresolution output from it, but third party like krpano- single level. Will test it and write back.
Yes it does, and so does your flat exports also of course, and this is essentially what is the benefit (better progressive loading, and better adaption to all screen sizes). Even if it's not multi-resolution, it would still be multi-file (at least 6 cube faces). Marzipano have an example of a single-res cubic sphere here:
http://www.marzipano.net/demos/cube-sin ... index.html

If you are really worried about "amount of files" stored on your server because of PRICE/COST, then why not just use equirectangular 8192px? That should be the ultimate solution. KRpano single level will still be at least 6 files of course, and if you want it high-resolution, it will be massive tile-sizes (2048px at least), which negates all advantages of cube format in the first place. In fact, 2048 cube faces single-level panorama is approximately identical to a 8192 px single-file equirect, but without any benefits (just more work). Thus, I am curious to know why you would want to do this.
GeoPal wrote:p.s. from marzipano output from many panos- it puts 0-, 1-, 2-...etc in front of the names of the pano files. Do we need to put this indexes on the file names also, to have exact match?
I don't know if you remember, but it's not easy to configure marzipano to read an export format from another unrelated tool like krpano. It's already setup for FLAT pano's and you can see how tedious that is ... But more importantly, I don't see any point. If you are worried about too many files and don't want multi-resolution, then use equirect. What would be the advantage of exporting a single-level cube from krpano?

You can't just add a random cube export from a different tool. X3 will need to know ALL details (including tilesize), and then I would need to add multiple parameters (like we have for FLAT). X3 won't loop through ALL images and folders and try to figure out the format for you. If I see any advantage of this, I would consider it.
 
User avatar
GeoPal
Experienced
Posts: 180
Joined: 20 Dec 2007, 17:56

Re: X3 Panorama Plugin [X3.26.0 Beta]

15 Dec 2018, 13:19

I will definitely try 4k and 8k resolutions, thanks for the tip! Will write back what I've done.
Best, G