fix "sphereCorrection" type & update doc about panoData

mistic100 · mistic100 · commit d02a17a3c4bc · 2024-07-28T15:05:37.000+02:00
diff --git a/docs/.vuepress/components/CropPlayground.vue b/docs/.vuepress/components/CropPlayground.vue
@@ -65,7 +65,7 @@
             <div class="md-layout-item">
                 <label class="md-caption">Pose Heading</label>
                 <vue-slider
-                    v-model="panoData.poseHeading"
+                    v-model="sphereCorrection.pan"
                     :min="0"
                     :max="360"
                     :marks="[0, 90, 180, 270, 360]"
@@ -76,7 +76,7 @@
             <div class="md-layout-item">
                 <label class="md-caption">Pose Pitch</label>
                 <vue-slider
-                    v-model="panoData.posePitch"
+                    v-model="sphereCorrection.pitch"
                     :min="-90"
                     :max="90"
                     :marks="[-90, 0, 90]"
@@ -87,7 +87,7 @@
             <div class="md-layout-item">
                 <label class="md-caption">Pose Roll</label>
                 <vue-slider
-                    v-model="panoData.poseRoll"
+                    v-model="sphereCorrection.roll"
                     :min="-180"
                     :max="180"
                     :marks="[-180, -90, 0, 90, 180]"
@@ -138,10 +138,12 @@ export default {
             croppedHeight: null,
             croppedX: null,
             croppedY: null,
-            poseHeading: null,
-            posePitch: null,
-            poseRoll: null,
         },
