lottie-ios 3.2.3 → 3.4.0

package/{lottie-swift/src → Sources}/Private/Utility/Primitives/ColorExtension.swift

@@ -5,35 +5,39 @@
 //  Created by Brandon Withrow on 1/14/19.
 //
 
-import Foundation
 import CoreGraphics
+import Foundation
+
+// MARK: - Color + Codable
 
 extension Color: Codable {
 
+  // MARK: Lifecycle
+
   public init(from decoder: Decoder) throws {
     var container = try decoder.unkeyedContainer()
-    
+
     var r1: Double
     if !container.isAtEnd {
       r1 = try container.decode(Double.self)
     } else {
       r1 = 0
     }
-    
+
     var g1: Double
     if !container.isAtEnd {
       g1 = try container.decode(Double.self)
     } else {
       g1 = 0
     }
-    
+
     var b1: Double
     if !container.isAtEnd {
       b1 = try container.decode(Double.self)
     } else {
       b1 = 0
     }
-    
+
     var a1: Double
     if !container.isAtEnd {
       a1 = try container.decode(Double.self)
@@ -46,12 +50,14 @@ extension Color: Codable {
       b1 = b1 / 255
       a1 = a1 / 255
     }
-    self.r = r1
-    self.g = g1
-    self.b = b1
-    self.a = a1
+    r = r1
+    g = g1
+    b = b1
+    a = a1
   }
-  
+
+  // MARK: Public
+
   public func encode(to encoder: Encoder) throws {
     var container = encoder.unkeyedContainer()
     try container.encode(r)
@@ -59,15 +65,41 @@ extension Color: Codable {
     try container.encode(b)
     try container.encode(a)
   }
-  
+
+}
+
+// MARK: - Color + AnyInitializable
+
+extension Color: AnyInitializable {
+
+  init(value: Any) throws {
+    guard var array = value as? [Double] else {
+      throw InitializableError.invalidInput
+    }
+    var r: Double = array.count > 0 ? array.removeFirst() : 0
+    var g: Double = array.count > 0 ? array.removeFirst() : 0
+    var b: Double = array.count > 0 ? array.removeFirst() : 0
+    var a: Double = array.count > 0 ? array.removeFirst() : 1
+    if r > 1, g > 1, b > 1, a > 1 {
+      r /= 255
+      g /= 255
+      b /= 255
+      a /= 255
+    }
+    self.r = r
+    self.g = g
+    self.b = b
+    self.a = a
+  }
+
 }
 
 extension Color {
-  
+
   static var clearColor: CGColor {
-    return CGColor(colorSpace: CGColorSpaceCreateDeviceRGB(), components: [0, 0, 0, 0])!
+    CGColor(colorSpace: CGColorSpaceCreateDeviceRGB(), components: [0, 0, 0, 0])!
   }
-  
+
   var cgColorValue: CGColor {
     // TODO: Fix color spaces
     let colorspace = CGColorSpaceCreateDeviceRGB()

package/{lottie-swift/src → Sources}/Private/Utility/Primitives/CompoundBezierPath.swift

@@ -5,112 +5,119 @@
 //  Created by Brandon Withrow on 1/14/19.
 //
 
-import Foundation
 import CoreGraphics
+import Foundation
 
-/**
- A collection of BezierPath objects that can be trimmed and added.
- 
- */
+/// A collection of BezierPath objects that can be trimmed and added.
+///
 struct CompoundBezierPath {
-  
-  let paths: [BezierPath]
-  
-  let length: CGFloat
-  
+
+  // MARK: Lifecycle
+
   init() {
     paths = []
     length = 0
   }
-  
+
   init(path: BezierPath) {
-    self.paths = [path]
-    self.length = path.length
+    paths = [path]
+    length = path.length
   }
-  
+
   init(paths: [BezierPath], length: CGFloat) {
     self.paths = paths
     self.length = length
   }
-  
+
   init(paths: [BezierPath]) {
     self.paths = paths
     var l: CGFloat = 0
     for path in paths {
       l = l + path.length
     }
-    self.length = l
+    length = l
   }
-  
+
+  // MARK: Internal
+
+  let paths: [BezierPath]
+
+  let length: CGFloat
+
   func addPath(path: BezierPath) -> CompoundBezierPath {
     var newPaths = paths
     newPaths.append(path)
     return CompoundBezierPath(paths: newPaths, length: length + path.length)
   }
-  
+
   func combine(_ compoundBezier: CompoundBezierPath) -> CompoundBezierPath {
     var newPaths = paths
     newPaths.append(contentsOf: compoundBezier.paths)
     return CompoundBezierPath(paths: newPaths, length: length + compoundBezier.length)
   }
-  
+
   func trim(fromPosition: CGFloat, toPosition: CGFloat, offset: CGFloat, trimSimultaneously: Bool) -> CompoundBezierPath {
     if fromPosition == toPosition {
       return CompoundBezierPath()
     }
-    
+
     if trimSimultaneously {
       /// Trim each path individually.
       var newPaths = [BezierPath]()
       for path in paths {
-        newPaths.append(contentsOf: path.trim(fromLength: fromPosition * path.length,
-                                              toLength: toPosition * path.length,
-                                              offsetLength: offset * path.length))
+        newPaths.append(contentsOf: path.trim(
+          fromLength: fromPosition * path.length,
+          toLength: toPosition * path.length,
+          offsetLength: offset * path.length))
       }
       return CompoundBezierPath(paths: newPaths)
     }
-    
+
     /// Normalize lengths to the curve length.
-    var startPosition = (fromPosition+offset).truncatingRemainder(dividingBy: 1)
-    var endPosition =  (toPosition+offset).truncatingRemainder(dividingBy: 1)
-    
+    var startPosition = (fromPosition + offset).truncatingRemainder(dividingBy: 1)
+    var endPosition = (toPosition + offset).truncatingRemainder(dividingBy: 1)
+
     if startPosition < 0 {
       startPosition = 1 + startPosition
     }
-    
+
     if endPosition < 0 {
       endPosition = 1 + endPosition
     }
-    
+
     if startPosition == 1 {
       startPosition = 0
     }
     if endPosition == 0 {
       endPosition = 1
     }
-    
-    if startPosition == 0 && endPosition == 1 ||
+
+    if
+      startPosition == 0 && endPosition == 1 ||
       startPosition == endPosition ||
-      startPosition == 1 && endPosition == 0 {
+      startPosition == 1 && endPosition == 0
+    {
       /// The trim encompasses the entire path. Return.
       return self
     }
-    
+
     var positions: [(start: CGFloat, end: CGFloat)]
     if endPosition < startPosition {
-      positions = [(start: 0, end: endPosition * length),
-                   (start: startPosition * length, end: length)]
+      positions = [
+        (start: 0, end: endPosition * length),
+        (start: startPosition * length, end: length),
+      ]
     } else {
       positions = [(start: startPosition * length, end: endPosition * length)]
     }
-    
+
     var compoundPath = CompoundBezierPath()
     var trim = positions.remove(at: 0)
     var pathStartPosition: CGFloat = 0
-    
-    var finishedTrimming: Bool = false
-    var i: Int = 0
-    
+
+    var finishedTrimming = false
+    var i = 0
+
     while !finishedTrimming {
       if paths.count <= i {
         /// Rounding errors
@@ -118,27 +125,29 @@ struct CompoundBezierPath {
         continue
       }
       let path = paths[i]
-      
+
       let pathEndPosition = pathStartPosition + path.length
-      
+
       if pathEndPosition < trim.start {
         /// Path is not included in the trim, continue.
         pathStartPosition = pathEndPosition
         i = i + 1
         continue
-        
+
       } else if trim.start <= pathStartPosition, pathEndPosition <= trim.end {
         /// Full Path is inside of trim. Add full path.
         compoundPath = compoundPath.addPath(path: path)
       } else {
-        if let trimPath = path.trim(fromLength: trim.start > pathStartPosition ? (trim.start - pathStartPosition) : 0,
-                                 toLength: trim.end < pathEndPosition ? (trim.end - pathStartPosition) : path.length,
-                                 offsetLength: 0).first {
-            compoundPath = compoundPath.addPath(path: trimPath)
+        if
+          let trimPath = path.trim(
+            fromLength: trim.start > pathStartPosition ? (trim.start - pathStartPosition) : 0,
+            toLength: trim.end < pathEndPosition ? (trim.end - pathStartPosition) : path.length,
+            offsetLength: 0).first
+        {
+          compoundPath = compoundPath.addPath(path: trimPath)
         }
       }
 
-      
       if trim.end <= pathEndPosition {
         /// We are done with the current trim.
         /// Advance trim but remain on the same path in case the next trim overlaps it.
@@ -154,5 +163,5 @@ struct CompoundBezierPath {
     }
     return compoundPath
   }
-  
+
 }

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

@@ -0,0 +1,186 @@
+//
+//  CurveVertex.swift
+//  lottie-swift
+//
+//  Created by Brandon Withrow on 1/11/19.
+//
+
+import CoreGraphics
+import Foundation
+
+/// A single vertex with an in and out tangent
+struct CurveVertex {
+
+  // MARK: Lifecycle
+
+  /// Initializes a curve point with absolute values
+  init(_ inTangent: CGPoint, _ point: CGPoint, _ outTangent: CGPoint) {
+    self.point = point
+    self.inTangent = inTangent
+    self.outTangent = outTangent
+  }
+
+  /// Initializes a curve point with relative values
+  init(point: CGPoint, inTangentRelative: CGPoint, outTangentRelative: CGPoint) {
+    self.point = point
+    inTangent = point.add(inTangentRelative)
+    outTangent = point.add(outTangentRelative)
+  }
+
+  /// Initializes a curve point with absolute values
+  init(point: CGPoint, inTangent: CGPoint, outTangent: CGPoint) {
+    self.point = point
+    self.inTangent = inTangent
+    self.outTangent = outTangent
+  }
+
+  // MARK: Internal
+
+  let point: CGPoint
+
+  let inTangent: CGPoint
+  let outTangent: CGPoint
+
+  var inTangentRelative: CGPoint {
+    inTangent.subtract(point)
+  }
+
+  var outTangentRelative: CGPoint {
+    outTangent.subtract(point)
+  }
+
+  func reversed() -> CurveVertex {
+    CurveVertex(point: point, inTangent: outTangent, outTangent: inTangent)
+  }
+
+  func translated(_ translation: CGPoint) -> CurveVertex {
+    CurveVertex(point: point + translation, inTangent: inTangent + translation, outTangent: outTangent + translation)
+  }
+
+  /// Trims a path defined by two Vertices at a specific position, from 0 to 1
+  ///
+  /// The path can be visualized below.
+  ///
+  /// F is fromVertex.
+  /// V is the vertex of the receiver.
+  /// P is the position from 0-1.
+  /// O is the outTangent of fromVertex.
+  /// F====O=========P=======I====V
+  ///
+  /// After trimming the curve can be visualized below.
+  ///
+  /// S is the returned Start vertex.
+  /// E is the returned End vertex.
+  /// T is the trim point.
+  /// TI and TO are the new tangents for the trimPoint
+  /// NO and NI are the new tangents for the startPoint and endPoints
+  /// S==NO=========TI==T==TO=======NI==E
+  func splitCurve(toVertex: CurveVertex, position: CGFloat) ->
+    (start: CurveVertex, trimPoint: CurveVertex, end: CurveVertex)
+  {
+
+    /// If position is less than or equal to 0, trim at start.
+    if position <= 0 {
+      return (
+        start: CurveVertex(point: point, inTangentRelative: inTangentRelative, outTangentRelative: .zero),
+        trimPoint: CurveVertex(point: point, inTangentRelative: .zero, outTangentRelative: outTangentRelative),
+        end: toVertex)
+    }
+
+    /// If position is greater than or equal to 1, trim at end.
+    if position >= 1 {
+      return (
+        start: self,
+        trimPoint: CurveVertex(
+          point: toVertex.point,
+          inTangentRelative: toVertex.inTangentRelative,
+          outTangentRelative: .zero),
+        end: CurveVertex(
+          point: toVertex.point,
+          inTangentRelative: .zero,
+          outTangentRelative: toVertex.outTangentRelative))
+    }
+
+    if outTangentRelative.isZero && toVertex.inTangentRelative.isZero {
+      /// If both tangents are zero, then span to be trimmed is a straight line.
+      let trimPoint = point.interpolate(to: toVertex.point, amount: position)
+      return (
+        start: self,
+        trimPoint: CurveVertex(point: trimPoint, inTangentRelative: .zero, outTangentRelative: .zero),
+        end: toVertex)
+    }
+    /// Cutting by amount gives incorrect length....
+    /// One option is to cut by a stride until it gets close then edge it down.
+    /// Measuring a percentage of the spans does not equal the same as measuring a percentage of length.
+    /// This is where the historical trim path bugs come from.
+    let a = point.interpolate(to: outTangent, amount: position)
+    let b = outTangent.interpolate(to: toVertex.inTangent, amount: position)
+    let c = toVertex.inTangent.interpolate(to: toVertex.point, amount: position)
+    let d = a.interpolate(to: b, amount: position)
+    let e = b.interpolate(to: c, amount: position)
+    let f = d.interpolate(to: e, amount: position)
+    return (
+      start: CurveVertex(point: point, inTangent: inTangent, outTangent: a),
+      trimPoint: CurveVertex(point: f, inTangent: d, outTangent: e),
+      end: CurveVertex(point: toVertex.point, inTangent: c, outTangent: toVertex.outTangent))
+  }
+
+  /// Trims a curve of a known length to a specific length and returns the points.
+  ///
+  /// There is not a performant yet accurate way to cut a curve to a specific length.
+  /// This calls splitCurve(toVertex: position:) to split the curve and then measures
+  /// the length of the new curve. The function then iterates through the samples,
+  /// adjusting the position of the cut for a more precise cut.
+  /// Usually a single iteration is enough to get within 0.5 points of the desired
+  /// length.
+  ///
+  /// This function should probably live in PathElement, since it deals with curve
+  /// lengths.
+  func trimCurve(toVertex: CurveVertex, atLength: CGFloat, curveLength: CGFloat, maxSamples: Int, accuracy: CGFloat = 1) ->
+    (start: CurveVertex, trimPoint: CurveVertex, end: CurveVertex)
+  {
+    var currentPosition = atLength / curveLength
+    var results = splitCurve(toVertex: toVertex, position: currentPosition)
+
+    if maxSamples == 0 {
+      return results
+    }
+
+    for _ in 1...maxSamples {
+      let length = results.start.distanceTo(results.trimPoint)
+      let lengthDiff = atLength - length
+      /// Check if length is correct.
+      if lengthDiff < accuracy {
+        return results
+      }
+      let diffPosition = max(min((currentPosition / length) * lengthDiff, currentPosition * 0.5), currentPosition * -0.5)
+      currentPosition = diffPosition + currentPosition
+      results = splitCurve(toVertex: toVertex, position: currentPosition)
+    }
+    return results
+  }
+
+  /// The distance from the receiver to the provided vertex.
+  ///
+  /// For lines (zeroed tangents) the distance between the two points is measured.
+  /// For curves the curve is iterated over by sample count and the points are measured.
+  /// This is ~99% accurate at a sample count of 30
+  func distanceTo(_ toVertex: CurveVertex, sampleCount: Int = 25) -> CGFloat {
+
+    if outTangentRelative.isZero && toVertex.inTangentRelative.isZero {
+      /// Return a linear distance.
+      return point.distanceTo(toVertex.point)
+    }
+
+    var distance: CGFloat = 0
+
+    var previousPoint = point
+    for i in 0..<sampleCount {
+      let pointOnCurve = splitCurve(toVertex: toVertex, position: CGFloat(i) / CGFloat(sampleCount)).trimPoint
+      distance = distance + previousPoint.distanceTo(pointOnCurve.point)
+      previousPoint = pointOnCurve.point
+    }
+    distance = distance + previousPoint.distanceTo(toVertex.point)
+    return distance
+  }
+}

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

@@ -0,0 +1,75 @@
+//
+//  PathElement.swift
+//  lottie-swift
+//
+//  Created by Brandon Withrow on 1/11/19.
+//
+
+import CoreGraphics
+import Foundation
+
+/// A path section, containing one point and its length to the previous point.
+///
+/// The relationship between this path element and the previous is implicit.
+/// Ideally a path section would be defined by two vertices and a length.
+/// We don't do this however, as it would effectively double the memory footprint
+/// of path data.
+///
+struct PathElement {
+
+  // MARK: Lifecycle
+
+  /// Initializes a new path with length of 0
+  init(vertex: CurveVertex) {
+    length = 0
+    self.vertex = vertex
+  }
+
+  /// Initializes a new path with length
+  private init(length: CGFloat, vertex: CurveVertex) {
+    self.length = length
+    self.vertex = vertex
+  }
+
+  // MARK: Internal
+
+  /// The absolute Length of the path element.
+  let length: CGFloat
+
+  /// The vertex of the element
+  let vertex: CurveVertex
+
+  /// Returns a new path element define the span from the receiver to the new vertex.
+  func pathElementTo(_ toVertex: CurveVertex) -> PathElement {
+    PathElement(length: vertex.distanceTo(toVertex), vertex: toVertex)
+  }
+
+  func updateVertex(newVertex: CurveVertex) -> PathElement {
+    PathElement(length: length, vertex: newVertex)
+  }
+
+  /// Splits an element span defined by the receiver and fromElement to a position 0-1
+  func splitElementAtPosition(fromElement: PathElement, atLength: CGFloat) ->
+    (leftSpan: (start: PathElement, end: PathElement), rightSpan: (start: PathElement, end: PathElement))
+  {
+    /// Trim the span. Start and trim go into the first, trim and end go into second.
+    let trimResults = fromElement.vertex.trimCurve(toVertex: vertex, atLength: atLength, curveLength: length, maxSamples: 3)
+
+    /// Create the elements for the break
+    let spanAStart = PathElement(
+      length: fromElement.length,
+      vertex: CurveVertex(
+        point: fromElement.vertex.point,
+        inTangent: fromElement.vertex.inTangent,
+        outTangent: trimResults.start.outTangent))
+    /// Recalculating the length here is a waste as the trimCurve function also accurately calculates this length.
+    let spanAEnd = spanAStart.pathElementTo(trimResults.trimPoint)
+
+    let spanBStart = PathElement(vertex: trimResults.trimPoint)
+    let spanBEnd = spanBStart.pathElementTo(trimResults.end)
+    return (
+      leftSpan: (start: spanAStart, end: spanAEnd),
+      rightSpan: (start: spanBStart, end: spanBEnd))
+  }
+
+}

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

@@ -0,0 +1,115 @@
+// Copyright (C) 2008 Apple Inc. All Rights Reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions
+// are met:
+// 1. Redistributions of source code must retain the above copyright
+//    notice, this list of conditions and the following disclaimer.
+// 2. Redistributions in binary form must reproduce the above copyright
+//    notice, this list of conditions and the following disclaimer in the
+//    documentation and/or other materials provided with the distribution.
+//
+// THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
+// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+// PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
+// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+import CoreGraphics
+import Foundation
+
+/// Defines a cubic-bezier where the endpoints are (0, 0) and (1, 1)
+///
+/// The main use case is computing the progress of an animation at a given percent completion. For instance,
+/// for a linear animation, the expected progress at `0.5` is `0.5`.
+///
+/// - Note: This is a Swift port of [Apple's WebKit code](
+///   http://svn.webkit.org/repository/webkit/trunk/Source/WebCore/platform/graphics/UnitBezier.h
+/// )
+///
+struct UnitBezier {
+
+  // MARK: Lifecycle
+
+  init(controlPoint1: CGPoint, controlPoint2: CGPoint) {
+    cx = 3.0 * controlPoint1.x
+    bx = 3.0 * (controlPoint2.x - controlPoint1.x) - cx
+    ax = 1.0 - cx - bx
+    cy = 3.0 * controlPoint1.y
+    by = 3.0 * (controlPoint2.y - controlPoint1.y) - cy
+    ay = 1.0 - cy - by
+  }
+
+  // MARK: Internal
+
+  /// Computes the progress `y` value for a given `x` value
+  func value(for x: CGFloat, epsilon: CGFloat) -> CGFloat {
+    sampleCurveY(solveCurveX(x, epsilon: epsilon))
+  }
+
+  // MARK: Private
+
+  private let ax: CGFloat
+  private let bx: CGFloat
+  private let cx: CGFloat
+  private let ay: CGFloat
+  private let by: CGFloat
+  private let cy: CGFloat
+
+  /// Compute `x(t)` for a given `t`
+  private func sampleCurveX(_ t: CGFloat) -> CGFloat {
+    // `ax t^3 + bx t^2 + cx t' expanded using Horner's rule.
+    ((ax * t + bx) * t + cx) * t
+  }
+
+  /// Compute `y(t)` for a given `t`
+  private func sampleCurveY(_ t: CGFloat) -> CGFloat {
+    ((ay * t + by) * t + cy) * t
+  }
+
+  /// Compute `x'(t)` for a given `t`
+  private func sampleCurveDerivativeX(_ t: CGFloat) -> CGFloat {
+    (3.0 * ax * t + 2.0 * bx) * t + cx
+  }
+
+  /// Given an `x` value solve for the parametric value `t`
+  private func solveCurveX(_ x: CGFloat, epsilon: CGFloat) -> CGFloat {
+    var t0, t1, t2, x2, d2: CGFloat
+
+    // First try a few iterations of Newton-Raphson -- normally very fast.
+    t2 = x
+    for _ in 0..<8 {
+      x2 = sampleCurveX(t2) - x
+      guard abs(x2) >= epsilon else { return t2 }
+      d2 = sampleCurveDerivativeX(t2)
+      guard abs(d2) >= 1e-6 else { break }
+      t2 = t2 - x2 / d2
+    }
+
+    // Fall back to the bisection method for reliability.
+    t0 = 0.0
+    t1 = 1.0
+    t2 = x
+    guard t2 >= t0 else { return t0 }
+    guard t2 <= t1 else { return t1 }
+
+    while t0 < t1 {
+      x2 = sampleCurveX(t2)
+      guard abs(x2 - x) >= epsilon else { return t2 }
+      if x > x2 {
+        t0 = t2
+      } else {
+        t1 = t2
+      }
+      t2 = (t1 - t0) * 0.5 + t0
+    }
+
+    return t2
+  }
+}