lottie-ios 3.2.3 → 3.4.0

package/Sources/Private/Utility/Primitives/VectorsExtensions.swift

@@ -0,0 +1,341 @@
+//
+//  Vector.swift
+//  lottie-swift
+//
+//  Created by Brandon Withrow on 1/7/19.
+//
+
+import CoreGraphics
+import Foundation
+import QuartzCore
+
+// MARK: - Vector1D + Codable
+
+/// Single value container. Needed because lottie sometimes wraps a Double in an array.
+extension Vector1D: Codable {
+
+  // MARK: Lifecycle
+
+  public init(from decoder: Decoder) throws {
+    /// Try to decode an array of doubles
+    do {
+      var container = try decoder.unkeyedContainer()
+      value = try container.decode(Double.self)
+    } catch {
+      value = try decoder.singleValueContainer().decode(Double.self)
+    }
+  }
+
+  // MARK: Public
+
+  public func encode(to encoder: Encoder) throws {
+    var container = encoder.singleValueContainer()
+    try container.encode(value)
+  }
+
+  // MARK: Internal
+
+  var cgFloatValue: CGFloat {
+    CGFloat(value)
+  }
+
+}
+
+// MARK: - Vector1D + AnyInitializable
+
+extension Vector1D: AnyInitializable {
+
+  init(value: Any) throws {
+    if
+      let array = value as? [Double],
+      let double = array.first
+    {
+      self.value = double
+    } else if let double = value as? Double {
+      self.value = double
+    } else {
+      throw InitializableError.invalidInput
+    }
+  }
+
+}
+
+extension Double {
+  var vectorValue: Vector1D {
+    Vector1D(self)
+  }
+}
+
+// MARK: - Vector2D
+
+/// Needed for decoding json {x: y:} to a CGPoint
+public struct Vector2D: Codable, Hashable {
+
+  // MARK: Lifecycle
+
+  init(x: Double, y: Double) {
+    self.x = x
+    self.y = y
+  }
+
+  public init(from decoder: Decoder) throws {
+    let container = try decoder.container(keyedBy: Vector2D.CodingKeys.self)
+
+    do {
+      let xValue: [Double] = try container.decode([Double].self, forKey: .x)
+      x = xValue[0]
+    } catch {
+      x = try container.decode(Double.self, forKey: .x)
+    }
+
+    do {
+      let yValue: [Double] = try container.decode([Double].self, forKey: .y)
+      y = yValue[0]
+    } catch {
+      y = try container.decode(Double.self, forKey: .y)
+    }
+  }
+
+  // MARK: Public
+
+  public func encode(to encoder: Encoder) throws {
+    var container = encoder.container(keyedBy: Vector2D.CodingKeys.self)
+    try container.encode(x, forKey: .x)
+    try container.encode(y, forKey: .y)
+  }
+
+  // MARK: Internal
+
+  var x: Double
+  var y: Double
+
+  var pointValue: CGPoint {
+    CGPoint(x: x, y: y)
+  }
+
+  // MARK: Private
+
+  private enum CodingKeys: String, CodingKey {
+    case x
+    case y
+  }
+}
+
+// MARK: AnyInitializable
+
+extension Vector2D: AnyInitializable {
+
+  init(value: Any) throws {
+    guard let dictionary = value as? [String: Any] else {
+      throw InitializableError.invalidInput
+    }
+
+    if
+      let array = dictionary[CodingKeys.x.rawValue] as? [Double],
+      let double = array.first
+    {
+      x = double
+    } else if let double = dictionary[CodingKeys.x.rawValue] as? Double {
+      x = double
+    } else {
+      throw InitializableError.invalidInput
+    }
+    if
+      let array = dictionary[CodingKeys.y.rawValue] as? [Double],
+      let double = array.first
+    {
+      y = double
+    } else if let double = dictionary[CodingKeys.y.rawValue] as? Double {
+      y = double
+    } else {
+      throw InitializableError.invalidInput
+    }
+  }
+}
+
+extension CGPoint {
+  var vector2dValue: Vector2D {
+    Vector2D(x: Double(x), y: Double(y))
+  }
+}
+
+// MARK: - Vector3D + Codable
+
+/// A three dimensional vector.
+/// These vectors are encoded and decoded from [Double]
+
+extension Vector3D: Codable {
+
+  // MARK: Lifecycle
+
+  init(x: CGFloat, y: CGFloat, z: CGFloat) {
+    self.x = Double(x)
+    self.y = Double(y)
+    self.z = Double(z)
+  }
+
+  public init(from decoder: Decoder) throws {
+    var container = try decoder.unkeyedContainer()
+
+    if !container.isAtEnd {
+      x = try container.decode(Double.self)
+    } else {
+      x = 0
+    }
+
+    if !container.isAtEnd {
+      y = try container.decode(Double.self)
+    } else {
+      y = 0
+    }
+
+    if !container.isAtEnd {
+      z = try container.decode(Double.self)
+    } else {
+      z = 0
+    }
+  }
+
+  // MARK: Public
+
+  public func encode(to encoder: Encoder) throws {
+    var container = encoder.unkeyedContainer()
+    try container.encode(x)
+    try container.encode(y)
+    try container.encode(z)
+  }
+
+}
+
+// MARK: - Vector3D + AnyInitializable
+
+extension Vector3D: AnyInitializable {
+
+  init(value: Any) throws {
+    guard var array = value as? [Double] else {
+      throw InitializableError.invalidInput
+    }
+    x = array.count > 0 ? array.removeFirst() : 0
+    y = array.count > 0 ? array.removeFirst() : 0
+    z = array.count > 0 ? array.removeFirst() : 0
+  }
+
+}
+
+extension Vector3D {
+  public var pointValue: CGPoint {
+    CGPoint(x: x, y: y)
+  }
+
+  public var sizeValue: CGSize {
+    CGSize(width: x, height: y)
+  }
+}
+
+extension CGPoint {
+  var vector3dValue: Vector3D {
+    Vector3D(x: x, y: y, z: 0)
+  }
+}
+
+extension CGSize {
+  var vector3dValue: Vector3D {
+    Vector3D(x: width, y: height, z: 1)
+  }
+}
+
+extension CATransform3D {
+
+  static func makeSkew(skew: CGFloat, skewAxis: CGFloat) -> CATransform3D {
+    let mCos = cos(skewAxis.toRadians())
+    let mSin = sin(skewAxis.toRadians())
+    let aTan = tan(skew.toRadians())
+
+    let transform1 = CATransform3D(
+      m11: mCos,
+      m12: mSin,
+      m13: 0,
+      m14: 0,
+      m21: -mSin,
+      m22: mCos,
+      m23: 0,
+      m24: 0,
+      m31: 0,
+      m32: 0,
+      m33: 1,
+      m34: 0,
+      m41: 0,
+      m42: 0,
+      m43: 0,
+      m44: 1)
+
+    let transform2 = CATransform3D(
+      m11: 1,
+      m12: 0,
+      m13: 0,
+      m14: 0,
+      m21: aTan,
+      m22: 1,
+      m23: 0,
+      m24: 0,
+      m31: 0,
+      m32: 0,
+      m33: 1,
+      m34: 0,
+      m41: 0,
+      m42: 0,
+      m43: 0,
+      m44: 1)
+
+    let transform3 = CATransform3D(
+      m11: mCos,
+      m12: -mSin,
+      m13: 0,
+      m14: 0,
+      m21: mSin,
+      m22: mCos,
+      m23: 0,
+      m24: 0,
+      m31: 0,
+      m32: 0,
+      m33: 1,
+      m34: 0,
+      m41: 0,
+      m42: 0,
+      m43: 0,
+      m44: 1)
+    return CATransform3DConcat(transform3, CATransform3DConcat(transform2, transform1))
+  }
+
+  static func makeTransform(
+    anchor: CGPoint,
+    position: CGPoint,
+    scale: CGSize,
+    rotation: CGFloat,
+    skew: CGFloat?,
+    skewAxis: CGFloat?)
+    -> CATransform3D
+  {
+    if let skew = skew, let skewAxis = skewAxis {
+      return CATransform3DMakeTranslation(position.x, position.y, 0).rotated(rotation).skewed(skew: -skew, skewAxis: skewAxis)
+        .scaled(scale * 0.01).translated(anchor * -1)
+    }
+    return CATransform3DMakeTranslation(position.x, position.y, 0).rotated(rotation).scaled(scale * 0.01).translated(anchor * -1)
+  }
+
+  func rotated(_ degrees: CGFloat) -> CATransform3D {
+    CATransform3DRotate(self, degrees.toRadians(), 0, 0, 1)
+  }
+
+  func translated(_ translation: CGPoint) -> CATransform3D {
+    CATransform3DTranslate(self, translation.x, translation.y, 0)
+  }
+
+  func scaled(_ scale: CGSize) -> CATransform3D {
+    CATransform3DScale(self, scale.width, scale.height, 1)
+  }
+
+  func skewed(skew: CGFloat, skewAxis: CGFloat) -> CATransform3D {
+    CATransform3DConcat(CATransform3D.makeSkew(skew: skew, skewAxis: skewAxis), self)
+  }
+}

