lottie-ios 3.2.2 → 3.4.1

package/Sources/Public/macOS/FilepathImageProvider.macOS.swift

@@ -0,0 +1,67 @@
+//
+//  FilepathImageProvider.swift
+//  lottie-swift
+//
+//  Created by Brandon Withrow on 2/1/19.
+//
+
+#if os(macOS)
+import AppKit
+
+/// An `AnimationImageProvider` that provides images by name from a specific filepath.
+public class FilepathImageProvider: AnimationImageProvider {
+
+  // MARK: Lifecycle
+
+  /// Initializes an image provider with a specific filepath.
+  ///
+  /// - Parameter filepath: The absolute filepath containing the images.
+  ///
+  public init(filepath: String) {
+    self.filepath = URL(fileURLWithPath: filepath)
+  }
+
+  public init(filepath: URL) {
+    self.filepath = filepath
+  }
+
+  // MARK: Public
+
+  public func imageForAsset(asset: ImageAsset) -> CGImage? {
+    if
+      asset.name.hasPrefix("data:"),
+      let url = URL(string: asset.name),
+      let data = try? Data(contentsOf: url),
+      let image = NSImage(data: data)
+    {
+      return image.lottie_CGImage
+    }
+
+    let directPath = filepath.appendingPathComponent(asset.name).path
+    if FileManager.default.fileExists(atPath: directPath) {
+      return NSImage(contentsOfFile: directPath)?.lottie_CGImage
+    }
+
+    let pathWithDirectory = filepath.appendingPathComponent(asset.directory).appendingPathComponent(asset.name).path
+    if FileManager.default.fileExists(atPath: pathWithDirectory) {
+      return NSImage(contentsOfFile: pathWithDirectory)?.lottie_CGImage
+    }
+
+    LottieLogger.shared.assertionFailure("Could not find image \"\(asset.name)\" in bundle")
+    return nil
+  }
+
+  // MARK: Internal
+
+  let filepath: URL
+}
+
+extension NSImage {
+  @nonobjc
+  var lottie_CGImage: CGImage? {
+    guard let imageData = tiffRepresentation else { return nil }
+    guard let sourceData = CGImageSourceCreateWithData(imageData as CFData, nil) else { return nil }
+    return CGImageSourceCreateImageAtIndex(sourceData, 0, nil)
+  }
+}
+#endif

package/Tests/AnimationKeypathTests.swift

