Overview

Introduction

uPano (Unity Panoramic Framework) is a universal solution for displaying dynamic and static panoramas, and creating VR 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.

 

Supports Unity v2017.1 or later.

Supported platforms: Standalone, iOS, Android, Universal Windows Platform, WebGL.

Other platforms have not been tested, but most likely uPano will work well.

 

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.

 

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.

 

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

Cubic panorama is obtained by projecting images onto the inner faces of the cube. You can imagine an observer inside a huge cube, on the inner walls of which are glued images of the appropriate scale. Cubic panorama allows you to create panoramas with viewing angles of 360 degrees horizontally and 180 degrees vertically. Like a spherical panorama, the cubic panorama is prone to distortions.

 

To display cubic panoramas on six images. use Cube Faces Pano Renderer.

 

Cubic panorama on single image

In this type of panorama, the images of the sides of the cube are combined into one large image.

 

There are three main types of layouts:

1. Crosses

2. Lines

3. 3 rows, 2 columns

Each type has a horizontal and vertical orientation.

Sides of the panorama can be reflected and / or rotated by a fixed angle (90, 180, 270).

 

uPano has presets for the main types of layouts and allows you to adjust UV of each side of the panorama.

 

To display cubic panoramas on single image, use Single Texture Cube Faces Pano Renderer.

 

Cubemap

 

uPano can display an existing cubemap as a panorama.

https://docs.unity3d.com/Manual/class-Cubemap.html

 

To display cubemap panoramas, use Cubemap Pano Renderer.

 

Controls

Components that allow the user to control the panorama.

You can use an unlimited number of different controls in any combination.

 

Mouse Control

Implements panorama control using the mouse and touch (on mobile devices).

 

Modes:

  1. Drag (by default) - the panorama will be moved by dragging. Supports inertia when you stop dragging.
  2. Free - the panorama will constantly move towards the cursor.
  3. Left Mouse Button Down - the panorama will move towards the cursor while you hold the left mouse button.

 

Implements the changing of fov using the mouse wheel and pinch to zoom (on mobile devices).

 

Keyboard Control

Implements panorama control using the keyboard.

To change pan and tilt, use the horizontal and vertical input axes.

https://docs.unity3d.com/Manual/class-InputManager.html

 

To change fov, use «+» and «-» buttons on the main or numeric keypad.

 

You can adjust the sensitivity of changing the values and limit the rotation axes of the panorama.

 

Tip: To prevent pan, tilt or fov from changing using the keyboard, set the sensitivity to 0.

 

Compass Control

Implements panorama control using a device compass.

This control changes only pan.

 

Gyro Control

Implements panorama control using a device gyro.

This control changes pan and tilt. 

 

UI Buttons Control

Implements panorama control using the on-screen buttons.

Automatically integrates with Auto Rotate plugin.

 

Joystick Control

Implements control panorama uing the on-screen joystick.

Drag the center part of the joystick and the panorama will move in the same direction.

 

UI Compass Control

Compass showing the current orientation of the panorama.

When you click on the center, it sets the orientation to the north.

When you click on the side arrows, the panorama rotates 90 degrees clockwise or counterclockwise.

 

Plugins

Scripts that implement additional features of panoramas.

 

Formally, all control, managers of interactive elements and some other components are also plug-ins, but they have a lot of features and will be described in separate sections.

 

Auto Rotate

Automatically rotates the panorama clockwise.

When the user interacts with the panorama using any control, the automatic rotation stops.

After 10 seconds of inactivity, automatic rotation resumes.

If tilt is not equal to zero, then this value will gradually tend to zero.

 

Automatically integrates with UI Buttons Control.

 

Limits

Allows you to limit the valid values of pan, tilt, and fov.

Strongly recommended for use.

 

Multi Camera

Synchronous changes fov for multiple cameras.

 

Additionally, it can change the local position of cameras depending on fov.

This is useful for VR applications to prevent the problem of too much divergence of images for the left and right eyes when fov value is small.

 

Orthographic Cameras

Extends Multi Camera plug-in, allowing cameras to have an orthographic projection.

Additionally it has the ability to customize the conversion of fov - orthographicSize values.

 

 

Interactive Elements

Interactive element is an object in the panorama, with which the user can interact.

Interactive elements support events and actions, and can be programmed for any behavior.

 

Hot Spot

Hot Spot Manager component adds hot spot support to the panorama.

 

Hot spot is an interactive GameObject, which is positioned on the panorama using pan and tilt.

Hot Spot Manager contains:

  1. Button «+» - add a new hot spot.
  2. Total: X - the number of elements.
  3. Visual Editor - opens a visual editor.
  4. Collapse all - Collapses all items and their events. 
  5. Arrow down - collapse item fields.
  6. Title. This name will set to the GameObject - a hot spot instance.
  7. Button «x» - remove the hot spot.
  8. Prefab - GameObject, a copy of which will be used for hot spot.
  9. Pan, tilt - position hot spot on the panorama.
  10. Rotation - local rotation of the hot spot instance.
  11. Scale - local scale of the hot spot instance.
  12. Distance Multiplier - the multiplier of the distance from the center of the panorama to the point on the mesh. Allows you to move the hot spot closer if it goes beyond the panorama.
  13. Events - hot spot events. 

 

