Merge pull request #39 from nytm/develop

v 0.6.0

NYT360Video.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
     s.name             = 'NYT360Video'
-    s.version          = '0.5.3'
+    s.version          = '0.6.0'
     s.summary          = 'NYT360Video plays 360º video streamed from an AVPlayer.'
 
     s.description      = <<-DESC

NYT360VideoExample/Info.plist

@@ -15,7 +15,7 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.5.3</string>
+	<string>0.6.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleVersion</key>

NYT360VideoExample/ViewController.m

@@ -35,6 +35,13 @@ - (void)viewDidLoad {
     [self.nyt360VC didMoveToParentViewController:self];
 
     [self.player play];
+
+    UITapGestureRecognizer *tapRecognizer = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(reorientVerticalCameraAngle:)];
+    [self.view addGestureRecognizer:tapRecognizer];
+}
+
+- (void)reorientVerticalCameraAngle:(id)sender {
+    [self.nyt360VC reorientVerticalCameraAngleToHorizon:YES];
 }
 
 @end

NYT360VideoTests/Info.plist

@@ -15,7 +15,7 @@
 	<key>CFBundlePackageType</key>
 	<string>BNDL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.5.3</string>
+	<string>0.6.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleVersion</key>

NYT360VideoTests/NYT360EulerAngleCalculationsTests.m

@@ -7,6 +7,7 @@
 //
 
 @import XCTest;
+@import SceneKit;
 
 #import "NYT360DataTypes.h"
 #import "NYT360EulerAngleCalculations.h"
@@ -132,4 +133,74 @@ - (void)testItCalculatesTheOptimalYFovForAVarietyOfInputs {
     XCTAssertEqualWithAccuracy(NYT360OptimalYFovForViewSize(CGSizeMake(0, 1)),      120.0,   2.0);
 }
 
+- (void)testItCalculatesTheCorrectCompassAngleForAVarietyOfInputs {
+
+    SCNVector3 eulerAngles;
+    float pi = M_PI;
+    float compassAngle;
+    float referenceAngle;
+
+    referenceAngle = NYT360EulerAngleCalculationDefaultReferenceCompassAngle;
+
+    eulerAngles.y = 0;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, pi, 0.001);
+
+    eulerAngles.y = pi;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, 0, 0.001);
+
+    eulerAngles.y = -pi;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, 0, 0.001);
+
+    eulerAngles.y = pi * 0.5;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, pi * 1.5, 0.001);
+
+    eulerAngles.y = pi * -0.5;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, pi * 0.5, 0.001);
+
+    eulerAngles.y = pi * 1.5;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, pi * 0.5, 0.001);
+
+    eulerAngles.y = pi * -1.5;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, pi * -0.5, 0.001);
+
+    eulerAngles.y = pi * 2.0;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, pi, 0.001);
+
+    eulerAngles.y = pi * -2.0;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, -pi, 0.001);
+
+    eulerAngles.y = pi * 2.5;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, pi * 1.5, 0.001);
+
+    eulerAngles.y = pi * -2.5;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, pi * -1.5, 0.001);
+
+    eulerAngles.y = pi * 3.0;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, 0, 0.001);
+
+    eulerAngles.y = pi * -3.0;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, 0, 0.001);
+
+    eulerAngles.y = pi * 4.0;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, pi, 0.001);
+
+    eulerAngles.y = pi * -4.0;
+    compassAngle = NYT360CompassAngleForEulerAngles(eulerAngles, referenceAngle);
+    XCTAssertEqualWithAccuracy(compassAngle, -pi, 0.001);
+}
+
 @end

README.md

