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.