Direction

Direction Manager component adds support for direction to the panorama.

 

Direction is an arrow that points in the direction of another panorama. This is positioned in the panorama using the pan.

 

In general, Direction Manager has the same fields as Hot Spot Manager, except for the settings for all directions:

Default Prefab - GameObject, an instance of which will be used for direction, if no prefab for the element is specified.

Internal Radius - the radius from the central point of rotation to the instance of the direction.

External Radius - the radius from the camera to the center point around which direction will be located.

Vertical Offset - vertical offset of the center point.

 

Visual Editor

Visual editor makes it easy to manage hot spots on the panorama.

 

Important: In the current version, the visual editor supports only spherical, cylindrical and cubic panoramas on single image.

 

Click «Hot Spot Manager / Virtual Editor» or «Window / Infinity Code / uPano / Visual HotSpot Editor» to open the visual editor.

Select in the «Hierarchy» or «Project» window any GameObject containing a panorama to display the used texture and hot spots.

 

You can drag and scale the viewing area.

Click «Reset view» to reset the movement and scale of the viewing area.

 

To create a hot spot, right-click and select «Create HotSpot» from the context menu. A new hot spot will be created under the cursor.

You can drag hot spot to any available panorama area. But you can not drag a hot spot outside UV of the panoramas.

To remove hot spot, right click on it and select «Remove HotSpot» from the context menu.

 

Click on the hot spot with the left mouse button to open the hot spot settings window.

This window displays the settings only for one hot spot, so it is much more convenient to use it in Hot Spot Manager inspector

 

Above the hot spot icon displayed title.

If the title is red, then prefab is not specified and hot spot will not be displayed.

 

Events

Interactive elements has five events:

Clicking, pressing the left mouse button (or touch), releasing the left mouse button (or touch), the cursor is enter to the interactive element, the cursor is out from the interactive element.

 

For each event, you can add an unlimited number of actions.

Action is a public method of a class that inherits MonoBehaviour, which takes an interactive element as a parameter.

You can create your own actions, or use a predefined actions.

 

Global events

If your interactive elements have the same actions for an event, you can use global events that will be called for all interactive elements of the same type before the element's events.

To use global events, add the global event component of the appropriate type.

For hot spot: HotSpotGlobalActions.

For direction: DirectionGlobalActions.

 

If some interactive element should ignore global events, you can specify it in the settings of the element.

 

Predefined actions

Predefined actions are: used for all types of interactive elements and used only for hot spots.

 

For all types of interactive elements:

Destroy Current Panorama

Instantiate Prefab

Load Another Panorama

Load Scene

Set Cursor

Set Scale

 

Only for hot spots:

Destroy Current Hot Spot

Set Hot Spot Color

Set Hot Spot Rotation

Show TextMesh Tooltip

Show Tooltip

Show Tooltip Multi Camera

 

All predefined actions have a public Invoke method, which must be called to perform the action.

 

Note: Show Tooltip Show Tooltip Multi Camera and Show TextMesh Tooltip actions have three public methods: Invoke and Show - show tooltip, Hide - hide tooltip.

 

In the future, the list of predefined actions will expand.

If you have suggestions, what other actions need to be added, please contact us.

 

Quick actions

For interactive elements, there are the same actions that you will most likely use for most elements.

You can create quick actions in Quick Actions section of the settings of the interactive element.

 

Load another panorama on click:

Specify Target Panorama and Load Another Panorama action will be automatically added to the interactive element.

 

Showing a tooltip:

Enter Tooltip text, select the action, and specify Tooltip Prefab.

For the interactive element, the specified action will be automatically added.

 

Interactive elements without programming

uPano allows you to specify the behavior of interactive elements without programming.

 

Step by step instructions on the example of hot spot:

Create a child GameObject for the panorama, which will contain hot spot events.

Tip: Create separate GameObject for each action. This will help you more easily navigate in action.

 

Important: If you want to make a prefab of the panorama, the action must be on the child of the panorama GameObject. Prefab can not reference objects in the scene outside the prefab.

 

 

Select GameObject that will store the action.

Add one of the predefined actions, or your own script containing the action.

 

In Hot Spot Manager, create a new Hot Spot.

In the event that should perform this action, press «+».

Specify GameObject that contains the action.

Select the action script and Invoke method if you use predefined actions, or your own method that should be called.

 

Note: the method must contain the interactive element parameter, in which the element that triggered the action will be passed.

 

 

Additional features

Video panoramas

uPano can display video panoramas.

 

To use a video panorama:

Import the video into the project.

Create a new Render Texture (Assets / Create / Render Texture).

