Skip to main content
Version: v5.3

IafViewer Photosphere

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​

On IafViewerDBM, set mode to "photo" and pass appId. Configure the viewer with the photosphere prop group:

PropTypePurposeDefault
photosphere.enablebooleanEnable/disable the Photosphere viewerfalse
photosphere.visiblebooleanShow or hide the enabled widget without turning the mode off. When false, the launcher can still open the widget if showLauncher is true.true
photosphere.configobjectmodelUriBase (base URL for panorama images) and model (scene data). See Photosphere Configuration Object.{ modelUriBase: '' }
photosphere.eventHandlerfunction(event) => void for Photosphere events, such as a scene change or a hotspot clickundefined
photosphere.displayModeenumDEFAULT, SPLIT, FULLSCREEN, FIXEDDEFAULT
photosphere.showToolbarbooleanShow/hide the widget's own toolbartrue
photosphere.showLauncherbooleanShow/hide the main-toolbar button that opens the viewertrue
photosphere.alignmentenumLEFT_TOP, LEFT_BOTTOM, RIGHT_TOP, RIGHT_BOTTOM. Applies only to SPLIT and FIXED.RIGHT_TOP
photosphere.ordernumberDisplay order when several widgets are shown6
photosphere.marginnumberMargin around the widget0

For the full prop reference with required flags, see IafViewer — Photosphere. IafViewerDBM forwards the same photosphere props.

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.