@@ -31,6 +31,10 @@ NYT360Video is available through [CocoaPods](http://cocoapods.org). To install i
 pod 'NYT360Video'
 ```
 
+## Known Issues
+
+- **iOS 10 CoreAudio Crash** - On devices running iOS 10 (at least as of Beta 7), host applications will crash if the device is locked while an NYT360ViewController is visible (whether paused or not). The crash is caused by a CoreAudio exception. [An extended discussion of the issue can be found here](https://github.com/nytm/ios-360-videos/issues/37). A workaround that appears to work for some, though not all, apps is to enable the background audio capability in the host application's plist.
+
 ## Authors
 
 - Maxwell Dayvson Da Silva: <maxwell.dasilva@nytimes.com>

Sources/Info.plist

@@ -15,7 +15,7 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.5.3</string>
+	<string>0.6.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleVersion</key>

Sources/NYT360CameraController.h

@@ -14,17 +14,51 @@
 #import "NYT360MotionManagement.h"
 
 @class NYT360CameraPanGestureRecognizer;
+@class NYT360CameraController;
+
+/**
+ * The block type used for compass angle updates.
+ *
+ *  @param compassAngle The compass angle in radians.
+ */
+typedef void(^NYT360CompassAngleUpdateBlock)(float compassAngle);
 
 NS_ASSUME_NONNULL_BEGIN
 
+@protocol NYT360CameraControllerDelegate <NSObject>
+
+/**
+ *  Called the first time the user moves the camera.
+ *
+ *  @note This method is called synchronously when the camera angle is updated; an implementation should return quickly to avoid performance implications. 
+ *
+ *  @param controller   The camera controller with which the user interacted.
+ *  @param method       The method by which the user moved the camera.
+ */
+- (void)cameraController:(NYT360CameraController *)controller userInitallyMovedCameraViaMethod:(NYT360UserInteractionMethod)method;
+
+@end
+
 @interface NYT360CameraController : NSObject <UIGestureRecognizerDelegate>
 
-#pragma mark - Camera Angle Direction
+/**
+ *  The delegate of the controller.
+ */
+@property (nullable, nonatomic, weak) id <NYT360CameraControllerDelegate> delegate;
+
+#pragma mark - Compass Angle
+
+/**
+ *  Returns the current compass angle in radians
+ */
+@property (nonatomic, readonly) float compassAngle;
 
 /**
- Returns the latest camera angle direction.
+ *  A block invoked whenever the compass angle has been updated.
+ *
+ *  @note This method is called synchronously from SCNSceneRendererDelegate. Its implementation should return quickly to avoid performance implications.
  */
-@property (nonatomic, readonly) double cameraAngleDirection;
+@property (nonatomic, copy, nullable) NYT360CompassAngleUpdateBlock compassAngleUpdateBlock;
 
 #pragma mark - Initializers
 
@@ -56,29 +90,45 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  *  Updates the camera angle based on the current device motion. It's assumed that this method will be called many times a second during SceneKit rendering updates.
  */
-- (void)updateCameraAngle;
-
-#pragma mark - Panning Options
+- (void)updateCameraAngleForCurrentDeviceMotion;
 
 /**
  *  Updates the yFov of the camera to provide the optimal viewing angle for a given view size. Portrait videos will use a wider angle than landscape videos.
  */
 - (void)updateCameraFOV:(CGSize)viewSize;
 
+/**
+ *  Reorients the camera's vertical angle component so it's pointing directly at the horizon.
+ *
+ *  @param animated Passing `YES` will animate the change with a standard duration.
+ */
+- (void)reorientVerticalCameraAngleToHorizon:(BOOL)animated;
+
+#pragma mark - Panning Options
+
 /**
  *  An otherwise vanilla subclass of UIPanGestureRecognizer used by NYT360Video to enable manual camera panning. This class is exposed so that host applications can more easily configure interaction with other gesture recognizers without having to have references to specific instances of an NYT360Video pan recognizer.
  */
 @property (nonatomic, readonly) NYT360CameraPanGestureRecognizer *panRecognizer;
 
 
 /**
- *  Changing this property will allow you to suppress undesired range of motion along either the x or y axis. For example, y axis input should be suppressed when a 360 video is playing inline in a scroll view.
+ *  Changing this property will allow you to suppress undesired range of motion along either the x or y axis for device motion input. For example, y axis input might be suppressed when a 360 video is playing inline in a scroll view.
+ 
+ *  When this property is set, any disallowed axis will cause the current camera angles to be clamped to zero for that axis. Existing angles for the any allowed axes will not be affected.
+ 
+ *  Defaults to NYT360PanningAxisHorizontal | NYT360PanningAxisVertical.
+ */
+@property (nonatomic, assign) NYT360PanningAxis allowedDeviceMotionPanningAxes;
+
+/**
+ *  Changing this property will allow you to suppress undesired range of motion along either the x or y axis for pan gesture recognizer input. For example, y axis input should probably be suppressed when a 360 video is playing inline in a scroll view.
  
  *  When this property is set, any disallowed axis will cause the current camera angles to be clamped to zero for that axis. Existing angles for the any allowed axes will not be affected.
  
  *  Defaults to NYT360PanningAxisHorizontal | NYT360PanningAxisVertical.
  */
-@property (nonatomic, assign) NYT360PanningAxis allowedPanningAxes;
+@property (nonatomic, assign) NYT360PanningAxis allowedPanGesturePanningAxes;
 
 @end