react-native-image-stitcher 0.1.0

package/ios/Sources/RNImageStitcher/QualityChecker.swift

@@ -0,0 +1,252 @@
+// SPDX-License-Identifier: Apache-2.0
+// QualityChecker.swift
+//
+// Pure-Swift implementations of the on-device quality scores the SDK
+// surfaces to the JS layer.  No React Native dependency in this file —
+// the bridge wrapper lives in `QualityCheckerBridge.swift` and only
+// translates promise resolves into the same numeric scores this file
+// produces.  Keeping the bridge thin means XCTest hits the algorithms
+// directly (via SwiftPM `swift test`) instead of needing an iOS
+// simulator + RN runtime to validate a Laplacian variance.
+//
+// Why this layer at all (instead of OpenCV)?
+//   Phase-1 quality checks (blur + brightness) are a tiny slice of
+//   what OpenCV does and Apple already ships the primitives in the OS
+//   (Accelerate's vImage convolutions, CoreImage's CIAreaAverage).
+//   Pulling in opencv-mobile only for two filters would add ~10 MB to
+//   the IPA for no functional gain — opencv-mobile gets paid for in
+//   Phase 2 when stitching arrives, where Apple has no equivalent.
+//
+// Algorithm references:
+//   * Blur: variance-of-Laplacian.  Pech-Pacheco et al. 2000,
+//     "Diatom autofocusing in brightfield microscopy: a comparative
+//     study."  Threshold ~50–100 separates "soft" from "blurry" for
+//     mobile shelf imagery in our pilot data.
+//   * Brightness: mean luminance.  Underexposed = mean < 60,
+//     overexposed = mean > 200, both unusable for downstream OCR.
+
+import Accelerate
+import CoreGraphics
+import CoreImage
+import Foundation
+
+/// Errors the quality check can surface to the bridge.  Each maps to a
+/// dedicated reject-code on the JS side so the host app can branch on
+/// "missing file" vs. "couldn't decode" vs. "internal".
+public enum QualityCheckError: Error {
+  case fileNotFound(path: String)
+  case imageDecodeFailed(path: String)
+  case bufferAllocationFailed
+  case convolutionFailed(vImageError: vImage_Error)
+}
+
+/// Numeric quality measurements; mirrors the QualityReport TS shape.
+public struct QualityScores: Equatable {
+  /// Variance of the Laplacian.  Higher = sharper.  Implementation
+  /// returns a non-negative Double; +∞ is reserved for the JS shim
+  /// fallback so production code can distinguish "we measured this
+  /// and it's astonishingly sharp" from "we never measured it."
+  public let blurScore: Double
+
+  /// Mean luminance in [0, 255].  255 = pure white, 0 = pure black.
+  /// We use the standard ITU-R BT.601 luma weights (0.299 R + 0.587 G +
+  /// 0.114 B) — vImage's RGB-to-Y conversion uses the same weights so
+  /// keeping them here means the mean we compute matches the mean
+  /// vImage would produce had we asked it directly.
+  public let brightnessScore: Double
+
+  public init(blurScore: Double, brightnessScore: Double) {
+    self.blurScore = blurScore
+    self.brightnessScore = brightnessScore
+  }
+}
+
+public enum QualityChecker {
+
+  /// Measure both blur and brightness in one decode pass.
+  ///
+  /// Call sites that only need one score (rare — both are cheap once
+  /// the image is decoded) can ignore the unused field.  Bundling the
+  /// API means we decode + convert-to-grayscale exactly once per call,
+  /// which is the bulk of the work; reading the grayscale buffer twice
+  /// to extract the two stats is essentially free.
+  public static func measure(imagePath: String) throws -> QualityScores {
+    let cgImage = try decodeImage(at: imagePath)
+    let grayBuffer = try makeGrayscaleBuffer(from: cgImage)
+    defer { grayBuffer.free() }
+
+    let brightness = grayBuffer.mean()
+    let blur = try grayBuffer.varianceOfLaplacian()
+    return QualityScores(blurScore: blur, brightnessScore: brightness)
+  }
+
+  /// Convenience: measure blur only.  Provided so unit tests can call
+  /// the algorithm in isolation without invoking the brightness path.
+  public static func measureBlurScore(imagePath: String) throws -> Double {
+    return try measure(imagePath: imagePath).blurScore
+  }
+
+  /// Convenience: measure brightness only.
+  public static func measureBrightness(imagePath: String) throws -> Double {
+    return try measure(imagePath: imagePath).brightnessScore
+  }
+
+  // MARK: - Internal helpers
+
+  /// Decode the file at `imagePath` into a CGImage.  Strips any
+  /// `file://` prefix the bridge may have passed through unchanged so
+  /// callers don't have to remember whether the SDK wants a URL or a
+  /// path.
+  private static func decodeImage(at imagePath: String) throws -> CGImage {
+    let cleaned = imagePath.hasPrefix("file://")
+      ? String(imagePath.dropFirst("file://".count))
+      : imagePath
+    guard FileManager.default.fileExists(atPath: cleaned) else {
+      throw QualityCheckError.fileNotFound(path: imagePath)
+    }
+    let url = URL(fileURLWithPath: cleaned)
+    guard
+      let source = CGImageSourceCreateWithURL(url as CFURL, nil),
+      let cgImage = CGImageSourceCreateImageAtIndex(source, 0, nil)
+    else {
+      throw QualityCheckError.imageDecodeFailed(path: imagePath)
+    }
+    return cgImage
+  }
+
+  /// Convert a CGImage to an 8-bit single-channel grayscale buffer.
+  ///
+  /// Why vImage instead of CoreImage's CIPhotoEffectMono filter?
+  ///   CIFilter chains are deferred and lazy — we'd have to render
+  ///   anyway to read the pixels back out.  vImage gives us an actual
+  ///   contiguous Y' buffer in one shot, which is exactly what the
+  ///   blur/brightness stats want.
+  private static func makeGrayscaleBuffer(from cgImage: CGImage) throws -> GrayscaleBuffer {
+    var format = vImage_CGImageFormat(
+      bitsPerComponent: 8,
+      bitsPerPixel: 8,
+      colorSpace: Unmanaged.passRetained(CGColorSpaceCreateDeviceGray()),
+      bitmapInfo: CGBitmapInfo(rawValue: CGImageAlphaInfo.none.rawValue),
+      version: 0,
+      decode: nil,
+      renderingIntent: .defaultIntent
+    )
+    var buffer = vImage_Buffer()
+    let createErr = vImageBuffer_InitWithCGImage(
+      &buffer, &format, nil, cgImage, vImage_Flags(kvImageNoFlags)
+    )
+    guard createErr == kvImageNoError else {
+      throw QualityCheckError.bufferAllocationFailed
+    }
+    return GrayscaleBuffer(buffer: buffer)
+  }
+}
+
+/// RAII wrapper around vImage_Buffer + the algorithms that read it.
+/// Owns the underlying pixel memory so callers `defer { buf.free() }`
+/// after construction.
+struct GrayscaleBuffer {
+  var buffer: vImage_Buffer
+
+  func free() {
+    if buffer.data != nil { Foundation.free(buffer.data) }
+  }
+
+  /// Mean pixel value across the buffer, [0, 255].  vImage doesn't
+  /// expose a direct mean function for Planar8 so we walk the rows
+  /// manually with vDSP_meanv on each row's bytes-as-floats.
+  func mean() -> Double {
+    let width = Int(buffer.width)
+    let height = Int(buffer.height)
+    let rowBytes = buffer.rowBytes
+    let basePtr = buffer.data.assumingMemoryBound(to: UInt8.self)
+
+    var total: Double = 0
+    var count: Double = 0
+    var rowAccumulator = [Float](repeating: 0, count: width)
+    for y in 0..<height {
+      let rowPtr = basePtr.advanced(by: y * rowBytes)
+      // vImageConvert_Planar8toPlanarF would do the type conversion in
+      // bulk; for the per-row mean the manual loop is faster than
+      // setting up a vImage call per row.
+      for x in 0..<width {
+        rowAccumulator[x] = Float(rowPtr[x])
+      }
+      var rowMean: Float = 0
+      vDSP_meanv(rowAccumulator, 1, &rowMean, vDSP_Length(width))
+      total += Double(rowMean)
+      count += 1
+    }
+    return count > 0 ? total / count : 0
+  }
+
+  /// Variance-of-Laplacian — the canonical "how blurry is this" score.
+  ///
+  /// Steps:
+  ///   1. Convolve the grayscale buffer with the discrete Laplacian
+  ///      kernel.  Output = high-frequency / edge response.
+  ///   2. Compute the variance of the convolved buffer.  Sharp images
+  ///      have lots of edges with widely varying magnitudes; blurry
+  ///      images have weak, similar values throughout.
+  func varianceOfLaplacian() throws -> Double {
+    let width = buffer.width
+    let height = buffer.height
+
+    // Allocate the output buffer.  vImageConvolve_Planar8 writes the
+    // convolved bytes into a new buffer of the same dimensions.
+    var output = vImage_Buffer()
+    let outputBytes = Int(height) * Int(width)
+    output.data = malloc(outputBytes)
+    output.width = width
+    output.height = height
+    output.rowBytes = Int(width)
+    guard output.data != nil else {
+      throw QualityCheckError.bufferAllocationFailed
+    }
+    defer { Foundation.free(output.data) }
+
+    // Discrete Laplacian.  Sums to zero so the convolved buffer's
+    // mean is ~0 except where edges live; variance then quantifies
+    // edge response — exactly the "is this image sharp" question.
+    //   0  -1   0
+    //  -1   4  -1
+    //   0  -1   0
+    let kernel: [Int16] = [0, -1, 0, -1, 4, -1, 0, -1, 0]
+    let divisor: Int32 = 1
+
+    // vImageConvolve_Planar8 takes mutable buffer pointers; copy into
+    // local vars so we can hand it inout refs without violating Swift's
+    // exclusive-access rules on `self.buffer`.
+    var input = buffer
+    let convErr = kernel.withUnsafeBufferPointer { kernelPtr -> vImage_Error in
+      // backgroundColor is unused with kvImageEdgeExtend (we extend
+      // edge pixels rather than padding) — pass 0 as a placeholder.
+      vImageConvolve_Planar8(
+        &input, &output, nil, 0, 0,
+        kernelPtr.baseAddress, 3, 3,
+        divisor, 0,
+        vImage_Flags(kvImageEdgeExtend)
+      )
+    }
+    guard convErr == kvImageNoError else {
+      throw QualityCheckError.convolutionFailed(vImageError: convErr)
+    }
+
+    // Compute variance over the output pixels.  vImage gives us the
+    // bytes; vDSP gives us the stats.  Convert U8 → F32 in one bulk op
+    // so vDSP_normalize / vDSP_measqv can run native.
+    let count = Int(width) * Int(height)
+    var floatBuffer = [Float](repeating: 0, count: count)
+    let outBytes = output.data.assumingMemoryBound(to: UInt8.self)
+    for i in 0..<count {
+      floatBuffer[i] = Float(outBytes[i])
+    }
+
+    var mean: Float = 0
+    var meanSquare: Float = 0
+    vDSP_meanv(floatBuffer, 1, &mean, vDSP_Length(count))
+    vDSP_measqv(floatBuffer, 1, &meanSquare, vDSP_Length(count))
+    let variance = Double(meanSquare) - Double(mean) * Double(mean)
+    return max(0, variance)
+  }
+}

