Photosphere Viewer for React.JS
npm install react-photo-sphere-viewerOriginal Wrapped Library: PhotoSphereViewer Version: 5.4.0 [NEW] Now the component version is composed by the semantic version of the wrapper and the version of the original library. For example, the current version is 3.4.0-psv5.4.0. This means that the wrapper is in version 3.4.0 and the original library psv is in version 5.4.0.
React.App.-.Personale.-.Microsoft.Edge.2022-07-21.17-50-44.mp4
This is a simple React component that allows you to display a 360° photo sphere. It is based on PhotoSphereViewer by Mistic100. This component is a well managed wrapper around the original JS library. It is easy to use and has a lot of features. It is also easy to customize. It is also easy to extend. Addictional features are:
- Little Planet Mode: display the panorama like a little planet (Similar to the DJI drones exported panoramas)
- Using React
import './App.css';
import { ReactPhotoSphereViewer } from 'react-photo-sphere-viewer';
import React from 'react';
function App() {
return (
<div className="App">
<ReactPhotoSphereViewer src="Test_Pano.jpg" height={'100vh'} width={"100%"}></ReactPhotoSphereViewer>
</div>
);
}
export default App;- Using Next.js
import './App.css';
import React, { useEffect, useRef } from 'react';
import dynamic from 'next/dynamic';
// import { ReactPhotoSphereViewer } from 'react-photo-sphere-viewer';
const ReactPhotoSphereViewer = dynamic(
() =>
import('react-photo-sphere-viewer').then(
(mod) => mod.ReactPhotoSphereViewer
),
{
ssr: false,
}
);
export default function Home() {
return (
<div className="App">
<ReactPhotoSphereViewer src="Test_Pano.jpg" height={'100vh'} width={"100%"}></ReactPhotoSphereViewer>
</div>
);
}Important
To use <ReactPhotoSphereViewer /> in Next.js with App Router, make sure to include "use client" in your component embedding the viewer. Refer to the documentation for more details.
I've added this custom effect that allows you to display the panorama like a little planet. To enable it, you need to pass the littlePlanet prop to the component.
<ReactPhotoSphereViewer src="Test_Pano.jpg" littlePlanet={true} height={'100vh'} width={"100%"}></ReactPhotoSphereViewer>The effect is this:
React.App.-.Personale.-.Microsoft.Edge.2022-07-21.17-47-56.mp4
type standardProps = {
src: string; // The URL of the panorama image.
height: number;
width?: number;
containerClass?: string; // The class name of the div that wrap the component.
littlePlanet?: boolean; // Display the panorama like a little planet.
}Currently all options of the original library are supported and exported as props.
/**
* Viewer configuration
* @link https://photo-sphere-viewer.js.org/guide/config.html
*/
type ViewerConfig = {
container: HTMLElement | string;
panorama?: any;
overlay?: any;
/** @default 1 */
overlayOpacity?: number;
/** @default equirectangular */
adapter?: AdapterConstructor | [AdapterConstructor, any];
plugins?: Array<PluginConstructor | [PluginConstructor, any]>;
/** @default null */
caption?: string;
/** @default null */
description?: string;
/** @default null */
downloadUrl?: string;
/** @default null */
loadingImg?: string;
/** @default 'Loading...' */
loadingTxt?: string;
/** @default `container` size */
size?: CssSize;
/** @default false */
fisheye?: boolean | number;
/** @default 30 */
minFov?: number;
/** @default 90 */
maxFov?: number;
/** @default 50 */
defaultZoomLvl?: number;
/** @deprecated use `defaultYaw` */
defaultLong?: number;
/** @deprecated use `defaultPitch` */
defaultLat?: number;
/** @default 0 */
defaultYaw?: number | string;
/** @default 0 */
defaultPitch?: number | string;
/** @default `0,0,0` */
sphereCorrection?: SphereCorrection;
/** @default 1 */
moveSpeed?: number;
/** @default 1 */
zoomSpeed?: number;
/** @deprecated use the 'autorotate' plugin */
autorotateDelay?: number | null;
/** @deprecated use the 'autorotate' plugin */
autorotateIdle?: boolean;
/** @deprecated use the 'autorotate' plugin */
autorotateSpeed?: string | number;
/** @deprecated use the 'autorotate' plugin */
autorotateLat?: number;
/** @deprecated use the 'autorotate' plugin */
autorotateZoomLvl?: number;
/** @default true */
moveInertia?: boolean;
/** @default true */
mousewheel?: boolean;
/** @default true */
mousemove?: boolean;
/** @default false */
mousewheelCtrlKey?: boolean;
/** @default false */
touchmoveTwoFingers?: boolean;
/** @default true */
useXmpData?: boolean;
panoData?: PanoData | PanoDataProvider;
requestHeaders?: Record<string, string> | ((url: string) => Record<string, string>);
/** @default '#000' */
canvasBackground?: string;
/** @default false */
withCredentials?: boolean;
/** @default 'autorotate zoom move download description caption fullscreen' */
navbar?: boolean | string | Array<string | NavbarCustomButton>;
lang?: {
zoom: string;
zoomOut: string;
zoomIn: string;
moveUp: string;
moveDown: string;
moveLeft: string;
moveRight: string;
download: string;
fullscreen: string;
menu: string;
close: string;
twoFingers: string;
ctrlZoom: string;
loadError: string;
[K: string]: string;
};
keyboard?: boolean | Record<string, ACTIONS>;
};This code is generated from the original library. Click here to see documentation.
To use the standard plugins provided by the original library, you need to pass the plugins prop to the component. The prop is an array of plugins. Each plugin can be a constructor or an array of constructor and options. To include them in the component, you need to import them directly from the "react-photo-sphere-viewer" package.
The only "third-party" plugin that is supported is the "Lensflare" plugin. To use it, you need to import it from the "react-photo-sphere-viewer" package.
import { ReactPhotoSphereViewer, CompassPlugin, MarkersPlugin } from 'react-photo-sphere-viewer';
function App() {
const plugins = [
[CompassPlugin, {
hotspots: [
{ longitude: '0deg' },
{ longitude: '90deg' },
{ longitude: '180deg' },
{ longitude: '270deg' },
],
}],
[MarkersPlugin, {
markers: [
{
id: 'polygon',
polygonPx: [2941, 1413, 3042, 1402, 3222, 1419, 3433, 1463, 3480, 1505, 3438, 1538, 3241, 1543, 3041, 1555, 2854, 1559, 2739, 1516, 2775, 1469, 2941, 1413 ],
svgStyle : {
fill : 'rgba(255,0,0,0.2)',
stroke : 'rgba(255, 0, 50, 0.8)',
strokeWidth: '2px',
},
data: { compass: 'rgba(255, 0, 50, 0.8)' },
},
{
id: 'polyline',
polylinePx: [2478, 1635, 2184, 1747, 1674, 1953, 1166, 1852, 709, 1669, 301, 1519, 94, 1399, 34, 1356],
svgStyle: {
stroke : 'rgba(80, 150, 50, 0.8)',
strokeLinecap : 'round',
strokeLinejoin: 'round',
strokeWidth : '20px',
},
data: { compass: 'rgba(80, 150, 50, 0.8)' },
},
],
}],
]
return (
<div className="App">
<ReactPhotoSphereViewer src="Test_pano.jpg" plugins={plugins} height={'100vh'} width={"100%"}></ReactPhotoSphereViewer>
</div>
);
}Calling plugin methods and handling events from outside the component NEW
To handle events from outside the component, you need to declare the callback function in the onReady(instance: Viewer) prop. The instance is the instance of the viewer. You can call the plugin methods using the instance.getPlugin() method. The instance.getPlugin() method returns the plugin instance. You can call the plugin methods using the plugin instance.
const handleReady = (instance) => {
const markersPlugs = instance.getPlugin(MarkersPlugin);
if (!markersPlugs)
return;
markersPlugs.addMarker({
id: "imageLayer2",
imageLayer: "drone.png",
size: { width: 220, height: 220 },
position: { yaw: '130.5deg', pitch: '-0.1deg' },
tooltip: "Image embedded in the scene"
});
markersPlugs.addEventListener("select-marker", () => {
console.log("asd");
});
}
return (
<div className="App">
<ReactPhotoSphereViewer src="Test_pano.jpg" plugins={plugins} height={'100vh'} width={"100%"} onReady={handleReady}></ReactPhotoSphereViewer>
</div>
);Click here to see plugins documentation.
To use the standard library adapters provided by the original library, you need to pass the adapter prop to the component. The prop is an array of adapters. Each adapter can be a constructor or an array of constructor and options. To include them in the component, you need to import them directly from the "react-photo-sphere-viewer" package.
import { CubemapAdapter, CubemapAdapterOptions } from 'react-photo-sphere-viewer';Click here to see adapters documentation.
All documented events are exported as props (function names).
type ViewerEvents = {
onPositionChange?(lat: number, lng: number, instance: Viewer): any;
onZoomChange?(data: events.ZoomUpdatedEvent & { type: "zoom-updated"; }, instance: Viewer): any;
onClick?(data: events.ClickEvent & { type: "click"; }, instance: Viewer): void;
onDblclick?(data: events.ClickEvent & { type: "dblclick"; }, instance: Viewer): void;
onReady?(instance: Viewer): void;
}You can declare an event callback:
const handleClick = (data: events.ClickEvent & { type: "click"; }) => {
console.log(data);
}and then:
{/*Pass the callback to the component*/}
<ReactPhotoSphereViewer ref={photoSphereRef} src="Test_Pano.jpg" onClick={handleClick}></ReactPhotoSphereViewer>To see the original events, click here.
To trigger a method you need to pass a reference to the component and access the method directly.
// Create a reference to the component
const photoSphereRef = React.createRef<ReactPhotoSphereViewer>();
// And calling the method
photoSphereRef.current.zoom(10);
// Or to be sure that the component is mounted
React.useEffect(() => {
if (!photoSphereRef.current)
return;
photoSphereRef.current.animate({
yaw: 0,
pitch: 0,
zoom: 55,
speed: '10rpm',
}); // Or any other method
}, [photoSphereRef]);And then:
{/*Pass the ref to the component*/}
<ReactPhotoSphereViewer ref={photoSphereRef} src="Test_Pano.jpg"></ReactPhotoSphereViewer>Currently managed methods are:
- animate(options: AnimateOptions)
- destroy()
- rotate(options: { x: number, y: number })
- setOption(option: keyof ViewerOptions, value: any)
- setOptions(options: ViewerOptions)
- zoom(value: number)
- zoomIn()
- zoomOut()
- resize(size: CssSize)
- enterFullscreen()
- exitFullscreen()
- toggleFullscreen()
- isFullscreenEnabled()
- getPlugin(pluginName: string)
- getPosition()
- getZoomLevel()
- getSize()
- needsUpdate()
- autoSize()
- setPanorama(path: string, options?: object)
- setOverlay(path: string, opacity?: number)
- toggleAutorotate()
- showError(message: string)
- hideError()
- startKeyboardControl()
- stopKeyboardControl()
To see the original methods, click here.
MIT © elius94