Three Panorama Controls

Panorama controls for three.js.

Demo: https://ps3fsk.csb.app

Contents

• Setup
• Usage
  • Vanilla
  • React Three Fiber
• Configuration Options

Setup

Install the package.

npm install three-panorama-controls

Usage

The package can be used both in vanilla JavaScript and with React Three Fiber.

Vanilla

CodeSandbox

import * as THREE from "three";
import { PanoramaControls } from "three-panorama-controls";

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(
  75,
  window.innerWidth / window.innerHeight,
  0.1,
  1000
);
camera.position.z = 5;

const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// Setup a mesh with the panorama image applied as a texture to a sphere.
const sphere = new THREE.SphereGeometry(10, 60, 20);
// Invert the geometry on the x-axis so that all of the faces point inward.
sphere.scale(-1, 1, 1);
const texture = new THREE.TextureLoader().load("./path/to/panorama/image.png");
texture.colorSpace = THREE.SRGBColorSpace;
const material = new THREE.MeshBasicMaterial({ map: texture });
const mesh = new THREE.Mesh(sphere, material);
scene.add(mesh);

// Use panorama controls.
const panoramaControls = new PanoramaControls(camera, renderer.domElement);

function animate() {
  requestAnimationFrame(animate);
  panoramaControls.update();
  renderer.render(scene, camera);
}
animate();

React Three Fiber

CodeSandbox

import React from "react";
import { createRoot } from "react-dom/client";
import { BackSide, TextureLoader } from "three";
import { Canvas, useLoader } from "@react-three/fiber";
import { PanoramaControls } from "three-panorama-controls/react";

const Scene = () => {
  const imageMap = useLoader(TextureLoader, "sample-panorama.jpg");

  return (
    // Setup a mesh with the panorama image applied as a texture to a sphere.
    // And invert the mesh on the x-axis to avoid mirroring the image.
    <mesh scale={[-1, 1, 1]}>
      <sphereGeometry args={[10, 60, 20]} />
      <meshBasicMaterial map={imageMap} side={BackSide} />
    </mesh>
  );
};

createRoot(document.getElementById("root")).render(
  <Canvas>
    <Scene />
    {/* Use panorama controls. */}
    <PanoramaControls makeDefault />
  </Canvas>
);

Configuration Options

The controls can be configured by setting the following properties.

Option	Default	Description
enabled: boolean	true	Enable or disable the controls.
zoomable: boolean	true	Whether the user can zoom or not.
minFov: number	10	The minimum field of view (FOV). Limits how much the user can zoom in.
maxFov: number	90	The maximum field of view (FOV). Limits how much the user can zoom out.
zoomSpeed: number	0.05	Sets the speed of zooming.
panSpeed: number	0.1	Sets the speed of panning (moving the view).

Setting the options in vanilla JavaScript.

const panoramaControls = new PanoramaControls(camera, renderer.domElement);
panoramaControls.enabled = true;
panoramaControls.zoomable = true;
panoramaControls.minFov = 20;
panoramaControls.maxFov = 75;
panoramaControls.zoomSpeed = 0.025;
panoramaControls.panSpeed = 0.05;

Setting the options in React Three Fiber.

<PanoramaControls
  makeDefault
  enabled
  zoomable
  minFov={20}
  maxFov={75}
  zoomSpeed={0.025}
  panSpeed={0.05}
/>