Panorama 360 iPod Touch & iPhone

Introduction

PanoramaGL library is the first open source library in the world to see panoramic views on the iPod Touch 1G, 2G, 3G and iPhone EDGE, 3G and 3GS.

SVN and source code in http://code.google.com/p/panoramagl/

Created by Javier Baez - Visit Ecuador Team

HelloPanorama image

Important Note: Please add the credits in their projects when using the library.

Background

The supported features in version 0.1 Beta are:

Supports OpenGLES 1.1
Tested with SDK 3.0 to 3.2
Supports cubic, spherical and cylindrical panoramic images
Allows scrolling and continuous scrolling
Supports scrolling left to right and from top to bottom using the accelerometer
Allows to use the inertia to stop scrolling
Supports zoom in and zoom out (moving two fingers on the screen)
Supports reset (placing three fingers on the screen)
Allows you to control the range of rotation in the x, y and z axis
Supports Portrait, Portrait Upside Down, Landscape Left and Landscape Right orientation using the accelerometer
Supports for events on view

Using the Code

To create a simple panoramic image viewer for the iPhone with PanoramaGL library, you must perform the following steps:

1. Creating a project for iPhone (iPhone view based).

Open XCode
Go to "File -> New Project -> iPhone OS -> Application -> View-based Application"

Click on "Choose" button and Save the project as "HelloPanorama"

2. Import PanoramaGL library.

Download "PanoramaGL" library (Parent project folder)
Decompress "PanoramaGL" library (double click on zip file)
Go to menu "Project -> Edit Active Target 'HelloPanorama'"
Go to "General" Tab

Click on "+" button in the "Linked Library Section"

Click on "Add Other" button and find "PanoramaGL" project

Select "PanoramaGL" folder, select "PanoramaGL.xcodeproj" file and click on "Add" button returning to "General" Tab"

Go to "Direct Dependencies" section and click on "+" button

Select "PanoramaGL" and click on "Add Target" button returning to "General" Tab
Now go to "Build" Tab

Find option "Header Search Paths" and double click on it.

