Add support for configuring image content gravity (#2177)

Co-authored-by: Cal Stephens <cal.stephens@airbnb.com>

Example/Example/AnimationPreviewView.swift

@@ -218,7 +218,9 @@ extension Color {
 
 extension AnimationImageProvider where Self == FilepathImageProvider {
   static var exampleAppSampleImages: FilepathImageProvider {
-    FilepathImageProvider(filepath: Bundle.main.resourceURL!.appending(path: "Samples/Images"))
+    FilepathImageProvider(
+      filepath: Bundle.main.resourceURL!.appending(path: "Samples/Images"),
+      contentsGravity: .resizeAspect)
   }
 }
 

Sources/Private/CoreAnimation/Layers/ImageLayer.swift

@@ -48,6 +48,7 @@ final class ImageLayer: BaseCompositionLayer {
 
     self.imageAsset = imageAsset
     contentsLayer.contents = image
+    contentsLayer.contentsGravity = context.imageProvider.contentsGravity(for: imageAsset)
     setNeedsLayout()
   }
 

Sources/Private/MainThread/LayerContainers/CompLayers/ImageCompositionLayer.swift

@@ -47,4 +47,10 @@ final class ImageCompositionLayer: CompositionLayer {
       }
     }
   }
+
+  var imageContentsGravity: CALayerContentsGravity = .resize {
+    didSet {
+      contentsLayer.contentsGravity = imageContentsGravity
+    }
+  }
 }

Sources/Private/MainThread/LayerContainers/Utility/CachedImageProvider.swift

@@ -3,6 +3,7 @@
 
 import CoreGraphics
 import Foundation
+import QuartzCore
 
 // MARK: - CachedImageProvider
 