@@ -0,0 +1,94 @@
+// Created by Cal Stephens on 1/24/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import SnapshotTesting
+import XCTest
+
+@testable import Lottie
+
+final class AnimationKeypathTests: XCTestCase {
+
+  // MARK: Internal
+
+  func testKeypathMatches() {
+    let keypath = AnimationKeypath(keypath: "Layer.Shape Group.Stroke 1.Color")
+
+    XCTAssertTrue(keypath.matches("Layer.Shape Group.Stroke 1.Color"))
+    XCTAssertTrue(keypath.matches("**.Color"))
+    XCTAssertTrue(keypath.matches("**.Stroke 1.Color"))
+    XCTAssertTrue(keypath.matches("**.Shape Group.Stroke 1.Color"))
+    XCTAssertTrue(keypath.matches("Layer.**.Color"))
+    XCTAssertTrue(keypath.matches("Layer.Shape Group.*.Color"))
+    XCTAssertTrue(keypath.matches("Layer.*.*.Color"))
+
+    XCTAssertFalse(keypath.matches("Layer.*.Color"))
+    XCTAssertFalse(keypath.matches("**.Layer.Shape Group.Stroke 1.Color"))
+    XCTAssertFalse(keypath.matches("*.Layer.Shape Group.Stroke 1.Color"))
+    XCTAssertFalse(keypath.matches("Layer.Shape Group.Stroke 1.Color.*"))
+    XCTAssertFalse(keypath.matches("Layer.Shape Group.Stroke 1.Color.**"))
+  }
+
+  func testLayerForKeypath() {
+    let animationView = AnimationView(
+      animation: Samples.animation(named: "Boat_Loader"),
+      configuration: LottieConfiguration(renderingEngine: .mainThread))
+
+    XCTAssertNotNil(animationView.animationLayer?.layer(for: "Success.FishComplete.Fish1Tail 7"))
+    XCTAssertNotNil(animationView.animationLayer?.layer(for: "Success.FishComplete"))
+    XCTAssertNotNil(animationView.animationLayer?.layer(for: "Success"))
+    XCTAssertNotNil(animationView.animationLayer?.layer(for: "Success.*.Fish1Tail 7"))
+  }
+
+  func testMainThreadEngineKeypathLogging() {
+    snapshotHierarchyKeypaths(
+      animationName: "Switch",
+      configuration: LottieConfiguration(renderingEngine: .mainThread))
+  }
+
+  func testCoreAnimationEngineKeypathLogging() {
+    snapshotHierarchyKeypaths(
+      animationName: "Switch",
+      configuration: LottieConfiguration(renderingEngine: .coreAnimation))
+  }
+
+  /// The Core Animation engine supports a subset of the keypaths supported by the Main Thread engine.
+  /// All keypaths that are supported in the Core Animation engine should also be supported by the Main Thread engine.
+  func testCoreAnimationEngineKeypathCompatibility() {
+    let mainThreadKeypaths = Set(hierarchyKeypaths(animationName: "Switch", configuration: .init(renderingEngine: .mainThread)))
+    let coreAnimationKeypaths = hierarchyKeypaths(animationName: "Switch", configuration: .init(renderingEngine: .coreAnimation))
+
+    for coreAnimationKeypath in coreAnimationKeypaths {
+      XCTAssert(mainThreadKeypaths.contains(coreAnimationKeypath))
+    }
+  }
+
+  // MARK: Private
+
+  private func snapshotHierarchyKeypaths(
+    animationName: String,
+    configuration: LottieConfiguration,
+    function: String = #function,
+    line: UInt = #line)
+  {
+    let hierarchyKeypaths = hierarchyKeypaths(animationName: animationName, configuration: configuration)
+
+    assertSnapshot(
+      matching: hierarchyKeypaths.sorted().joined(separator: "\n"),
+      as: .description,
+      named: animationName,
+      testName: function,
+      line: line)
+  }
+
+  private func hierarchyKeypaths(animationName: String, configuration: LottieConfiguration) -> [String] {
+    var printedMessages = [String]()
+    let logger = LottieLogger(info: { message in
+      printedMessages.append(message())
+    })
+
+    let animationView = SnapshotConfiguration.makeAnimationView(for: animationName, configuration: configuration, logger: logger)
+    animationView?.logHierarchyKeypaths()
+    return Array(printedMessages[1...])
+  }
+
+}

package/Tests/AutomaticEngineTests.swift

@@ -0,0 +1,57 @@
+// Created by Cal Stephens on 5/2/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import SnapshotTesting
+import UIKit
+import XCTest
+
+@testable import Lottie
+
+final class AutomaticEngineTests: XCTestCase {
+
+  /// Snapshot tests for whether or not each sample animation supports the Core Animation engine
+  func testAutomaticEngineDetection() throws {
+    for sampleAnimationName in Samples.sampleAnimationNames {
+      guard let animation = Samples.animation(named: sampleAnimationName) else { continue }
+
+      var compatibilityIssues = [CompatibilityIssue]()
+
+      let animationLayer = try XCTUnwrap(CoreAnimationLayer(
+        animation: animation,
+        imageProvider: BundleImageProvider(bundle: Bundle.main, searchPath: nil),
+        fontProvider: DefaultFontProvider(),
+        compatibilityTrackerMode: .track,
+        logger: .shared))
+
+      animationLayer.didSetUpAnimation = { issues in
+        compatibilityIssues = issues
+      }
+
+      animationLayer.bounds = CGRect(origin: .zero, size: animation.size)
+      animationLayer.layoutIfNeeded()
+      animationLayer.display()
+
+      let compatibilityReport: String
+      if compatibilityIssues.isEmpty {
+        compatibilityReport = "Supports Core Animation engine"
+      } else {
+        compatibilityReport = "Does not support Core Animation engine. Encountered compatibility issues:\n"
+          + compatibilityIssues.map { $0.description }.joined(separator: "\n")
+      }
+
+      assertSnapshot(
+        matching: compatibilityReport,
+        as: .description,
+        named: sampleAnimationName)
+    }
+  }
+
+  override func setUp() {
+    LottieLogger.shared = .printToConsole
+  }
+
+  override func tearDown() {
+    LottieLogger.shared = LottieLogger()
+  }
+
+}

package/Tests/BundleTests.swift

@@ -0,0 +1,25 @@
+//
+//  BundleTests.swift
+//  LottieTests
+//
+//  Created by Marcelo Fabri on 5/5/22.
+//
+
+import XCTest
+
+@testable import Lottie
+
+final class BundleTests: XCTestCase {
+
+  var bundle: Bundle { .module }
+
+  func testGetAnimationDataWithSuffix() throws {
+    let data = try bundle.getAnimationData("HamburgerArrow.json", subdirectory: "Samples")
+    XCTAssertNotNil(data)
+  }
+
+  func testGetAnimationDataWithoutSuffix() throws {
+    let data = try bundle.getAnimationData("HamburgerArrow", subdirectory: "Samples")
+    XCTAssertNotNil(data)
+  }
+}

package/Tests/DataURLTests.swift

@@ -0,0 +1,64 @@
+// Created by Nicholas Mata on 2/23/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import Foundation
+import XCTest
+
+@testable import Lottie
+
+// MARK: - DataURLTests
+
+// Tests are based on implementation found here
+// https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
+final class DataURLTests: XCTestCase {
+
+  let red5x5 =
+    "%89%50%4e%47%0d%0a%1a%0a%00%00%00%0d%49%48%44%52%00%00%00%05%00%00%00%05%08%06%00%00%00%8d%6f%26%e5%00%00%00%12%49%44%41%54%78%da%63%fc%cf%c0%00%44%a8%80%91%06%82%00%5c%65%09%fc%86%fe%00%b0%00%00%00%00%49%45%4e%44%ae%42%60%82"
+
+  let red5x5Base64 = "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAEklEQVR42mP8z8AARKiAkQaCAFxlCfyG/gCwAAAAAElFTkSuQmCC"
+
+  func testValidDataURL() {
+    let dataString = "data:image/png;base64,\(red5x5Base64)"
+
+    let data = Data(dataString: dataString)
+    XCTAssertNotNil(data, "Data should not be nil if valid base64 string")
+    let image = UIImage(data: data!)
+    XCTAssertNotNil(image, "Should be valid image")
+
+    // Since legacy options will print nil host logs
+    let legacyData = Data(dataString: dataString, options: .legacy)
+    XCTAssertNotNil(legacyData, "Data should not be nil if valid base64 string")
+    let legacyImage = UIImage(data: legacyData!)
+    XCTAssertNotNil(legacyImage, "Should be valid image")
+
+    XCTAssertEqual(data, legacyData)
+  }
+
+  func testValidDataURLWithoutBase64() {
+    let dataString = "data:image/png,\(red5x5)"
+    // Since ;base64 is missing still prints nil host warnings.
+    // If we can figure out how to turn red5x5 into Data properly
+    // like Data(contentsOf:) does then we can avoid the warning.
+    let data = Data(dataString: dataString)
+    XCTAssertNotNil(data, "Data should not be nil since format is valid data URL")
+
+    let image = UIImage(data: data!)
+    XCTAssertNotNil(image, "Should be valid image. Since missing ';base64' the data is valid just not base64 encoded")
+  }
+
+  func testInvalidDataURLWithBadBase64() {
+    let dataString = "data:image/png;base64,INVALIDBASE64"
+
+    let data = Data(dataString: dataString)
+    let legacyData = Data(dataString: dataString, options: .legacy)
+    XCTAssertNil(data, "Data should be nil because 'INVALIDBASE64' is not valid base64 string.")
+    XCTAssertNil(legacyData, "Data should be nil because 'INVALIDBASE64' is not valid base64 string.")
+  }
+
+  func testInvalidDataURL() {
+    let dataString = "ImageAssetName"
+
+    let data = Data(dataString: dataString)
+    XCTAssertNil(data, "Data should be nil as valid Data URL starts with 'data:'")
+  }
+}

package/Tests/ParsingTests.swift

@@ -0,0 +1,43 @@
+//
+//  ParsingTests.swift
+//  Lottie
+//
+//  Created by Marcelo Fabri on 5/5/22.
+//
+
+import Difference
+import Foundation
+import Lottie
+import XCTest
+
+// MARK: - ParsingTests
+
+final class ParsingTests: XCTestCase {
+
+  func testParsingIsTheSameForBothImplementations() throws {
+    for url in Samples.sampleAnimationURLs {
+      do {
+        let data = try Data(contentsOf: url)
+        let codableAnimation = try Animation.from(data: data, strategy: .codable)
+        let dictAnimation = try Animation.from(data: data, strategy: .dictionaryBased)
+
+        XCTAssertNoDiff(codableAnimation, dictAnimation)
+      } catch {
+        XCTFail("Error for \(url.lastPathComponent): \(error)")
+      }
+    }
+  }
+}
+
+func XCTAssertNoDiff<T>(
+  _ expected: @autoclosure () throws -> T,
+  _ received: @autoclosure () throws -> T,
+  file: StaticString = #filePath,
+  line: UInt = #line) rethrows
+{
+  let expected = try expected()
+  let received = try received()
+  let diff = diff(expected, received)
+  let isEqual = diff.isEmpty || diff.allSatisfy(\.isEmpty)
+  XCTAssertTrue(isEqual, "Found difference for \n" + diff.joined(separator: ", "), file: file, line: line)
+}

package/Tests/PerformanceTests.swift

@@ -0,0 +1,215 @@
+// Created by Cal Stephens on 2/14/22.
+// Copyright © 2022 Airbnb Inc. All rights reserved.
+
+import Foundation
+import XCTest
+
+@testable import Lottie
+
+// MARK: - PerformanceTests
+
+final class PerformanceTests: XCTestCase {
+
+  // MARK: Internal
+
+  func testAnimationViewSetup_simpleAnimation() {
+    // Compare the performance of displaying this simple animation in the two animation engines
+    let ratio = compareEngineSetupPerformance(
+      of: .mainThread,
+      with: .coreAnimation,
+      for: simpleAnimation,
+      iterations: 2000)
+
+    // This is basically a snapshot test for the performance of the Core Animation engine
+    // compared to the Main Thread engine. Currently, the Core Animation engine is
+    // about the same speed as the Main Thread engine in this example.
+    XCTAssertEqual(ratio, 1.0, accuracy: 0.35)
+  }
+
+  func testAnimationViewSetup_complexAnimation() {
+    // Compare the performance of displaying this simple animation in the two animation engines
+    let ratio = compareEngineSetupPerformance(
+      of: .mainThread,
+      with: .coreAnimation,
+      for: complexAnimation,
+      iterations: 500)
+
+    // The Core Animation engine is currently about 1.5x slower than the
+    // Main Thread engine in this example.
+    XCTAssertEqual(ratio, 1.5, accuracy: 0.6)
+  }
+
+  func testAnimationViewSetup_automaticEngine() {
+    // Compare the performance of displaying this simple animation with the core animation engine
+    // vs with the automatic engine option
+    let ratio = compareEngineSetupPerformance(
+      of: .coreAnimation,
+      with: .automatic,
+      for: simpleAnimation,
+      iterations: 2000)
+
+    // The automatic engine option should have the same performance as the core animation engine,
+    // when rendering an animation supported by the CA engine.
+    XCTAssertEqual(ratio, 1.0, accuracy: 0.2)
+  }
+
+  func testAnimationViewScrubbing_simpleAnimation() {
+    let ratio = compareEngineScrubbingPerformance(for: simpleAnimation, iterations: 2000)
+    XCTAssertEqual(ratio, 0.01, accuracy: 0.01)
+  }
+
+  func testAnimationViewScrubbing_complexAnimation() {
+    let ratio = compareEngineScrubbingPerformance(for: complexAnimation, iterations: 2000)
+    XCTAssertEqual(ratio, 0.01, accuracy: 0.01)
+  }
+
+  func testParsing_simpleAnimation() throws {
+    let data = try XCTUnwrap(Bundle.module.getAnimationData("loading_dots_1", subdirectory: "Samples/LottieFiles"))
+    let ratio = try compareDeserializationPerformance(data: data, iterations: 2000)
+    XCTAssertEqual(ratio, 2, accuracy: 0.55)
+  }
+
+  func testParsing_complexAnimation() throws {
+    let data = try XCTUnwrap(Bundle.module.getAnimationData("LottieLogo2", subdirectory: "Samples"))
+    let ratio = try compareDeserializationPerformance(data: data, iterations: 500)
+    XCTAssertEqual(ratio, 1.7, accuracy: 0.6)
+  }
+
+  override func setUp() {
+    TestHelpers.performanceTestsAreRunning = true
+  }
+
+  override func tearDown() {
+    TestHelpers.performanceTestsAreRunning = false
+  }
+
+  // MARK: Private
+
+  private let simpleAnimation = Animation.named(
+    "loading_dots_1",
+    bundle: .module,
+    subdirectory: "Samples/LottieFiles")!
+
+  private let complexAnimation = Animation.named(
+    "LottieLogo2",
+    bundle: .module,
+    subdirectory: "Samples")!
+
+  /// Compares initializing the given animation with the two given engines,
+  /// and returns the ratio of how much slower engine B is than engine A.
+  private func compareEngineSetupPerformance(
+    of engineA: RenderingEngineOption,
+    with engineB: RenderingEngineOption,
+    for animation: Animation,
+    iterations: Int)
+    -> Double
+  {
+    let engineAPerformance = measurePerformance {
+      for _ in 0..<iterations {
+        // Each animation setup needs to be wrapped in its own `CATransaction`
+        // in order for the layers to be deallocated immediately. Otherwise
+        // the layers aren't deallocated until the end of the test run,
+        // which causes memory usage to grow unbounded.
+        CATransaction.begin()
+        let animationView = setupAnimationView(with: animation, configuration: .init(renderingEngine: engineA))
+        // Call `display()` on the layer to make sure any pending setup occurs immediately
+        animationView.animationLayer!.display()
+        CATransaction.commit()
+      }
+    }
+
+    LottieLogger.shared.info("\(engineA) engine took \(engineAPerformance) seconds")
+
+    let engineBPerformance = measurePerformance {
+      for _ in 0..<iterations {
+        // Each animation setup needs to be wrapped in its own `CATransaction`
+        // in order for the layers to be deallocated immediately. Otherwise
+        // the layers aren't deallocated until the end of the test run,
+        // which causes memory usage to grow unbounded.
+        CATransaction.begin()
+        let animationView = setupAnimationView(with: animation, configuration: .init(renderingEngine: engineB))
+        // Call `display()` on the layer to make sure any pending setup occurs immediately
+        animationView.animationLayer!.display()
+        CATransaction.commit()
+      }
+    }
+
+    LottieLogger.shared.info("\(engineB) engine took \(engineBPerformance) seconds")
+
+    let ratio = engineBPerformance / engineAPerformance
+    LottieLogger.shared.info("\(engineB) engine took \(ratio)x as long as \(engineA) engine")
+    return ratio
+  }
+
+  /// Compares performance of scrubbing the given animation with both the Main Thread and Core Animation engine,
+  /// and returns the ratio of how much slower the Core Animation is than the Main Thread engine
+  private func compareEngineScrubbingPerformance(for animation: Animation, iterations: Int) -> Double {
+    let mainThreadAnimationView = setupAnimationView(with: animation, configuration: .init(renderingEngine: .mainThread))
+    let mainThreadEnginePerformance = measurePerformance {
+      for i in 0..<iterations {
+        mainThreadAnimationView.currentProgress = Double(i) / Double(iterations)
+
+        // Since the main thread engine only re-renders in `display()`, which is normally called by Core Animation,
+        // we have to invoke it manually. This triggers the same code path that would happen when scrubbing in
+        // a real use case.
+        mainThreadAnimationView.animationLayer!.display()
+      }
+    }
+
+    LottieLogger.shared.info("Main thread engine took \(mainThreadEnginePerformance) seconds")
+
+    let coreAnimationView = setupAnimationView(with: animation, configuration: .init(renderingEngine: .coreAnimation))
+    let coreAnimationEnginePerformance = measurePerformance {
+      for i in 0..<iterations {
+        coreAnimationView.currentProgress = Double(i) / Double(iterations)
+
+        // Call `display()` on the layer to make sure any pending setup occurs immediately
+        coreAnimationView.animationLayer!.display()
+      }
+    }
+
+    LottieLogger.shared.info("Core Animation engine took \(coreAnimationEnginePerformance) seconds")
+
+    let ratio = coreAnimationEnginePerformance / mainThreadEnginePerformance
+    LottieLogger.shared.info("Core Animation engine took \(ratio)x as long as the Main Thread engine")
+    return ratio
+  }
+
+  private func compareDeserializationPerformance(data: Data, iterations: Int) throws -> Double {
+    let codablePerformance = try measurePerformance {
+      for _ in 0..<iterations {
+        _ = try Animation.from(data: data, strategy: .codable)
+      }
+    }
+
+    LottieLogger.shared.info("Codable deserialization took \(codablePerformance) seconds")
+
+    let dictPerformance = try measurePerformance {
+      for _ in 0..<iterations {
+        _ = try Animation.from(data: data, strategy: .dictionaryBased)
+      }
+    }
+
+    LottieLogger.shared.info("DictionaryBased deserialization took \(dictPerformance) seconds")
+    let ratio = codablePerformance / dictPerformance
+    LottieLogger.shared.info("Codable deserialization took \(ratio)x as long as DictionaryBased")
+    return ratio
+  }
+
+  @discardableResult
+  private func setupAnimationView(with animation: Animation, configuration: LottieConfiguration) -> AnimationView {
+    let animationView = AnimationView(animation: animation, configuration: configuration)
+    animationView.frame.size = CGSize(width: animation.width, height: animation.height)
+    animationView.layoutIfNeeded()
+    return animationView
+  }
+
+  private func measurePerformance(_ block : () throws -> Void) rethrows -> TimeInterval {
+    let start = DispatchTime.now()
+    try block()
+    let end = DispatchTime.now()
+    let nanoTime = end.uptimeNanoseconds - start.uptimeNanoseconds
+    return Double(nanoTime) / 1_000_000_000
+  }
+
+}