+        sphereCorrection: {
+            pan: null,
+            pitch: null,
+            roll: null,
+        }
     }),
     mounted() {
         // ugly hack to load PSV from jsdelivr as an ES module
@@ -227,9 +229,9 @@ __s.remove();
             this.panoData.croppedHeight = height;
             this.panoData.croppedX = croppedX;
             this.panoData.croppedY = croppedY;
-            this.panoData.poseHeading = 0;
-            this.panoData.posePitch = 0;
-            this.panoData.poseRoll = 0;
+            this.sphereCorrection.pan = 0;
+            this.sphereCorrection.pitch = 0;
+            this.sphereCorrection.roll = 0;
         },
 
         updateOutput() {
@@ -244,25 +246,35 @@ __s.remove();
       <GPano:CroppedAreaImageHeightPixels>${this.panoData.croppedHeight}</GPano:CroppedAreaImageHeightPixels>
       <GPano:CroppedAreaLeftPixels>${this.panoData.croppedX}</GPano:CroppedAreaLeftPixels>
       <GPano:CroppedAreaTopPixels>${this.panoData.croppedY}</GPano:CroppedAreaTopPixels>
-      <GPano:PoseHeadingDegrees>${this.panoData.poseHeading}</GPano:PoseHeadingDegrees>
-      <GPano:PosePitchDegrees>${this.panoData.posePitch}</GPano:PosePitchDegrees>
-      <GPano:PoseRollDegrees>${this.panoData.poseRoll}</GPano:PoseRollDegrees>
+      <GPano:PoseHeadingDegrees>${this.sphereCorrection.pan}</GPano:PoseHeadingDegrees>
+      <GPano:PosePitchDegrees>${this.sphereCorrection.pitch}</GPano:PosePitchDegrees>
+      <GPano:PoseRollDegrees>${this.sphereCorrection.roll}</GPano:PoseRollDegrees>
     </rdf:Description>
   </rdf:RDF>
 </x:xmpmeta>
 <?xpacket end="r"?>`;
         },
 
         loadViewer() {
+            const sphereCorrection = {
+                pan: -this.sphereCorrection.pan,
+                pitch: -this.sphereCorrection.pitch,
+                roll: -this.sphereCorrection.roll,
+            };
+
             if (this.viewer) {
-                this.viewer.setPanorama(this.imageData, { panoData: this.panoData });
+                this.viewer.setPanorama(this.imageData, {
+                    panoData: this.panoData,
+                    sphereCorrection: sphereCorrection,
+                });
             } else {
                 this.viewer = new this.Viewer({
                     panorama: this.imageData,
                     container: 'viewer',
                     loadingImg: 'https://photo-sphere-viewer-data.netlify.app/assets/loader.gif',
                     panoData: this.panoData,
-                    navbar: ['zoom', 'fullscreen'],
+                    sphereCorrection: sphereCorrection,
+                    navbar: ['zoom', 'move', 'fullscreen'],
                     size: {
                         height: 500,
                     },
diff --git a/docs/guide/adapters/equirectangular.md b/docs/guide/adapters/equirectangular.md
@@ -82,6 +82,9 @@ The data can also contains angular values:
 -   Pose Heading
 -   Pose Pitch
 -   Pose Roll
+-   Initial View Heading
+-   Initial View Pitch
+-   Initial Horizontal FOV
 
 ![XMP_pano_pixels](../../images/XMP_pano_pixels.png)
 
@@ -101,15 +104,21 @@ The XMP payload is as follow:
   <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
     <rdf:Description rdf:about="" xmlns:GPano="http://ns.google.com/photos/1.0/panorama/">
       <GPano:ProjectionType>equirectangular</GPano:ProjectionType>
+      <!-- cropping information -->
       <GPano:FullPanoWidthPixels>6000</GPano:FullPanoWidthPixels>
       <GPano:FullPanoHeightPixels>3000</GPano:FullPanoHeightPixels>
       <GPano:CroppedAreaImageWidthPixels>4000</GPano:CroppedAreaImageWidthPixels>
       <GPano:CroppedAreaImageHeightPixels>2000</GPano:CroppedAreaImageHeightPixels>
       <GPano:CroppedAreaLeftPixels>1000</GPano:CroppedAreaLeftPixels>
       <GPano:CroppedAreaTopPixels>500</GPano:CroppedAreaTopPixels>
+      <!-- pose information -->
       <GPano:PoseHeadingDegrees>0</GPano:PoseHeadingDegrees>
       <GPano:PosePitchDegrees>0</GPano:PosePitchDegrees>
       <GPano:PoseRollDegrees>0</GPano:PoseRollDegrees>
+      <!-- initial view information -->
+      <GPano:InitialViewHeadingDegrees>0</GPano:InitialViewHeadingDegrees>
+      <GPano:InitialViewPitchDegrees>0</GPano:InitialViewPitchDegrees>
+      <GPano:InitialHorizontalFOVDegrees>0</GPano:InitialHorizontalFOVDegrees>
     </rdf:Description>
   </rdf:RDF>
 </x:xmpmeta>
@@ -130,17 +139,28 @@ You can also directly pass the values to Photo Sphere Viewer with the `panoData`
 const viewer = new PhotoSphereViewer.Viewer({
     container: 'viewer',
     panorama: 'path/to/panorama.jpg',
+
+    // cropping information
     panoData: {
         fullWidth: 6000,
         fullHeight: 3000,
         croppedWidth: 4000,
         croppedHeight: 2000,
         croppedX: 1000,
         croppedY: 500,
-        poseHeading: 0, // 0 to 360
-        posePitch: 0, // -90 to 90
-        poseRoll: 0, // -180 to 180
     },
+
+    // pose information
+    // sphereCorrection: {
+    //   pan: '0deg',
+    //   tilt: '0deg',
+    //   roll: '0deg',
+    // },
+
+    // initial view information
+    // defaultYaw: '0deg',
+    // defaultPitch: '0deg',
+    // defaultZoomLvl: 50,
 });
 ```
 
diff --git a/docs/guide/config.md b/docs/guide/config.md
@@ -205,29 +205,15 @@ Requires two fingers to rotate the panorama. This allows standard touch-scroll n
 
 #### `sphereCorrection`
 
--   type: `{ pan: double, tilt: double, roll: double }`
+-   type: `{ pan: double | string, tilt: double | string, roll: double | string }`
 -   default: `{ pan:0, tilt:0, roll: 0 }`
 
-Allows to rotate the panorama sphere. Angles are in radians.
+Allows to fix the panorama orientation.
 
-**Note:** if the XMP data and/or `panoData` contains heading/pitch/roll data, they will be applied before `sphereCorrection`.
+**Note:** if the XMP data contains pose heading/pitch/roll data, they will be applied before `sphereCorrection`.
 
 ![pan-tilt-toll](../images/pan-tilt-roll.png)
 
-#### `moveSpeed`
-
--   type: `double`
--   default `1`
-
-Speed multiplicator for panorama moves. Used for click move, touch move and navbar buttons.
-
-#### `zoomSpeed`
-
--   type: `double`
--   default `1`
-
-Speed multiplicator for panorama zooms. Used for mouse wheel, touch pinch and navbar buttons.
-
 #### `panoData`
 
 -   type: `object | function<Image, PanoData, PanoData>`
@@ -243,9 +229,6 @@ panoData: {
   croppedHeight: 2000,
   croppedX: 1000,
   croppedY: 500,
-  poseHeading: 270, // 0 to 360
-  posePitch: 0, // -90 to 90
-  poseRoll: 0, // -180 to 180
 }
 ```
 
@@ -262,12 +245,24 @@ panoData: (image, xmpData) => ({
 });
 ```
 
-**Note:** if the XMP data and/or `panoData` contains heading/pitch/roll data, they will be applied before `sphereCorrection`.
-
 ::: warning
-Only the default [equirectangular](./adapters/equirectangular.md) adapter and low-resolution panorama of [equirectangular-tiles](./adapters/equirectangular-tiles.md) supports `panoData`, for other adapters you can only use [`sphereCorrection`](#spherecorrection) if the tilt/roll/pan needs to be corrected.
+Only the default [equirectangular](./adapters/equirectangular.md) adapter supports `panoData`.
 :::
 
+#### `moveSpeed`
+
+-   type: `double`
+-   default `1`
+
+Speed multiplicator for panorama moves. Used for click move, touch move and navbar buttons.
+
+#### `zoomSpeed`
+
+-   type: `double`
+-   default `1`
+
+Speed multiplicator for panorama zooms. Used for mouse wheel, touch pinch and navbar buttons.
+
 #### `requestHeaders`
 
 -   type: `object | function<string, object>`
diff --git a/docs/plugins/virtual-tour.md b/docs/plugins/virtual-tour.md
@@ -155,7 +155,7 @@ virtualTour.setNodes([
         links: [{ nodeId: '2' }],
         markers: [markerLighthouse],
         gps: [-80.156479, 25.666725, 3],
-        panoData: { poseHeading: 327 },
+        sphereCorrection: { pan: '33deg' },
     },
     {
         id: '2',
@@ -166,7 +166,7 @@ virtualTour.setNodes([
         links: [{ nodeId: '3' }, { nodeId: '1' }],
         markers: [markerLighthouse],
         gps: [-80.156168, 25.666623, 3],
-        panoData: { poseHeading: 318 },
+        sphereCorrection: { pan: '42deg' },
     },
     {
         id: '3',
@@ -176,7 +176,7 @@ virtualTour.setNodes([
         caption: `[3] ${caption}`,
         links: [{ nodeId: '4' }, { nodeId: '2' }, { nodeId: '5' }],
         gps: [-80.155932, 25.666498, 5],
-        panoData: { poseHeading: 310 },
+        sphereCorrection: { pan: '50deg' },
     },
     {
         id: '4',
@@ -186,7 +186,7 @@ virtualTour.setNodes([
         caption: `[4] ${caption}`,
         links: [{ nodeId: '3' }, { nodeId: '5' }],
         gps: [-80.156089, 25.666357, 3],
-        panoData: { poseHeading: 78 },
+        sphereCorrection: { pan: '-78deg' },
     },
     {
         id: '5',
@@ -196,7 +196,7 @@ virtualTour.setNodes([
         caption: `[5] ${caption}`,
         links: [{ nodeId: '6' }, { nodeId: '3' }, { nodeId: '4' }],
         gps: [-80.156292, 25.666446, 2],
-        panoData: { poseHeading: 190 },
+        sphereCorrection: { pan: '170deg' },
     },
     {
         id: '6',
@@ -206,7 +206,7 @@ virtualTour.setNodes([
         caption: `[6] ${caption}`,
         links: [{ nodeId: '5' }, { nodeId: '7' }],
         gps: [-80.156465, 25.666496, 2],
-        panoData: { poseHeading: 295 },
+        sphereCorrection: { pan: '65deg' },
     },
     {
         id: '7',
@@ -216,7 +216,7 @@ virtualTour.setNodes([
         caption: `[7] ${caption}`,
         links: [{ nodeId: '6' }],
         gps: [-80.15707, 25.6665, 3],
-        panoData: { poseHeading: 250, posePitch: 3 },
+        sphereCorrection: { pan: '110deg', pitch: -3 },
     },
 ], '2');
 ```
diff --git a/examples/plugin-virtual-tour.html b/examples/plugin-virtual-tour.html
@@ -73,7 +73,7 @@
                         },
                     ],
                     gps: [-80.15635, 25.66675, 3],
-                    panoData: { poseHeading: 327 },
+                    sphereCorrection: { pan: '33deg' },
                     map: { x: 660, y: 570, color: '#fffd99' },
                     plan: { color: '#fffd99' },
                 },
@@ -94,7 +94,7 @@
                         },
                     ],
                     gps: [-80.15611, 25.6667, 5],
-                    panoData: { poseHeading: 318 },
+                    sphereCorrection: { pan: '42deg' },
                     map: { x: 750, y: 590, color: '#ffb075' },
                     plan: { color: '#ffb075' },
                 },
@@ -110,7 +110,7 @@
                         { nodeId: '5', position: { pitch: 0, yaw: '270deg' }, linkOffset: { depth: 2 } },
                     ],
                     gps: [-80.15593, 25.66659, 5],
-                    panoData: { poseHeading: 310 },
+                    sphereCorrection: { pan: '50deg' },
                     map: { x: 815, y: 640, color: '#b7c1ff' },
                     plan: { color: '#b7c1ff' },
                 },
@@ -125,7 +125,7 @@
                         { nodeId: '5', position: { pitch: 0, yaw: '300deg' } },
                     ],
                     gps: [-80.15611, 25.666435, 3],
-                    panoData: { poseHeading: 78 },
+                    sphereCorrection: { pan: '-78deg' },
                     map: { x: 750, y: 705, color: '#64dbdb' },
                     plan: { color: '#64dbdb' },
                 },
@@ -141,7 +141,7 @@
                         { nodeId: '4', position: { pitch: 0, yaw: '150deg' } },
                     ],
                     gps: [-80.15628, 25.666485, 3],
-                    panoData: { poseHeading: 190 },
+                    sphereCorrection: { pan: '170deg' },
                     map: { x: 685, y: 685, color: '#9c9af9' },
                     plan: { color: '#9c9af9' },
                 },
@@ -156,7 +156,7 @@
                         { nodeId: '5', position: { pitch: 0, yaw: '130deg' } },
                     ],
                     gps: [-80.156465, 25.666486, 2],
-                    panoData: { poseHeading: 295 },
+                    sphereCorrection: { pan: '65deg' },
                     map: { x: 615, y: 685, color: '#de91f2' },
                     plan: { color: '#de91f2' },
                 },
@@ -168,7 +168,7 @@
                     caption: `[7] ${caption}`,
                     links: [{ nodeId: '6', position: { pitch: 0, yaw: '80deg' } }],
                     gps: [-80.15709, 25.66634, 3],
-                    panoData: { poseHeading: 250, posePitch: 3 },
+                    sphereCorrection: { pan: '110deg', pitch: -3 },
                     map: { x: 385, y: 745, color: '#8bed82' },
                     plan: { color: '#8bed82' },
                 },
diff --git a/packages/core/src/model.ts b/packages/core/src/model.ts
@@ -37,10 +37,10 @@ export type CssSize = {
 /**
  * Object defining angular corrections to a sphere
  */
-export type SphereCorrection = {
-    pan?: number;
-    tilt?: number;
-    roll?: number;
+export type SphereCorrection<T = number | string> = {
+    pan?: T;
+    tilt?: T;
+    roll?: T;
 };
 
 /**
diff --git a/packages/core/src/services/DataHelper.ts b/packages/core/src/services/DataHelper.ts
@@ -285,7 +285,7 @@ export class DataHelper extends AbstractService {
     /**
      * Ensure a SphereCorrection object is valid
      */
-    cleanSphereCorrection(sphereCorrection: SphereCorrection): SphereCorrection {
+    cleanSphereCorrection(sphereCorrection: SphereCorrection): SphereCorrection<number> {
         return {
             pan: parseAngle(sphereCorrection?.pan || 0),
             tilt: parseAngle(sphereCorrection?.tilt || 0, true),