Specify the size of the Render Texture to be equal to the video resolution.

In the scene, create a new GameObject, and add Video Player component to it.

In Video Clip field, specify a video.

Select Render Mode - Render Texture and specify the early created Render Texture in Terget Texture field.

In Pano Renderer, set Render Texture to Texture field, and adjust UV.

When you start the scene, you will see a video panorama.

 

Tip: For Youtube 360 video, you need to use Single Texture Cube Faces Pano Renderer. 

UV Preset - Youtube (3x2).

Google Street View

uPano can download panorama from Google Street View by panorama ID, or by location (latitude and longitude in decimal).

 

Important: Google Street View requires Spherical Pano Renderer.

 

The component has two work scenarios:

  1. Dynamic. When you start the scene, the image from Google Street View will be downloaded and used as a texture of the panorama.
  2. Static. Click «Download» to download the panorama and save it in the project. 
    After the panorama image is downloaded, this component should be removed from GameObject.

 

Size of a panorama texture:

Width = 512 * 2 ^ zoom.

The height of the panorama is not constant, and is calculated based on the colors of the loaded image.

 

Downloader

A tool for downloading panoramas from Google Maps and Yandex Maps by URL.

 

Open the browser and go to Google Maps or Yandex Maps site.

Use the map to open the panorama.

Copy URL from your browser's address bar.

Open Window / Infinity Code / uPano / Pano Downloader.

Paste URL into URL field and click Download.

The downloaded panorama will be saved in the folder «Assets / Panoramas».

 

 

Online Maps integration

https://assetstore.unity.com/packages/tools/integration/online-maps-13261

Integration with Online Maps allows you to display Google Street View panoramas using uPano.

Online Maps is not included in the package and you should buy it separately.

For integration, you need to have uPano and Online Maps in the project.

 

To enable integration, add Online Maps Pano Connector to the map GameObject and click Enable uPano.

The map will show overlay for which Google Street View panoramas are available.

When you click on the map, uPano will download and display the panorama of the location.

 

uPano API

For more information about all public classes, methods, and variables, see API Reference.

 

Online version:

http://infinity-code.com/docs/api/upano/

 

The local version of API Reference is located in «Standard Assets / Infinity Code / uPano / Documentation / API Reference (Do not unpack in assets folder).zip».

 

Important: do not unpack the archive into Assets folder of your project. 

 

The order of the values in the point on the panorama:

Vector2, Vector3: X - pan, Y - tilt;

Parameters of methods: first - pan, then - tilt.

 

The order of values in geographic coordinates:

Vector2, Vector3: X - longitude, Y - latitude;

Parameters of methods: first - longitude, then - latitude.

 

Making changes to the source code uPano

We do not recommend that you make changes to uPano code yourself, because you will lose it on update.

Most tasks can be solved using API.

If you really need to modify the source code of uPano, please send us your changes. We will include your changes into the project, or we will give you the best way to do it.

 

Updating

We send only stable versions to Unity Asset Store.

The update period is several months.

 

uPano has a built-in update system, using which you can download the latest versions.

 

Important: Always make backups of the project before updating assets.

 

Select 

Window / Infinity Code / uPano / Check Updates

or 

uPano / Help / Check Updates

to open the built-in update system.

Specify your Invoice Number or Order Number.

Select the update channel and click «Check New Versions».

 

You can find out your Invoice Number in Unity Asset Store order confirmation email, or page: 

https://assetstore.unity.com/orders

 

Each channel shows a maximum of 10 latest updates.

If updates are available, then you can read the list of changes and download it.

 

If you have problems installing the update, then:

1. Open an empty scene.

2. Delete folder «Standard Assets / Infinity Code / uPano».

3. Import the new version of uPano into the project.

If you want to return to the previous version of uPano, then select the «Stable Previous» channel. Using this channel you will be able to get 10 previous stable versions.

 

uPano automatically checks for updates every 24 hours. 

If the new version is available, you will see a red label in uPano Inspector header. Clicking on it will open the built-in update system.

Automatic check of the update does not require Invoice Number and uses the last selected update channel. If the update channel is not selected, only stable versions will be checked.

 

Support

We provide support by email (support@infinity-code.com) in English and Russian, or on the forum (http://forum.infinity-code.com) in English.

If something does not work for you, you found a bug, or you have any suggestions, please contact to us.

Please dont forget to specify your version of Unity, OS and the current version of uPano.

 

The usual response time is from a few minutes to 24 hours.

We manually control the spam folder, so do not worry, we will not miss your request.

 

If you did not receive a response within 24 hours:

1. Check the spam folder.

2. Contact us using an another way.

 

Final words

We sincerely hope that you will enjoy using uPano.

If you have any questions or problems, please contact us.

We will try to help you as soon as possible.

 

Please do not forget to add your review in Unity Asset Store.

It is very important for us to have feedback from users to make our asset better.

This will help other users to create the right understanding of the asset quality and features.

English