Skip to main content
Version: v5.1

Photosphere features

Overview#

The IafViewer allows you to explore a model using photosphere technology. Photospheres are 360 degree panoramic images which provide an immersive view of a location.

This page demonstrates how to implement 360° panoramic viewing using the {{photosphere}} property of {{IafViewerDBM}}. The photosphere viewer enables immersive interior exploration through equirectangular panoramic images.

Core components#

IafViewerDBM with Photosphere Mode#

IafViewerDBM is the database-managed viewer component that supports 360° panoramic viewing for immersive interior visualization.

Key Props for Photosphere Rendering#

Refer to the props examples showen below.

{  mode: "photo",              // Mode identifier for photosphere rendering  appId: string,              // Application identifier
  // Photosphere-specific configuration (REQUIRED)  photosphere: {    enable: boolean,           // Enable/disable photosphere viewer    config: {                 // Configuration object      modelUriBase: string,   // Base URL for image assets      model: object          // Model object with scene data    },    displayMode: enum,        // Display layout mode    showToolbar: boolean,     // Toolbar visibility    alignment: enum          // Widget alignment position  }}

Photosphere Configuration Object#

The {{config}} property contains settings for loading and displaying panoramic images. See explanations below.

{  modelUriBase: string,      // Base URL path for panorama images  model: {                   // Model object defining tour structure    id: string,              // Unique identifier    defaultImage: string,    // Default panorama image filename    defaultScene: object,    // Initial scene configuration    scenes: array           // Optional: Additional scenes for navigation  }}

Required Properties#

enable (Boolean)

Enables or disables the photosphere viewer.

photosphere: {  enable: true  // Must be true to activate}

config (Object)

Configuration object containing model and asset information.

config.modelUriBase (String)

Base URL path for loading panorama images.

config: {  modelUriBase: "/reference/invicara/models/360Tour/"}

Usage: Combined with image filenames to create full image URLs#

Example: {{modelUriBase and defaultImage}} → {{/reference/invicara/models/360Tour/lobby.jpg}}

config.model (Object)

Model object defining the photosphere tour structure.

Required Model Properties:

{{model.id}} - Unique identifier for the photosphere model

model: {  id: "BuildingTour"}

{{model.defaultImage}} - Filename of the default panorama image.

model: {  defaultImage: "lobby.jpg"}

{{model.defaultScene}} - Initial scene configuration

defaultScene: {  id: "lobby-scene",           // Required: Scene identifier  title: "Building Lobby",     // Required: Display title  type: "equirectangular",     // Required: Panorama type  panorama: "lobby.jpg",        // Required: Image filename  autoLoad: true,              // Optional: Auto-load on mount  // Optional camera settings  hfov: 110,                   // Horizontal field of view (degrees)  pitch: 0,                    // Initial pitch angle (-90 to 90)  yaw: 0,                      // Initial yaw angle (-180 to 180)  // Optional navigation  hotSpots: []                 // Array of hotspot objects}

{{model.scenes}} - Additional scenes for navigation (Optional)

scenes: [  {    id: "scene-id-2",                    // Required: Scene identifier    title: "Conference Room",              // Required: Display title    type: "equirectangular",              // Required: Panorama type    imageSource: "/path/to/image2.jpg",   // Required: Full or relative path    hfov: 110,                           // Optional    pitch: 0,                            // Optional    yaw: 0,                              // Optional    hotSpots: []                         // Optional  }]

HotSpot Configuration#

HotSpots enable navigation between scenes.

Scene navigation hotspot example 

{  pitch: 2.0,           // Vertical position on panorama  yaw: -90.0,          // Horizontal position on panorama  type: "scene",       // Navigation hotspot  text: "Go to Room",  // Tooltip text  sceneId: "room-id",  // Target scene identifier  targetYaw: 0,        // Camera yaw when entering target  targetPitch: 0       // Camera pitch when entering target}

How to set up files#

Step 1: Define Photosphere Configuration#

//photo/config.js

export const PHOTO_CONFIG = {  modelUriBase: "/reference/invicara/models/360Tour/"};
export const publicPath = "/reference/invicara";
const BUILDING_TOUR = {  id: "BuildingTour",  defaultImage: "lobby.jpg",  defaultScene: {    id: "lobby",    autoLoad: true,    title: "Building Lobby",    type: "equirectangular",    panorama: "lobby.jpg",    hfov: 110,    pitch: 0,    yaw: 0,    hotSpots: [      {        pitch: 0,        yaw: 90,        type: "scene",        text: "Go to Reception",        sceneId: "reception",        targetYaw: 180,        targetPitch: 0      }    ]  },  scenes: [    {      id: "reception",      title: "Reception Area",      type: "equirectangular",      imageSource: ${publicPath}/models/360Tour/reception.jpg,      hfov: 110,      pitch: 0,      yaw: 180,      hotSpots: [        {          pitch: 0,          yaw: -90,          type: "scene",          text: "Back to Lobby",          sceneId: "lobby",          targetYaw: 0,          targetPitch: 0        }      ]    }  ]};
export const AVAILABLE_MODELS = {  "BuildingTour": BUILDING_TOUR};

Step 2: Create Photosphere Properties Helper#

// photo/properties.js

import { APPLICATION_ID } from "../states";import { PHOTO_CONFIG, AVAILABLE_MODELS } from "./config";
export function getPhotoSphereProperties(buildingName = "BuildingTour") {  return {    mode: "photo",    appId: APPLICATION_ID,    config: {      ...PHOTO_CONFIG,      model: AVAILABLE_MODELS[buildingName]    }  };}

Component Summary#

Main components#

The main components are:

  • {{photosphere}} - Photosphere viewer configuration (always required for photosphere rendering)
  • {{photosphere.config.modelUriBase}} - Base URL for panorama images (required)
  • {{photosphere.config.model}} - Model object with scene data (required)

Optional Components#

The optional components are:

  • {{photosphere.config.model.scenes}} - Additional scenes for navigation (optional)
  • {{photosphere.displayMode}} - Display layout mode (optional, defaults to DEFAULT)
  • {{photosphere.showToolbar}} - Toolbar visibility (optional, defaults to true)
  • {{photosphere.alignment}} - Widget alignment (optional, for SPLIT or FIXED modes)

Camera settngs#

Field of View (hfov)#

Controls the zoom level of the panorama

Range: 50-120 degrees

Default: 110 degrees Lower value = more zoomed in

Pitch (Vertical Angle)#

Initial vertical camera angle

Range: -90 to 90 degrees

Negative = looking down

Positive = looking up

0 = straight ahead

Yaw (Horizontal Angle)#

Initial horizontal camera angle

Range: -180 to 180 degrees

0 = forward

-90 = left

90 = right

Display Modes#

FULLSCREEN#

Photosphere viewer covers entire viewport. Best for standalone photosphere viewing.

See example below.

photosphere: {  enable: true,  displayMode: IafEvmUtils.EVMDisplayMode.FULLSCREEN,  showToolbar: true}

DEFAULT#

Photosphere viewer shares space with other views. Best for multi-view integration.

See example below.

photosphere: {  enable: true,  displayMode: IafEvmUtils.EVMDisplayMode.DEFAULT,  alignment: IafEvmUtils.EVMWidgetAlignment.RIGHT_TOP,  showToolbar: true}

SPLIT#

Photosphere viewer splits viewport with another view.

See example below.

photosphere: {  enable: true,  displayMode: IafEvmUtils.EVMDisplayMode.SPLIT,  alignment: IafEvmUtils.EVMWidgetAlignment.LEFT_BOTTOM}

Widget alignment options#

The alignment options are:

  • LEFT_TOP
  • LEFT_BOTTOM
  • RIGHT_TOP
  • RIGHT_BOTTOM

These control the viewer position in SPLIT or FIXED display modes.