Close #243 Support tiled panorama, externalize cubemap

mistic100 · Apr 5, 2021 · df56f8d · df56f8d
1 parent 9fe015a
commit df56f8d
Show file tree

Hide file tree

Showing 32 changed files with 1,555 additions and 492 deletions.
diff --git a/docs/.jsdoc/index.md b/docs/.jsdoc/index.md
@@ -9,11 +9,13 @@
 - [Viewer](PSV.Viewer.html)
 - [Events](PSV.html#.event:autorotate)
 - [Plugins](PSV.plugins.html)
+- [Adapters](PSV.adapters.html)
 
 ---
 
 ## Exported members
 
+- [AbstractAdapter](PSV.adapters.AbstractAdapter.html) - Base class for render adapters
 - [AbstractButton](PSV.buttons.AbstractButton.html) - Base class for plugins buttons
 - [AbstractPlugin](PSV.plugins.AbstractPlugin.html) - Base class for plugins
 - [Animation](PSV.Animation.html) - Animations manager

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -40,9 +40,17 @@ module.exports = {
             'events',
             'navbar',
             'markers',
-            'cubemap',
             'cropped-panorama',
             'migration-v3',
+            {
+              title: 'Adapters',
+              path: '/guide/adapters/',
+              collapsable : false,
+              children: [
+                'adapters/cubemap',
+                'adapters/tiles',
+              ],
+            },
             {
               title: 'Reusable components',
               path: '/guide/components/',

diff --git a/docs/README.md b/docs/README.md
@@ -20,8 +20,8 @@ features:
 footer: Licensed under MIT License, documentation under CC BY 3.0
 ---
 
-::: tip New playground
-Test Photo Sphere Viewer with you own panorama in the [Playground](playground.md)
+::: tip New tiles support
+Improve the loading time of big panorams with the the [Tiles adapter](guide/adapters/tiles.md).
 :::
 
 <iframe style="width: 100%; height: 600px;" src="//jsfiddle.net/mistic100/5r684etx/embedded/result,js/dark" allowfullscreen="allowfullscreen" frameborder="0"></iframe>

diff --git a/docs/guide/README.md b/docs/guide/README.md
@@ -42,7 +42,7 @@ You can also [download the latest release](https://github.com/mistic100/Photo-Sp
 
 Include all JS & CSS files in your page manually or with your favorite bundler and init the viewer.
 
-The `panorama` must be an [equirectangular projection](https://en.wikipedia.org/wiki/Equirectangular_projection) of your photo. You can also use [cubemap projection](./cubemap.md) with a special syntax.
+The `panorama` must be an [equirectangular projection](https://en.wikipedia.org/wiki/Equirectangular_projection) of your photo. Other modes are supported through [adapters](./adapters/).
 
 :::: tabs
 

diff --git a/docs/guide/adapters/README.md b/docs/guide/adapters/README.md
@@ -0,0 +1,32 @@
+# Adapters
+
+Adapters are small pieces of code responsible to load the panorama texture(s) in the THREE.js scene.
+
+The supported adapters are:
+- `equirectangular`: the default adapter, used to load full or partial equirectangular panoramas
+- [cubemap](cubemap.md): used to load cubemaps projections (six textures)
+- [equirectangular tiles](tiles.md): used to load tiled equirectangular panoramas
+
+## Import an adapter
+
+Official adapters (listed on the left menu) are available in the the main `photo-sphere-viewer` package inside the `dist/adapters` directory.
+
+**Example for the Cubemap adapter:**
+
+:::: tabs
+
+::: tab Direct import
+```html
+<!-- base imports of PSV and dependencies -->
+
+<script src="https://cdn.jsdelivr.net/npm/photo-sphere-viewer@4/dist/adapters/cubemap.min.js"></script>
+```
+:::
+
+::: tab ES import
+```js
+import CubemapAdapter from 'photo-sphere-viewer/dist/adapters/cubemap';
+```
+:::
+
+::::
diff --git a/docs/guide/adapters/cubemap.md b/docs/guide/adapters/cubemap.md
@@ -0,0 +1,57 @@
+# Cubemap adapter
+
+> [Cube mapping](https://en.wikipedia.org/wiki/Cube_mapping) is a kind of projection where the environment is mapped to the six faces of a cube around the viewer.
+
+This adapter is available in the core `photo-sphere-viewer` package in `dist/adapters/cubemap.js`.
+
+Photo Sphere Viewer supports cubemaps as six distinct image files. The files can be provided as an object or an array. All features of Photo Sphere Viewer are fully supported when using cubemaps but the `fisheye` option gives funky results.
+
+```js
+new PhotoSphereViewer.Viewer({
+  adapter: PhotoSphereViewer.CubemapAdapter,
+  panorama: {
+    left:   'path/to/left.jpg',
+    front:  'path/to/front.jpg',
+    right:  'path/to/right.jpg',
+    back:   'path/to/back.jpg',
+    top:    'path/to/top.jpg',
+    bottom: 'path/to/bottom.jpg',
+  },
+});
+```
+
+::: warning
+This adapter does not use `panoData` option. You can use `sphereCorrection` if the tilt/roll/pan needs to be corrected.
+:::
+
+
+## Example
+
+<iframe style="width: 100%; height: 600px;" src="//jsfiddle.net/mistic100/1jL5yc2r/embedded/result,js/dark" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+
+
+## Configuration
+
+When using this adapter the `panorama` option and the `setPanorama()` method accept an array or an object of six URLs.
+
+```js
+// Cubemap as array (order is important) :
+panorama: [
+  'path/to/left.jpg',
+  'path/to/front.jpg',
+  'path/to/right.jpg',
+  'path/to/back.jpg',
+  'path/to/top.jpg',
+  'path/to/bottom.jpg',
+]
+
+// Cubemap as object :
+panorama: {
+  left:   'path/to/left.jpg',
+  front:  'path/to/front.jpg',
+  right:  'path/to/right.jpg',
+  back:   'path/to/back.jpg',
+  top:    'path/to/top.jpg',
+  bottom: 'path/to/bottom.jpg',
+}
+```
diff --git a/docs/guide/adapters/tiles.md b/docs/guide/adapters/tiles.md
@@ -0,0 +1,77 @@
+# Equirectangular tiles adapter
+
+> Reduce the initial loading time and used bandwidth by slicing big panoramas into many small tiles.
+
+This adapter is available in the core `photo-sphere-viewer` package in `dist/adapters/equirectangular-tiles.js`.
+
+```js
+new PhotoSphereViewer.Viewer({
+  adapter: PhotoSphereViewer.EquirectangularTilesAdapter,
+  panorama: {
+    width: 6000,
+    cols: 16,
+    rows: 8,
+    baseUrl: 'low_res.jpg',
+    tileUrl: (col, row) => {
+      return `tile_${col}x${row}.jpg`;
+    },
+  },
+});
+```
+
+::: warning
+This adapter does not use `panoData` option. You can use `sphereCorrection` if the tilt/roll/pan needs to be corrected.
+:::
+
+
+## Example
+
+<iframe style="width: 100%; height: 600px;" src="//jsfiddle.net/mistic100/419yhpek/embedded/result,js/dark" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+
+
+## Configuration
+
+When using this adapter the `panorama` option and the `setPanorama()` method accept an object to configure the tiles.
+
+#### `width` (required)
+- type: `number`
+
+Total width of the panorama, the height is always width / 2.
+
+#### `cols` (required)
+- type: `number`
+
+Number of columns, must  be power of two (4, 6, 16, 32, 64) and the maximum value is 64.
+
+#### `rows` (required)
+- type: `number`
+
+Number of rows, must  be power of two (2, 4, 6, 16, 32) and the maximum value is 32.
+
+#### `tileUrl` (required)
+- type: `function: (col, row) => string`
+
+Function used to build the URL of a tile.
+
+#### `baseUrl` (recommended)
+- type: `string`
+
+URL of a low resolution complete panorama image to display while the tiles are loading.
+
+
+## Preparing the panorama
+
+The tiles can be easily generated using [ImageMagick](https://imagemagick.org) software.
+
+Let's say you have a 12.000x6.000 pixels panorama you want to split in 32 columns and 16 rows, use the following command:
+
+```
+magick panorama.jpg -crop 375x375 tile_%04d.jpg
+```
+
+You can also use this [online tool](https://pinetools.com/split-image).
+
+
+::: tip Performances
+It is recommanded to not exceed tiles with a size of 1024x1024 pixels, thus limiting the maximum panorama size to 65.536x32.768 pixels (a little more than 2 Gigapixels).
+:::
diff --git a/docs/guide/config.md b/docs/guide/config.md
@@ -23,29 +23,15 @@ container: document.querySelector('.viewer')
 container: 'viewer' // will target [id="viewer"]
 ```
 
-#### `panorama` (required)
-- type: `string | string[] | object`
+#### `adapter`
+- default: `equirectangular`
 
-Path to the panorama image(s). It must be a single string for equirectangular panoramas and an array or an object for cubemaps.
+Which [adapter](./adapters) used to load the panorama.
 
-```js
-// Equirectangular panorama :
-panorama: 'path/to/panorama.jpg'
-
-// Cubemap as array (order is important) :
-panorama: [
-  'path/to/left.jpg', 'path/to/front.jpg',
-  'path/to/right.jpg', 'path/to/back.jpg',
-  'path/to/top.jpg', 'path/to/bottom.jpg',
-]
-
-// Cubemap as object :
-panorama: {
-  left:   'path/to/left.jpg',  front:  'path/to/front.jpg',
-  right:  'path/to/right.jpg', back:   'path/to/back.jpg',
-  top:    'path/to/top.jpg',   bottom: 'path/to/bottom.jpg',
-}
-```
+#### `panorama` (required)
+- type: `*`
+
+Path to the panorama. Must be a single URL for the default equirectangular adapter. Other adapters support other values.
 
 #### `plugins`
 - type: `array`

diff --git a/docs/guide/cubemap.md b/docs/guide/cubemap.md
diff --git a/docs/plugins/README.md b/docs/plugins/README.md
@@ -6,7 +6,7 @@ Plugins are used to add new functionalities to Photo Sphere Viewer. They can acc
 
 Official plugins (listed on the left menu) are available in the the main `photo-sphere-viewer` package inside the `dist/plugins` directory. Some plugins also have an additional CSS file.
 
-**Example for the Markers plugins:**
+**Example for the Markers plugin:**
 
 :::: tabs
 

diff --git a/example/cubemap.html b/example/cubemap.html
@@ -37,6 +37,7 @@
 <script src="../node_modules/uevent/browser.js"></script>
 <script src="../node_modules/nosleep.js/dist/NoSleep.js"></script>
 <script src="../dist/photo-sphere-viewer.js"></script>
+<script src="../dist/adapters/cubemap.js"></script>
 <script src="../dist/plugins/markers.js"></script>
 
 <script>
@@ -67,6 +68,7 @@
 
   var PSV = new PhotoSphereViewer.Viewer({
     container : 'photosphere',
+    adapter   : PhotoSphereViewer.CubemapAdapter,
     panorama  : panos[0].url,
     caption   : panos[0].desc,
     loadingImg: 'assets/photosphere-logo.gif',