Click on "+" button and create a new setting string
Select "Recursive" check, write a relative path of "PanoramaGL" folder (in this case "../PanoramaGL" and click on "OK" button
Close "Project Active Target" window
Go to "Group & Files" panel, find and select "PanoramaGL.xcodeproj"
Check target option of "libPanoramaGL.a" on top-right panel as shown below:

3. In the controller class HelloPanoramaViewController must be implemented the code shown below:

#import <UIKit/UIKit.h>
#import "PLView.h"

@interface HelloPanoramaViewController : UIViewController {
	IBOutlet PLView * plView;
}

@property (nonatomic, retain) IBOutlet PLView *plView;

@end

4. The view created must inherit from PLView, instead of UIView, so it must be modified in the resource file HelloPanoramaViewController.xib.

5. In the controller class HelloPanoramaViewController must implement code in order to configure the view as shown below:

#import "HelloPanoramaViewController.h"

@implementation HelloPanoramaViewController

@synthesize plView;

// Implement viewDidLoad to do additional setup after loading the view, typically from a nib.
- (void)viewDidLoad 
{
    [super viewDidLoad];
    //Example with Spherical type
    plView.isDeviceOrientationEnabled = YES;
    plView.isAccelerometerEnabled = YES;
    plView.isScrollingEnabled = YES;
    plView.isInertiaEnabled = YES;
    plView.type = PLViewTypeSpherical;
    [plView addTextureAndRelease:[PLTexture textureWithPath:[[NSBundle mainBundle] pathForResource:@"pano" ofType:@"jpg"]]];
}

- (void)dealloc 
{
    [plView release];
    [super dealloc];
}

@end

6. plView variable pointing to the view in the resource file "MainWindow.xib"

7. Add a resource image as "pano.jpg" this image must be Spherical for this example.

Classes Documentation

Then proceed to explain briefly the operation of the classes used:

PLView class, this class is a view (inherits from UIView) allowing a simple set of features for power display panoramic images. The properties and methods of this class are:

BOOL isDeviceOrientationEnabled; //If the view allows you to enable orientation of the device supports (manually, typical of the Library)
UIDeviceOrientation deviceOrientation; //lets see what orientation has this view, or set in that we want the view orientation appears. Eg. plView.deviceOrientation=UIDeviceOrientationLandscapeLeft;
PLOrientationSupported deviceOrientationSupported; //This property allows you to tell the view that positions of orientation is enabled and running. Eg. PlView.deviceOrientationSupported = (PLOrientationSupportedPortrait | PLOrientationSupportedLandscapeLeft) <- in this case only allows for Portrait orientation and LandscapeLeft
BOOL isAccelerometerEnabled; //This property enables the operation of the accelerometer
BOOL isAccelerometerLeftRightEnabled; // This property activates the accelerometer operation only in the x-axis and depends on this active property isAccelerometerEnabled
BOOL isAccelerometerUpDownEnabled; // This property activates the accelerometer operation only in the y-axis and depends on this active property isAccelerometerEnabled
float accelerometerSensitivity; // Set the sensitivity with which to operate the accelerometer (motion sensing)
NSTimeInterval accelerometerInterva;l // Sets the refresh time in seconds of accelerometer

CGPoint startPoint; // This property tells us which position he made the first touch when the event occurs (Touch Begin event)
CGPoint endPoint; // This property will be cooling while moving the finger on the screen (Touch Move event)
BOOL isScrollingEnabled; // This property tells us if you could make a scrolling at the hearing, if not active, only move when the fingers moving on the screen
NSUInteger minDistanceToEnableScrolling; // Minimum distance that must be traveled with the fingers to activate the scrolling
BOOL isInertiaEnabled; / / Check the inertia that means that when someone performs a scroll inertia is activated to slow the scroll to stop the movement
NSTimeInterval inertiaInterval; // Duration of inertia in seconds
BOOL isResetEnabled; // Property that can be enabled to reset the view to its original position when placing three fingers on the screen
PLViewType type; // Type of view to be used can be (PLViewTypeSpherical, PLViewTypeCubeFaces, PLViewTypeCylindrical)
PLCamera * camera; / / Property allows us to change or take the parameters of the camera

- (void) addTexture: (PLTexture *) texture; // Add a texture to be used, in the case of spherical and cylindrical single view to invoke this method once, in the case of cubic view use this method six times (one texture per face)
- (void) removeTexture: (PLTexture *) texture; // Removes an object of type texture of the view
- (void) removeTextureAtIndex: (NSUInteger) index; // Removes an object of type texture by index of the view
- (void) removeAllTextures; // Removes all the textures that the view can use

PLTexture class allows us to load a texture that will be used by the view, its properties and methods are:

GLuint textureId; // read-only property giving the identifier of an OpenGL texture
int width, height; // read-only properties for the width and height of a texture loaded
BOOL isValid; // Property to know if the texture failed to load

- (id) init; // Default Constructor
- (id) initWithImage: (UIImage *) image; // Constructor that receives an object of type UIImage where an image must be loaded
- (id) initWithImage: (UIImage *) image rotate (int) angle; // Same as the previous method but can rotate the image 90, 180, 270 degrees
- (id) initWithPath: (NSString *) path; // Constructor that receives the image path (jpeg, png)
- (id) initWithPath: (NSString *) path rotate (int) angle; // Same as the previous method but can rotate the image 90, 180, 270 degrees

// Constructors static type that operate with the same parameters that the init equivalent functions

+ (id) textureWithImage: (UIImage *) image;
+ (id) textureWithPath: (NSString *) path;
+ (id) textureWithImage: (UIImage *) image rotate (int) angle;
+ (id) textureWithPath: (NSString *) path rotate (int) angle;

- (BOOL) loadTextureWithImage: (UIImage *) image; // Load a texture from an image object
- (BOOL) loadTextureWithImage: (UIImage *) image rotate (int) angle; / / Same as the previous method but can rotate the image 90, 180, 270 degrees
- (BOOL) loadTextureWithPath: (NSString *) path, // Load a texture from image path (jpeg, png)
- (BOOL) loadTextureWithPath: (NSString *) path rotate (int) angle; / / Same as the previous method but can rotate the image 90, 180, 270 degrees

Eg. PLTexture * texture = 
[PLTexture textureWithPath:[[NSBundle mainBundle] pathForResource:@"pano" ofType:@"jpg"]]; 
[plView addTexture:[PLTexture textureWithPath:texture]];

PLCamera class allows us to change the display settings of the hearing, their properties are:

BOOL IsFovEnabled; // Enable zoom in or zoom out eg. plView.camera.isFovEnabled = NO;
float fov; // zoom level for the Hearing eg. plView.camera.fov = 10;
float fovSensitivity; // sensitivity for the zoom when you place two fingers on the screen eg. plView.camera.fovSensitivity = 70;
PLRange fovRange; // Range in values that will allow for the default zoom from -180 to 180 eg. plView.camera.fovRange = PLRangeMake (-10.10);
PLRange fovFactorRange; // Range in which the zoom will work internaly (This range is for internal use with fovFactor property)
BOOL isXAxisEnabled, isYAxisEnabled, isZAxisEnabled; // This properties enabled if the camera can move in the x, y, z eg. plView.camera.isXAxisEnabled = NO;
PLPosition position; // property to place the camera in a position. PLPosition has the property x, y, z eg. plView.camera.x = 6;
PLRange xRange, yRange, zRange; // Define the range in which it can move in the x, y, z eg. plView.camera.xRange = PLRangeMake (-100, 100);
BOOL isPitchEnabled, isYawEnabled, isRollEnabled; // These properties enable that axes can rotate the camera x, y, z eg. plView.camera.isPitchEnabled = NO;
BOOL IsReverseRotation; // Enable the rotation of the camera displacement is inversely related to the user to do with the touch or accelerometer. Eg. plView.camera.isReverseRotation = YES;
PLRotation rotation; // angles of rotation (in degrees) of the camera x, y, z eg. plView.camera.rotation.pitch = 80;
PLRange pitchRange, yawRange, rollRange; // Range in which the camera can rotate in x, y, z eg. plView.camera.pitchRange = PLRangeMake (-90, 90); <- on the x axis can only rotate the angle - 90 to 90
float rotateSensitivity; // value of sensitivity in which the camera will rotate when the user moves the view eg . plView.camera.rotateSensitivity = 40;

- (void) reset; / / Lets reset the camera settings back to the original position of the camera eg. [plView.camera reset];

Eg. plView.camera.yawRange = PLRangeMake(-70, 70);

Many of the properties and methods named in the previous section have not been implemented in the example but it serves as reference documentation for those wishing to download the PanoramaGL library and begin using in their projects.

This weekend or next week maximum official library documentation will be published.