package/Sources/Public/Animation/AnimationPublic.swift

@@ -0,0 +1,269 @@
+//
+//  AnimationPublic.swift
+//  lottie-swift
+//
+//  Created by Brandon Withrow on 2/5/19.
+//
+
+import CoreGraphics
+import Foundation
+
+extension Animation {
+
+  /// A closure for an Animation download. The closure is passed `nil` if there was an error.
+  public typealias DownloadClosure = (Animation?) -> Void
+
+  /// The duration in seconds of the animation.
+  public var duration: TimeInterval {
+    Double(endFrame - startFrame) / framerate
+  }
+
+  /// The natural bounds in points of the animation.
+  public var bounds: CGRect {
+    CGRect(x: 0, y: 0, width: width, height: height)
+  }
+
+  /// The natural size in points of the animation.
+  public var size: CGSize {
+    CGSize(width: width, height: height)
+  }
+
+  // MARK: Animation (Loading)
+
+  /// Loads an animation model from a bundle by its name. Returns `nil` if an animation is not found.
+  ///
+  /// - Parameter name: The name of the json file without the json extension. EG "StarAnimation"
+  /// - Parameter bundle: The bundle in which the animation is located. Defaults to `Bundle.main`
+  /// - Parameter subdirectory: A subdirectory in the bundle in which the animation is located. Optional.
+  /// - Parameter animationCache: A cache for holding loaded animations. Optional.
+  ///
+  /// - Returns: Deserialized `Animation`. Optional.
+  public static func named(
+    _ name: String,
+    bundle: Bundle = Bundle.main,
+    subdirectory: String? = nil,
+    animationCache: AnimationCacheProvider? = nil)
+    -> Animation?
+  {
+    /// Create a cache key for the animation.
+    let cacheKey = bundle.bundlePath + (subdirectory ?? "") + "/" + name
+
+    /// Check cache for animation
+    if
+      let animationCache = animationCache,
+      let animation = animationCache.animation(forKey: cacheKey)
+    {
+      /// If found, return the animation.
+      return animation
+    }
+
+    do {
+      /// Decode animation.
+      guard let json = try bundle.getAnimationData(name, subdirectory: subdirectory) else {
+        return nil
+      }
+      let animation = try Animation.from(data: json)
+      animationCache?.setAnimation(animation, forKey: cacheKey)
+      return animation
+    } catch {
+      /// Decoding error.
+      LottieLogger.shared.warn("Error when decoding animation \"\(name)\": \(error)")
+      return nil
+    }
+  }
+
+  /// Loads an animation from a specific filepath.
+  /// - Parameter filepath: The absolute filepath of the animation to load. EG "/User/Me/starAnimation.json"
+  /// - Parameter animationCache: A cache for holding loaded animations. Optional.
+  ///
+  /// - Returns: Deserialized `Animation`. Optional.
+  public static func filepath(
+    _ filepath: String,
+    animationCache: AnimationCacheProvider? = nil)
+    -> Animation?
+  {
+
+    /// Check cache for animation
+    if
+      let animationCache = animationCache,
+      let animation = animationCache.animation(forKey: filepath)
+    {
+      return animation
+    }
+
+    do {
+      /// Decode the animation.
+      let json = try Data(contentsOf: URL(fileURLWithPath: filepath))
+      let animation = try Animation.from(data: json)
+      animationCache?.setAnimation(animation, forKey: filepath)
+      return animation
+    } catch {
+      /// Decoding Error.
+      return nil
+    }
+  }
+
+  ///    Loads an animation model from the asset catalog by its name. Returns `nil` if an animation is not found.
+  ///    - Parameter name: The name of the json file in the asset catalog. EG "StarAnimation"
+  ///    - Parameter bundle: The bundle in which the animation is located. Defaults to `Bundle.main`
+  ///    - Parameter animationCache: A cache for holding loaded animations. Optional.
+  ///    - Returns: Deserialized `Animation`. Optional.
+  public static func asset(
+    _ name: String,
+    bundle: Bundle = Bundle.main,
+    animationCache: AnimationCacheProvider? = nil)
+    -> Animation?
+  {
+    /// Create a cache key for the animation.
+    let cacheKey = bundle.bundlePath + "/" + name
+
+    /// Check cache for animation
+    if
+      let animationCache = animationCache,
+      let animation = animationCache.animation(forKey: cacheKey)
+    {
+      /// If found, return the animation.
+      return animation
+    }
+
+    /// Load jsonData from Asset
+    guard let json = Data.jsonData(from: name, in: bundle) else {
+      return nil
+    }
+
+    do {
+      /// Decode animation.
+      let animation = try Animation.from(data: json)
+      animationCache?.setAnimation(animation, forKey: cacheKey)
+      return animation
+    } catch {
+      /// Decoding error.
+      return nil
+    }
+  }
+
+  /// Loads a Lottie animation from a `Data` object containing a JSON animation.
+  ///
+  /// - Parameter data: The object to load the animation from.
+  /// - Parameter strategy: How the data should be decoded. Defaults to using the strategy set in `LottieConfiguration.shared`.
+  /// - Returns: Deserialized `Animation`. Optional.
+  ///
+  public static func from(
+    data: Data,
+    strategy: DecodingStrategy = LottieConfiguration.shared.decodingStrategy) throws
+    -> Animation
+  {
+    switch strategy {
+    case .codable:
+      return try JSONDecoder().decode(Animation.self, from: data)
+    case .dictionaryBased:
+      let json = try JSONSerialization.jsonObject(with: data)
+      guard let dict = json as? [String: Any] else {
+        throw InitializableError.invalidInput
+      }
+      return try Animation(dictionary: dict)
+    }
+  }
+
+  /// Loads a Lottie animation asynchronously from the URL.
+  ///
+  /// - Parameter url: The url to load the animation from.
+  /// - Parameter closure: A closure to be called when the animation has loaded.
+  /// - Parameter animationCache: A cache for holding loaded animations.
+  ///
+  public static func loadedFrom(
+    url: URL,
+    closure: @escaping Animation.DownloadClosure,
+    animationCache: AnimationCacheProvider?)
+  {
+
+    if let animationCache = animationCache, let animation = animationCache.animation(forKey: url.absoluteString) {
+      closure(animation)
+    } else {
+      let task = URLSession.shared.dataTask(with: url) { data, _, error in
+        guard error == nil, let jsonData = data else {
+          DispatchQueue.main.async {
+            closure(nil)
+          }
+          return
+        }
+        do {
+          let animation = try Animation.from(data: jsonData)
+          DispatchQueue.main.async {
+            animationCache?.setAnimation(animation, forKey: url.absoluteString)
+            closure(animation)
+          }
+        } catch {
+          DispatchQueue.main.async {
+            closure(nil)
+          }
+        }
+
+      }
+      task.resume()
+    }
+  }
+
+  // MARK: Animation (Helpers)
+
+  /// Markers are a way to describe a point in time by a key name.
+  ///
+  /// Markers are encoded into animation JSON. By using markers a designer can mark
+  /// playback points for a developer to use without having to worry about keeping
+  /// track of animation frames. If the animation file is updated, the developer
+  /// does not need to update playback code.
+  ///
+  /// Returns the Progress Time for the marker named. Returns nil if no marker found.
+  public func progressTime(forMarker named: String) -> AnimationProgressTime? {
+    guard let markers = markerMap, let marker = markers[named] else {
+      return nil
+    }
+    return progressTime(forFrame: marker.frameTime)
+  }
+
+  /// Markers are a way to describe a point in time by a key name.
+  ///
+  /// Markers are encoded into animation JSON. By using markers a designer can mark
+  /// playback points for a developer to use without having to worry about keeping
+  /// track of animation frames. If the animation file is updated, the developer
+  /// does not need to update playback code.
+  ///
+  /// Returns the Frame Time for the marker named. Returns nil if no marker found.
+  public func frameTime(forMarker named: String) -> AnimationFrameTime? {
+    guard let markers = markerMap, let marker = markers[named] else {
+      return nil
+    }
+    return marker.frameTime
+  }
+
+  /// Converts Frame Time (Seconds * Framerate) into Progress Time
+  /// (optionally clamped to between 0 and 1).
+  public func progressTime(
+    forFrame frameTime: AnimationFrameTime,
+    clamped: Bool = true)
+    -> AnimationProgressTime
+  {
+    let progressTime = ((frameTime - startFrame) / (endFrame - startFrame))
+
+    if clamped {
+      return progressTime.clamp(0, 1)
+    } else {
+      return progressTime
+    }
+  }
+
+  /// Converts Progress Time (0 to 1) into Frame Time (Seconds * Framerate)
+  public func frameTime(forProgress progressTime: AnimationProgressTime) -> AnimationFrameTime {
+    ((endFrame - startFrame) * progressTime) + startFrame
+  }
+
+  /// Converts Frame Time (Seconds * Framerate) into Time (Seconds)
+  public func time(forFrame frameTime: AnimationFrameTime) -> TimeInterval {
+    Double(frameTime - startFrame) / framerate
+  }
+
+  /// Converts Time (Seconds) into Frame Time (Seconds * Framerate)
+  public func frameTime(forTime time: TimeInterval) -> AnimationFrameTime {
+    CGFloat(time * framerate) + startFrame
+  }
+}