package/ios/Sources/RNImageStitcher/QualityCheckerBridge.m

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// QualityCheckerBridge.m
+//
+// Obj-C glue that registers the Swift `QualityCheckerBridge`
+// class with the React Native module map.  React Native's
+// `RCT_EXTERN_MODULE` and `RCT_EXTERN_METHOD` are C macros — they
+// can't be invoked from Swift directly — so a `.m` shim is required
+// even though the actual implementation is Swift.
+//
+// The first arg to RCT_EXTERN_MODULE is the Obj-C-visible class name.
+// Marking the Swift class `@objc(RNImageStitcherQualityChecker)` aliases it
+// to the same name on the Obj-C side, which means the JS layer sees
+// `NativeModules.RNImageStitcherQualityChecker` regardless of the Swift
+// class's actual Swift-side name.
+//
+
+#import <React/RCTBridgeModule.h>
+
+@interface RCT_EXTERN_MODULE(RNImageStitcherQualityChecker, NSObject)
+
+RCT_EXTERN_METHOD(measure:(NSString *)imagePath
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
+@end

package/ios/Sources/RNImageStitcher/QualityCheckerBridge.swift

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+// QualityCheckerBridge.swift
+//
+// React Native bridge for `QualityChecker`.  This file does NOT contain
+// algorithm code — it converts JS-side promise calls into the pure
+// Swift API in `QualityChecker.swift` and converts the resulting
+// scores or errors back into a shape the JS layer can consume.
+//
+// Pairing pattern:
+//   * QualityChecker.swift    — pure Swift, XCTest-able, no RN.
+//   * QualityCheckerBridge.swift (this file) — RN-aware, registered
+//     via `@objc(RNImageStitcherQualityChecker)` so the JS shim can find it
+//     at NativeModules.RNImageStitcherQualityChecker.
+//
+// Why two files instead of one?
+//   The bridge depends on React (RCTPromiseResolveBlock,
+//   RCTBridgeModule).  XCTest in SwiftPM mode can't resolve those
+//   without an Xcode workspace.  Splitting means the algorithm tests
+//   build clean from the command line, and only the bridge requires
+//   a host-app context to compile (which it already has, via the
+//   mobile app's Pods workspace).
+
+#if canImport(React)
+import Foundation
+import React
+
+@objc(RNImageStitcherQualityChecker)
+public class QualityCheckerBridge: NSObject {
+
+  // RCT_EXPORT_MODULE — the Obj-C bridge file picks up this name and
+  // registers it with the JS module map.  Returning false here means
+  // the module's queue methods aren't required to run on the main
+  // thread, which we want — image decode is CPU work.
+  @objc public static func requiresMainQueueSetup() -> Bool { return false }
+
+  /// Bridged entry: measure both blur + brightness and resolve with
+  /// `{ blurScore, brightnessScore }`.  Reject with a stable code so
+  /// the JS layer can branch (e.g. "missing-file" can fall back to a
+  /// retry, "decode-failed" usually can't).
+  @objc(measure:resolver:rejecter:)
+  public func measure(
+    imagePath: NSString,
+    resolver: @escaping RCTPromiseResolveBlock,
+    rejecter: @escaping RCTPromiseRejectBlock
+  ) {
+    do {
+      let scores = try QualityChecker.measure(imagePath: imagePath as String)
+      resolver([
+        "blurScore": scores.blurScore,
+        "brightnessScore": scores.brightnessScore,
+      ])
+    } catch let err as QualityCheckError {
+      switch err {
+      case .fileNotFound(let path):
+        rejecter("file-not-found", "File not found at path: \(path)", err)
+      case .imageDecodeFailed(let path):
+        rejecter("decode-failed", "Could not decode image at \(path)", err)
+      case .bufferAllocationFailed:
+        rejecter("buffer-alloc-failed", "Failed to allocate pixel buffer", err)
+      case .convolutionFailed(let vImageError):
+        rejecter(
+          "convolution-failed",
+          "vImage convolution failed (error \(vImageError))",
+          err
+        )
+      }
+    } catch {
+      rejecter("unknown", "Unexpected error: \(error)", error)
+    }
+  }
+}
+#endif

package/ios/Sources/RNImageStitcher/RNSARCameraView.swift

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// RNSARCameraView — native UIView that renders the AR camera
+// feed for the SDK's pose-aware capture surface.
+//
+// Phase 4.4 of the AR measurement plan.  This is the camera-access
+// handoff: vision-camera owns the camera in non-AR audits, ARKit
+// owns it in AR audits.  React Native picks which CameraView the
+// host mounts; the host never sees both at once.
+//
+// Why ARSCNView vs custom Metal:
+//   We just need to render `ARFrame.capturedImage` to screen — no
+//   3D content overlays, no SceneKit nodes.  Custom Metal would be
+//   ~150 lines of MTKView setup + a textured-quad shader.  ARSCNView
+//   does the same thing in 2 lines: it's a UIKit view that auto-
+//   renders the camera feed as the SceneKit background whenever its
+//   `session` property points at a running ARSession.  Phase 5
+//   stitching consumes pose data, NOT pixels-from-Metal, so we
+//   never need the lower-level rendering control.
+//
+// Why a wrapper UIView (vs. exposing ARSCNView directly):
+//   RCTViewManager expects to vend a UIView subclass it owns.
+//   Wrapping ARSCNView lets us:
+//     - resize its frame to match the React Native layout in
+//       `layoutSubviews` (auto-resizing masks alone don't always
+//       fire when RN's flexbox engine assigns a new bounds rect),
+//     - add lifecycle hooks (start/stop the singleton AR session
+//       when the view enters / leaves the window hierarchy), and
+//     - keep room for future overlays (tracking-state HUD, focus
+//       indicator, etc.) without touching ARSCNView internals.
+
+import Foundation
+import ARKit
+import UIKit
+
+
+@objc(RNSARCameraView)
+public final class RNSARCameraView: UIView {
+
+    /// The ARSCNView that does the actual rendering.  Bound to the
+    /// singleton's ARSession so all preview surfaces share the same
+    /// session (and the same pose log that the stitcher consumes).
+    private var arSCNView: ARSCNView!
+
+    public override init(frame: CGRect) {
+        super.init(frame: frame)
+        setupView()
+    }
+
+    public required init?(coder: NSCoder) {
+        super.init(coder: coder)
+        setupView()
+    }
+
+    private func setupView() {
+        arSCNView = ARSCNView(frame: bounds)
+        arSCNView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+
+        // Bind to the singleton's session.  This is the critical
+        // line — without it, ARSCNView would try to create its own
+        // session and we'd lose the pose log.  Sharing means:
+        //   - The host's `useARSession` hook still drives lifecycle.
+        //   - Pose data captured via `RNSARSession.shared`'s
+        //     delegate callbacks remains intact; this view is purely
+        //     a renderer.
+        arSCNView.session = RNSARSession.shared.arSession
+
+        // We don't draw any 3D content in Phase 4.4.  Disable
+        // SceneKit's automatic statistics overlay and lighting model
+        // — we just want the camera feed.
+        arSCNView.showsStatistics = false
+        arSCNView.automaticallyUpdatesLighting = false
+
+        // Black background while ARKit is initialising so the user
+        // sees a clean frame instead of whatever was there before.
+        backgroundColor = .black
+        addSubview(arSCNView)
+    }
+
+    public override func layoutSubviews() {
+        super.layoutSubviews()
+        // RN's flexbox can re-bound this view at any time; keep the
+        // ARSCNView locked to our bounds.  autoresizingMask handles
+        // most cases but isn't always enough on rotation transitions.
+        arSCNView.frame = bounds
+    }
+
+    public override func didMoveToWindow() {
+        super.didMoveToWindow()
+        // When this view enters the hierarchy, ensure the AR session
+        // is running.  When it leaves, stop the session so the
+        // hardware camera is freed for vision-camera or other uses.
+        //
+        // The singleton's start/stop are idempotent, so multiple
+        // ARCameraView instances mounting/unmounting won't fight
+        // each other (last-mount-wins semantics).  In practice the
+        // host only mounts one at a time.
+        if window != nil {
+            if !RNSARSession.shared.isRunning {
+                RNSARSession.shared.start()
+            }
+        } else {
+            // Removed from window — stop the session.  Don't clear
+            // the pose log here; the host explicitly clears between
+            // captures via `RNSARSession.shared.clearPoseLog()`
+            // so the JS layer controls when poses get discarded.
+            if RNSARSession.shared.isRunning {
+                RNSARSession.shared.stop()
+            }
+        }
+    }
+}
+
+