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
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;
- (void)viewDidLoad
{
[super viewDidLoad];
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.
Points of Interest
- Panoramic images (Spherical, Cylindrical, Cubic)
- Panoramic viewer
History
- 22 February, 2009: Initial post