@@ -35,6 +36,11 @@ private final class CachedImageProvider: AnimationImageProvider {
 
   let imageCache: NSCache<NSString, CGImage> = .init()
   let imageProvider: AnimationImageProvider
+
+  func contentsGravity(for asset: ImageAsset) -> CALayerContentsGravity {
+    imageProvider.contentsGravity(for: asset)
+  }
+
 }
 
 extension AnimationImageProvider {

Sources/Private/MainThread/LayerContainers/Utility/LayerImageProvider.swift

@@ -47,6 +47,7 @@ final class LayerImageProvider {
     for imageLayer in imageLayers {
       if let asset = imageAssets[imageLayer.imageReferenceID] {
         imageLayer.image = imageProvider.imageForAsset(asset: asset)
+        imageLayer.imageContentsGravity = imageProvider.contentsGravity(for: asset)
       }
     }
   }

Sources/Public/ImageProvider/AnimationImageProvider.swift

@@ -7,6 +7,7 @@
 
 import CoreGraphics
 import Foundation
+import QuartzCore
 
 // MARK: - AnimationImageProvider
 
@@ -26,10 +27,19 @@ public protocol AnimationImageProvider {
 
   /// The image to display for the given `ImageAsset` defined in the `LottieAnimation` JSON file.
   func imageForAsset(asset: ImageAsset) -> CGImage?
+
+  /// Specifies how the layer's contents are positioned or scaled within its bounds for a given asset.
+  /// Defaults to `.resize`, which stretches the image to fill the layer.
+  func contentsGravity(for asset: ImageAsset) -> CALayerContentsGravity
 }
 
 extension AnimationImageProvider {
   public var cacheEligible: Bool {
     true
   }
+
+  /// The default value is `.resize`, similar to that of `CALayer`.
+  public func contentsGravity(for _: ImageAsset) -> CALayerContentsGravity {
+    .resize
+  }
 }

Sources/Public/iOS/BundleImageProvider.swift

@@ -23,10 +23,12 @@ public class BundleImageProvider: AnimationImageProvider {
   ///
   /// - Parameter bundle: The bundle containing images for the provider.
   /// - Parameter searchPath: The subpath is a path within the bundle to search for image assets.
+  /// - Parameter contentsGravity: The contents gravity to use when rendering the image.
   ///
-  public init(bundle: Bundle, searchPath: String?) {
+  public init(bundle: Bundle, searchPath: String?, contentsGravity: CALayerContentsGravity = .resize) {
     self.bundle = bundle
     self.searchPath = searchPath
+    self.contentsGravity = contentsGravity
   }
 
   // MARK: Public
@@ -81,10 +83,15 @@ public class BundleImageProvider: AnimationImageProvider {
     return image.cgImage
   }
 
+  public func contentsGravity(for _: ImageAsset) -> CALayerContentsGravity {
+    contentsGravity
+  }
+
   // MARK: Internal
 
   let bundle: Bundle
   let searchPath: String?
+  let contentsGravity: CALayerContentsGravity
 }
 
 extension BundleImageProvider: Equatable {

Sources/Public/iOS/FilepathImageProvider.swift

@@ -17,13 +17,21 @@ public class FilepathImageProvider: AnimationImageProvider {
   /// Initializes an image provider with a specific filepath.
   ///
   /// - Parameter filepath: The absolute filepath containing the images.
+  /// - Parameter contentsGravity: The contents gravity to use when rendering the images.
   ///
-  public init(filepath: String) {
+  public init(filepath: String, contentsGravity: CALayerContentsGravity = .resize) {
     self.filepath = URL(fileURLWithPath: filepath)
+    self.contentsGravity = contentsGravity
   }
 
-  public init(filepath: URL) {
+  /// Initializes an image provider with a specific filepath.
+  ///
+  /// - Parameter filepath: The absolute filepath containing the images.
+  /// - Parameter contentsGravity: The contents gravity to use when rendering the images.
+  ///
+  public init(filepath: URL, contentsGravity: CALayerContentsGravity = .resize) {
     self.filepath = filepath
+    self.contentsGravity = contentsGravity
   }
 
   // MARK: Public
@@ -52,9 +60,14 @@ public class FilepathImageProvider: AnimationImageProvider {
     return nil
   }
 
+  public func contentsGravity(for _: ImageAsset) -> CALayerContentsGravity {
+    contentsGravity
+  }
+
   // MARK: Internal
 
   let filepath: URL
+  let contentsGravity: CALayerContentsGravity
 }
 
 extension FilepathImageProvider: Equatable {

Sources/Public/macOS/BundleImageProvider.macOS.swift

@@ -20,10 +20,12 @@ public class BundleImageProvider: AnimationImageProvider {
   ///
   /// - Parameter bundle: The bundle containing images for the provider.
   /// - Parameter searchPath: The subpath is a path within the bundle to search for image assets.
+  /// - Parameter contentsGravity: The contents gravity to use when rendering the image.
   ///
-  public init(bundle: Bundle, searchPath: String?) {
+  public init(bundle: Bundle, searchPath: String?, contentsGravity: CALayerContentsGravity = .resize) {
     self.bundle = bundle
     self.searchPath = searchPath
+    self.contentsGravity = contentsGravity
   }
 
   // MARK: Public
@@ -70,10 +72,15 @@ public class BundleImageProvider: AnimationImageProvider {
     return image.lottie_CGImage
   }
 
+  public func contentsGravity(for _: ImageAsset) -> CALayerContentsGravity {
+    contentsGravity
+  }
+
   // MARK: Internal
 
   let bundle: Bundle
   let searchPath: String?
+  let contentsGravity: CALayerContentsGravity
 }
 
 extension BundleImageProvider: Equatable {

Sources/Public/macOS/FilepathImageProvider.macOS.swift

@@ -16,13 +16,21 @@ public class FilepathImageProvider: AnimationImageProvider {
   /// Initializes an image provider with a specific filepath.
   ///
   /// - Parameter filepath: The absolute filepath containing the images.
+  /// - Parameter contentsGravity: The contents gravity to use when rendering the images.
   ///
-  public init(filepath: String) {
+  public init(filepath: String, contentsGravity: CALayerContentsGravity = .resize) {
     self.filepath = URL(fileURLWithPath: filepath)
+    self.contentsGravity = contentsGravity
   }
 
-  public init(filepath: URL) {
+  /// Initializes an image provider with a specific filepath.
+  ///
+  /// - Parameter filepath: The absolute filepath containing the images.
+  /// - Parameter contentsGravity: The contents gravity to use when rendering the images.
+  ///
+  public init(filepath: URL, contentsGravity: CALayerContentsGravity = .resize) {
     self.filepath = filepath
+    self.contentsGravity = contentsGravity
   }
 
   // MARK: Public
@@ -51,9 +59,14 @@ public class FilepathImageProvider: AnimationImageProvider {
     return nil
   }
 
+  public func contentsGravity(for _: ImageAsset) -> CALayerContentsGravity {
+    contentsGravity
+  }
+
   // MARK: Internal
 
   let filepath: URL
+  let contentsGravity: CALayerContentsGravity
 }
 
 extension FilepathImageProvider: Equatable {

Tests/CompatibleAnimationViewTests.swift

@@ -14,7 +14,7 @@ final class CompatibleAnimationViewTests: XCTestCase {
     #if os(iOS)
     let animation = CompatibleAnimation(name: "LottieLogo2", subdirectory: Samples.directoryName, bundle: .lottie)
     let animationView = CompatibleAnimationView(compatibleAnimation: animation)
-    animationView.frame.size = animation.animation!.snapshotSize
+    animationView.frame.size = animation.animation!.snapshotSize(for: .default)
     animationView.currentProgress = 0.5
     assertSnapshot(matching: animationView, as: .imageOfPresentationLayer())
     #endif

Tests/Samples/Nonanimating/dog_landscape.json

@@ -0,0 +1 @@
+{"v":"5.4.3","fr":60,"ip":0,"op":300,"w":442,"h":440,"nm":"Screen Shot 2019-03-20 at 1.17.42 PM","ddd":0,"assets":[{"id":"dog-landscape","w":442,"h":440,"u":"","p":"dog-landscape.jpeg","e":1}],"layers":[{"ddd":0,"ind":1,"ty":2,"nm":"Screen Shot 2019-03-20 at 1.17.42 PM.png","cl":"17 42 png","refId":"dog-landscape","sr":1,"ks":{"o":{"a":0,"k":100,"ix":11},"r":{"a":0,"k":0,"ix":10},"p":{"a":0,"k":[221,220,0],"ix":2},"a":{"a":0,"k":[221,220,0],"ix":1},"s":{"a":0,"k":[100,100,100],"ix":6}},"ao":0,"ip":0,"op":300,"st":0,"bm":0}],"markers":[]}

Tests/SnapshotConfiguration.swift

@@ -33,6 +33,12 @@ struct SnapshotConfiguration {
   ///  - Enabling this for a set of animations gives us a regression suite for
   ///    the code supporting the automatic engine.
   var testWithAutomaticEngine = false
+
+  /// Whether or not this snapshot doesn't animate, so only needs to be snapshot once.
+  var nonanimating = false
+
+  /// The maximum size to allow for the resulting snapshot image
+  var maxSnapshotDimension: CGFloat = 500
 }
 
 // MARK: Custom mapping
@@ -100,7 +106,13 @@ extension SnapshotConfiguration {
     ]),
 
     // Test cases for `AnimatedImageProvider`
-    "Nonanimating/_dog": .customImageProvider(HardcodedImageProvider(imageName: "Samples/Images/dog.png")),
+    //  - These snapshots are pretty large (2 MB) by default, so we limit their number and size.
+    "Nonanimating/dog": .customImageProvider(HardcodedImageProvider(imageName: "Samples/Images/dog.png"))
+      .nonanimating()
+      .precision(0.9),
+    "Nonanimating/dog_landscape": .customImageProvider(HardcodedImageProvider(imageName: "Samples/Images/dog-landscape.jpeg"))
+      .nonanimating()
+      .precision(0.9),
 
     // Test cases for `AnimatedTextProvider`
     "Issues/issue_1722": .customTextProvider(HardcodedTextProvider(text: "Bounce-bounce")),
@@ -190,6 +202,27 @@ extension SnapshotConfiguration {
     return configuration
   }
 
+  /// A copy of this `SnapshotConfiguration` with `nonanimating` set to `true`
+  func nonanimating(_ value: Bool = true) -> SnapshotConfiguration {
+    var copy = self
+    copy.nonanimating = value
+    return copy
+  }
+
+  /// A copy of this `SnapshotConfiguration` with `maxSnapshotDimension` set to the given value
+  func maxSnapshotDimension(_ maxSnapshotDimension: CGFloat) -> SnapshotConfiguration {
+    var copy = self
+    copy.maxSnapshotDimension = maxSnapshotDimension
+    return copy
+  }
+
+  /// A copy of this `SnapshotConfiguration` with the given precision when comparing the existing snapshot image
+  func precision(_ precision: Float) -> SnapshotConfiguration {
+    var copy = self
+    copy.precision = precision
+    return copy
+  }
+
   /// Whether or not this sample should be included in the snapshot tests for the given configuration
   func shouldSnapshot(using configuration: LottieConfiguration) -> Bool {
     switch configuration.renderingEngine {

Tests/SnapshotTests.swift

@@ -49,7 +49,7 @@ class SnapshotTests: XCTestCase {
         .replacingOccurrences(of: "testCoreAnimationRenderingEngine.", with: "")
         .replacingOccurrences(of: "testAutomaticRenderingEngine.", with: "")
 
-      for percentage in progressPercentagesToSnapshot {
+      for percentage in progressPercentagesToSnapshot(for: .default) {
         animationName = animationName.replacingOccurrences(
           of: "-\(Int(percentage * 100)).png",
           with: "")
@@ -99,7 +99,13 @@ class SnapshotTests: XCTestCase {
   // MARK: Private
 
   /// `currentProgress` percentages that should be snapshot in `compareSampleSnapshots`
-  private let progressPercentagesToSnapshot = [0, 0.25, 0.5, 0.75, 1.0]
+  private func progressPercentagesToSnapshot(for snapshotConfiguration: SnapshotConfiguration) -> [Double] {
+    if snapshotConfiguration.nonanimating {
+      return [0]
+    } else {
+      return [0, 0.25, 0.5, 0.75, 1.0]
+    }
+  }
 
   /// Captures snapshots of `sampleAnimationURLs` and compares them to the snapshot images stored on disk
   private func compareSampleSnapshots(
@@ -111,7 +117,7 @@ class SnapshotTests: XCTestCase {
 
     #if os(iOS)
     for sampleAnimationName in Samples.sampleAnimationNames {
-      for percent in progressPercentagesToSnapshot {
+      for percent in progressPercentagesToSnapshot(for: SnapshotConfiguration.forSample(named: sampleAnimationName)) {
         guard
           let animationView = await SnapshotConfiguration.makeAnimationView(
             for: sampleAnimationName,
@@ -138,8 +144,8 @@ class SnapshotTests: XCTestCase {
 
 extension LottieAnimation {
   /// The size that this animation should be snapshot at
-  var snapshotSize: CGSize {
-    let maxDimension: CGFloat = 500
+  func snapshotSize(for configuration: SnapshotConfiguration) -> CGSize {
+    let maxDimension: CGFloat = configuration.maxSnapshotDimension
 
     // If this is a landscape aspect ratio, we clamp the width
     if width > height {
@@ -293,7 +299,7 @@ extension SnapshotConfiguration {
 
     // Set up the animation view with a valid frame
     // so the geometry is correct when setting up the `CAAnimation`s
-    animationView.frame.size = animation.snapshotSize
+    animationView.frame.size = animation.snapshotSize(for: snapshotConfiguration)
 
     for (keypath, customValueProvider) in snapshotConfiguration.customValueProviders {
       animationView.setValueProvider(customValueProvider, keypath: keypath)

Tests/Utils/HardcodedImageProvider.swift

@@ -20,4 +20,8 @@ struct HardcodedImageProvider: AnimationImageProvider {
     return nil
     #endif
   }
+
+  func contentsGravity(for _: ImageAsset) -> CALayerContentsGravity {
+    .resizeAspectFill
+  }
 }

Tests/__Snapshots__/AutomaticEngineTests/testAutomaticEngineDetection.Nonanimating-dog.txt

@@ -0,0 +1 @@
+Supports Core Animation engine

Tests/__Snapshots__/AutomaticEngineTests/testAutomaticEngineDetection.Nonanimating-dog_landscape.txt

@@ -0,0 +1 @@
+Supports Core Animation engine