Documentation for uPano v3

Overview

Thanks for using uPano! Don't forget to leave a review on the store page if you liked it, this helps us a lot! https://assetstore.unity.com/packages/tools/integration/upano-126396

Introduction

uPano (Unity Panoramic Framework) is a universal solution for displaying dynamic and static panoramas, and creating virtual tours.

Most of the existing types of panoramas are supported: spherical, cylindrical, cubic panoramas on single or six images, cubemap.

uPano is very easy to learn and use, and is great for people who do not have programming experience. In most usage scenarios, you can make interactive panoramas without creating your own scripts (for more details, see Interactive Element / Events section).

If you have some very specific purpose, uPano has a powerful and easy-to-use API that will allow you to implement any behavior.

Platforms: Standalone, iOS, Android, Universal Windows Platform, WebGL. Other platforms have not been tested, but most likely uPano will work well.

Quick tour creation

Select Window / Infinity Code / uPano / Tour Maker.

Click «Create a new tour». This will create a new empty tour with default settings.

If you are making a tour for Google VR, select Hierarchy / uPano Tour / Tour (Script) / Preset - Google VR. This will remove the keyboard and mouse controls, add Timed Gaze plugin, and apply the required settings for VR.

Drag and drop panorama textures from Project to Tour Maker.

A separate panorama will be created for each texture.

Right-click on the panorama with which you want to start the tour, and select Set Start Panorama in the context menu. The start panorama will be highlighted in green.

To create an interactive element for switching between panoramas, right-click on the panorama from which you want to switch, drag to the target panorama, and release the right mouse button.

This will open Visual Element Editor in connection mode.

Right-click in the place where you want to create an interactive element, and select the element type (HotArea, HotSpot or Direction).

In Tour Maker, outgoing transitions from the selected panorama will be highlighted in blue.

Quickly create a panorama (wizard)

Select Hierarchy / Create / 3D Object / Panorama or Window / Infinity Code / uPano / Wizard to open the panorama wizard.

Select the type of panorama, specify the texture, enable the controls and plugins you need, and click «Create».

uPano will create a fully-ready panorama. Just start the scene, and enjoy the result.

Structure

uPano consists of:

• Pano - main panorama script. Contains the panorama orientation (pan, tilt) and camera settings. Must be present in every panorama.
• Pano Renderers - scripts to displaying the panorama type. Contains settings for mesh, texture, material, shader and UV. Each panorama should use one Pano Renderers.
• Controls - scripts that implement control of the panorama using input sources.
• Plugins - scripts that implement additional features.

Using controls and plugins is optional. You can use them in any combination, or not use at all.

Viewing parameters

To position any point on the panorama, two values are used:

Pan - the horizontal angle of rotation of the camera is 0-360 degrees clockwise, where 0 is north, 90 is east, 180 is south, 270 is west.

Tilt - deviation angle «up» and «down» from the horizon. The range is from -90 to 90 degrees, where 0 is horizontal, 90 is up, and -90 is down.

The point on the panorama that the camera is looking at is called Point of View (POV).

Important: changing the tilt in a cylindrical panorama moves the camera up / down instead of rotating.

The camera has two additional parameters: Fov - the vertical field of view of the camera in degrees. North Pan - the horizontal angle of rotation of the camera is 0-360 degrees clockwise to the true north.

Cameras

uPano requires a camera to properly display and interact with the panorama. To interact with interactive elements, the camera must have a Physics Raycaster component.

By default, uPano creates a new camera to display the panorama. But if you need, you can specify an existing camera. For example, this is very useful when creating a VR application.

To work with multiple cameras, use Multi Camera component.

To work with cameras that have an orthographic projection, use Orthograpthic Cameras component.

Orientation of a panorama

uPano supports panorama orientation in three modes:

1. Rotate Camera (by default) - when changing pan and tilt, the camera that displays the panorama will be rotated. In most cases, it is recommended to use this mode.
2. Rotate Panorama - when changing pan and tilt, the GameObject of the panorama will be rotated.
3. Rotate GameObject - when changing pan and tilt, the specified GameObject will be rotated. This is useful for VR applications when you want to rotate multiple cameras simultaneously.

Important: For the camera created by uPano, only Rotate Camera mode is available. If you want to change the orientation mode, specify an existing camera.

Huge Textures

If you want to use textures with a huge resolution (over 8k), then you can do it using Huge Texture asset. https://assetstore.unity.com/packages/tools/input-management/huge-texture-163576

This will give you a big boost in the quality of the displayed panorama. Read more about how this works in the Huge Texture documentation.

UV

For all types of panoramas, except for a cubic panorama on six images and a cubemap, you can adjust UV of the panorama. For a cubic panorama on single image, you can rotate the side texture to 90, 180 or 270 degrees.

Proper adjustment of UV is very important for a cubic panorama on single image. Even a small error can give a visible seam on the faces of the cube, so be careful when setting up UV.

In most cases, UV for the other types of panoramas do not need to be adjusted. But still it can be useful for solving specific problems. For example, to clip an empty area at the bottom of an image downloaded from Google Street View by third-party ways.

Texture Compression

When you use a texture that you have in a project, the compression and format of the textures depends on your texture import settings.

When you download a texture using Downloader, Google Street View, or set Texture2D using uPano API, the texture compression depends on Pano Renderer / Compress Texture field.

If texture compression is enabled, the texture will be automatically compressed to DXT1 or DXT5 format, which greatly reduces memory usage.

Scriptable Render Pipeline (URP, HDRP)

uPano automatically detects the use of Scriptable Render Pipeline, and if necessary, will ask you to enter the shader parameter where the texture should be set.

WebGL

When you'll try to use Google Street View, you may encounter a CORS (Cross-Origin Resource Sharing) restriction. https://en.wikipedia.org/wiki/Cross-origin_resource_sharing

Currently there is only one way to work around this - use PHP bridge (proxy). Example and instructions you can download here: https://infinity-code.com/downloads/uPanoCORS.zip

Panorama types (Pano Renderers)

Spherical

The basis of the spherical panorama is an image collected from a variety of individual frames in a spherical (equidistant) projection. A characteristic feature of spherical panoramas is the maximum possible viewing angle (360 × 180 degrees).

uPano can display this type of panorama on a sphere or icosahedron. Icosahedron is a regular convex polyhedron, each face of which is an equilateral triangle. Using icosahedron allows you to improve the display of the panorama at the top and bottom points.

To display spherical panoramas, use Spherical Pano Renderer.

Cylindrical

Cylindrical panorama is characterized by a viewing angle of 360 degrees horizontally and a viewing angle of less than 180 degrees vertically. In other words, a cylindrical panorama is a variant of a spherical panorama, devoid of zenith and nadir (images of the highest and lowest points of view).

To display cylindrical panoramas, use Cylindrical Pano Renderer.

Cubic panorama on six images