react-native-nitro-image-pipeline 0.3.5 → 1.1.0

package/README.md

@@ -10,7 +10,7 @@ A high-performance image loading, caching, and processing library for React Nati
 
 - Load remote images with built-in memory and disk caching
 - Prefetch single or multiple images in the background
-- Apply Gaussian blur and rounded corners at load time
+- Apply Gaussian blur and rounded corners (uniform or per-corner) at load time
 - Apply Gaussian blur to already-loaded images
 - Clear the image cache on demand
 - `useImage` hook for declarative image loading in components
@@ -48,7 +48,7 @@ import { useImage } from 'react-native-nitro-image-pipeline';
 function MyComponent() {
   const { image, error } = useImage({
     url: 'https://example.com/photo.jpg',
-    blur: 4,
+    blur: 4, // Gaussian sigma in source pixels — same result on iOS and Android
     cornerRadius: 12,
   });
 
@@ -67,11 +67,17 @@ import { NitroImagePipeline } from 'react-native-nitro-image-pipeline';
 
 // Load an image with options
 const image = await NitroImagePipeline.loadImage('https://example.com/photo.jpg', {
-  blur: 4,
+  blur: 4, // Gaussian sigma in source pixels — see "Blur units"
   cornerRadius: 12,
   cache: 'disk',
 });
 
+// Per-corner radii — e.g. a "ticket" shape with larger bottom corners.
+// The rounding is baked into the bitmap, so no view-layer masking is needed.
+const ticket = await NitroImagePipeline.loadImage('https://example.com/photo.jpg', {
+  cornerRadius: { topLeft: 24, topRight: 24, bottomLeft: 48, bottomRight: 48 },
+});
+
 // Prefetch a single image
 await NitroImagePipeline.preLoadImage('https://example.com/photo.jpg');
 
@@ -96,8 +102,8 @@ Loads an image from a URL and returns a `Promise<Image>`.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `blur` | `number` | `0` | Gaussian blur radius applied at load time |
-| `cornerRadius` | `number` | `0` | Corner radius in points |
+| `blur` | `number` | `0` | Gaussian blur strength applied at load time — see [Blur units](#blur-units) |
+| `cornerRadius` | `number \| CornerRadii` | `0` | Corner radius in points — a single number for all four corners, or `{ topLeft?, topRight?, bottomLeft?, bottomRight? }` for independent per-corner radii (omitted corners stay square) |
 | `cache` | `'memory' \| 'disk' \| 'none'` | platform default | Caching strategy |
 
 ### `preLoadImage(url)`
@@ -110,12 +116,66 @@ Prefetches multiple images into the cache. Returns `Promise<void>`.
 
 ### `gaussianBlur(image, radius)`
 
-Applies a Gaussian blur to an existing `Image` object. Returns `Promise<Image>`.
+Applies a Gaussian blur to an existing `Image` object. Returns `Promise<Image>`. `radius` uses the
+same unit as the `blur` option — see [Blur units](#blur-units).
+
+### Blur units
+
+`blur` (and `gaussianBlur`'s `radius`) is the **standard deviation (sigma) of the Gaussian, in
+source-image pixels**. The same value on the same source file produces the same result on iOS and
+Android — the platforms are calibrated against each other rather than each exposing its native
+backend's own idea of "radius".
+
+```ts
+// ~11px of blur on both platforms, whatever the device
+await NitroImagePipeline.loadImage(url, { blur: 11 });
+```
+
+Two things follow from the unit being *source* pixels:
+
+- Blur is measured against the image's own resolution, not the size it is displayed at. A 4000px
+  photo at `blur: 11` looks subtler than a 400px thumbnail at `blur: 11`. To keep a feed visually
+  consistent, scale the value with the source width.
+- Coming from React Native's `<Image blurRadius={n} />`? That halves its input internally, so
+  `blurRadius={n}` ≈ `blur: n / 2`. RN's value is also density-scaled on Android and not on iOS,
+  which is why the two never quite matched there.
+
+Values below ~1 are smaller than the smallest kernel either backend can build and are effectively a
+no-op. There is no upper bound.
+
+Implementation: iOS runs three Accelerate box-convolution passes sized to hit the requested sigma
+(the standard three-box Gaussian approximation, accurate to a few percent); Android uses
+RenderScript's true Gaussian, downscaling first when sigma exceeds the single-pass ceiling of
+~10.6px and compensating the radius so the result is unchanged. Both clamp at the edges, so blurred
+images keep their borders instead of fading out.
 
 ### `clearCache()`
 
 Removes all cached images from memory and disk. Returns `Promise<void>` that resolves once both caches are cleared.
 
+## Upgrading from 0.3.x
+
+`blur` and `gaussianBlur(image, radius)` changed meaning in 1.0. They used to hand the number
+straight to each platform's native blur, and the two platforms disagreed about what it meant; now
+both read it as a Gaussian sigma in source-image pixels (see [Blur units](#blur-units)).
+
+| | what `blur: n` did in 0.3.x | what it does in 1.0 |
+|---|---|---|
+| iOS | fed `n` to `CIGaussianBlur(inputRadius:)`, measured at `sigma ≈ 1.18 × n` | `sigma = n` |
+| Android | RenderScript on a copy downscaled to 512px, so strength scaled with the source resolution: `sigma ≈ (0.4n + 0.6) × max(w, h) / 512` | `sigma = n`, resolution-independent |
+
+To keep the look you had:
+
+- **iOS:** multiply your old value by ~1.18 (`blur: 10` → `blur: 12`).
+- **Android:** there is no single factor — the old result depended on the source image's
+  resolution. Re-tune against iOS, which the two platforms now agree with.
+
+Also changed:
+
+- `blur` above 25 used to reject the promise on Android. Sigma is now unbounded.
+- Fractional values used to be truncated to whole numbers on iOS. They are honoured now.
+- Blurred images used to fade out at the borders on iOS. Edges are clamped on both platforms now.
+
 ## Credits
 
 Bootstrapped with [create-nitro-module](https://github.com/patrickkabwe/create-nitro-module).

package/android/src/main/java/com/margelo/nitro/nitroimagepipeline/HybridNitroImagePipeline.kt

@@ -40,10 +40,23 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
 
   override fun loadImage(url: String, options: Options?): Promise<HybridImageSpec> = Promise.async {
     val blur = options?.blur?.toFloat() ?: 0f
-    val cornerRadius = options?.cornerRadius?.toFloat() ?: 0f
     val transformations = buildList {
       if (blur > 0f) add(BlurTransformation(context, blur))
-      if (cornerRadius > 0f) add(RoundedCornersTransformation(cornerRadius))
+      options?.cornerRadius?.match(
+          first = { radius ->
+            if (radius > 0.0) add(RoundedCornersTransformation(radius.toFloat()))
+          },
+          second = { radii ->
+            // RoundedCornersTransformation rejects negative radii; treat them as square.
+            val topLeft = (radii.topLeft?.toFloat() ?: 0f).coerceAtLeast(0f)
+            val topRight = (radii.topRight?.toFloat() ?: 0f).coerceAtLeast(0f)
+            val bottomLeft = (radii.bottomLeft?.toFloat() ?: 0f).coerceAtLeast(0f)
+            val bottomRight = (radii.bottomRight?.toFloat() ?: 0f).coerceAtLeast(0f)
+            if (topLeft > 0f || topRight > 0f || bottomLeft > 0f || bottomRight > 0f) {
+              add(RoundedCornersTransformation(topLeft, topRight, bottomLeft, bottomRight))
+            }
+          },
+      )
     }
     val request =
         ImageRequest.Builder(context)
@@ -105,10 +118,15 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
   override fun gaussianBlur(image: HybridImageSpec, radius: Double): Promise<HybridImageSpec> =
       Promise.async {
         val hybridImage = image as? HybridImage ?: throw Error("Image is not a HybridImage")
-        val clampedRadius = radius.toFloat().coerceIn(0.01f, 25f)
-        val blurred =
-            BlurTransformation(context, clampedRadius).transform(hybridImage.bitmap, Size.ORIGINAL)
-        HybridImage(blurred)
+        // `radius` is a Gaussian sigma in source-image pixels — see BlurTransformation.
+        val sigma = radius.toFloat()
+        if (sigma <= 0f) {
+          hybridImage
+        } else {
+          val blurred =
+              BlurTransformation(context, sigma).transform(hybridImage.bitmap, Size.ORIGINAL)
+          HybridImage(blurred)
+        }
       }
 
   override fun clearCache(): Promise<Unit> = Promise.async {

package/android/src/main/java/com/margelo/nitro/nitroimagepipeline/transform/BlurTransformation.kt

@@ -13,33 +13,57 @@ import androidx.core.graphics.applyCanvas
 import androidx.core.graphics.scale
 import coil3.size.Size
 import coil3.transform.Transformation
+import kotlin.math.ceil
+import kotlin.math.max
 
+/**
+ * Gaussian blur of standard deviation [sigma], measured in *source image pixels*.
+ *
+ * The unit is the point of this class: the same sigma on the same source file produces the same
+ * result here and on iOS. It is deliberately not a "radius" — RenderScript, CoreImage and React
+ * Native's `blurRadius` each define radius differently, which is why blurs never matched across
+ * platforms.
+ *
+ * For reference, React Native's `<Image blurRadius={n} />` halves its input before convolving, so
+ * `blurRadius={n}` is roughly `sigma = n / 2`.
+ */
 class BlurTransformation(
     private val context: Context,
-    private val radius: Float = 10f,
-    private val sampling: Float = 1f,
+    private val sigma: Float,
 ) : Transformation() {
 
   init {
-    require(radius in 0.01..25.0) { "radius must be in (0, 25]." }
-    require(sampling >= 1f) { "sampling must be >= 1." }
+    require(sigma > 0f && sigma.isFinite()) { "sigma must be > 0." }
   }
 
-  override val cacheKey = "${BlurTransformation::class.java.name}-$radius-$sampling"
+  override val cacheKey = "${BlurTransformation::class.java.name}-$sigma"
 
   override suspend fun transform(input: Bitmap, size: Size): Bitmap {
+    // ScriptIntrinsicBlur's `radius` maps to a Gaussian sigma of 0.4 * radius + 0.6, and radius is
+    // capped at 25 — so a single pass tops out at sigma ~10.6px. Larger blurs are reached by
+    // blurring a downscaled copy: scaling down by `s`, blurring with sigma/s and scaling back up
+    // multiplies the effective sigma by `s`. A blur is a low-pass filter, so the detail the
+    // downscale drops is detail the blur was going to remove anyway. Downscale only as far as the
+    // sigma ceiling forces, which keeps small blurs pixel-exact.
+    val sampling = max(1f, sigma / MAX_SIGMA)
+    val scaledWidth = ceil(input.width / sampling).toInt().coerceAtLeast(1)
+    val scaledHeight = ceil(input.height / sampling).toInt().coerceAtLeast(1)
+    // Rounding to whole pixels shifts the scale slightly; derive the sigma from the scale actually
+    // applied rather than the requested one.
+    val scaleX = scaledWidth.toFloat() / input.width
+    val scaleY = scaledHeight.toFloat() / input.height
+    val scaledSigma = sigma * max(scaleX, scaleY)
+    val radius = ((scaledSigma - SIGMA_INTERCEPT) / SIGMA_SLOPE).coerceIn(MIN_RADIUS, MAX_RADIUS)
+
     val paint = Paint(Paint.ANTI_ALIAS_FLAG or Paint.FILTER_BITMAP_FLAG)
-    // Auto-scale so the blurred image is at most 512px on the longest side.
-    // Blur is a low-pass filter so blurring at lower resolution is identical in quality.
-    val autoSampling = (maxOf(input.width, input.height) / 512f).coerceAtLeast(sampling)
-    val scaledWidth = (input.width / autoSampling).toInt().coerceAtLeast(1)
-    val scaledHeight = (input.height / autoSampling).toInt().coerceAtLeast(1)
-    val softwareInput = if (input.config == Bitmap.Config.HARDWARE) input.copy(Bitmap.Config.ARGB_8888, false) else input
+    val softwareInput =
+        if (input.config == Bitmap.Config.HARDWARE) input.copy(Bitmap.Config.ARGB_8888, false)
+        else input
     val softwareConfig = softwareInput.config ?: Bitmap.Config.ARGB_8888
 
     val output = Bitmap.createBitmap(scaledWidth, scaledHeight, softwareConfig)
     output.applyCanvas {
-      scale(1 / autoSampling, 1 / autoSampling)
+      scale(scaleX, scaleY)
       drawBitmap(softwareInput, 0f, 0f, paint)
     }
 
@@ -69,23 +93,25 @@ class BlurTransformation(
       blur?.destroy()
     }
 
-    return output.scale(input.width, input.height)
+    return if (scaledWidth == input.width && scaledHeight == input.height) output
+    else output.scale(input.width, input.height)
   }
 
   override fun equals(other: Any?): Boolean {
     if (this === other) return true
-    return other is BlurTransformation &&
-        context == other.context &&
-        radius == other.radius &&
-        sampling == other.sampling
+    return other is BlurTransformation && context == other.context && sigma == other.sigma
   }
 
-  override fun hashCode(): Int {
-    var result = context.hashCode()
-    result = 31 * result + radius.hashCode()
-    result = 31 * result + sampling.hashCode()
-    return result
-  }
+  override fun hashCode(): Int = 31 * context.hashCode() + sigma.hashCode()
 
-  override fun toString() = "BlurTransformation(radius=$radius, sampling=$sampling)"
+  override fun toString() = "BlurTransformation(sigma=$sigma)"
+
+  private companion object {
+    // sigma = 0.4 * radius + 0.6, per RenderScript's ScriptIntrinsicBlur.
+    const val SIGMA_SLOPE = 0.4f
+    const val SIGMA_INTERCEPT = 0.6f
+    const val MIN_RADIUS = 0.01f
+    const val MAX_RADIUS = 25f
+    const val MAX_SIGMA = SIGMA_SLOPE * MAX_RADIUS + SIGMA_INTERCEPT
+  }
 }

package/ios/GaussianBlur.swift

@@ -0,0 +1,135 @@
+//
+//  GaussianBlur.swift
+//  NitroImagePipeline
+//
+//  Cross-platform Gaussian blur — the kernel itself.
+//
+//  This file deliberately depends on nothing but Accelerate and CoreGraphics
+//  so `scripts/verify-blur.swift` can compile and measure it on the host
+//  machine. The UIImage/Nuke plumbing lives in GaussianBlurProcessor.swift.
+//
+//  `sigma` is the standard deviation of the Gaussian, measured in *source
+//  image pixels* — the same sigma applied to the same source file produces
+//  the same result on iOS and Android. It is deliberately not a "radius":
+//  CIGaussianBlur, RenderScript and React Native's `blurRadius` each define
+//  radius differently, which is why blurs never matched across platforms.
+//
+//  For reference, React Native's `<Image blurRadius={n} />` halves its input
+//  before convolving, so `blurRadius={n}` is roughly `sigma = n / 2`.
+//
+
+import Accelerate
+import CoreGraphics
+import Foundation
+
+enum GaussianBlur {
+    /// Runs the box-blur passes over `cgImage`. Returns `nil` if the pixel
+    /// buffers could not be allocated.
+    static func convolve(_ cgImage: CGImage, boxes: [UInt32]) -> CGImage? {
+        // Normalise to premultiplied ARGB8888 — vImageBoxConvolve_ARGB8888
+        // needs four 8-bit channels, and premultiplied alpha is what keeps
+        // transparent edges from bleeding dark halos into the blur.
+        guard var format = vImage_CGImageFormat(
+            bitsPerComponent: 8,
+            bitsPerPixel: 32,
+            colorSpace: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGBitmapInfo(rawValue: CGImageAlphaInfo.premultipliedFirst.rawValue),
+            renderingIntent: .defaultIntent
+        ) else { return nil }
+
+        var source = vImage_Buffer()
+        guard vImageBuffer_InitWithCGImage(
+            &source, &format, nil, cgImage, vImage_Flags(kvImageNoFlags)
+        ) == kvImageNoError else { return nil }
+        defer { free(source.data) }
+
+        var scratch = vImage_Buffer()
+        guard vImageBuffer_Init(
+            &scratch, source.height, source.width, 32, vImage_Flags(kvImageNoFlags)
+        ) == kvImageNoError else { return nil }
+        defer { free(scratch.data) }
+
+        // kvImageEdgeExtend clamps at the borders instead of sampling
+        // transparent black, so the image keeps its edges instead of fading
+        // out into the frame (CIGaussianBlur's default, and the reason blurred
+        // images used to come back with washed-out borders).
+        let flags = vImage_Flags(kvImageEdgeExtend)
+        // The passes use two different kernel widths; size the scratch buffer
+        // for the widest one so every pass fits in it.
+        let widest = boxes.max() ?? 1
+        let tempSize = vImageBoxConvolve_ARGB8888(
+            &source, &scratch, nil, 0, 0, widest, widest, nil,
+            vImage_Flags(kvImageEdgeExtend | kvImageGetTempBufferSize)
+        )
+        guard tempSize > 0, let temp = malloc(tempSize) else { return nil }
+        defer { free(temp) }
+
+        // Ping-pong between the two buffers; after an odd number of passes the
+        // result sits in `input`.
+        var input = source
+        var output = scratch
+        for box in boxes {
+            guard vImageBoxConvolve_ARGB8888(
+                &input, &output, temp, 0, 0, box, box, nil, flags
+            ) == kvImageNoError else { return nil }
+            swap(&input, &output)
+        }
+
+        var error = vImage_Error(kvImageNoError)
+        guard let blurred = vImageCreateCGImageFromBuffer(
+            &input, &format, nil, nil, vImage_Flags(kvImageNoFlags), &error
+        )?.takeRetainedValue(), error == kvImageNoError else { return nil }
+
+        return blurred
+    }
+
+    /// Widths for the three box-blur passes that approximate a Gaussian of
+    /// `sigma` (the classic approximation: three boxes land within a few
+    /// percent of a true Gaussian, and Accelerate runs them in O(1) per pixel
+    /// regardless of how wide they are).
+    ///
+    /// Three boxes of widths w1…w3 produce a standard deviation of
+    /// `sqrt((w1² + w2² + w3² - 3) / 12)`. Box widths have to be odd, so the
+    /// passes are split between the two odd integers straddling the ideal
+    /// width and the split landing closest to `sigma` wins — which keeps the
+    /// error under half a pixel at any sigma instead of always undershooting.
+    static func boxSizes(forSigma sigma: Double) -> [UInt32] {
+        let passes = 3
+        var lower = Int(((12 * sigma * sigma / Double(passes)) + 1).squareRoot())
+        if lower % 2 == 0 { lower -= 1 }
+        // Upper bound keeps `upper` inside UInt32 for absurd sigmas; a kernel
+        // that wide is already far larger than any real image.
+        lower = min(max(lower, 1), Int(UInt32.max) - 2)
+        let upper = lower + 2
+
+        // Written as a plain loop rather than map/min(by:): the inferred
+        // version tripped "type of expression is ambiguous" on Swift 6.2.
+        var best: [UInt32] = []
+        var bestError: Double = .infinity
+        for lowerCount in 0...passes {
+            var candidate: [UInt32] = []
+            for pass in 0..<passes {
+                candidate.append(UInt32(pass < lowerCount ? lower : upper))
+            }
+            // `.magnitude` rather than `abs()`: Nitro's C++ interop puts
+            // std::abs overloads in scope, and Swift 6.2 calls the resulting
+            // `abs` ambiguous when this file is compiled as part of the pod.
+            let error: Double = (standardDeviation(of: candidate) - sigma).magnitude
+            if error < bestError {
+                bestError = error
+                best = candidate
+            }
+        }
+        return best
+    }
+
+    /// The standard deviation three box blurs of the given widths add up to.
+    private static func standardDeviation(of boxes: [UInt32]) -> Double {
+        var sum: Double = 0
+        for box in boxes {
+            let width = Double(box)
+            sum += width * width - 1
+        }
+        return (sum / 12).squareRoot()
+    }
+}

package/ios/GaussianBlurProcessor.swift

@@ -0,0 +1,41 @@
+//
+//  GaussianBlurProcessor.swift
+//  NitroImagePipeline
+//
+//  UIImage and Nuke plumbing around the kernel in GaussianBlur.swift.
+//
+
+import CoreGraphics
+import Foundation
+import Nuke
+import UIKit
+
+extension GaussianBlur {
+    /// Applies a Gaussian blur of standard deviation `sigma` (in image pixels).
+    ///
+    /// Returns `image` unchanged when `sigma` is too small to affect a pixel,
+    /// and `nil` only when the pixel buffers could not be allocated.
+    static func apply(to image: UIImage, sigma: Double) -> UIImage? {
+        guard sigma > 0, sigma.isFinite, let cgImage = image.cgImage else { return image }
+
+        let boxes = boxSizes(forSigma: sigma)
+        guard boxes.contains(where: { $0 > 1 }) else { return image }
+        guard let blurred = convolve(cgImage, boxes: boxes) else { return nil }
+
+        return UIImage(cgImage: blurred, scale: image.scale, orientation: image.imageOrientation)
+    }
+}
+
+/// Nuke processor so `loadImage(url:, { blur })` and `gaussianBlur(image:, sigma)`
+/// go through the exact same kernel.
+struct GaussianBlurProcessor: ImageProcessing {
+    let sigma: Double
+
+    var identifier: String { "com.nitroimagepipeline.gaussianBlur?sigma=\(sigma)" }
+
+    var hashableIdentifier: AnyHashable { identifier }
+
+    func process(_ image: PlatformImage) -> PlatformImage? {
+        GaussianBlur.apply(to: image, sigma: sigma)
+    }
+}

package/ios/HybridNitroImagePipeline.swift

@@ -11,7 +11,6 @@ import NitroImage
 import Nuke
 
 import UIKit
-import CoreImage
 
 private class HybridImage: HybridImageSpec, NativeImage {
     let uiImage: UIImage
@@ -101,9 +100,6 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
 
     private static let sharedPrefetcher = ImagePrefetcher(pipeline: sharedPipeline)
 
-    // CIContext is expensive to create; Apple recommends reusing one.
-    private static let ciContext = CIContext()
-
     private var pipeline: ImagePipeline { Self.sharedPipeline }
     private var prefetcher: ImagePrefetcher { Self.sharedPrefetcher }
 
@@ -122,10 +118,20 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
 
             var processors: [any ImageProcessing] = []
             if let blur = options?.blur, blur > 0 {
-                processors.append(.gaussianBlur(radius: Int(blur)))
+                processors.append(GaussianBlurProcessor(sigma: blur))
             }
-            if let cornerRadius = options?.cornerRadius, cornerRadius > 0 {
-                processors.append(.roundedCorners(radius: cornerRadius))
+            switch options?.cornerRadius {
+            case .first(let radius):
+                if radius > 0 {
+                    processors.append(.roundedCorners(radius: radius))
+                }
+            case .second(let radii):
+                let roundedCorners = RoundedCornersProcessor(radii: radii)
+                if roundedCorners.hasRounding {
+                    processors.append(roundedCorners)
+                }
+            case nil:
+                break
             }
 
             let imgRequest = ImageRequest(
@@ -168,22 +174,11 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
                 throw RuntimeError.error(withMessage: "Unsupported image type")
             }
 
-            let uiImage = nativeImage.uiImage
-
-            guard let ciImage = CIImage(image: uiImage) else {
-                throw RuntimeError.error(withMessage: "Failed to read image data")
-            }
-
-            let filter = CIFilter(name: "CIGaussianBlur")!
-            filter.setValue(ciImage, forKey: kCIInputImageKey)
-            filter.setValue(radius, forKey: kCIInputRadiusKey)
-
-            guard let output = filter.outputImage,
-                  let cgImage = Self.ciContext.createCGImage(output, from: ciImage.extent) else {
+            guard let blurred = GaussianBlur.apply(to: nativeImage.uiImage, sigma: radius) else {
                 throw RuntimeError.error(withMessage: "Failed to apply gaussian blur")
             }
 
-            return HybridImage(uiImage: UIImage(cgImage: cgImage))
+            return HybridImage(uiImage: blurred)
         }
     }
 

package/ios/RoundedCornersProcessor.swift

@@ -0,0 +1,118 @@
+//
+//  RoundedCornersProcessor.swift
+//  NitroImagePipeline
+//
+//  Bakes independent per-corner radii into the bitmap. Nuke's built-in
+//  ImageProcessors.RoundedCorners only supports one uniform radius, so the
+//  asymmetric case clips through a hand-built CGPath instead.
+//
+
+import CoreGraphics
+import Foundation
+import Nuke
+import UIKit
+
+/// Nuke processor that rounds each corner with its own radius (in points,
+/// like `ImageProcessors.RoundedCorners` with `unit: .points`).
+struct RoundedCornersProcessor: ImageProcessing {
+    let topLeft: CGFloat
+    let topRight: CGFloat
+    let bottomLeft: CGFloat
+    let bottomRight: CGFloat
+
+    init(radii: CornerRadii) {
+        // Negative radii would make CGPath arcs undefined; treat them as square.
+        topLeft = CGFloat(max(radii.topLeft ?? 0, 0))
+        topRight = CGFloat(max(radii.topRight ?? 0, 0))
+        bottomLeft = CGFloat(max(radii.bottomLeft ?? 0, 0))
+        bottomRight = CGFloat(max(radii.bottomRight ?? 0, 0))
+    }
+
+    var hasRounding: Bool {
+        topLeft > 0 || topRight > 0 || bottomLeft > 0 || bottomRight > 0
+    }
+
+    var identifier: String {
+        "com.nitroimagepipeline.roundedCorners?tl=\(topLeft),tr=\(topRight),bl=\(bottomLeft),br=\(bottomRight)"
+    }
+
+    var hashableIdentifier: AnyHashable { identifier }
+
+    func process(_ image: PlatformImage) -> PlatformImage? {
+        let size = image.size
+        guard size.width > 0, size.height > 0 else { return image }
+
+        let format = UIGraphicsImageRendererFormat()
+        format.scale = image.scale
+        format.opaque = false
+
+        let rect = CGRect(origin: .zero, size: size)
+        return UIGraphicsImageRenderer(size: size, format: format).image { context in
+            context.cgContext.addPath(Self.clipPath(
+                in: rect,
+                topLeft: topLeft,
+                topRight: topRight,
+                bottomLeft: bottomLeft,
+                bottomRight: bottomRight
+            ))
+            context.cgContext.clip()
+            image.draw(in: rect)
+        }
+    }
+
+    /// A rounded-rect outline with independent corner radii, clamped the way
+    /// CSS `border-radius` clamps: if two radii on one edge overlap, all four
+    /// scale down proportionally until they fit.
+    static func clipPath(
+        in rect: CGRect,
+        topLeft: CGFloat,
+        topRight: CGFloat,
+        bottomLeft: CGFloat,
+        bottomRight: CGFloat
+    ) -> CGPath {
+        var scale: CGFloat = 1
+        for (edge, pair) in [
+            (rect.width, topLeft + topRight),
+            (rect.width, bottomLeft + bottomRight),
+            (rect.height, topLeft + bottomLeft),
+            (rect.height, topRight + bottomRight),
+        ] where pair > edge {
+            scale = min(scale, edge / pair)
+        }
+        let topLeft = topLeft * scale
+        let topRight = topRight * scale
+        let bottomLeft = bottomLeft * scale
+        let bottomRight = bottomRight * scale
+
+        // addArc(tangent1End:tangent2End:radius: 0) degenerates to a line
+        // through the corner, so square corners need no special-casing.
+        let path = CGMutablePath()
+        path.move(to: CGPoint(x: rect.minX + topLeft, y: rect.minY))
+        path.addLine(to: CGPoint(x: rect.maxX - topRight, y: rect.minY))
+        path.addArc(
+            tangent1End: CGPoint(x: rect.maxX, y: rect.minY),
+            tangent2End: CGPoint(x: rect.maxX, y: rect.minY + topRight),
+            radius: topRight
+        )
+        path.addLine(to: CGPoint(x: rect.maxX, y: rect.maxY - bottomRight))
+        path.addArc(
+            tangent1End: CGPoint(x: rect.maxX, y: rect.maxY),
+            tangent2End: CGPoint(x: rect.maxX - bottomRight, y: rect.maxY),
+            radius: bottomRight
+        )
+        path.addLine(to: CGPoint(x: rect.minX + bottomLeft, y: rect.maxY))
+        path.addArc(
+            tangent1End: CGPoint(x: rect.minX, y: rect.maxY),
+            tangent2End: CGPoint(x: rect.minX, y: rect.maxY - bottomLeft),
+            radius: bottomLeft
+        )
+        path.addLine(to: CGPoint(x: rect.minX, y: rect.minY + topLeft))
+        path.addArc(
+            tangent1End: CGPoint(x: rect.minX, y: rect.minY),
+            tangent2End: CGPoint(x: rect.minX + topLeft, y: rect.minY),
+            radius: topLeft
+        )
+        path.closeSubpath()
+        return path
+    }
+}

package/lib/commonjs/index.js

@@ -27,6 +27,17 @@ function useImage({
     error: undefined
   });
   const loadedUrlRef = (0, _react.useRef)(url);
+
+  // Split the option into primitives so an inline `{ topLeft: 24, ... }`
+  // literal (new identity every render) doesn't re-trigger the effect.
+  const isUniformRadius = typeof cornerRadius === 'number';
+  const uniformRadius = isUniformRadius ? cornerRadius : 0;
+  const {
+    topLeft = 0,
+    topRight = 0,
+    bottomLeft = 0,
+    bottomRight = 0
+  } = isUniformRadius ? {} : cornerRadius;
   (0, _react.useEffect)(() => {
     let cancelled = false;
     // Only reset to the loading state when the URL changes; for same-URL
@@ -43,7 +54,12 @@ function useImage({
       try {
         const result = await NitroImagePipeline.loadImage(url, {
           blur,
-          cornerRadius,
+          cornerRadius: isUniformRadius ? uniformRadius : {
+            topLeft,
+            topRight,
+            bottomLeft,
+            bottomRight
+          },
           cache
         });
         if (!cancelled) {
@@ -65,7 +81,7 @@ function useImage({
     return () => {
       cancelled = true;
     };
-  }, [url, blur, cornerRadius, cache]);
+  }, [url, blur, isUniformRadius, uniformRadius, topLeft, topRight, bottomLeft, bottomRight, cache]);
   return image;
 }
 //# sourceMappingURL=index.js.map